Crate cratestack 

CrateStack server facade — Postgres (sqlx) + Axum.

This crate is the server-side slice of the framework. It re-exports the shared schema / parser / policy / SQL surface plus the sqlx (Postgres) runtime, Axum HTTP bindings, and the generated Rust client runtime.

It deliberately does not depend on cratestack-rusqlite. That keeps libsqlite3-sys out of the dep graph, so consumers can use the official sqlx umbrella crate (which optionally declares sqlx-sqlite and trips Cargo’s links = "sqlite3" collision rule) without needing a local sqlx-shim workaround.

For embedded / mobile / wasm targets, depend on cratestack-sqlite instead. The two crates are strictly disjoint by design.

Schema macros emit ::cratestack::* paths, so consumers rename this crate via Cargo’s package = field:

[dependencies]
cratestack = { package = "cratestack-pg", version = "0.4" }

Re-exports

pub use chrono;

pub use cratestack_client_rust as client_rust;

pub use regex;

pub use serde;

pub use serde_json;

pub use tracing;

pub use uuid;

pub use cratestack_axum::axum;

Modules

audit

Audit log primitives.

axum

axum is an HTTP routing and request-handling library that focuses on ergonomics and modularity.

batch

Batch envelope.

context

Request-scoped context: authenticated identity, structured principal, transport extensions, plus the AuthProvider trait that auth middlewares implement.

envelope

Signed envelope (HMAC-SHA-256).

error

CoolError — the framework’s error type, its 4xx/5xx HTTP mapping, and the public response envelope clients see on failure.

events

Model-event bus: typed created/updated/deleted envelopes that procedure handlers can subscribe to.

headers

Header helpers used by axum-bound handlers: optimistic-locking ETag parsing/emission, W3C traceparent extraction, RFC 7239 Forwarded client-IP extraction, and context enrichment that bundles those.

idempotency

Idempotency-key middleware.

json

Schema-declared Json columns need a model-struct field type that’s the same on every backend so the same struct compiles on server and on embedded (including wasm32-unknown-unknown, which can’t depend on sqlx).

page

Generic paginated-page envelope used by every list route. The shape mirrors what generated clients consume.

projection

query

Query-string parsing for axum-bound handlers: percent-decoded pair extraction and the structured filter expression grammar (?where=...) used by macro-generated list endpoints.

ratelimit

Per-principal rate limiting.

rpc

Runtime primitives for the transport rpc generation style.

schema

Schema IR — the parsed shape of a .cstack file. Every IR node carries source-span back-pointers so consumers can map errors to positions in the original text.

sqlx

Compatibility shim that exposes a sqlx-shaped API by re-exporting from sqlx-core + sqlx-postgres directly.

validators

Field-level validators.

value

Backend-agnostic JSON-shaped value used throughout the framework (auth claims, audit payloads, RPC error details, schema config).

Macros

include_client_schema

HTTP client schema: model/input/procedure stubs for talking to a server over the wire. No DB, no router, no FromRow impls. Renamed from include_client_macro! in 0.3.0.

include_embedded_schema

Embedded ORM schema: rusqlite backend only. Compiles to native and to wasm32-unknown-unknown (via sqlite-wasm-rs). No sqlx, no axum, no procedures. Local apps that don’t need an RPC surface use this.

include_server_schema

Full server schema: sqlx Postgres backend, Cratestack runtime, axum router, procedures, events. Pass db = Postgres (only value currently supported; MySQL / SQLite-via-sqlx will land in a future release).

Structs

Aggregate

AggregateColumn

AggregateCount

Attribute

AuditActor

AuditEvent

AuthBlock

BatchItemError

Public, safe-to-expose shape of a per-item failure. Mirrors crate::CoolErrorResponse without the optional details field — batch callers asking for per-item detail can repeat the operation singly against the failed item to get the full error envelope.

BatchItemResult

