api: implement fuzzy search API

This PR introduces the /v1/search/fuzzy API endpoint, used for fuzzy
searching objects in Nomad. The fuzzy search endpoint routes requests
to the Nomad Server leader, which implements the Search.FuzzySearch RPC
method.

Requests to the fuzzy search API are based on the api.FuzzySearchRequest
object, e.g.

{
  "Text": "ed",
  "Context": "all"
}

Responses from the fuzzy search API are based on the api.FuzzySearchResponse
object, e.g.

{
  "Index": 27,
  "KnownLeader": true,
  "LastContact": 0,
  "Matches": {
    "tasks": [
      {
        "ID": "redis",
        "Scope": [
          "default",
          "example",
          "cache"
        ]
      }
    ],
    "evals": [],
    "deployment": [],
    "volumes": [],
    "scaling_policy": [],
    "images": [
      {
        "ID": "redis:3.2",
        "Scope": [
          "default",
          "example",
          "cache",
          "redis"
        ]
      }
    ]
  },
  "Truncations": {
    "volumes": false,
    "scaling_policy": false,
    "evals": false,
    "deployment": false
  }
}

The API is tunable using the new server.search stanza, e.g.

server {
  search {
    fuzzy_enabled   = true
    limit_query     = 200
    limit_results   = 1000
    min_term_length = 5
  }
}

These values can be increased or decreased, so as to provide more
search results or to reduce load on the Nomad Server. The fuzzy search
API can be disabled entirely by setting `fuzzy_enabled` to `false`.

CHANGELOG.md

