ffapi

package
v1.5.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 3, 2025 License: Apache-2.0 Imports: 36 Imported by: 12

Documentation

Index

Constants

View Source 
const APIServerMetricsSubSystemName = "api_server_rest"
View Source 
const DefaultRequestIDHeader = "X-FireFly-Request-ID"

Variables

View Source 
var (
	ConfMonitoringServerEnabled      = "enabled"
	ConfMonitoringServerMetricsPath  = "metricsPath"
	ConfMonitoringServerLivenessPath = "livenessPath"

	ConfAPIDefaultFilterLimit     = "defaultFilterLimit"
	ConfAPIMaxFilterLimit         = "maxFilterLimit"
	ConfAPIMaxFilterSkip          = "maxFilterSkip"
	ConfAPIRequestTimeout         = "requestTimeout"
	ConfAPIRequestMaxTimeout      = "requestMaxTimeout"
	ConfAPIAlwaysPaginate         = "alwaysPaginate"
	ConfAPIDynamicPublicURLHeader = "dynamicPublicURLHeader"
)

Functions

func CalcRequestTimeout added in v1.2.11 

func CalcRequestTimeout(req *http.Request, defaultTimeout, maxTimeout time.Duration) time.Duration

func CheckObjectDocumented added in v1.4.0 

func CheckObjectDocumented(example interface{})

CheckObjectDocumented lets unit tests on individual structures validate that all the ffstruct tags are set, without having to build their own swagger.

func InitAPIServerConfig added in v1.2.8 

func InitAPIServerConfig(apiConfig, monitoringConfig, corsConfig config.Section)

func RequestIDHeader added in v1.5.0 

func RequestIDHeader() string

RequestIDHeader returns the header name used to pass the request ID for ffapi server and ffresty client requests.

func SetRequestIDHeader added in v1.5.0 

func SetRequestIDHeader(header string)

SetRequestIDHeader configures the header used to pass the request ID between ffapi server and ffresty client requests. Should be set at initialization of a process.

func ValueString added in v1.1.5 

func ValueString(f FieldSerialization) string

Types

type APIRequest 

type APIRequest struct {
	Req             *http.Request
	QP              map[string]string
	QAP             map[string][]string
	PP              map[string]string
	FP              map[string]string
	Filter          AndFilter
	Input           interface{}
	Part            *Multipart
	SuccessStatus   int
	ResponseHeaders http.Header
	AlwaysPaginate  bool
}

func (*APIRequest) FilterResult added in v1.1.5 

func (r *APIRequest) FilterResult(items interface{}, res *FilterResult, err error) (interface{}, error)

Encourage consideration for new APIs of using ItemsResult() - generic and documented, and always returns the same output for all queries FilterResult is a helper to transform a filter result into a REST API standard payload

type APIServer added in v1.2.8 

type APIServer interface {
	Serve(ctx context.Context) error
	Started() <-chan struct{}
	MuxRouter(ctx context.Context) (*mux.Router, error)
	APIPublicURL() string // valid to call after server is successfully started
}

APIServer is an opinionated use of the HTTP Server facilities in common, to provide an API server with: - a set of routes defining API endpoints - a swagger endpoint on /api - optional metrics endpoint on /metrics (configurable)

func NewAPIServer added in v1.2.8 

func NewAPIServer[T any](ctx context.Context, options APIServerOptions[T]) APIServer

NewAPIServer makes a new server, with the specified configuration, and the supplied wrapper function - which will inject

type APIServerOptions added in v1.2.8 

type APIServerOptions[T any] struct {
	MetricsRegistry           metric.MetricsRegistry
	MetricsSubsystemName      string
	Routes                    []*Route // move to use VersionedAPIs for support of Tags and ExternalDocs
	VersionedAPIs             *VersionedAPIs
	MonitoringRoutes          []*Route
	EnrichRequest             func(r *APIRequest) (T, error)
	Description               string
	APIConfig                 config.Section
	MonitoringConfig          config.Section
	CORSConfig                config.Section
	FavIcon16                 []byte
	FavIcon32                 []byte
	PanicOnMissingDescription bool
	SupportFieldRedaction     bool
	HandleYAML                bool
}

type APIServerRouteExt added in v1.2.8 

type APIServerRouteExt[T any] struct {
	JSONHandler   func(*APIRequest, T) (output interface{}, err error)
	UploadHandler func(*APIRequest, T) (output interface{}, err error)
	StreamHandler func(*APIRequest, T) (output io.ReadCloser, err error)
}

type APIVersion added in v1.5.2 

