Athena Gateway Crate

crates/athena-gateway is the portability seam for Athena gateway request and response contracts. The crate is intentionally runtime-light: it should own shapes, parsing, normalization, and other request-domain helpers that can be shared across the main server, future adapters, SDK-side tooling, and later crate splits.

What Lives Here Today

• Gateway CRUD and RPC request DTOs.
• Deferred gateway queue payloads and operation-kind constants.
• Normalized gateway error envelope types and public error codes.
• Schema and table normalization helpers used by gateway request parsers.
• Relation-select compatibility rewrite helpers used to translate bounded /gateway/query SQL into structured-fetch request bodies without pulling in Actix or runtime state.
• Structured-fetch SQL compilation, relation metadata loading, and portable execution helpers for Postgres-backed structured gateway reads.
• Metadata-aware fetch condition builders that turn gateway equality filters into athena-query conditions and resolve information_schema type hints through the extracted Postgres driver helpers.
• PostgREST compatibility parsing and filter conversion for the legacy /rest/v1/* shim, with the Actix request wrapper left in athena_rs.
• Gateway authorization right naming and wildcard matching helpers used by /gateway/*, storage proxy, and Typesense proxy authorization checks.
• RPC compatibility parsing for legacy /rpc/{function_name} GET and wrapped POST surfaces, with route execution left in athena_rs.
• Delete-side resource-ID lookup planning and explicit column normalization for /gateway/delete, with backend-specific fallback column discovery still left in athena_rs.
• Fetch singleflight coordination for /gateway/fetch, with the runtime wait timeout and global wrapper left in athena_rs.
• Gateway resource-ID fallback resolution heuristics used by insert, delete, and legacy PostgREST upsert paths, with the live Scylla schema query adapter left in athena_rs.
• Fetch body preprocessing for /gateway/fetch and /gateway/data, including the legacy-versus-structured body split, normalized table selector resolution, pagination defaults, and condition/sort parsing.
• Legacy GET /data compatibility planning, including query-parameter translation into the delegated fetch JSON body plus its cache-key derivation.
• /gateway/query request parsing and planning, including SQL normalization, schema validation, bounded relation-select rewrite planning, and derived read-right calculation before the runtime adapter picks a backend.
• /gateway/update request planning, including qualified table resolution, update-payload extraction, room_id condition coercion, condition sorting, and derived table-based write-right calculation before the runtime adapter picks a backend.
• /gateway/delete request planning, including trimmed table/resource validation, qualified table resolution, explicit resource_id column normalization, lookup-table planning, and derived table-based delete-right calculation before the runtime adapter picks a backend.
• Fetch-domain request helpers:
  • SortOptions
  • PostProcessingConfig
  • TimeGranularity
  • AggregationStrategy
  • fetch cache-key hashing
  • room_id condition validation and coercion
  • grouped-row post-processing and cumulative aggregation
  • structured-fetch plan types, request parsing, and select-string compatibility parsing
• Raw SQL gateway request DTOs and portable execution-mode enums for /gateway/query and /query/sql.

What Still Stays In athena_rs

• Actix route handlers and HttpResponse construction.
• Pool resolution, runtime client registries, and backend selection.
• Gateway auth enforcement and request logging.
• Route-level pool resolution and HTTP response construction.

Current Extraction Rule

Use athena-gateway when code is about the gateway contract itself and can run without AppState, HttpRequest, or runtime registries. Direct sqlx::PgPool lookups are acceptable here when the logic is still contract-driven and only needs extracted driver metadata helpers.

Keep code in athena_rs when it needs:

• Actix types
• runtime state
• pool/client registries
• backend selection
• background worker wiring

Near-Term Direction

The next gateway slices should keep following the same boundary:

1. Move portable request parsing, identifiers, and contract-level helpers first.
2. Leave thin adapters in src/api/gateway/* for HTTP concerns.
3. Keep bounded SQL compatibility rewrites here when they only transform gateway grammar into portable structured-fetch inputs.
4. Keep PostgREST grammar parsing here when it only depends on query strings, headers, and extracted query/driver helper crates.
5. Delay runtime-heavy concerns until the dedicated crates exist:
   • athena-actix
   • athena-driver
   • athena-api-key