github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/nomad/structs/search.go (about)

     1  package structs
     2  
     3  // Context defines the scope in which a search for Nomad object operates, and
     4  // is also used to query the matching index value for this context.
     5  type Context string
     6  
     7  const (
     8  	// Individual context types.
     9  	Allocs          Context = "allocs"
    10  	Deployments     Context = "deployment"
    11  	Evals           Context = "evals"
    12  	Jobs            Context = "jobs"
    13  	Nodes           Context = "nodes"
    14  	Namespaces      Context = "namespaces"
    15  	Quotas          Context = "quotas"
    16  	Recommendations Context = "recommendations"
    17  	ScalingPolicies Context = "scaling_policy"
    18  	Plugins         Context = "plugins"
    19  	Variables       Context = "vars"
    20  	Volumes         Context = "volumes"
    21  
    22  	// Subtypes used in fuzzy matching.
    23  	Groups   Context = "groups"
    24  	Services Context = "services"
    25  	Tasks    Context = "tasks"
    26  	Images   Context = "images"
    27  	Commands Context = "commands"
    28  	Classes  Context = "classes"
    29  
    30  	// Union context types.
    31  	All Context = "all"
    32  )
    33  
    34  // SearchConfig is used in servers to configure search API options.
    35  type SearchConfig struct {
    36  	// FuzzyEnabled toggles whether the FuzzySearch API is enabled. If not
    37  	// enabled, requests to /v1/search/fuzzy will reply with a 404 response code.
    38  	FuzzyEnabled bool `hcl:"fuzzy_enabled"`
    39  
    40  	// LimitQuery limits the number of objects searched in the FuzzySearch API.
    41  	// The results are indicated as truncated if the limit is reached.
    42  	//
    43  	// Lowering this value can reduce resource consumption of Nomad server when
    44  	// the FuzzySearch API is enabled.
    45  	LimitQuery int `hcl:"limit_query"`
    46  
    47  	// LimitResults limits the number of results provided by the FuzzySearch API.
    48  	// The results are indicated as truncate if the limit is reached.
    49  	//
    50  	// Lowering this value can reduce resource consumption of Nomad server per
    51  	// fuzzy search request when the FuzzySearch API is enabled.
    52  	LimitResults int `hcl:"limit_results"`
    53  
    54  	// MinTermLength is the minimum length of Text required before the FuzzySearch
    55  	// API will return results.
    56  	//
    57  	// Increasing this value can avoid resource consumption on Nomad server by
    58  	// reducing searches with less meaningful results.
    59  	MinTermLength int `hcl:"min_term_length"`
    60  }
    61  
    62  func (s *SearchConfig) Copy() *SearchConfig {
    63  	if s == nil {
    64  		return nil
    65  	}
    66  
    67  	ns := *s
    68  	return &ns
    69  }
    70  
    71  // SearchResponse is used to return matches and information about whether
    72  // the match list is truncated specific to each type of Context.
    73  type SearchResponse struct {
    74  	// Map of Context types to ids which match a specified prefix
    75  	Matches map[Context][]string
    76  
    77  	// Truncations indicates whether the matches for a particular Context have
    78  	// been truncated
    79  	Truncations map[Context]bool
    80  
    81  	QueryMeta
    82  }
    83  
    84  // SearchRequest is used to parameterize a request, and returns a
    85  // list of matches made up of jobs, allocations, evaluations, and/or nodes,
    86  // along with whether or not the information returned is truncated.
    87  type SearchRequest struct {
    88  	// Prefix is what ids are matched to. I.e, if the given prefix were
    89  	// "a", potential matches might be "abcd" or "aabb"
    90  	Prefix string
    91  
    92  	// Context is the type that can be matched against. A context can be a job,
    93  	// node, evaluation, allocation, or empty (indicated every context should be
    94  	// matched)
    95  	Context Context
    96  
    97  	QueryOptions
    98  }
    99  
   100  // FuzzyMatch is used to describe the ID of an object which may be a machine
   101  // readable UUID or a human readable Name. If the object is a component of a Job,
   102  // the Scope is a list of IDs starting from Namespace down to the parent object of
   103  // ID.
   104  //
   105  // e.g. A Task-level service would have scope like,
   106  //
   107  //	["<namespace>", "<job>", "<group>", "<task>"]
   108  type FuzzyMatch struct {
   109  	ID    string   // ID is UUID or Name of object
   110  	Scope []string `json:",omitempty"` // IDs of parent objects
   111  }
   112  
   113  // FuzzySearchResponse is used to return fuzzy matches and information about
   114  // whether the match list is truncated specific to each type of searchable Context.
   115  type FuzzySearchResponse struct {
   116  	// Matches is a map of Context types to IDs which fuzzy match a specified query.
   117  	Matches map[Context][]FuzzyMatch
   118  
   119  	// Truncations indicates whether the matches for a particular Context have
   120  	// been truncated.
   121  	Truncations map[Context]bool
   122  
   123  	QueryMeta
   124  }
   125  
   126  // FuzzySearchRequest is used to parameterize a fuzzy search request, and returns
   127  // a list of matches made up of jobs, allocations, evaluations, and/or nodes,
   128  // along with whether or not the information returned is truncated.
   129  type FuzzySearchRequest struct {
   130  	// Text is what names are fuzzy-matched to. E.g. if the given text were
   131  	// "py", potential matches might be "python", "mypy", etc. of jobs, nodes,
   132  	// allocs, groups, services, commands, images, classes.
   133  	Text string
   134  
   135  	// Context is the type that can be matched against. A Context of "all" indicates
   136  	// all Contexts types are queried for matching.
   137  	Context Context
   138  
   139  	QueryOptions
   140  }