type APIVersion struct {
	Routes       []*Route               // the routes
	Tags         openapi3.Tags          // (OPTIONAL) description and external documentation of tags used in the routes, all tags in this array will need to be used by at least one of routes
	ExternalDocs *openapi3.ExternalDocs // (OPTIONAL) external documentation of this API version
}

APIVersion defines a version of the API it contains a list of routes and associated metadata for the OpenAPI spec generation

type AndFilter added in v1.1.5 

type AndFilter interface{ MultiConditionFilter }

type BaseURLVariable added in v1.3.0 

type BaseURLVariable struct {
	Default     string
	Description string
}

type BigIntField added in v1.2.8 

type BigIntField struct{}

func (*BigIntField) Description added in v1.2.8 

func (f *BigIntField) Description() string

func (*BigIntField) FilterAsString added in v1.2.8 

func (f *BigIntField) FilterAsString() bool

func (*BigIntField) GetSerialization added in v1.2.8 

func (f *BigIntField) GetSerialization() FieldSerialization

type BoolField added in v1.1.5 

type BoolField struct{}

func (*BoolField) Description added in v1.1.5 

func (f *BoolField) Description() string

func (*BoolField) FilterAsString added in v1.1.5 

func (f *BoolField) FilterAsString() bool

func (*BoolField) GetSerialization added in v1.1.5 

func (f *BoolField) GetSerialization() FieldSerialization

type Bytes32Field added in v1.1.5 

type Bytes32Field struct{}

func (*Bytes32Field) Description added in v1.1.5 

func (f *Bytes32Field) Description() string

func (*Bytes32Field) FilterAsString added in v1.1.5 

func (f *Bytes32Field) FilterAsString() bool

func (*Bytes32Field) GetSerialization added in v1.1.5 

func (f *Bytes32Field) GetSerialization() FieldSerialization

type CtxFFRequestIDKey added in v1.2.0 

type CtxFFRequestIDKey struct{}

type CtxHeadersKey added in v1.2.0 

type CtxHeadersKey struct{}

type FFStringArrayField added in v1.1.5 

type FFStringArrayField struct{}

func (*FFStringArrayField) Description added in v1.1.5 

func (f *FFStringArrayField) Description() string

func (*FFStringArrayField) FilterAsString added in v1.1.5 

func (f *FFStringArrayField) FilterAsString() bool

func (*FFStringArrayField) GetSerialization added in v1.1.5 

func (f *FFStringArrayField) GetSerialization() FieldSerialization

type Field added in v1.1.5 

type Field interface {
	GetSerialization() FieldSerialization
	Description() string
	FilterAsString() bool
}

type FieldMod added in v1.3.0 

type FieldMod int
const (
	FieldModLower FieldMod = iota
)

type FieldResolverFn added in v1.5.6 

type FieldResolverFn func(ctx context.Context, fieldName string) (resolvedFieldName string, err error)

type FieldSerialization added in v1.1.5 

type FieldSerialization interface {
	driver.Valuer
	sql.Scanner // Implementations can assume the value is ALWAYS a string
}

FieldSerialization - we stand on the shoulders of the well adopted SQL serialization interface here to help us define what string<->value looks like, even though this plugin interface is not tightly coupled to SQL.

type Filter added in v1.1.5 

type Filter interface {
	FilterModifiers[Filter]

	// Finalize completes the filter, and for the plugin to validated output structure to convert
	Finalize() (*FilterInfo, error)

	// Builder returns the builder that made it
	Builder() FilterBuilder

	// Assert that this is a value filter, not an and/or
	ValueFilter() ValueFilter
}

Filter is the output of the builder

func ParseFilterParam added in v1.4.0 

func ParseFilterParam(ctx context.Context, fb FilterBuilder, field string, values []string) (Filter, error)

type FilterBuilder added in v1.1.5 

