api

Documentation

Index

• Variables
• func APIErrToGRPC(err error) error
• func AddRBACSuffix() string
• func AsErrNotFound(msg string, args ...interface{}) error
• func AsValidationError(msg string, args ...interface{}) error
• func BindArgs(i interface{}, c echo.Context) error
• func BindPatch(i interface{}, c echo.Context) error
• func CORSWithTargetedOrigin(next echo.HandlerFunc) echo.HandlerFunc
• func EchoErrToGRPC(err error) (bool, error)
• func EffectiveLimit(limit int, offset int, total int) int
• func EffectiveOffset(reqOffset int, total int) (offset int)
• func EffectiveOffsetNLimit(reqOffset int, reqLimit int, totalItems int) (offset int, limit int)
• func GrpcErrToEcho(err error) (bool, error)
• func JSONErrorHandler(err error, c echo.Context)
• func NotFoundErrMsg(name string, id string) string
• func NotFoundErrs(name string, id string, statusErr bool) error
• func Paginate(p **apiv1.Pagination, values interface{}, offset, limit int32) error
• func Route(handler func(c echo.Context) (interface{}, error)) echo.HandlerFunc
• func Sort(slice interface{}, order apiv1.OrderBy, keys ...interface{})
• func WebSocketRoute(handler func(socket *websocket.Conn, c echo.Context) error) echo.HandlerFunc
• func Where(values interface{}, check func(int) bool)
• func WrapWithFallbackCode(err error, code codes.Code, msg string) error
• type Batch
• type BatchOfOne
  • func ToBatchOfOne(x interface{}) BatchOfOne
  • func (l BatchOfOne) ForEach(f func(interface{}) error) error
  • func (l BatchOfOne) Size() int
• type BatchRequest
• type BatchResult
  • func ErrBatchResult(err error) BatchResult
  • func OkBatchResult(b Batch) BatchResult
  • func (r *BatchResult) Batch() Batch
  • func (r *BatchResult) Err() error
• type BatchStreamProcessor
  • func NewBatchStreamProcessor(req BatchRequest, fetcher FetchBatchFn, terminateCheck TerminationCheckFn, ...) *BatchStreamProcessor
  • func (p *BatchStreamProcessor) Run(ctx context.Context, res chan BatchResult)
• type FetchBatchFn
• type Filter
• type FilterOperation
• type MaybeInt
  • func (i *MaybeInt) UnmarshalJSON(data []byte) error
• type OnBatchFn
• type Pagination
  • func CalculatePagination(total, offset, limit int) (*Pagination, error)
• type TerminationCheckFn

Variables

var (
	// ErrInvalid is the inner error for errors that convert to a 400. Currently
	// only apiServer.askAtDefaultSystem respects this.
	ErrInvalid = errors.New("invalid arguments")
	// ErrNotFound is the inner error for errors that convert to a 404.
	ErrNotFound = errors.New("not found")
	// ErrNotImplemented is the inner error for errors that convert to a 501.
	ErrNotImplemented = errors.New("not implemented")

	// ErrAPIRemoved is an error to inform the client they are calling an old, removed API.
	ErrAPIRemoved = errors.New(`the API being called was removed,
please ensure the client consuming the API is up to date and report a bug if the problem persists`)
)

Functions

func APIErrToGRPC

func APIErrToGRPC(err error) error

APIErrToGRPC converts internal api error categories into grpc status.Errors.

func AddRBACSuffix

func AddRBACSuffix() string

AddRBACSuffix adds a "check your permission" string to errors if RBAC is enabled. This suffix is applied to any endpoint that can be limited by RBAC, specifically 404 errors and should not expose that the entity exists.

func AsErrNotFound

func AsErrNotFound(msg string, args ...interface{}) error

AsErrNotFound returns an error that wraps ErrNotFound, so that errors.Is can identify it.

func AsValidationError

func AsValidationError(msg string, args ...interface{}) error

