Documentation
¶
Overview ¶
Package query provides a generic, resource-agnostic engine for declaring what fields of a resource are queryable/sortable, validating an incoming query.v1.Payload against that declaration, and translating a validated Payload into a parameterized Postgres WHERE/ORDER BY fragment.
It holds no knowledge of any specific resource (users, sessions, ...) — each resource-owning service declares its own Descriptor with NewDescriptor, serves it from its own schema RPC, and reuses the same Descriptor to validate and translate incoming Payloads. That single declaration is what keeps a resource's advertised schema and its actual server-side enforcement from drifting apart.
Index ¶
- func BuildOrderBy(desc *queryv1.Descriptor, fm FieldMap, sorts []*queryv1.Sort) string
- func BuildQuery(selectSQL string, desc *queryv1.Descriptor, fm FieldMap, ...) (string, []any, error)
- func BuildWhere(desc *queryv1.Descriptor, fm FieldMap, filters *queryv1.Filters, argOffset int) (string, []any, error)
- func InterpolateSQL(q string, args []any) string
- func ParseValue(t queryv1.FieldType, raw string) (any, error)
- func Validate(desc *queryv1.Descriptor, p *queryv1.Payload) error
- type Column
- type DescriptorBuilder
- type FieldMap
- type Mandatory
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildOrderBy ¶
BuildOrderBy translates Sort keys into a SQL ORDER BY fragment (without the leading "ORDER BY"), falling back to the descriptor's default_sort when sorts is empty. Returns "" when there is nothing to sort by.
func BuildQuery ¶
func BuildQuery(selectSQL string, desc *queryv1.Descriptor, fm FieldMap, payload *queryv1.Payload, mandatory []Mandatory, limit, offset int) (string, []any, error)
BuildQuery assembles a full paginated SQL query from a base "SELECT ... FROM ..." header, a client's Filters/Sort (validate the enclosing Payload against desc with Validate before calling this), and a set of Mandatory conditions that apply regardless of the client's own Filters.op.
The Filters-derived WHERE fragment is parenthesized before ANDing mandatory conditions onto it — without that, a client-chosen Filters.op = OR would exploit SQL's AND-binds-tighter-than-OR precedence to dilute a mandatory (e.g. obligation-derived) constraint instead of being scoped by it.
Returns the complete query string and its positional arguments, ready to pass to a pgx Query call. Callers still own their own SELECT column list and row-scanning, since those are resource-specific.
func BuildWhere ¶
func BuildWhere(desc *queryv1.Descriptor, fm FieldMap, filters *queryv1.Filters, argOffset int) (string, []any, error)
BuildWhere translates a Filters group into a parameterized SQL WHERE clause fragment (without the leading "WHERE") using Postgres-style $N placeholders, plus the arguments to bind to it in order. argOffset is the number of positional arguments already bound ahead of this fragment (0 if none). Returns "", nil, nil when filters has no conditions.
Callers must run Validate on the enclosing Payload against the same desc first — BuildWhere trusts that every condition's field and operator have already been checked against the resource's Descriptor.
func InterpolateSQL ¶
InterpolateSQL inlines args into a $-parameterized query, producing a single-line standalone statement that can be pasted into a query console to reproduce a logged call. It is for debug logging only — never use the result to execute a query, since the substitution is not injection-safe.
func ParseValue ¶
ParseValue parses a raw condition value according to a field's declared type, returning a Go-typed value (string, float64, bool, or time.Time) suitable for use directly as a SQL query argument.
func Validate ¶
func Validate(desc *queryv1.Descriptor, p *queryv1.Payload) error
Validate checks a Payload against a resource's Descriptor: every filter condition's field must exist on the resource, its operator must be one the field's descriptor allows, and its value(s) must parse according to the field's declared type. Sort fields are checked for existence only. A nil Payload is always valid.
Types ¶
type Column ¶
type Column struct {
// Name is the SQL column name. Empty means the same as the field name.
Name string
// Array marks Name as a Postgres array column (e.g. "roles" text[]).
// eq/ne become array-membership checks (true when any element matches,
// with the same glob-wildcard support as scalar string eq/ne) and in
// becomes an array-overlap check against a literal value set, instead
// of the usual scalar comparisons.
Array bool
}
Column describes how a single descriptor field name resolves to SQL.
type DescriptorBuilder ¶
type DescriptorBuilder struct {
// contains filtered or unexported fields
}
DescriptorBuilder incrementally builds a resource's query Descriptor.
func NewDescriptor ¶
func NewDescriptor(resource string) *DescriptorBuilder
NewDescriptor starts a Descriptor for the given resource identifier, e.g. "users".
func (*DescriptorBuilder) Build ¶
func (b *DescriptorBuilder) Build() *queryv1.Descriptor
Build returns the assembled Descriptor.
func (*DescriptorBuilder) DefaultSort ¶
func (b *DescriptorBuilder) DefaultSort(field string, dir queryv1.SortDir) *DescriptorBuilder
DefaultSort appends a sort key applied when a client's Payload specifies none.
func (*DescriptorBuilder) Field ¶
func (b *DescriptorBuilder) Field(name string, typ queryv1.FieldType, ops ...queryv1.Operator) *DescriptorBuilder
Field declares a queryable/sortable field and the operators valid against it.
type FieldMap ¶
FieldMap overrides how a resource's descriptor field names resolve to SQL columns. A field absent from the map resolves to a non-array column of its own name. It is declared by the resource-owning service alongside its Descriptor and is never derived from client input, so every column identifier that reaches the generated SQL originates from a trusted, server-declared string.
type Mandatory ¶
type Mandatory struct {
// Column is the SQL column name to constrain.
Column string
// Array marks Column as a Postgres array column, using the same
// overlap ("&&") semantics as an "in" Condition on an array field (see
// arrayOverlapCondition). When false, an equality condition is built
// against Values[0].
Array bool
// Values holds the operand(s). An empty Values means "no constraint";
// BuildQuery skips such entries, so callers may unconditionally append
// a Mandatory built from an obligation that turned out to be absent.
Values []string
}
Mandatory is a single AND condition enforced independent of a client's Filters — typically derived from authz obligations rather than client input (e.g. scoping a listing to the caller's org). Column must be a trusted, server-declared identifier, never taken from client input.