type FilterBuilder interface {
	FilterModifiers[FilterBuilder]

	// Fields is the list of available fields
	Fields() []string
	// And requires all sub-filters to match
	And(and ...Filter) AndFilter
	// Or requires any of the sub-filters to match
	Or(and ...Filter) OrFilter
	// Eq equal - case sensitive
	Eq(name string, value driver.Value) Filter
	// Neq not equal - case sensitive
	Neq(name string, value driver.Value) Filter
	// IEq equal - case insensitive
	IEq(name string, value driver.Value) Filter
	// INeq not equal - case insensitive
	NIeq(name string, value driver.Value) Filter
	// In one of an array of values
	In(name string, value []driver.Value) Filter
	// NotIn not one of an array of values
	NotIn(name string, value []driver.Value) Filter
	// Lt less than
	Lt(name string, value driver.Value) Filter
	// Gt greater than
	Gt(name string, value driver.Value) Filter
	// Gte greater than or equal
	Gte(name string, value driver.Value) Filter
	// Lte less than or equal
	Lte(name string, value driver.Value) Filter
	// Contains allows the string anywhere - case sensitive
	Contains(name string, value driver.Value) Filter
	// NotContains disallows the string anywhere - case sensitive
	NotContains(name string, value driver.Value) Filter
	// IContains allows the string anywhere - case insensitive
	IContains(name string, value driver.Value) Filter
	// INotContains disallows the string anywhere - case insensitive
	NotIContains(name string, value driver.Value) Filter
	// StartsWith allows the string at the start - case sensitive
	StartsWith(name string, value driver.Value) Filter
	// NotStartsWith disallows the string at the start - case sensitive
	NotStartsWith(name string, value driver.Value) Filter
	// IStartsWith allows the string at the start - case insensitive
	IStartsWith(name string, value driver.Value) Filter
	// NotIStartsWith disallows the string att the start - case insensitive
	NotIStartsWith(name string, value driver.Value) Filter
	// EndsWith allows the string at the end - case sensitive
	EndsWith(name string, value driver.Value) Filter
	// NotEndsWith disallows the string at the end - case sensitive
	NotEndsWith(name string, value driver.Value) Filter
	// IEndsWith allows the string at the end - case insensitive
	IEndsWith(name string, value driver.Value) Filter
	// NotIEndsWith disallows the string att the end - case insensitive
	NotIEndsWith(name string, value driver.Value) Filter
}

FilterBuilder is the syntax used to build the filter, where And() and Or() can be nested

type FilterInfo added in v1.1.5 

type FilterInfo struct {
	GroupBy        []string
	RequiredFields []string
	Sort           []*SortField
	Skip           uint64
	Limit          uint64
	Count          bool
	CountExpr      string
	Field          string
	FieldMods      []FieldMod
	Op             FilterOp
	Values         []FieldSerialization
	Value          FieldSerialization
	Children       []*FilterInfo
}

FilterInfo is the structure returned by Finalize to the plugin, to serialize this filter into the underlying database mechanism's filter language

func (*FilterInfo) String added in v1.1.5 

func (f *FilterInfo) String() string

type FilterJSON added in v1.4.1 

type FilterJSON struct {
	Or []*FilterJSON `ffstruct:"FilterJSON" json:"or,omitempty"`
	FilterJSONOps
}

func (*FilterJSON) BuildAndFilter added in v1.4.6 

func (jf *FilterJSON) BuildAndFilter(ctx context.Context, fb FilterBuilder, options ...*JSONBuildFilterOpt) (AndFilter, error)

func (*FilterJSON) BuildSubFilter added in v1.4.6 

func (jf *FilterJSON) BuildSubFilter(ctx context.Context, fb FilterBuilder, options ...*JSONBuildFilterOpt) (Filter, error)

type FilterJSONBase added in v1.4.1 

type FilterJSONBase struct {
	Not             bool   `ffstruct:"FilterJSON" json:"not,omitempty"`
	CaseInsensitive bool   `ffstruct:"FilterJSON" json:"caseInsensitive,omitempty"`
	Field           string `ffstruct:"FilterJSON" json:"field,omitempty"`
}

type FilterJSONKeyValue added in v1.4.1 

type FilterJSONKeyValue struct {
	FilterJSONBase
	Value SimpleFilterValue `ffstruct:"FilterJSON" json:"value,omitempty"`
}

type FilterJSONKeyValues added in v1.4.1 

type FilterJSONKeyValues struct {
	FilterJSONBase
	Values []SimpleFilterValue `ffstruct:"FilterJSON" json:"values,omitempty"`
}

type FilterJSONOps added in v1.4.6 