AsValidationError returns an error that wraps ErrInvalid, so that errors.Is can identify it.

func BindArgs

func BindArgs(i interface{}, c echo.Context) error

BindArgs binds path and query parameters in the context to struct fields.

func BindPatch

func BindPatch(i interface{}, c echo.Context) error

BindPatch binds the request body of PATCH requests to the provided interface.

func CORSWithTargetedOrigin

func CORSWithTargetedOrigin(next echo.HandlerFunc) echo.HandlerFunc

CORSWithTargetedOrigin builds on labstack/echo CORS by dynamically setting the origin header to the request's origin.

func EchoErrToGRPC

func EchoErrToGRPC(err error) (bool, error)

EchoErrToGRPC converts internal api error categories into grpc status.Errors.

func EffectiveLimit

func EffectiveLimit(limit int, offset int, total int) int

EffectiveLimit computes a hard limit based on the offset and total available items if there is a limit set. Input: non-negative offset.

func EffectiveOffset

func EffectiveOffset(reqOffset int, total int) (offset int)

EffectiveOffset translated negative offsets into positive ones.

func EffectiveOffsetNLimit

func EffectiveOffsetNLimit(reqOffset int, reqLimit int, totalItems int) (offset int, limit int)

EffectiveOffsetNLimit chains EffectiveOffset and EffectiveLimit together.

func GrpcErrToEcho

func GrpcErrToEcho(err error) (bool, error)

GrpcErrToEcho converts grpc status.Errors into internal api error categories.

func JSONErrorHandler

func JSONErrorHandler(err error, c echo.Context)

JSONErrorHandler sends a JSON response with a single "message" key containing the error message.

func NotFoundErrMsg

func NotFoundErrMsg(name string, id string) string

NotFoundErrMsg creates a formatted message about a resource not being found.

func NotFoundErrs

func NotFoundErrs(name string, id string, statusErr bool) error

NotFoundErrs is a wrapper function to create status.Errors with an informative message as to what category of error (NotFound), the name (trial/task/workspace etc) & the specific ID is. The statusErr bool returns a status.Error if true, or a NewHTTPError if false..

func Paginate

func Paginate(
	p **apiv1.Pagination,
	values interface{},
	offset, limit int32,
) error

Paginate returns a paginated subset of the values and sets the pagination response.

func Route

func Route(handler func(c echo.Context) (interface{}, error)) echo.HandlerFunc

Route returns an echo compatible handler for JSON requests.

func Sort

func Sort(
	slice interface{}, order apiv1.OrderBy, keys ...interface{},
)

Sort sorts the provided slice in place. The second parameter denotes whether sorting should be in ascending or descending order. All following parameters are the sort keys. Sort keys must be the same value as the field number that must be sorted.

func WebSocketRoute

func WebSocketRoute(handler func(socket *websocket.Conn, c echo.Context) error) echo.HandlerFunc

WebSocketRoute upgrades incoming requests to websocket requests.

func Where

func Where(values interface{}, check func(int) bool)

Where filters in place the provide reference to the slice. The check function is given an index of the current element it will check to filter. Returning false will remove the element from the slice.

func WrapWithFallbackCode

func WrapWithFallbackCode(err error, code codes.Code, msg string) error

WrapWithFallbackCode prepares errors for returning to the client by providing a fallback code and more context.

Types

type Batch

type Batch interface {
	ForEach(func(interface{}) error) error
	Size() int
}

Batch represents a batch of logs.

type BatchOfOne

type BatchOfOne struct {
	Inner interface{}
}

BatchOfOne is a wrapper for a single log that implements Batch.

func ToBatchOfOne

func ToBatchOfOne(x interface{}) BatchOfOne

ToBatchOfOne wraps a single entry as a BatchOfOne that implements Batch.

func (BatchOfOne) ForEach

func (l BatchOfOne) ForEach(f func(interface{}) error) error

ForEach implements Batch.

func (BatchOfOne) Size

