api

Documentation

Index

• Constants
• Variables
• func ExtractSchemeAddr(addr string) (scheme string, address string)
• func ExtractUnixSocket(addr string) (socketFile string)
• func GetHealthHandler() func(context.Context, *struct{}) (*GetHealthOutput, error)
• func GetHealthOperation() huma.Operation
• func GetInfoOperation() huma.Operation
• func GetReadyHandler() func(context.Context, *struct{}) (*GetReadyOutput, error)
• func GetReadyOperation() huma.Operation
• func GetServiceInfoHandler(serviceName string) func(context.Context, *struct{}) (*GetInfoOutput, error)
• func OnKeepalive(send sse.Sender) error
• func OnResult(res *results.Result, send sse.Sender) error
• func RateLimitMiddleware(limiter *rate.Limiter) func(ctx huma.Context, next func(huma.Context))
• func RecursionDetectorMiddleware(headerKey, match string) gin.HandlerFunc
• func RegisterProfiling(router *gin.Engine)
• func RegisterQueryAPI(a huma.API, caller string, querier query.Runner, middlewares huma.Middlewares)
• func RequestLoggingMiddleware() gin.HandlerFunc
• func TraceIDMiddleware() gin.HandlerFunc
• type ArgsInput
• type ArgsParamsInput
• type FinalResult
• type GetHealthOutput
• type GetInfoOutput
• type GetReadyOutput
• type Keepalive
• type PartialResult
• type QueryResultOutput
• type SSEQueryRunner
• type ServiceInfo
• type StreamEventType

Constants

const (

	// HealthRoute denotes the route / URI path to the health endpoint
	HealthRoute = infoPrefix + "/health"
	// InfoRoute denotes the route / URI path to the info endpoint
	InfoRoute = infoPrefix + "/info"
	// ReadyRoute denotes the route / URI path to the ready endpoint
	ReadyRoute = infoPrefix + "/ready"
)

const (
	// QueryRoute is the route to run a goquery query
	QueryRoute = "/_query"

	// ValidationRoute is the route to validate a goquery query
	ValidationRoute = QueryRoute + "/validate"

	// SSEQueryRoute runs a goquery query with a return channel for partial results
	SSEQueryRoute = QueryRoute + "/sse"
)

Variables

var (
	// ErrTooManyConcurrentRequest denotes that the number of concurrent queries
	// has been exhausted
	ErrTooManyConcurrentRequest = errors.New("too many concurrent requests")
)

Functions

func ExtractSchemeAddr

func ExtractSchemeAddr(addr string) (scheme string, address string)

ExtractSchemeAddr extracts the scheme from the address if it is present and returns the trimmed address with it. If not scheme match is found, scheme is empty and the input to the function will be returned in address

func ExtractUnixSocket

func ExtractUnixSocket(addr string) (socketFile string)

ExtractUnixSocket determines whether the provided address contains a unix: prefix. If so, it will treat the remainder as the path to the socket

func GetHealthHandler

func GetHealthHandler() func(context.Context, *struct{}) (*GetHealthOutput, error)

GetHealthHandler returns a handler that returns the application readiness state

func GetHealthOperation

func GetHealthOperation() huma.Operation

GetHealthOperation is the operation for getting the health of the app

func GetInfoOperation

func GetInfoOperation() huma.Operation

GetInfoOperation is the operation for getting a greeting.

func GetReadyHandler

func GetReadyHandler() func(context.Context, *struct{}) (*GetReadyOutput, error)

GetReadyHandler returns a handler that returns the application readiness state

func GetReadyOperation

func GetReadyOperation() huma.Operation

GetReadyOperation is the operation for getting the ready state

func GetServiceInfoHandler

func GetServiceInfoHandler(serviceName string) func(context.Context, *struct{}) (*GetInfoOutput, error)

GetServiceInfoHandler returns a huma compatible handler that returns the service name, version, and commit

func OnKeepalive

func OnKeepalive(send sse.Sender) error

OnResultFn is a generic handler / function that sends a keepalive signal via an SSE sender to the client(s)

func OnResult

func OnResult(res *results.Result, send sse.Sender) error

OnResult is a generic handler / function that sends a result via an SSE sender to the client(s)

func RateLimitMiddleware