type FilterJSONOps struct {
	Equal              []*FilterJSONKeyValue  `ffstruct:"FilterJSON" json:"equal,omitempty"`
	Eq                 []*FilterJSONKeyValue  `ffstruct:"FilterJSON" json:"eq,omitempty"`  // short name
	NEq                []*FilterJSONKeyValue  `ffstruct:"FilterJSON" json:"neq,omitempty"` // negated short name
	Contains           []*FilterJSONKeyValue  `ffstruct:"FilterJSON" json:"contains,omitempty"`
	StartsWith         []*FilterJSONKeyValue  `ffstruct:"FilterJSON" json:"startsWith,omitempty"`
	EndsWith           []*FilterJSONKeyValue  `ffstruct:"FilterJSON" json:"endsWith,omitempty"`
	LessThan           []*FilterJSONKeyValue  `ffstruct:"FilterJSON" json:"lessThan,omitempty"`
	LT                 []*FilterJSONKeyValue  `ffstruct:"FilterJSON" json:"lt,omitempty"` // short name
	LessThanOrEqual    []*FilterJSONKeyValue  `ffstruct:"FilterJSON" json:"lessThanOrEqual,omitempty"`
	LTE                []*FilterJSONKeyValue  `ffstruct:"FilterJSON" json:"lte,omitempty"` // short name
	GreaterThan        []*FilterJSONKeyValue  `ffstruct:"FilterJSON" json:"greaterThan,omitempty"`
	GT                 []*FilterJSONKeyValue  `ffstruct:"FilterJSON" json:"gt,omitempty"` // short name
	GreaterThanOrEqual []*FilterJSONKeyValue  `ffstruct:"FilterJSON" json:"greaterThanOrEqual,omitempty"`
	GTE                []*FilterJSONKeyValue  `ffstruct:"FilterJSON" json:"gte,omitempty"` // short name
	In                 []*FilterJSONKeyValues `ffstruct:"FilterJSON" json:"in,omitempty"`
	NIn                []*FilterJSONKeyValues `ffstruct:"FilterJSON" json:"nin,omitempty"` // negated short name
	Null               []*FilterJSONBase      `ffstruct:"FilterJSON" json:"null,omitempty"`
}

type FilterModifiers added in v1.2.19 

type FilterModifiers[T any] interface {
	// Sort adds a set of sort conditions (all in a single sort order)
	Sort(...string) T

	// GroupBy adds a set of fields to group rows that have the same values into summary rows. Not assured every persistence implementation will support this (doc DBs cannot)
	GroupBy(...string) T

	// Ascending sort order
	Ascending() T

	// Descending sort order
	Descending() T

	// Skip for pagination
	Skip(uint64) T

	// Limit for pagination
	Limit(uint64) T

	// Request a count to be returned on the total number that match the query
	Count(c bool) T

	// Which fields we require to be returned. Only supported when using CRUD layer on top of underlying DB.
	// Might allow optimization of the query (in the case of SQL DBs, where it can be combined with GroupBy), or request post-query redaction (in the case of document DBs).
	RequiredFields(...string) T
}

type FilterOp added in v1.1.5 

type FilterOp string

FilterOp enum of filter operations that must be implemented by plugins - the string value is used in the core string formatting method (for logging etc.) 

const (
	// FilterOpAnd and
	FilterOpAnd FilterOp = "&&"
	// FilterOpOr or
	FilterOpOr FilterOp = "||"
	// FilterOpEq equal
	FilterOpEq FilterOp = "=="
	// FilterOpIEq equal
	FilterOpIEq FilterOp = ":="
	// FilterOpNe not equal
	FilterOpNeq FilterOp = "!="
	// FilterOpNIeq not equal
	FilterOpNIeq FilterOp = ";="
	// FilterOpIn in list of values
	FilterOpIn FilterOp = "IN"
	// FilterOpNotIn not in list of values
	FilterOpNotIn FilterOp = "NI"
	// FilterOpGt greater than
	FilterOpGt FilterOp = ">>"
	// FilterOpLt less than
	FilterOpLt FilterOp = "<<"
	// FilterOpGte greater than or equal
	FilterOpGte FilterOp = ">="
	// FilterOpLte less than or equal
	FilterOpLte FilterOp = "<="
	// FilterOpCont contains the specified text, case sensitive
	FilterOpCont FilterOp = "%="
	// FilterOpNotCont does not contain the specified text, case sensitive
	FilterOpNotCont FilterOp = "!%"
	// FilterOpICont contains the specified text, case insensitive
	FilterOpICont FilterOp = ":%"
	// FilterOpNotICont does not contain the specified text, case insensitive
	FilterOpNotICont FilterOp = ";%"
	// FilterOpStartsWith contains the specified text, case sensitive
	FilterOpStartsWith FilterOp = "^="
	// FilterOpNotCont does not contain the specified text, case sensitive
	FilterOpNotStartsWith FilterOp = "!^"
	// FilterOpICont contains the specified text, case insensitive
	FilterOpIStartsWith FilterOp = ":^"
	// FilterOpNotICont does not contain the specified text, case insensitive
	FilterOpNotIStartsWith FilterOp = ";^"
	// FilterOpEndsWith contains the specified text, case sensitive
	FilterOpEndsWith FilterOp = "$="
	// FilterOpNotCont does not contain the specified text, case sensitive
	FilterOpNotEndsWith FilterOp = "!$"
	// FilterOpICont contains the specified text, case insensitive
	FilterOpIEndsWith FilterOp = ":$"
	// FilterOpNotICont does not contain the specified text, case insensitive
	FilterOpNotIEndsWith FilterOp = ";$"
)

