postrust_worker/lib.rs
1//! Postrust's REST API in a Cloudflare Worker, reaching PostgreSQL through
2//! Hyperdrive.
3//!
4//! The request pipeline is `postrust-engine`, the same one the server runs, and
5//! the database driver is `postrust_core::db::PgSocketDb`: the PostgreSQL wire
6//! protocol over a `worker::Socket` to Hyperdrive. That driver is held to
7//! answering exactly as the server's sqlx driver does. Every request runs in a
8//! transaction that sets the token's role and claims, as on the server, so
9//! row-level security applies the same way.
10//!
11//! What is different here, and why:
12//!
13//! * **One connection per request.** A Worker may not share an I/O object
14//! between requests. Hyperdrive pools connections on its side, so opening
15//! one costs little.
16//! * **The schema cache is kept in Workers KV** (`POSTRUST_SCHEMA_CACHE`), so
17//! a cold isolate reads it rather than querying the catalog. It is loaded
18//! live on a miss, refreshed by a Cron Trigger or by an authenticated
19//! `POST /_/reload`, and re-read from KV once `PGRST_WORKER_SCHEMA_TTL`
20//! seconds (default 60) have passed. The KV copy expires after the TTL (at
21//! least 60 seconds), so a migration is seen without a reload too.
22//! * **Rows are capped** at `PGRST_DB_MAX_ROWS`, 1000 unless set, because an
23//! isolate has 128 MB. `unlimited`, under that name or `PGRST_MAX_ROWS`,
24//! lifts the cap.
25//! * **REST only.** No GraphQL, no subscriptions, no `LISTEN`.
26//!
27//! The REST API answers at the root, as PostgREST does: `/todos`, `/rpc/f`.
28//! Configuration is the server's own variables (`PGRST_DB_SCHEMAS`,
29//! `PGRST_DB_ANON_ROLE`, `PGRST_JWT_SECRET`, ...), set as Worker variables or
30//! secrets. See docs/workers.md.
31//!
32//! The crate is on its own `0.x` line. See docs/stability.md.
33
34// The Worker itself is wasm32-only: a Worker's sockets, bindings and futures
35// are JavaScript objects. What it decides without them is in `settings`,
36// built for every target so that it is tested natively.
37#[cfg_attr(not(target_arch = "wasm32"), allow(dead_code))]
38mod settings;
39
40#[cfg(target_arch = "wasm32")]
41mod runtime;