func RateLimitMiddleware(limiter *rate.Limiter) func(ctx huma.Context, next func(huma.Context))

RateLimitMiddleware creates a global rate limit for all requests, using a maximum of r requests per second and a maximum burst rate of b tokens

func RecursionDetectorMiddleware

func RecursionDetectorMiddleware(headerKey, match string) gin.HandlerFunc

RecursionDetectorMiddleware provides a means to avoid having a distributed querier query itself into oblivion

func RegisterProfiling

func RegisterProfiling(router *gin.Engine)

RegisterProfiling registers the profiling middleware

func RegisterQueryAPI

func RegisterQueryAPI(a huma.API, caller string, querier query.Runner, middlewares huma.Middlewares)

RegisterQueryAPI registers all query related endpoints

func RequestLoggingMiddleware

func RequestLoggingMiddleware() gin.HandlerFunc

RequestLoggingMiddleware logs all requests received via the including hander chain

func TraceIDMiddleware

func TraceIDMiddleware() gin.HandlerFunc

TraceIDMiddleware injects a context into a request managed by [go-gin](https://github.com/gin-gonic/gin) from which logger/traces can be derived

Types

type ArgsInput

type ArgsInput struct {
	Body *query.Args
}

ArgsBodyInput stores the query args to be validated in the body

type ArgsParamsInput

type ArgsParamsInput struct {
	// for get parameters
	query.Args
	query.DNSResolution
}

ArgsParamsInput stores the query args to be validated in the query parameters

type FinalResult

type FinalResult struct{ *results.Result }

FinalResult represents the result which is sent after all aggregation of partial results has completed. It SHOULD only be sent at the end of a streaming operation. This data structure is relevant only in the context of SSE

type GetHealthOutput

type GetHealthOutput struct {
	Body struct {
		Status string `json:"status" doc:"Health status of application" example:"healthy"`
	}
}

HealthOutput returns the output of the health command

type GetInfoOutput

type GetInfoOutput struct {
	Body struct {
		*ServiceInfo
	}
}

GetInfoOutput is the output of the info request

type GetReadyOutput

type GetReadyOutput struct {
	Body struct {
		Status string `json:"status" doc:"Ready status of application" example:"ready"`
	}
}

GetReadyOutput returns the output of the ready command

type Keepalive

type Keepalive struct{}

Keepalive represents an keeplive signal. This data structure is relevant only in the context of SSE

type PartialResult

type PartialResult struct{ *results.Result }

PartialResult represents an update to the results structure. It SHOULD only be used if the results.Result object will be further modified / aggregated. This data structure is relevant only in the context of SSE

type QueryResultOutput

type QueryResultOutput struct {
	Body *results.Result
}

QueryResultOutput stores the result of a query

type SSEQueryRunner

type SSEQueryRunner interface {
	// RunStreaming takes a query statement, executes the underlying query and returns the result(s)
	// while sending partial results to the sse.Sender
	RunStreaming(ctx context.Context, args *query.Args, send sse.Sender) (*results.Result, error)

	query.Runner
}

SSEQueryRunner defines any query runner that supports partial results / SSE

type ServiceInfo

type ServiceInfo struct {
	Name    string `json:"name" doc:"Service name" example:"global-query"`                                                // Name: service name
	Version string `json:"version" doc:"Service (semantic) version" example:"4.0.0-824f5847"`                             // Version: (semantic) version and commit short
	Commit  string `json:"commit,omitempty" doc:"Full git commit SHA" example:"824f58479a8f326cb350085b3a0e287645e11bc1"` // Commit: full git commit SHA
	Pod     string `json:"pod,omitempty" doc:"Name of kubernetes pod (if available)"`                                     // Pod: name of kubernetes pod, if available
}

ServiceInfo summarizes the running service's name, version, and commit. If running in kubernetes, it will also print the name of the pod which returned the API call

type StreamEventType

type StreamEventType string

StreamEventType describes the type of server sent event

const (
	StreamEventQueryError    StreamEventType = "queryError"
	StreamEventPartialResult StreamEventType = "partialResult"
	StreamEventFinalResult   StreamEventType = "finalResult"
	StreamEventKeepalive     StreamEventType = "keepalive"
)

Different event types that the query server sends