The character pairs in this are not used anywhere externally, just in a to-string representation of queries

type FilterResult added in v1.1.5 

type FilterResult struct {
	TotalCount *int64
}

FilterResult is has additional info if requested on the query - currently only the total count

type FilterResultsWithCount added in v1.1.5 

type FilterResultsWithCount struct {
	Count int64       `json:"count"`
	Total *int64      `json:"total,omitempty"` // omitted if a count was not calculated (AlwaysPaginate enabled, and count not specified)
	Items interface{} `json:"items"`
}

Note if ItemsResultTyped below might be preferred for new APIs (if you are able to adopt always-return {items:[]} style)

type FormParam 

type FormParam struct {
	// Name is the name of the parameter, from the Gorilla path mux
	Name string
	// Description is a message key to a translatable description of the parameter
	Description i18n.MessageKey
}

FormParam is a description of a multi-part form parameter

type HandlerFactory 

type HandlerFactory struct {
	DefaultRequestTimeout time.Duration
	MaxTimeout            time.Duration
	DefaultFilterLimit    uint64
	MaxFilterSkip         uint64
	MaxFilterLimit        uint64
	HandleYAML            bool
	PassthroughHeaders    []string
	AlwaysPaginate        bool
	SupportFieldRedaction bool
	BasePath              string
	BasePathParams        []*PathParam
}

func (*HandlerFactory) APIWrapper 

func (hs *HandlerFactory) APIWrapper(handler HandlerFunction) http.HandlerFunc

func (*HandlerFactory) RouteHandler 

func (hs *HandlerFactory) RouteHandler(route *Route) http.HandlerFunc

func (*HandlerFactory) RoutePath added in v1.3.0 

func (hs *HandlerFactory) RoutePath(route *Route) string

type HandlerFunction added in v1.4.0 

type HandlerFunction func(res http.ResponseWriter, req *http.Request) (status int, err error)

type HasFieldMods added in v1.3.0 

type HasFieldMods interface {
	FieldMods() []FieldMod
}

HasFieldMods can be set on a QueryField to do special things that a DB might support - like lowercase index filtering

type Int64Field added in v1.1.5 

type Int64Field struct{}

func (*Int64Field) Description added in v1.1.5 

func (f *Int64Field) Description() string

func (*Int64Field) FilterAsString added in v1.1.5 

func (f *Int64Field) FilterAsString() bool

func (*Int64Field) GetSerialization added in v1.1.5 

func (f *Int64Field) GetSerialization() FieldSerialization

type ItemsResultTyped added in v1.4.3 

type ItemsResultTyped[T any] struct {
	Count int    `ffstruct:"CollectionResults" json:"count"`
	Total *int64 `ffstruct:"CollectionResults" json:"total,omitempty"` // omitted if a count was not calculated (AlwaysPaginate enabled, and count not specified)
	Items []T    `ffstruct:"CollectionResults" json:"items"`
}

func ItemsResult added in v1.4.3 

func ItemsResult[T any](items []T, res *FilterResult, err error) (*ItemsResultTyped[T], error)

ItemsResult is a helper to transform a filter result into a REST API standard payload

type JSONBuildFilterOpt added in v1.4.6 

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

func FieldResolver added in v1.5.6 

func FieldResolver(fn FieldResolverFn) *JSONBuildFilterOpt

If you want to know the full set of fields used in the field, and build a dynamic map of fields that might need JOIN relationships (such as labels)

func SkipFieldValidation added in v1.4.6 

func SkipFieldValidation() *JSONBuildFilterOpt

func ValueResolver added in v1.4.6 

func ValueResolver(fn ValueResolverFn) *JSONBuildFilterOpt

Option to add a handler that will be called at each OR level, before performing the normal processing on each

type JSONField added in v1.1.5 

type JSONField struct{}

func (*JSONField) Description added in v1.1.5 

func (f *JSONField) Description() string

func (*JSONField) FilterAsString added in v1.1.5 

func (f *JSONField) FilterAsString() bool

func (*JSONField) GetSerialization added in v1.1.5 

func (f *JSONField) GetSerialization() FieldSerialization

type MultiConditionFilter added in v1.1.5 

type MultiConditionFilter interface {
	Filter
	// Add adds filters to the condition
	Condition(...Filter) MultiConditionFilter
	GetConditions() []Filter
}

MultiConditionFilter gives convenience methods to add conditions

type Multipart 

