Module transport
Expand description
The one-shot SQL-over-HTTP transport seam.
§Why a trait and not a client
Neon’s /sql endpoint is reached over HTTPS. A real client on the host
target drags in a TLS stack, and the gate’s cargo deny allowlist is
MIT / Apache-2.0 / BSD-2 / BSD-3 / ISC / Unicode-3.0 / Zlib — which the usual
TLS crates are not reliably inside. On wasm32-unknown-unknown there is no
TLS stack at all: the only way out of the sandbox is the host’s fetch, via
wasm-bindgen. Those are two different clients, and neither of them is the
thing this crate exists to prove.
So the transport is a trait — one round trip, one read-settlement wait — and
the crate owns no socket. NullTransport is the in-tree implementation,
and it fails every round trip.
§What the shape of this trait is asserting
SqlTransport::round_trip takes the whole request by value and returns
the whole response body buffered. There is deliberately no way to spell
any of the following, because Neon’s endpoint cannot do them:
- open a session and hold it — there is no connection handle to return;
- read part of a result and decide what to send next inside the same transaction — there is no interactive transaction;
- pull rows incrementally — there is no cursor, so a response is a
Bytesthat either arrived whole or did not arrive.
The one thing the endpoint does offer beyond a single statement is the
non-interactive batch: an array of statements executed server-side inside
one BEGIN/COMMIT, at an isolation level chosen per request. That is
SqlRequest::statements holding more than one element. It is atomic, and it
is still one round trip — but the caller cannot branch on statement n’s
result before statement n + 1 runs. Every capability limit this crate
records comes from that one sentence.
§No async fn in the trait
Spelled -> impl Future<…> rather than async fn, for the same reason
happenstance-core does it: async fn in a public trait fires rustc’s
async_fn_in_trait lint, and the gate runs -D warnings. The desugared form
also makes it explicit that no Send bound is attached — which is the whole
point on wasm32.
Structs§
- Http
Response - A complete HTTP response, already buffered.
- Null
Transport - The transport that owns no I/O.
- Null
Transport Error - The only way
NullTransportfails. - Read
Ledger - The read-only round trips a transport has dispatched and the endpoint has not yet answered.
- Read
Ticket - Proof that one dispatched read has not settled. Dropping it settles the read.
- Reads
Settled - Resolves once every read its
ReadLedgerhad dispatched when it was created has settled. - SqlRequest
- Everything one round trip carries.
- SqlStatement
- One SQL statement and its bound parameters.
Enums§
- Isolation
Level - The isolation level a batched request runs at.
Constants§
- MAX_
RESPONSE_ BYTES - The largest response body Neon’s
/sqlendpoint will return.
Traits§
- SqlTransport
- One round trip to a SQL-over-HTTP endpoint.