Per-item result inside a BatchResponse. The index is the item’s position in the original request, so clients can pair results with inputs even after server-side reordering (e.g. parallel batch_get fetches in the future).

BatchRequest

Wire envelope for POST /<model>/batch-* request bodies. Holds the items in a single field so the envelope can grow (e.g. a future client_request_id) without breaking deserialization.

BatchResponse

Wire envelope returned by every batch route. Always 200 OK at the HTTP layer; inspect summary.err (or scan results) to surface per-item failures to the user.

BatchSummary

Summary counts attached to every BatchResponse so callers can branch on aggregate status without scanning the result list.

CoalesceExpr

Left-hand operand of a coalesce-based filter — chain a comparator method to turn it into a FilterExpr.

CoalesceFilter

COALESCE(col_a, col_b, ...) <op> <value> — left-hand expression is the first non-null among the listed columns; right-hand side is a bound value via the usual FilterValue envelope. Lets schemas express the “ranked-fallback compare” pattern that shows up in outbox / scheduler tables, where a single row carries several time columns and the dispatcher wants the earliest non-null one.

CodecSet

ConfigBlock

ConfigEntry

CoolAuthIdentity

CoolContext

CoolErrorResponse

CoolEventBus

CoolEventEnvelope

CreateDefault

CreateRecord

Datasource

DbErrorInfo

Structured information extracted from a driver-level database error.

DeleteMany

DeleteRecord

EnumDecl

EnumVariant

Field

FieldRef

Filter

FindMany

FindManyWith

FindUnique

HmacEnvelope

HMAC-SHA-256 backed envelope. Sealed messages are self-describing CBOR maps: signature recipients can decode the envelope, fetch the key by kid, and verify without out-of-band coordination.

InMemoryNonceStore

In-memory nonce store. One mutex; the working set is bounded by the clock-skew window — a 5-minute skew at 10k req/s caps at ~3M entries, which is fine. Production multi-replica deployments swap in Redis.

Json

Json for json and jsonb fields

JsonTextPath

Left-hand operand of a json_get_text filter — chain a comparison method (.eq, .lt, .is_null, …) to produce a FilterExpr.

Migration

A single migration step. The runner applies any rows not yet present in cratestack_migrations. down is recorded but never called — irreversible-by-default is the safe banking posture.

MigrationState

MixinDecl

Model

ModelColumn

ModelDelegate

ModelDescriptor

ModelEvent

MulticastAuditSink

Fan an audit event out to multiple sinks. Errors from any individual sink are aggregated into CoolError::Internal so a single failing downstream does not silently swallow problems with the others.

NoEnvelope

Pass-through envelope used when transport-layer signing is not required.

NoopAuditSink

Default sink that does nothing. The in-database audit table is treated as authoritative; downstream consumers are added by wrapping a different sink (or composing several).

OpDescriptor

Wire-shape of a single op in a transport rpc schema. See docs/design/rpc-transport.md for the full design — in short, an op is the dispatch unit shared by every RPC binding (HTTP unary, HTTP batch, HTTP stream, WebSocket). The macro emits one OpDescriptor per CRUD verb and per procedure when Schema.transport == TransportStyle::Rpc.

OrderClause

OwnedSchemaSummary

Page

PageInfo

PrincipalContext

PrincipalFacet

Procedure

ProcedureArg

ProcedurePolicy

ProjectedFindMany

ProjectedFindUnique

Projection

Result of a .select(...)-projected read. Holds the model with only the selected columns populated — non-selected fields carry their type’s Default::default() value ("" for String, 0 for integers, None for Option<T>, etc.).

ReadPolicy

RelationFilter

RelationInclude

Typed handle for an .include(...) call on a query builder. Carries everything the runtime needs to issue the side-load query for a to-one relation: a function pointer that extracts the FK value from a parent row, and a static descriptor of the related model.

RequestContext

RouteTransportCapabilities

Wire-level capabilities for one route under a REST binding.

