Documentation
¶
Index ¶
Constants ¶
const ( FilterTypeProperty = "property" FilterTypeOperator = "operator" )
const ( MinPage = 1 // MinPage represents the minimum allowed value for the pagination query's Page parameter. MinPerPage = 1 // MinPerPage represents the minimum allowed value for the pagination query's PerPage parameter. DefaultPerPage = 10 // DefaultPerPage represents the default value for the pagination query's PerPage parameter. MaxPerPage = 100 // MaxPerPage represents the maximum allowed value for the pagination query's PerPage parameter. )
const ( OrderAsc = "asc" OrderDesc = "desc" )
const ( // MaxFilterItems caps the number of entries in [Filters.Data]. MaxFilterItems = 8 // MaxStringValueLen caps a string in [FilterProperty.Value], and each // item when the value is an array. MaxStringValueLen = 256 // MaxArrayLen caps the length of an array in [FilterProperty.Value]. MaxArrayLen = 4 // MaxFilterRawBytes caps the base64-encoded filter query parameter // before decode. MaxFilterRawBytes = 16 * 1024 )
Size limits applied to client-supplied filters. Together they bound the cost of serving a malicious filter payload: the outer limit caps the raw request size, the inner limits cap the structural complexity after decode.
Variables ¶
var ( ErrFilterInvalid = errors.New("filter is invalid") ErrFilterPropertyInvalid = errors.New("filter property is not valid") ErrFilterOperatorInvalid = errors.New("filter operator is not valid") ErrFilterTooLarge = errors.New("filter exceeds the maximum size") ErrSorterFieldInvalid = errors.New("sort field is not valid") )
Functions ¶
func ValidateFilters ¶ added in v0.21.7
func ValidateFilters(filters *Filters, constraints FieldConstraints) error
ValidateFilters returns ErrFilterPropertyInvalid if any property filter references a (field, operator) pair not in constraints, carries a non-primitive Value, or exceeds the configured size limits. Operator filters (and/or) are left to the store to parse.
func ValidateSorter ¶ added in v0.21.7
ValidateSorter returns ErrSorterFieldInvalid if the sort field is set and not in allowed. An empty [Sorter.By] is valid (the store falls back to a stable default).
Types ¶
type FieldConstraints ¶ added in v0.21.7
FieldConstraints maps a filter field name to the set of operators allowed against it. It lets the handler reject field+operator combinations that the database rejects with a server-side error (e.g. ILIKE on an enum), turning them into a clean HTTP 400 before they reach the store.
func NewFieldConstraints ¶ added in v0.21.7
func NewFieldConstraints(entries map[string][]string) FieldConstraints
NewFieldConstraints returns a FieldConstraints initialized with the given field→operators pairs. An empty operators slice means the field is rejected entirely.
func (FieldConstraints) Allows ¶ added in v0.21.7
func (c FieldConstraints) Allows(name, operator string) bool
Allows reports whether operator is valid for the given field name.
type FieldSet ¶ added in v0.21.7
type FieldSet map[string]struct{}
FieldSet is a set of field names allowed for use as a database identifier in sort options.
func NewFieldSet ¶ added in v0.21.7
NewFieldSet returns a FieldSet containing the given names.
type Filter ¶
type Filter struct {
Type string `json:"type,omitempty"`
Params interface{} `json:"params,omitempty"`
}
func (*Filter) UnmarshalJSON ¶
type FilterOperator ¶
type FilterOperator struct {
// Name is the filter operator (e.g., "and", "or").
Name string `json:"name"`
}
FilterOperator represents a JSON representation of a filter operator in a query (e.g., "and", "or" in MongoDB queries).
type FilterProperty ¶
type FilterProperty struct {
// Name is the attribute to be observed in the operation.
Name string `json:"name"`
// Operator is the operation (e.g., "eq" for equal).
Operator string `json:"operator"`
// Value is the value used in the operation. (e.g., "eq" operations use Value to determine the value to be equal).
Value interface{} `json:"value"`
}
FilterProperty is a JSON representation of a property expression in a query.
Name is the attribute to be observed in the operation, Operator is the operation, and Value is the value used in the operation. While Name can be any string, the Operator must be supported by the implementation, and the Value is the value used in the operation.
Each operator has its own implementation, and one operator can have multiple implementations. For that reason, the operator must be converted to a useful value using build methods.
Examples: A FilterProperty with Operator "gt", Name "count", and Value 12 will filter documents with the attribute "count" greater than 12. Another FilterProperty with Operator "eq", Name "alias", and Value "foobar" will filter documents with the attribute "alias" equal to "foobar".
type Filters ¶
type Filters struct {
// Raw holds the raw data of the filter and it's a base64-encoded JSON.
Raw string `query:"filter"`
// Data stores the decoded filters; it's automatically populated with the Unmarshal method.
Data []Filter
}
Filters represents a set of filters that can be applied to queries.
func NewFilters ¶
func NewFilters() *Filters
NewFilters creates a new instance of Filters with an empty Data slice.
func (*Filters) Unmarshal ¶
Unmarshal decodes and unmarshals the raw filters, populating the Data attribute. It rejects payloads larger than MaxFilterRawBytes before decode to keep a hostile caller from allocating large buffers at JSON decode time.
type Paginator ¶
type Paginator struct {
// Page represents the current page number.
Page int `query:"page"`
// PerPage represents the number of items per page.
PerPage int `query:"per_page"`
}
Paginator represents the paginator parameters in a query.
func NewPaginator ¶
func NewPaginator() *Paginator
NewPaginator creates and returns a new Paginator instance with MinPage and DefaultPerPage.
func (*Paginator) Normalize ¶
func (p *Paginator) Normalize()
Normalize ensures valid values for Page and PerPage in the pagination query. If query.PerPage is less than zero, it is set to `DefaultPerPage`. If query.Page is less than one, it is set to `MinPage`. The maximum allowed value for query.PerPage is `MaxPerPage`.
type Sorter ¶
type Sorter struct {
By string `query:"sort_by"`
Order string `query:"order_by" validate:"omitempty,oneof=asc desc"`
}
Sorter represents the sorting order in a query.
Source Files