func (l BatchOfOne) Size() int

Size implements Batch.

type BatchRequest

type BatchRequest struct {
	Offset int
	Limit  int
	Follow bool
}

BatchRequest describes the parameters needed to target a subset of logs.

type BatchResult

type BatchResult struct {
	// contains filtered or unexported fields
}

BatchResult contains either a batch or an error.

func ErrBatchResult

func ErrBatchResult(err error) BatchResult

ErrBatchResult returns a BatchResult with an error and no batch.

func OkBatchResult

func OkBatchResult(b Batch) BatchResult

OkBatchResult returns a BatchResult with a valid batch and nil error.

func (*BatchResult) Batch

func (r *BatchResult) Batch() Batch

Batch returns the inner batch or nil.

func (*BatchResult) Err

func (r *BatchResult) Err() error

Err returns the inner error or nil.

type BatchStreamProcessor

type BatchStreamProcessor struct {
	// contains filtered or unexported fields
}

BatchStreamProcessor is an actor that fetches batches and processes them. It handles common logic around limits, offsets and backpressure.

The type of batches produced by the FetchBatchFn must match those handled by the OnBatchFn or the actor will panic.

func NewBatchStreamProcessor

func NewBatchStreamProcessor(
	req BatchRequest,
	fetcher FetchBatchFn,
	terminateCheck TerminationCheckFn,
	alwaysCheckTermination bool,
	batchWaitTime *time.Duration,
	batchMissWaitTime *time.Duration,
) *BatchStreamProcessor

NewBatchStreamProcessor creates a new BatchStreamProcessor.

func (*BatchStreamProcessor) Run

func (p *BatchStreamProcessor) Run(ctx context.Context, res chan BatchResult)

Run runs the batch stream processor. There is an implicit assumption upstream that errors won't be sent forever, so after encountering an error in Run, we should log and continue or send and return.

type FetchBatchFn

type FetchBatchFn func(BatchRequest) (Batch, error)

FetchBatchFn fetches returns a batch.

type Filter

type Filter struct {
	Field     string
	Operation FilterOperation
	Values    interface{}
}

Filter is a general representation for a filter provided to an API.

type FilterOperation

type FilterOperation int

FilterOperation is an operation in a filter.

const (
	// FilterOperationIn checks set membership.
	FilterOperationIn FilterOperation = iota
	// FilterOperationInOrNull checks membership or a NULL option.
	FilterOperationInOrNull
	// FilterOperationGreaterThan checks if the field is greater than a value.
	FilterOperationGreaterThan
	// FilterOperationLessThanEqual checks if the field is less than or equal to a value.
	FilterOperationLessThanEqual
	// FilterOperationStringContainment checks if the field contains a value as a substring.
	FilterOperationStringContainment
)

type MaybeInt

type MaybeInt struct {
	IsPresent bool
	Value     *int
}

MaybeInt allows JSON users to distinguish between absent and null values. It should be used as a non-pointer value in structs. After unmarshaling, IsPresent will be true if the corresponding key is present, whether or not the value is null; Value will be nil or not, depending on the value.

Based on: https://www.calhoun.io/how-to-determine-if-a-json-key-has-been-set-to-null-or-not-provided/

func (*MaybeInt) UnmarshalJSON

func (i *MaybeInt) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the given data, which should be an integer or null.

type OnBatchFn

type OnBatchFn func(Batch) error

OnBatchFn is a callback called on each batch.

type Pagination

type Pagination struct {
	StartIndex int // Inclusive
	EndIndex   int // Exclusive
}

Pagination contains resolved pagination indices.

func CalculatePagination

func CalculatePagination(total, offset, limit int) (*Pagination, error)

CalculatePagination calculates pagination values. Negative offsets denotes that offsets should be calculated from the end. Input offset: the number of entries you wish to skip.

type TerminationCheckFn

type TerminationCheckFn func() (bool, error)

TerminationCheckFn checks whether the log processing should stop or not.