Skip to main content

Module transport

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 Bytes that 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§

HttpResponse
A complete HTTP response, already buffered.
NullTransport
The transport that owns no I/O.
NullTransportError
The only way NullTransport fails.
ReadLedger
The read-only round trips a transport has dispatched and the endpoint has not yet answered.
ReadTicket
Proof that one dispatched read has not settled. Dropping it settles the read.
ReadsSettled
Resolves once every read its ReadLedger had dispatched when it was created has settled.
SqlRequest
Everything one round trip carries.
SqlStatement
One SQL statement and its bound parameters.

Enums§

IsolationLevel
The isolation level a batched request runs at.

Constants§

MAX_RESPONSE_BYTES
The largest response body Neon’s /sql endpoint will return.

Traits§

SqlTransport
One round trip to a SQL-over-HTTP endpoint.