type Multipart struct {
	Filename string
	Mimetype string
	Data     io.Reader
}

Multipart represents streaming data in a multi-part upload

type NullBehavior added in v1.1.5 

type NullBehavior int

NullBehavior specifies whether to sort nulls first or last in a query 

const (
	NullsDefault NullBehavior = iota
	NullsFirst
	NullsLast
)

type OpenAPIFormat added in v1.4.0 

type OpenAPIFormat int
const (
	OpenAPIFormatJSON OpenAPIFormat = iota
	OpenAPIFormatYAML
)

type OpenAPIHandlerFactory added in v1.4.0 

type OpenAPIHandlerFactory struct {
	BaseSwaggerGenOptions   SwaggerGenOptions
	StaticPublicURL         string
	DynamicPublicURLHeader  string
	DynamicPublicURLBuilder func(req *http.Request) string
}

func (*OpenAPIHandlerFactory) OpenAPIHandler added in v1.4.0 

func (ohf *OpenAPIHandlerFactory) OpenAPIHandler(apiPath string, format OpenAPIFormat, routes []*Route) HandlerFunction

func (*OpenAPIHandlerFactory) OpenAPIHandlerVersioned added in v1.5.4 

func (ohf *OpenAPIHandlerFactory) OpenAPIHandlerVersioned(apiPath string, format OpenAPIFormat, apiVersionObject *APIVersion) HandlerFunction

func (*OpenAPIHandlerFactory) SwaggerUIHandler added in v1.4.0 

func (ohf *OpenAPIHandlerFactory) SwaggerUIHandler(openAPIPath string) HandlerFunction

type OrFilter added in v1.1.5 

type OrFilter interface{ MultiConditionFilter }

type PathParam 

type PathParam struct {
	// Name is the name of the parameter, from the Gorilla path mux
	Name string
	// Default is the value that will be used in the case no value is supplied
	Default string
	// Example is a field to fill in, in the helper UI
	Example string
	// ExampleFromConf is a field to fill in, in the helper UI, from the runtime configuration
	ExampleFromConf config.RootKey
	// Description is a message key to a translatable description of the parameter
	Description i18n.MessageKey
}

PathParam is a description of a path parameter

type QueryFactory added in v1.1.5 

type QueryFactory interface {
	NewFilter(ctx context.Context) FilterBuilder
	NewFilterLimit(ctx context.Context, defLimit uint64) FilterBuilder
	NewUpdate(ctx context.Context) UpdateBuilder
}

QueryFactory creates a filter builder in the given context, and contains the rules on which fields can be used by the builder (and how they are serialized)

type QueryFields added in v1.1.5 

type QueryFields map[string]Field

func (QueryFields) Clone added in v1.5.6 

func (qf QueryFields) Clone() QueryFields

func (QueryFields) NewFilter added in v1.1.5 

func (qf QueryFields) NewFilter(ctx context.Context) FilterBuilder

func (QueryFields) NewFilterLimit added in v1.1.5 

func (qf QueryFields) NewFilterLimit(ctx context.Context, defLimit uint64) FilterBuilder

func (QueryFields) NewUpdate added in v1.1.5 

func (qf QueryFields) NewUpdate(ctx context.Context) UpdateBuilder

type QueryJSON added in v1.4.1 

type QueryJSON struct {
	FilterJSON
	Skip  *uint64  `ffstruct:"FilterJSON" json:"skip,omitempty"`
	Limit *uint64  `ffstruct:"FilterJSON" json:"limit,omitempty"`
	Sort  []string `ffstruct:"FilterJSON" json:"sort,omitempty"`
	Count *bool    `ffstruct:"FilterJSON" json:"count,omitempty"`
}

func (*QueryJSON) BuildFilter added in v1.4.1 

func (jq *QueryJSON) BuildFilter(ctx context.Context, qf QueryFactory, options ...*JSONBuildFilterOpt) (Filter, error)

type QueryParam 

type QueryParam struct {
	// Name is the name of the parameter, from the Gorilla path mux
	Name string
	// IsBool if this is a boolean query
	IsBool bool
	// IsArray if this is an array parameter (can be specified multiple times)
	IsArray bool
	// Default is the value that will be used in the case no value is supplied
	Default string
	// Example is a field to fill in, in the helper UI
	Example string
	// ExampleFromConf is a field to fill in, in the helper UI, from the runtime configuration
	ExampleFromConf config.RootKey
	// Description is a message key to a translatable description of the parameter
	Description i18n.MessageKey
	// Deprecated whether this param is deprecated
	Deprecated bool
}

QueryParam is a description of a path parameter

type Route 