RouteTransportDescriptor

Schema

SchemaError

SchemaSummary

ScopedAggregate

ScopedAggregateColumn

ScopedAggregateCount

ScopedCreateRecord

ScopedDeleteMany

ScopedDeleteRecord

ScopedFindMany

ScopedFindManyWith

ScopedFindUnique

ScopedModelDelegate

ScopedProjectedFindMany

ScopedProjectedFindUnique

ScopedUpdateMany

ScopedUpdateManySet

ScopedUpdateRecord

ScopedUpdateRecordSet

SealedEnvelope

SelectionQuery

SourceSpan

SpatialPoint

Builder returned by crate::point for assembling a spatial filter. Holds nothing but the lat/lng pair until a comparator is chained.

SqlColumnValue

SqlxIdempotencyStore

StaticKeyProvider

In-memory KeyProvider for tests and single-tenant deployments. Banks running real workloads bring a backed implementation (KMS, Vault, HSM).

TypeDecl

TypeRef

UpdateMany

UpdateManySet

UpdateRecord

UpdateRecordSet

View

ViewDelegate

View delegate for views that declared an @id field. Exposes find_many + find_unique (and refresh() on materialized views). Views declared @@no_unique get ViewDelegateNoUnique instead, which omits find_unique at the type level so a call like runtime.views().<v>().find_unique(()) is a compile error rather than a runtime “WHERE = $1” footgun.

ViewDelegateNoUnique

View delegate for views declared @@no_unique. Exposes only find_many — find_unique and refresh() are absent at the type level because:

ViewDescriptor

ViewSource

Enums

AuditOperation

BatchItemStatus

Either a successful per-item outcome (Ok) or a per-item failure (Error). Serializes as a tagged enum with the discriminant in status:

ConflictTarget

Conflict target for an upsert. Defaults to the model’s primary key (matching the previous PK-only behavior). Columns lets callers upsert on an arbitrary unique tuple — most commonly a natural key that’s distinct from the PK (e.g. (owner_id, provider) on a per-owner-and-provider settings row, or (pairing_id, slot) on a per-slot envelope).

CoolError

CreateDefaultType

FilterExpr

FilterOp

JsonFilter

JSON / JSONB filter predicates. Two flavors:

MigrationStatus

ModelEventKind

NullOrder

Where NULLs sort relative to non-NULL values. PostgreSQL’s default is NULLS LAST for ASC and NULLS FIRST for DESC; SQLite’s default is NULLS FIRST for both. CrateStack pins the framework default to NULLS LAST so listings stay deterministic across backends and so soft-deleted rows (typed Option<DateTime> that surface as None for visible rows) don’t muscle their way to the top of every listing. Override per-clause via OrderClause::nulls_first when scheduler / outbox queries want fresh-as-null tasks at the head of the queue.

OpKind

PolicyExpr

PolicyLiteral

ProcedureKind

ProcedurePolicyExpr

ProcedurePolicyLiteral

ProcedurePredicate

QueryExpr

ReadPredicate

RelationQuantifier

SortDirection

SpatialFilter

PostGIS spatial filter primitives. v1 ships two ops that cover the “is point inside this zone” / “is this point within radius of that zone” cases — the rest of the ST_* surface can land on demand.

SqlValue

TransactionIsolation

Transaction isolation level requested by a procedure via @isolation(...). Mirrors the PostgreSQL spec: lower variants tolerate more anomalies, higher ones cost more under contention. Banks running multi-row updates (transfers, postings) typically pick Serializable and pair it with retry-on-serialization-failure.

TransportStyle

Wire-shape the schema generates for. Picked once per schema (via the top-level transport rest|rpc directive) so generated servers and clients only carry one binding’s worth of surface.

TypeArity

Value

Constants

AUDIT_TABLE_DDL

DDL for the audit log table. Banks typically run migrations through their own tooling — this DDL is exposed so the crate::SqlxRuntime can idempotently ensure the table exists during bootstrap.

