ffapi

package
v1.2.5 Latest Latest
Warning

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

 Go to latest Published: Mar 16, 2023 License: Apache-2.0 Imports: 23 Imported by: 12

Documentation

Index

Constants

View Source 
const FFRequestIDHeader = "X-FireFly-Request-ID"

Variables

This section is empty.

Functions

func SwaggerUIHTML 

func SwaggerUIHTML(ctx context.Context, url string) []byte

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
	PP              map[string]string
	FP              map[string]string
	Filter          AndFilter
	Input           interface{}
	Part            *Multipart
	SuccessStatus   int
	ResponseHeaders http.Header
}

func (*APIRequest) FilterResult added in v1.1.5 

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

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

type AndFilter added in v1.1.5 

type AndFilter interface{ MultiConditionFilter }

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 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 {
	// Sort adds a set of sort conditions (all in a single sort order)
	Sort(...string) Filter

	// Ascending sort order
	Ascending() Filter

	// Descending sort order
	Descending() Filter

	// Skip for pagination
	Skip(uint64) Filter

	// Limit for pagination
	Limit(uint64) Filter

	// Request a count to be returned on the total number that match the query
	Count(c bool) 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
}

Filter is the output of the builder

type FilterBuilder added in v1.1.5 

type FilterBuilder interface {
	// 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 {
	Sort      []*SortField
	Skip      uint64
	Limit     uint64
	Count     bool
	CountExpr string
	Field     string
	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 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"`
	Items interface{} `json:"items"`
}

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
	PassthroughHeaders    []string
}

func (*HandlerFactory) APIWrapper 

func (hs *HandlerFactory) APIWrapper(handler func(res http.ResponseWriter, req *http.Request) (status int, err error)) http.HandlerFunc

func (*HandlerFactory) RouteHandler 

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

func (*HandlerFactory) SwaggerUIHandler 

func (hs *HandlerFactory) SwaggerUIHandler(url string) func(res http.ResponseWriter, req *http.Request) (status int, err error)

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 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
}

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 Options 

type Options struct {
	BaseURL                   string
	Title                     string
	Version                   string
	Description               string
	PanicOnMissingDescription bool
	DefaultRequestTimeout     time.Duration
	APIMaxFilterSkip          uint
	APIDefaultFilterLimit     string
	APIMaxFilterLimit         uint

	RouteCustomizations func(ctx context.Context, sg *SwaggerGen, route *Route, op *openapi3.Operation)
}

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) 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 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
	// 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
	// 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 code
	JSONOutputCodes []int
	// JSONHandler is a function for handling JSON content type input. Input/Ouptut 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)
	// 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 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 SwaggerGen 

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

func NewSwaggerGen 

func NewSwaggerGen(options *Options) *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 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

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.