Crate athena_gateway 

Portable gateway-domain contracts for Athena.

This crate intentionally stays free of Actix and runtime registry concerns. It owns the reusable request/response DTOs and normalization helpers that power /gateway/* routes across adapters, SDKs, deferred queue payloads, and future server splits.

The current scope covers:

• gateway operation kinds,
• fetch/insert/update/delete/rpc request bodies,
• delete-side resource-ID lookup planning and explicit column normalization,
• deferred gateway queue payloads,
• gateway authorization right naming and wildcard matching helpers,
• fetch request parsing and post-processing helpers,
• fetch body preprocessing for legacy and structured gateway fetch requests,
• legacy GET /data compatibility planning and cache-key derivation,
• fetch singleflight coordination for cache-equivalent gateway reads,
• metadata-aware fetch condition builders and stats-rollup type fallbacks,
• PostgREST compatibility parsing and filter conversion helpers,
• RPC compatibility parsing for legacy /rpc/{function_name} routes,
• gateway resource-ID fallback resolution heuristics for insert/delete/upsert paths,
• row-response metadata,
• schema/table normalization helpers for gateway requests,
• /gateway/query request parsing, normalization, and bounded compatibility planning,
• /gateway/update request planning, condition coercion, and derived write-right helpers,
• /gateway/delete request planning, resource-ID lookup planning, and derived delete-right helpers,
• relation-select compatibility rewrite helpers for bounded /gateway/query SQL-to-structured-fetch translation,
• structured-fetch SQL compilation, metadata loading, and execution helpers.

Structs

GatewayApiRequest

Unified API-level gateway request wrapper.

GatewayDeferredRequest

Canonical deferred queue payload for gateway operations.

GatewayDeleteRequest

Canonical /gateway/delete request shape.

GatewayDeleteRequestPlan

Portable delete request plan derived from the canonical /gateway/delete payload.

GatewayDeleteResourceIdPlan

Portable delete-side resource ID lookup plan.

GatewayErrorData

Normalized gateway error response data.

GatewayErrorEnvelope

Normalized gateway error response envelope.

GatewayFetchBodyPlan

Parsed fetch-body plan used by the runtime adapter to authorize and execute a read.

GatewayFetchConditionError

Structured validation error returned while parsing fetch request conditions.

GatewayFetchRequest

Canonical /gateway/fetch request shape.

GatewayFetchSingleflight

Stateful coordinator that deduplicates concurrent gateway fetches per cache key.

GatewayGetFetchCompatibilityPlan

Query-parameter-derived plan for the legacy GET /data compatibility route.

GatewayInFlightFetch

Tracks a single in-flight fetch result and wakes followers when it completes.

GatewayInsertRequest

Canonical /gateway/insert request shape.

GatewayQueryCompatibilityPlan

Structured rewrite plan for relation-select compatibility queries.

GatewayQueryRequestPlan

Portable request plan derived from a canonical /gateway/query payload.

GatewayRelationSelectRewrite

Structured-fetch rewrite result produced from a bounded compatibility SQL query.

GatewayRelationSelectTableRef

Normalized table selector derived from a relation-select compatibility query.

GatewayRequestCondition

Simple equality filter used by gateway CRUD requests.

GatewayRowsMeta

Shared response metadata for query-like gateway responses.

GatewayRowsResponse

Shared row-based gateway success response.

GatewayRpcFilter

Canonical RPC filter clause.

GatewayRpcOrder

Canonical RPC ordering clause.

GatewayRpcRequest

Canonical /gateway/rpc request shape.

GatewaySqlExecutionRequest

Canonical /query/sql + /gateway/sql request shape.

GatewaySqlRequest

Canonical /gateway/query request shape.

GatewayUpdateRequest

Canonical /gateway/update request shape.

GatewayUpdateRequestPlan

Portable request plan derived from a canonical /gateway/update payload.

OrderSpec

Parsed order query parameter.

PostProcessingConfig

Gateway fetch post-processing configuration parsed from request bodies.

PostgrestFilter

One parsed PostgREST filter expression.

PostgrestQuery

Normalized PostgREST query components derived from a request URL.

SortOptions

Sort options for gateway fetch requests.

StructuredColumnField

Column projection inside a structured fetch query.

StructuredFilter

Structured filter clause.

StructuredGatewayFetchPlan

Parsed structured gateway fetch request plus the normalized root selector.

StructuredOrderBy

Structured ordering clause.

StructuredRelationField

Nested relation projection inside a structured fetch query.

StructuredSelectQuery

Parsed structured fetch query.

Enums

AggregationStrategy

Supported aggregation strategies for grouped fetch results.

GatewayApiRequestPayload

API-level operation variants for normalized gateway requests.

GatewayDeleteRequestPlanError

Validation errors for portable /gateway/delete planning.

GatewayFetchBodyPlanError

Body-preprocessing validation errors for gateway fetch request parsing.

GatewayFetchSingleflightRole

Role assigned when a caller acquires a singleflight slot for a cache key.

GatewayGetFetchCompatibilityError

Validation errors for legacy GET /data query parsing.

GatewayOperationKind

Domain-owned operation kinds for gateway handlers.

GatewayQueryRequestParseError

Validation errors for parsing /gateway/query request bodies.

GatewayQueryRequestPlanError

Validation errors for portable /gateway/query planning.

GatewayRpcFilterOperator

Supported filter operators for RPC request pushdown.

GatewaySqlExecutionMode

Portable execution modes accepted by gateway SQL request payloads.

GatewayUpdateRequestPlanError

Validation errors for portable /gateway/update planning.

PostgrestFilterOperator

PostgREST filter operators supported by the legacy REST shim.

StructuredFilterOperator

Supported filter operators in structured fetch requests.

StructuredJoinKind

Join behavior for nested structured relation selections.

StructuredSelectField

Field projection entry in a structured fetch query.

StructuredSelectOperation

Structured-fetch operation kinds currently accepted by the public contract.

StructuredSortDirection

Supported sort directions in structured fetch requests.

TimeGranularity

Granularity options used for grouping timestamp rows during post-processing.

Constants

GATEWAY_DEFERRED_KIND_DELETE

GATEWAY_DEFERRED_KIND_FETCH

GATEWAY_DEFERRED_KIND_INSERT

GATEWAY_DEFERRED_KIND_QUERY

GATEWAY_DEFERRED_KIND_RPC

GATEWAY_DEFERRED_KIND_UPDATE

GATEWAY_ERROR_CODE_INTERNAL_ERROR

GATEWAY_ERROR_CODE_SERVICE_UNAVAILABLE

GATEWAY_ERROR_CODE_VALIDATION_FAILED

Functions

apply_post_processing

Applies grouping and aggregation rules to fetched gateway rows.

build_fetch_hashed_cache_key

Builds the hashed cache key used for POST gateway fetch requests.

build_fetch_hashed_cache_key_legacy8

Builds the legacy 8-character hashed cache key used during fetch cache cutovers.

build_gateway_delete_request_plan

Builds the portable /gateway/delete request plan from the canonical request payload.

build_gateway_fetch_body_plan

Builds the portable request-domain plan for a fetch body.

build_gateway_get_fetch_compatibility_plan

Builds the compatibility fetch plan for GET /data.

build_gateway_query_request_plan

Builds the portable /gateway/query execution plan.

build_gateway_update_request_plan

Builds the portable /gateway/update execution plan from a parsed JSON body.

build_structured_fetch_cache_key

Builds the structured fetch cache key from the normalized plan and compiled SQL.

build_structured_fetch_plan

Builds a parsed structured fetch plan when the request body uses the structured read contract.

camel_to_snake_case

Converts camelCase or PascalCase identifiers to snake_case.

coerce_room_id_eq_value

Coerces eq_value to a JSON number when the column is room_id / roomId.

convert_postgrest_filter_to_condition

Converts one parsed PostgREST filter into an Athena query condition.

convert_postgrest_filters_to_conditions

Converts parsed PostgREST filters into Athena query-builder conditions.

convert_postgrest_or_filter_groups_to_conditions

Converts OR filter groups into Athena query-builder condition groups.

delete_request_required_right

Derives the table-name-based delete right hint for /gateway/delete.

delete_right_for_resource

Required delete right for a specific resource or the gateway-wide fallback.

execute_structured_fetch_sql

Executes compiled structured fetch SQL against the selected Postgres pool.

extract_update_payload

Extracts normalized update payload from gateway body.

find_closest_uuid_column

Finds the UUID column with the smallest Levenshtein distance to table_name.

get_resource_id_key_with_uuid_loader

Resolves the fallback resource-ID column for table_name using an injected UUID-column loader.

merge_column_types_with_stats_fallback

Merges resolve_where_column_types output with static descriptors for client_statistics / client_table_statistics so string JSON filter values get correct cast handling and avoid Postgres 42883.

missing_required_rights

Returns the subset of required_rights not covered by granted_rights.

normalize_column_name

Normalizes a gateway column name, optionally forcing snake_case.

normalize_delete_resource_id_column_name

Normalizes and validates an explicit delete resource_id column selector.

normalize_delete_resource_id_lookup_table

Normalizes the table name used by metadata-backed delete resource-ID lookup.

normalize_gateway_schema_name

Validates and normalizes an optional schema name.

parse_columns_from_body

Parses columns from gateway body, supporting both CSV and JSON arrays.

parse_conditions_from_body

Parses request conditions from JSON body.

parse_gateway_fetch_conditions

Parses conditions from a gateway fetch payload.

parse_gateway_query_request_body

Parses the canonical /gateway/query request payload from raw bytes.

parse_postgrest_query

Parses a Supabase/PostgREST query into a normalized representation that can be mapped to Athena/Postgres operations.

parse_room_id_value

Parses eq_value for a room_id condition.

parse_rpc_argument_value

Parses a scalar or array literal from the compatibility RPC grammar.

parse_rpc_filter_expression

Parses a compact filter expression like eq.name or in.(a,b).

parse_rpc_order

Parses a compact column.asc / column.desc order clause.

parse_sort_options_from_body

Parses optional sortBy or sort_by from a fetch request body.

parse_uuid_columns_from_schema_rows

Parses Scylla system_schema.columns rows into UUID column names.

plan_delete_resource_id_resolution

Builds the portable delete resource-ID resolution plan for a request.

qualify_gateway_table_name

Builds the normalized schema.table target used by downstream SQL builders.

query_right

Right required for /gateway/query.

read_right_for_resource

Required read right for a specific resource or the gateway-wide fallback.

render_structured_fetch_sql

Loads relation metadata and compiles SQL for a parsed structured fetch plan.

resolve_where_column_types

Resolves information_schema.columns types for table_name, honoring the gateway’s optional schema.table prefix flag.

right_matches

Returns true when granted satisfies required, including wildcard forms.

rpc_request_from_get_compat

Parses the legacy GET /rpc/{function_name} query string into a canonical RPC request.

rpc_request_from_post_compat

Parses the legacy POST /rpc/{function_name} body into a canonical RPC request.

rpc_right

Right required for /gateway/rpc.

schema_name_from_body

Reads either schema_name or the compatibility alias schema from a request body.

storage_proxy_right

Right required for /storage/* proxy operations.

to_query_conditions

Converts request conditions into Postgres query conditions.

to_query_conditions_with_types

Like to_query_conditions, but stamps a Postgres placeholder cast on each condition based on the target column’s type descriptor (from information_schema.columns).

try_rewrite_relation_select_query

Rewrites a bounded relation-select compatibility query into a structured-fetch request body.

typesense_proxy_right

Right required for /typesense/* proxy/search operations.

write_right_for_resource

Required write right for a specific resource or the gateway-wide fallback.

Type Aliases

GatewayFetchRowsResult

Shared fetch result shape propagated between singleflight leader/follower tasks.

RequestCondition

Internal representation of a simple equality filter provided by gateway requests.