@@ -8,6 +8,7 @@ BUG FIXES:
  * ui: Fixed the rendering of interstitial components shown after processing a dynamic application sizing recommendation. [[GH-10094](https://github.com/hashicorp/nomad/pull/10094)]
 
 IMPROVEMENTS:
+ * api: Added an API endpoint for fuzzy search queries [[GH-10184](https://github.com/hashicorp/nomad/pull/10184)]
  * cli: Update defaults for `nomad operator debug` flags `-interval` and `-server-id` to match common usage. [[GH-10121](https://github.com/hashicorp/nomad/issues/10121)]
  * consul/connect: Enable setting `local_bind_address` field on connect upstreams [[GH-6248](https://github.com/hashicorp/nomad/issues/6248)]
  * driver/docker: Added support for optional extra container labels. [[GH-9885](https://github.com/hashicorp/nomad/issues/9885)]

api/contexts/contexts.go

@@ -1,9 +1,12 @@
+// Package contexts provides constants used with the Nomad Search API.
 package contexts
 
-// Context defines the scope in which a search for Nomad object operates
+// Context defines the scope in which a search for Nomad object operates.
 type Context string
 
 const (
+	// These Context types are used to reference the high level Nomad object
+	// types than can be searched.
 	Allocs          Context = "allocs"
 	Deployments     Context = "deployment"
 	Evals           Context = "evals"
@@ -15,5 +18,16 @@ const (
 	ScalingPolicies Context = "scaling_policy"
 	Plugins         Context = "plugins"
 	Volumes         Context = "volumes"
-	All             Context = "all"
+
+	// These Context types are used to associate a search result from a lower
+	// level Nomad object with one of the higher level Context types above.
+	Groups   Context = "groups"
+	Services Context = "services"
+	Tasks    Context = "tasks"
+	Images   Context = "images"
+	Commands Context = "commands"
+	Classes  Context = "classes"
+
+	// Context used to represent the set of all the higher level Context types.
+	All Context = "all"
 )

api/search.go

@@ -13,7 +13,7 @@ func (c *Client) Search() *Search {
 	return &Search{client: c}
 }
 
-// PrefixSearch returns a list of matches for a particular context and prefix.
+// PrefixSearch returns a set of matches for a particular context and prefix.
 func (s *Search) PrefixSearch(prefix string, context contexts.Context, q *QueryOptions) (*SearchResponse, *QueryMeta, error) {
 	var resp SearchResponse
 	req := &SearchRequest{Prefix: prefix, Context: context}
@@ -26,14 +26,72 @@ func (s *Search) PrefixSearch(prefix string, context contexts.Context, q *QueryO
 	return &resp, qm, nil
 }
 
+type SearchResponse struct {
+	Matches     map[contexts.Context][]string
+	Truncations map[contexts.Context]bool
+	QueryMeta
+}
+
 type SearchRequest struct {
 	Prefix  string
 	Context contexts.Context
 	QueryOptions
 }
 
-type SearchResponse struct {
-	Matches     map[contexts.Context][]string
+// FuzzySearch returns a set of matches for a given context and string.
+func (s *Search) FuzzySearch(text string, context contexts.Context, q *QueryOptions) (*FuzzySearchResponse, *QueryMeta, error) {
+	var resp FuzzySearchResponse
+
+	req := &FuzzySearchRequest{
+		Context: context,
+		Text:    text,
+	}
+
+	qm, err := s.client.putQuery("/v1/search/fuzzy", req, &resp, q)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	return &resp, qm, nil
+}
+
+// FuzzyMatch is used to describe the ID of an object which may be a machine
+// readable UUID or a human readable Name. If the object is a component of a Job,
+// the Scope is a list of IDs starting from Namespace down to the parent object of
+// ID.
+//
+// e.g. A Task-level service would have scope like,
+//   ["<namespace>", "<job>", "<group>", "<task>"]
+type FuzzyMatch struct {
+	ID    string   // ID is UUID or Name of object
+	Scope []string `json:",omitempty"` // IDs of parent objects
+}
+
+// FuzzySearchResponse is used to return fuzzy matches and information about
+// whether the match list is truncated specific to each type of searchable Context.
+type FuzzySearchResponse struct {
+	// Matches is a map of Context types to IDs which fuzzy match a specified query.
+	Matches map[contexts.Context][]FuzzyMatch
+
+	// Truncations indicates whether the matches for a particular Context have
+	// been truncated.
 	Truncations map[contexts.Context]bool
+
 	QueryMeta
 }
+
+// FuzzySearchRequest is used to parameterize a fuzzy search request, and returns
+// a list of matches made up of jobs, allocations, evaluations, and/or nodes,
+// along with whether or not the information returned is truncated.
+type FuzzySearchRequest struct {
+	// Text is what names are fuzzy-matched to. E.g. if the given text were
+	// "py", potential matches might be "python", "mypy", etc. of jobs, nodes,
+	// allocs, groups, services, commands, images, classes.
+	Text string
+
+	// Context is the type that can be matched against. A Context of "all" indicates
+	// all Contexts types are queried for matching.
+	Context contexts.Context
+
+	QueryOptions
+}

api/search_test.go

@@ -7,26 +7,46 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-func TestSearch_List(t *testing.T) {
-	require := require.New(t)
+func TestSearch_PrefixSearch(t *testing.T) {
 	t.Parallel()
 
 	c, s := makeClient(t, nil, nil)
 	defer s.Stop()
 
 	job := testJob()
 	_, _, err := c.Jobs().Register(job, nil)
-	require.Nil(err)
+	require.NoError(t, err)
 
 	id := *job.ID
 	prefix := id[:len(id)-2]
 	resp, qm, err := c.Search().PrefixSearch(prefix, contexts.Jobs, nil)
-
-	require.Nil(err)
-	require.NotNil(qm)
-	require.NotNil(qm)
+	require.NoError(t, err)
+	require.NotNil(t, qm)
+	require.NotNil(t, resp)
 
 	jobMatches := resp.Matches[contexts.Jobs]
-	require.Equal(1, len(jobMatches))
-	require.Equal(id, jobMatches[0])
+	require.Len(t, jobMatches, 1)
+	require.Equal(t, id, jobMatches[0])
+}
+
+func TestSearch_FuzzySearch(t *testing.T) {
+	t.Parallel()
+	c, s := makeClient(t, nil, nil)
+	defer s.Stop()
+
+	job := testJob()
+	_, _, err := c.Jobs().Register(job, nil)
+	require.NoError(t, err)
+
+	resp, qm, err := c.Search().FuzzySearch("bin", contexts.All, nil)
+	require.NoError(t, err)
+	require.NotNil(t, qm)
+	require.NotNil(t, resp)
+
+	commandMatches := resp.Matches[contexts.Commands]
+	require.Len(t, commandMatches, 1)
+	require.Equal(t, "/bin/sleep", commandMatches[0].ID)
+	require.Equal(t, []string{
+		"default", "redis", "group1", "task1",
+	}, commandMatches[0].Scope)
 }

command/agent/agent.go

@@ -418,6 +418,16 @@ func convertServerConfig(agentConfig *Config) (*nomad.Config, error) {
 		conf.RPCMaxConnsPerClient = limit
 	}
 
+	// Add the search configuration
+	if search := agentConfig.Server.Search; search != nil {
+		conf.SearchConfig = &structs.SearchConfig{
+			FuzzyEnabled:  search.FuzzyEnabled,
+			LimitQuery:    search.LimitQuery,
+			LimitResults:  search.LimitResults,
+			MinTermLength: search.MinTermLength,
+		}
+	}
+
 	return conf, nil
 }
 

command/agent/config.go

@@ -496,6 +496,44 @@ type ServerConfig struct {
 
 	// ExtraKeysHCL is used by hcl to surface unexpected keys
 	ExtraKeysHCL []string `hcl:",unusedKeys" json:"-"`
+
+	Search *Search `hcl:"search"`
+}
+
+// Search is used in servers to configure search API options.
+type Search struct {
+	// FuzzyEnabled toggles whether the FuzzySearch API is enabled. If not
+	// enabled, requests to /v1/search/fuzzy will reply with a 404 response code.
+	//
+	// Default: enabled.
+	FuzzyEnabled bool `hcl:"fuzzy_enabled"`
+
+	// LimitQuery limits the number of objects searched in the FuzzySearch API.
+	// The results are indicated as truncated if the limit is reached.
+	//
+	// Lowering this value can reduce resource consumption of Nomad server when
+	// the FuzzySearch API is enabled.
+	//
+	// Default value: 20.
+	LimitQuery int `hcl:"limit_query"`
+
+	// LimitResults limits the number of results provided by the FuzzySearch API.
+	// The results are indicated as truncate if the limit is reached.
+	//
+	// Lowering this value can reduce resource consumption of Nomad server per
+	// fuzzy search request when the FuzzySearch API is enabled.
+	//
+	// Default value: 100.
+	LimitResults int `hcl:"limit_results"`
+
+	// MinTermLength is the minimum length of Text required before the FuzzySearch
+	// API will return results.
+	//
+	// Increasing this value can avoid resource consumption on Nomad server by
+	// reducing searches with less meaningful results.
+	//
+	// Default value: 2.
+	MinTermLength int `hcl:"min_term_length"`
 }
 
 // ServerJoin is used in both clients and servers to bootstrap connections to
@@ -893,6 +931,12 @@ func DefaultConfig() *Config {
 				RetryInterval:    30 * time.Second,
 				RetryMaxAttempts: 0,
 			},
+			Search: &Search{
+				FuzzyEnabled:  true,
+				LimitQuery:    20,
+				LimitResults:  100,
+				MinTermLength: 2,
+			},
 		},
 		ACL: &ACLConfig{
 			Enabled:   false,
@@ -1424,6 +1468,19 @@ func (a *ServerConfig) Merge(b *ServerConfig) *ServerConfig {
 		result.DefaultSchedulerConfig = &c
 	}
 
+	if b.Search != nil {
+		result.Search = &Search{FuzzyEnabled: b.Search.FuzzyEnabled}
+		if b.Search.LimitQuery > 0 {
+			result.Search.LimitQuery = b.Search.LimitQuery
+		}
+		if b.Search.LimitResults > 0 {
+			result.Search.LimitResults = b.Search.LimitResults
+		}
+		if b.Search.MinTermLength > 0 {
+			result.Search.MinTermLength = b.Search.MinTermLength
+		}
+	}
+
 	// Add the schedulers
 	result.EnabledSchedulers = append(result.EnabledSchedulers, b.EnabledSchedulers...)
 

command/agent/http.go

@@ -312,6 +312,7 @@ func (s *HTTPServer) registerHandlers(enableDebug bool) {
 	s.mux.HandleFunc("/v1/status/leader", s.wrap(s.StatusLeaderRequest))
 	s.mux.HandleFunc("/v1/status/peers", s.wrap(s.StatusPeersRequest))
 
+	s.mux.HandleFunc("/v1/search/fuzzy", s.wrap(s.FuzzySearchRequest))
 	s.mux.HandleFunc("/v1/search", s.wrap(s.SearchRequest))
 
 	s.mux.HandleFunc("/v1/operator/license", s.wrap(s.LicenseRequest))

command/agent/search_endpoint.go

@@ -12,14 +12,14 @@ func (s *HTTPServer) SearchRequest(resp http.ResponseWriter, req *http.Request)
 	if req.Method == "POST" || req.Method == "PUT" {
 		return s.newSearchRequest(resp, req)
 	}
-	return nil, CodedError(405, ErrInvalidMethod)
+	return nil, CodedError(http.StatusMethodNotAllowed, ErrInvalidMethod)
 }
 
 func (s *HTTPServer) newSearchRequest(resp http.ResponseWriter, req *http.Request) (interface{}, error) {
 	args := structs.SearchRequest{}
 
 	if err := decodeBody(req, &args); err != nil {
-		return nil, CodedError(400, err.Error())
+		return nil, CodedError(http.StatusBadRequest, err.Error())
 	}
 
 	if s.parse(resp, req, &args.Region, &args.QueryOptions) {
@@ -34,3 +34,30 @@ func (s *HTTPServer) newSearchRequest(resp http.ResponseWriter, req *http.Reques
 	setMeta(resp, &out.QueryMeta)
 	return out, nil
 }
+
+func (s *HTTPServer) FuzzySearchRequest(resp http.ResponseWriter, req *http.Request) (interface{}, error) {
+	if req.Method == "POST" || req.Method == "PUT" {
+		return s.newFuzzySearchRequest(resp, req)
+	}
+	return nil, CodedError(http.StatusMethodNotAllowed, ErrInvalidMethod)
+}
+
+func (s *HTTPServer) newFuzzySearchRequest(resp http.ResponseWriter, req *http.Request) (interface{}, error) {
+	var args structs.FuzzySearchRequest
+
+	if err := decodeBody(req, &args); err != nil {
+		return nil, CodedError(http.StatusBadRequest, err.Error())
+	}
+
+	if s.parse(resp, req, &args.Region, &args.QueryOptions) {
+		return nil, nil
+	}
+
+	var out structs.FuzzySearchResponse
+	if err := s.agent.RPC("Search.FuzzySearch", &args, &out); err != nil {
+		return nil, err
+	}
+
+	setMeta(resp, &out.QueryMeta)
+	return out, nil
+}