BATCH_MAX_ITEMS

Default upper bound on items in a single batch request. Server backends enforce this before any SQL runs and surface CoolError::Validation on the outer Result when exceeded. The cap is identical for all five batch operations; deviating per-op would invite footguns where batch_get accepts a list that batch_create of the same length rejects.

CBOR_SEQUENCE_CONTENT_TYPE

MIGRATIONS_TABLE_DDL

Traits

AuditSink

Pluggable audit sink. Implementations fan audit events out to downstream systems (Kafka topics, Redis pubsub, HTTP webhooks, S3 buckets) for long-term retention or SIEM ingestion. The in-database audit table written by cratestack_sqlx remains the canonical record; sinks are best-effort projections.

AuthProvider

CoolCodec

CoolEnvelope

CreateModelInput

FromPartialPgRow

Companion to sqlx::FromRow that decodes a row projected by .select(...) — i.e. a row where only the named columns are present in the SQL SELECT list. Non-selected fields populate to their type’s Default::default() value.

HttpTransport

IntoColumnName

Anything that can name a single SQL column. Lets coalesce accept both bare &'static str column names and typed FieldRef handles, so callers don’t have to choose between schema-rooted typing and ad-hoc strings at the call site.

IntoSqlValue

KeyProvider

Resolves signing keys by kid (key id). Banks running multi-tenant or rotating keysets implement this so the envelope code never has to know the storage mechanism. Implementations must be constant- time for not-found vs wrong-tenant errors — never use the error message to leak whether a key id exists.

ModelPrimaryKey

Accessor for a model’s primary key. Implemented by the macro on every generated model struct so the batch operations can pair returned rows back to the position of their input PK in the request, producing a BatchItemResult with the right index and a NotFound entry for any requested PK that didn’t come back.

NonceStore

Tracks the nonces of sealed envelopes that have already been verified inside the clock-skew window, so a captured-and-replayed request gets rejected the second time. Banks running multi-replica deployments back this with Redis so the rejection holds cluster-wide.

ProcedureArgs

ProjectionDecoder

ReadSource

Anything a read-path query builder needs to plan and emit SQL.

UpdateModelInput

UpsertModelInput

Input shape for the upsert primitive — INSERT … ON CONFLICT (<pk>) DO UPDATE …. sql_values() must include the primary-key column (so the backend can target the conflict), and primary_key_value() exposes the PK separately so the runtime can issue a SELECT … FOR UPDATE before the upsert to drive Created vs. Updated event / audit semantics.

WriteSource

Anything a write-path query builder needs on top of ReadSource — create defaults, update / delete policy slots, audit + retention + versioning state, upsert column list, emitted event topics.

Functions

apply_pending

Apply every pending migration in the input slice in order. Each runs in its own transaction; checksum drift aborts the whole apply (banks treat drift as a release-process failure for humans, not a silent overwrite).

authorize_procedure

canonical_request_string

Canonical string assembled by the envelope signing path: METHOD\nPATH\nQUERY\nCONTENT-TYPE\nbody-hex. Both seal and verify reconstruct the same string from the same inputs.

coalesce

Build a COALESCE(...) left-hand operand. The returned CoalesceExpr carries the column list; chain a comparator method (.lte, .eq, .is_null, …) to produce a FilterExpr the query builders can consume.

cool_error_from_sqlx

Convert a sqlx::Error to CoolError, preserving structured database error information when available.

create_record_with_executor

decode_codec_request

decode_transport_request_for

encode_codec_response

encode_codec_result

encode_codec_result_with_status

encode_transport_result

encode_transport_result_with_status

encode_transport_result_with_status_for

encode_transport_sequence_result

encode_transport_sequence_result_with_status

encode_transport_sequence_result_with_status_for

enrich_context_from_headers

