backends

type Backend interface {
	// RegisterHandlers registers the provided Handlers into the Router
	RegisterHandlers(handlers.Lookup)
	// Handlers returns a map of the HTTP Handlers the Backend has registered
	Handlers() handlers.Lookup
	// DefaultPathConfigs returns the default PathConfigs for the given Provider
	DefaultPathConfigs(*bo.Options) po.List
	// Configuration returns the configuration for the Backend
	Configuration() *bo.Options
	// Name returns the name of the Backend
	Name() string
	// HTTPClient will return the HTTP Client for this Backend
	HTTPClient() *http.Client
	// SetCache sets the Cache object the Backend will use when caching origin content
	SetCache(cache.Cache)
	// Router returns a Router that handles HTTP Requests for this Backend
	Router() http.Handler
	// Cache returns a handle to the Cache instance used by the Backend
	Cache() cache.Cache
	// BaseUpstreamURL returns the base URL for upstream requests
	BaseUpstreamURL() *url.URL
	// SetHealthCheckProbe sets the Health Check Status Prober for the Client
	SetHealthCheckProbe(healthcheck.DemandProbe)
	// HealthHandler executes a Health Check Probe when called
	HealthHandler(http.ResponseWriter, *http.Request)
	// DefaultHealthCheckConfig returns the default Health Check Config for the given Provider
	DefaultHealthCheckConfig() *ho.Options
	// HealthCheckHTTPClient returns the HTTP Client used for Health Checking
	HealthCheckHTTPClient() *http.Client
}

type Backends map[string]Backend

type MergeableTimeseriesBackend interface {
	// MergePaths should return a slice of HTTP Paths that are safe to merge with
	// other requests of the same path (e.g.,   /api/v1/query_range in prometheus)
	MergeablePaths() []string
}

type Registrar func(handlers.Lookup)

type TSMMergeProvider interface {
	// ClassifyMerge inspects the query string and returns:
	//   - strategy: the merge strategy to use for fanout accumulation, as the
	//     underlying int value of dataset.MergeStrategy (avoids importing the
	//     dataset package here and breaking the shallow backends import graph).
	//   - needsDualQuery: true when a weighted arithmetic mean is required
	//     (i.e. the outer aggregator is "avg"). TSM will fire two sub-queries —
	//     a "sum" variant and a "count" variant — and divide after gathering.
	//   - warning: non-empty when the aggregator cannot be correctly merged
	//     across fanout shards (e.g. stddev, quantile). TSM will fall back to
	//     deduplication and surface this warning in the response.
	ClassifyMerge(query string) (strategy int, needsDualQuery bool, warning string)

	// RewriteForWeightedAvg returns two modified copies of r — one with the
	// outer aggregator replaced by its "sum" equivalent and one by its "count"
	// equivalent. Both copies have the replacement injected in whatever way the
	// provider's wire protocol requires (URL query parameter, POST body, header,
	// etc.). The returned requests must be safe for concurrent use; they should
	// not share any mutable state with each other or with r.
	RewriteForWeightedAvg(r *http.Request, query string) (sumReq, countReq *http.Request)
}

type TimeseriesBackend interface {
	// RegisterHandlers registers the provided Handlers into the Router
	RegisterHandlers(handlers.Lookup)
	// Handlers returns a map of the HTTP Handlers the Backend has registered
	Handlers() handlers.Lookup
	// DefaultPathConfigs returns the default PathConfigs for the given Provider
	DefaultPathConfigs(*bo.Options) po.List
	// ParseTimeRangeQuery returns a timeseries.TimeRangeQuery based on the provided HTTP Request
	ParseTimeRangeQuery(*http.Request) (*timeseries.TimeRangeQuery, *timeseries.RequestOptions, bool, error)
	// Configuration returns the configuration for the Backend
	Configuration() *bo.Options
	// Name returns the name of the Backend
	Name() string
	// FastForwardRequest returns an *http.Request crafted to collect Fast Forward data
	// from the Origin, based on the provided HTTP Request. If the inbound request is
	// POST/PUT/PATCH, a Content-Type header and non-nil body with the query parameters
	// must be set, in lieu of updated url query values, in the returned request
	FastForwardRequest(*http.Request) (*http.Request, error)
	// SetExtent will update an upstream request's timerange
	// parameters based on the provided timeseries.Extent
	SetExtent(*http.Request, *timeseries.TimeRangeQuery, *timeseries.Extent)
	// HTTPClient will return the HTTP Client for this Backend
	HTTPClient() *http.Client
	// SetCache sets the Cache object the Backend will use when caching origin content
	SetCache(cache.Cache)
	// Cache returns a handle to the Cache object used by the Backend
	Cache() cache.Cache
	// Router returns a Router that handles HTTP Requests for this Backend
	Router() http.Handler
	// BaseUpstreamURL returns the base URL for upstream requests
	BaseUpstreamURL() *url.URL
	// Modeler returns the Modeler for converting between DataSets and wire documents
	Modeler() *timeseries.Modeler
	// DefaultHealthCheckConfig returns the default HealthCHeck Config for the given Provider
	DefaultHealthCheckConfig() *ho.Options
	// SetHealthCheckProbe sets the Health Check Status Prober for the Client
	SetHealthCheckProbe(healthcheck.DemandProbe)
	// HealthHandler executes a Health Check Probe when called
	HealthHandler(http.ResponseWriter, *http.Request)
	// HealthCheckHTTPClient returns the HTTP Client used for Health Checking
	HealthCheckHTTPClient() *http.Client
	// ProcessTransformations executes any provider-specific transformations, like injecting
	// labels into the dataset
	ProcessTransformations(timeseries.Timeseries)
}