type Route struct {
	// Name is the operation name that will go into the Swagger definition, and prefix input/output schema
	Name string
	// Path is a Gorilla mux path spec
	Path string
	// PathParams is a list of documented path parameters
	PathParams []*PathParam
	// QueryParams is a list of documented query parameters
	QueryParams []*QueryParam
	// FormParams is a list of documented multi-part form parameters - combine with FormUploadHandler
	FormParams []*FormParam
	// Method is the HTTP method
	Method string
	// Description is a message key to a translatable description of the operation
	Description i18n.MessageKey
	// PreTranslatedDescription is a string describing the operation - used for programmatically generated routes where a built-in string translation is not available
	PreTranslatedDescription string
	// FilterFactory models the filter fields that can be specified on the API, and will automatically be parsed
	FilterFactory QueryFactory
	// JSONInputDecoder is a function that does the decoding completely - needed (as this was written pre-generics) for handling arrays
	JSONInputDecoder func(req *http.Request, body io.Reader) (interface{}, error)
	// JSONInputValue is a function that returns a pointer to a structure to take JSON input
	JSONInputValue func() interface{}
	// JSONInputMask are fields that aren't available for users to supply on input
	JSONInputMask []string
	// JSONInputSchema is a custom schema definition, for the case where the auto-gen + mask isn't good enough
	JSONInputSchema func(ctx context.Context, schemaGen SchemaGenerator) (*openapi3.SchemaRef, error)
	// JSONOutputSchema is a custom schema definition, for the case where the auto-gen + mask isn't good enough
	JSONOutputSchema func(ctx context.Context, schemaGen SchemaGenerator) (*openapi3.SchemaRef, error)
	// JSONOutputValue is a function that returns a pointer to a structure to take JSON output
	JSONOutputValue func() interface{}
	// JSONOutputCodes is the success response codes that could be returned by the API. Error codes are explicitly not supported by the framework since they could be subject to change by the errors thrown or how errors are handled.
	JSONOutputCodes []int
	// JSONHandler is a function for handling JSON content type input. Input/Output objects are returned by JSONInputValue/JSONOutputValue funcs
	JSONHandler func(r *APIRequest) (output interface{}, err error)
	// FormUploadHandler takes a single file upload, and returns a JSON object
	FormUploadHandler func(r *APIRequest) (output interface{}, err error)
	// StreamHandler allows for custom request handling with explicit stream (io.ReadCloser) responses
	StreamHandler func(r *APIRequest) (output io.ReadCloser, err error)
	// CustomResponseRefs allows for specifying custom responses for a route
	CustomResponseRefs map[string]*openapi3.ResponseRef
	// Deprecated whether this route is deprecated
	Deprecated bool
	// Tag a category identifier for this route in the generated OpenAPI spec
	Tag string
	// Extensions allows extension of the route struct by individual microservices
	Extensions interface{}
}

Route defines each API operation on the REST API of Firefly Having a standard pluggable layer here on top of Gorilla allows us to autmoatically maintain the OpenAPI specification in-line with the code, while retaining the power of the Gorilla mux without a deep abstraction layer.

type SchemaGenerator added in v0.1.11 

type SchemaGenerator func(o interface{}) (*openapi3.SchemaRef, error)

SchemaGenerator is passed into the JSONInputSchema advanced customization function, to give access to tools like object schema generation, for an anyOf schema for example

type SetOperation added in v1.1.5 

type SetOperation struct {
	Field string
	Value FieldSerialization
}

SetOperation is an individual update action to perform

type SimpleFilterValue added in v1.4.1 

type SimpleFilterValue string

func (SimpleFilterValue) String added in v1.4.1 

func (js SimpleFilterValue) String() string

func (*SimpleFilterValue) UnmarshalJSON added in v1.4.1 

func (js *SimpleFilterValue) UnmarshalJSON(b []byte) error

type SortField added in v1.1.5 

type SortField struct {
	Field      string
	Descending bool
	Nulls      NullBehavior
}

SortField is field+direction for sorting

type StringField added in v1.1.5 

type StringField struct{}

func (*StringField) Description added in v1.1.5 

func (f *StringField) Description() string

func (*StringField) FilterAsString added in v1.1.5 

func (f *StringField) FilterAsString() bool

func (*StringField) GetSerialization added in v1.1.5 

func (f *StringField) GetSerialization() FieldSerialization

type StringFieldLower added in v1.3.0 

type StringFieldLower struct {
	StringField
}

func (*StringFieldLower) FieldMods added in v1.3.0 

func (f *StringFieldLower) FieldMods() []FieldMod

func (*StringFieldLower) FilterAsString added in v1.3.0 