Enrich a CoolContext with the request id (from traceparent) and the client IP (from Forwarded/X-Forwarded-For). Malformed traceparent headers are silently ignored here — the auth/header-validation layer is the right place to reject them, not the enrichment seam.

ensure_migrations_table

event_topic

find_duplicate_position

Detect duplicate keys in a batch input, loud-failing the whole request when found. Returns the first duplicate (by position) so the surfaced error can name a specific offending index. Linear- time, allocation-only in proportion to the input length.

install_fips_crypto_provider

Crypto provider selection — banks running on FIPS-validated hardware enable the crypto-aws-lc-rs feature. The function below surfaces an error early when the feature is missing so the wrong build can’t slip into a regulated production cluster.

parse_client_ip

Extract the most-specific client IP available from the request headers, falling back to none. Prefers Forwarded (RFC 7239) over the legacy X-Forwarded-For. Banks running behind a single trusted L7 take the leftmost entry; deeper proxy chains must verify and rewrite at the edge.

parse_cuid

parse_emit_attribute

parse_filter_expression

parse_if_match_version

Parse an If-Match header carrying a strong ETag of the form "<int>". Returns None if the header is absent. Returns an error if the header is present but malformed (weak validators, non-integer payloads, etc.).

parse_query_pairs

parse_schema

parse_schema_file

parse_schema_named

parse_traceparent

Extract a W3C traceparent header, returning the trace-id portion when the header is present and well-formed. Returns Ok(None) when absent — callers should mint their own request id in that case so every audit row carries something. The trace-id is the second hyphen-delimited segment per W3C Trace Context; this implementation does not validate the flags/version segments since banks usually rebuild traceparent at the edge anyway.

point

Geographic point (WGS-84 lng/lat). The naming follows the PostGIS ST_MakePoint(x, y) convention — lng is the X axis (longitude), lat is the Y axis (latitude). Don’t accidentally swap them; the engine has no way to detect it and your filter will silently match points across the world.

run_in_isolated_tx

Begin a transaction at the requested isolation level, run body against the live transaction, and commit. On 40001 (serialization_failure) or 40P01 (deadlock_detected) the transaction is rolled back and the body runs again, up to MAX_RETRIES_DEFAULT times. Other errors propagate immediately.

run_in_isolated_tx_with_retries

Same as run_in_isolated_tx but with a caller-chosen retry budget. Banks running long-tail contended writes sometimes want a higher cap (5–10); single-row CAS workflows can drop to 1 to fail fast.

set_version_etag

Insert an ETag header onto a response, formatted as a strong validator over the integer optimistic-locking version.

status

Inspect each migration in migrations against cratestack_migrations and report which are pending / applied / drifted. Use before apply to surface drift to the operator without changing state.

update_record_with_executor

validate_codec_request_headers

validate_codec_response_headers

validate_email

Pragmatic email check: requires exactly one @, non-empty local and domain parts, at least one . in the domain, and no whitespace. Not a full RFC 5322 grammar — that grammar admits forms (quoted local parts, IP literals) banks rarely accept anyway. Reject early; let real KYC flows do deeper validation.

validate_iso4217

ISO 4217 currency codes are 3 ASCII uppercase letters. We do not enforce the registered set here — that table churns and is downstream policy. Banks typically pin allowed currencies via a separate allow-list anyway.

validate_length

validate_range_decimal

Decimal-typed @range enforcement. The parser accepts integer bounds (@range(min: 0, max: 100)) on both Int and Decimal fields; the i64 bounds are promoted to Decimal here so monetary fields can declare the same shape as integer counters. Banks routinely write things like amount Decimal @range(min: 0) to forbid negative amounts at the framework layer — without this, the validator silently no-ops and out-of-range values reach the database.

validate_range_i64

validate_transport_request_headers

validate_transport_request_headers_for

validate_transport_response_headers

validate_transport_response_headers_for

validate_uri

Type Aliases

CoolBody

Body bytes carried through the transport layer.

CoolEventFuture

Decimal