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