query

package
v0.65.3 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: AGPL-3.0 Imports: 6 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildOrderBy

func BuildOrderBy(desc *queryv1.Descriptor, fm FieldMap, sorts []*queryv1.Sort) string

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

func InterpolateSQL(q string, args []any) string

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

func ParseValue(t queryv1.FieldType, raw string) (any, error)

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

Field declares a queryable/sortable field and the operators valid against it.

type FieldMap

type FieldMap map[string]Column

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.

func (FieldMap) ColumnFor

func (fm FieldMap) ColumnFor(field string) string

ColumnFor resolves the SQL column name for a descriptor field name.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL