evaluations pagination & filtering

[tgross]

The List Evaluations and /v1/job/:jobid/evaluations (no docs?) APIs need to have pagination and filtering to support a refreshed evaluations list page.

I've dropped the current QueryOptions struct below.

• We already have filters available by Namespace and Region.
• The pagination parameters are already there (but unused in the RPC call).
• We have a Params map that's already being used for arbitrary filtering details in the Scaling & Recommendations APIs, so we can use that for filtering anything else.
• For the interaction between pagination and filtering, my first-pass naive thinking is that we use the Eval ID as the next token and then assume that the filtering is stable over that list. So passing the token will skip ahead to that Eval ID. If the data set changes out from underneath us, we end up with a stale query. WaitIndex can prevent that, as usual for the API.
• There's an existing filter pass happening in both RPCs, so actually implementing the filter seems like... a nominal amount of work? Mostly testing and documentation and deciding on which fields we want to be able to filter on.

---

// QueryOptions are used to parametrize a query
type QueryOptions struct {
	// Providing a datacenter overwrites the region provided
	// by the Config
	Region string

	// Namespace is the target namespace for the query.
	Namespace string

	// AllowStale allows any Nomad server (non-leader) to service
	// a read. This allows for lower latency and higher throughput
	AllowStale bool

	// WaitIndex is used to enable a blocking query. Waits
	// until the timeout or the next index is reached
	WaitIndex uint64

	// WaitTime is used to bound the duration of a wait.
	// Defaults to that of the Config, but can be overridden.
	WaitTime time.Duration

	// If set, used as prefix for resource list searches
	Prefix string

	// Set HTTP parameters on the query.
	Params map[string]string

	// AuthToken is the secret ID of an ACL token
	AuthToken string

	// PerPage is the number of entries to be returned in queries that support
	// paginated lists.
	PerPage int32

	// NextToken is the token used indicate where to start paging for queries
	// that support paginated lists.
	NextToken string

	// ctx is an optional context pass through to the underlying HTTP
	// request layer. Use Context() and WithContext() to manage this.
	ctx context.Context
}

cc @mikenomitch @ChaiWithJai

[tgross]

Working branch is f-evaluations-list-pagination.

[github-actions]

I'm going to lock this issue because it has been closed for 120 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.