func (f *StringFieldLower) FilterAsString() bool

func (*StringFieldLower) GetSerialization added in v1.3.0 

func (f *StringFieldLower) GetSerialization() FieldSerialization

type SwaggerGen 

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

func NewSwaggerGen 

func NewSwaggerGen(options *SwaggerGenOptions) *SwaggerGen

func (*SwaggerGen) AddParam 

func (sg *SwaggerGen) AddParam(ctx context.Context, op *openapi3.Operation, in, name, def, example string, description i18n.MessageKey, deprecated bool, msgArgs ...interface{})

func (*SwaggerGen) Generate 

func (sg *SwaggerGen) Generate(ctx context.Context, routes []*Route) *openapi3.T

type SwaggerGenOptions added in v1.4.0 

type SwaggerGenOptions struct {

	// attributes of openapi3.Info
	Title       string
	Version     string
	Description string

	// descriptions for the route parameters are parsed from the ffstruct tags
	// when set this flag to true, if a description is not found, the generator will panic
	// this is useful to ensure that all fields are documented
	PanicOnMissingDescription bool

	SupportFieldRedaction bool
	DefaultRequestTimeout time.Duration

	// ----------- API version specific options ------------
	// options to generate the base URL
	BaseURL          string
	BaseURLVariables map[string]BaseURLVariable

	// options of controlling query parameters values
	APIMaxFilterSkip      uint
	APIDefaultFilterLimit string
	APIMaxFilterLimit     uint

	// a custom function to modify the generated OpenAPI spec
	RouteCustomizations func(ctx context.Context, sg *SwaggerGen, route *Route, op *openapi3.Operation)

	// OpenAPI 3.0.x specific options
	Tags         openapi3.Tags
	ExternalDocs *openapi3.ExternalDocs
}

type TimeField added in v1.1.5 

type TimeField struct{}

func (*TimeField) Description added in v1.1.5 

func (f *TimeField) Description() string

func (*TimeField) FilterAsString added in v1.1.5 

func (f *TimeField) FilterAsString() bool

func (*TimeField) GetSerialization added in v1.1.5 

func (f *TimeField) GetSerialization() FieldSerialization

type UUIDField added in v1.1.5 

type UUIDField struct{}

func (*UUIDField) Description added in v1.1.5 

func (f *UUIDField) Description() string

func (*UUIDField) FilterAsString added in v1.1.5 

func (f *UUIDField) FilterAsString() bool

func (*UUIDField) GetSerialization added in v1.1.5 

func (f *UUIDField) GetSerialization() FieldSerialization

type Update added in v1.1.5 

type Update interface {
	// Set adds a set condition to the update
	Set(field string, value interface{}) Update

	// IsEmpty
	IsEmpty() bool

	// Finalize completes the update, and for the plugin to validated output structure to convert
	Finalize() (*UpdateInfo, error)
}

type UpdateBuilder added in v1.1.5 

type UpdateBuilder interface {
	// Set starts creation of a set operation
	Set(field string, value interface{}) Update

	// S starts an update that doesn't have any fields
	S() Update

	// Fields returns the available fields on the update
	Fields() []string
}

UpdateBuilder is the output of the builder

type UpdateFactory added in v1.1.5 

type UpdateFactory interface {
	New(ctx context.Context) UpdateBuilder
}

UpdateFactory creates a update builder in the given context, and contains the rules on which fields can be used by the builder (and how they are serialized)

type UpdateInfo added in v1.1.5 

type UpdateInfo struct {
	SetOperations []*SetOperation
}

UpdateInfo is the structure returned by Finalize to the plugin, to serialize this uilter into the underlying database mechanism's uilter language

func (*UpdateInfo) String added in v1.1.5 

func (u *UpdateInfo) String() string

type ValueFilter added in v1.4.6 

type ValueFilter interface {
	// The operation for this filter
	Op() FilterOp

	// The field name
	Field() string

	// The value
	Value() interface{}

	// Set the operation for this filter
	SetOp(op FilterOp)

	// Set the field name
	SetField(f string)

	// Set the value
	SetValue(v interface{})
}

ValueFilter is accessor functions for non-Or/And filters - for advanced traversal of the un-finalized tree

type ValueResolverFn added in v1.4.6 

type ValueResolverFn func(ctx context.Context, level *FilterJSON, fieldName, suppliedValue string) (driver.Value, error)

type VersionedAPIs added in v1.5.2 

type VersionedAPIs struct {
	DefaultVersion string                 // must be set to a version string if there are more than 1 API versions provided
	APIVersions    map[string]*APIVersion // a list of APIVersions, with the key being the version string
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.