Trait SqlTransport
pub trait SqlTransport {
type Error: Error + 'static;
// Required methods
fn round_trip(
&self,
request: SqlRequest,
) -> impl Future<Output = Result<HttpResponse, Self::Error>>;
fn reads_settled(&self) -> impl Future<Output = ()>;
}Expand description
One round trip to a SQL-over-HTTP endpoint.
Implementors own the TLS stack, the credentials and the retry policy. This
crate owns the SQL and the decoding, and nothing else. The retry policy is
bounded by one obligation, stated on round_trip’s
# Retries: a request that may have reached the endpoint is never sent
twice behind the adapter’s back.
Required Associated Types§
Required Methods§
fn round_trip(
&self,
request: SqlRequest,
) -> impl Future<Output = Result<HttpResponse, Self::Error>>
fn round_trip( &self, request: SqlRequest, ) -> impl Future<Output = Result<HttpResponse, Self::Error>>
Sends request and returns the whole answer.
Written -> impl Future rather than async fn so no Send bound is
implied; a wasm32 implementation over fetch cannot supply one.
§Errors
Returns Self::Error only when no HTTP response was obtained.
§Retries
An implementor MUST NOT transparently re-send a request that may
have reached the endpoint. A retry inside this method is allowed only
when the earlier send provably never left the process — a DNS or
connect failure. Any other failure of a send, a timeout or a connection
reset after the request was written included, MUST surface as
Self::Error, which NeonEventStore::append reports as
AppendError::Store.
ES-43 leans on this. The adapter reports an exhausted run of 40001
answers as AppendError::Busy, a promise that nothing was written, and
that holds only if every answer it read is the answer to the only
send of its request. A transport that re-sent a request whose first
send committed and whose response was lost would hand the adapter the
second send’s 40001, and an append that landed would be reported as
one that did not — which a caller re-running an unconditional append
would then write twice.
§Cancellation, and what this adapter does NOT assume
This adapter makes no assumption that dropping the returned future
cancels the request. NeonEventStore::append awaits this method, so
ES-23’s answer for the store is inherited from whatever an implementor
does here.
An implementor MUST NOT present its transport as cancellation-safe
unless it can guarantee the endpoint never observes an abandoned
request. That is a guarantee about a remote system rather than about a
Future, and dropping a client future is not it: a request already
written to a socket has been sent.
Stated as this adapter’s expectation of a transport rather than as a measured fact — nothing here has measured what any particular endpoint does with a request whose response nobody reads.
fn reads_settled(&self) -> impl Future<Output = ()>
fn reads_settled(&self) -> impl Future<Output = ()>
Resolves once every read-only request this transport dispatched before this call has been answered or has failed.
Required, with no default: a default that resolved at once would compile in every transport and leave the ordering below silently unmet.
§Ordering (ES-11)
NeonEventStore::append awaits this once, before its first attempt, so
no write leaves while a read the same transport sent earlier is
unanswered. An answer follows the statement’s execution, so the read’s
snapshot precedes the write — an order the endpoint itself honours, which
no ordering of two independent requests does.
To make that true an implementor MUST:
- register a request whose
SqlRequest::read_onlyis set beforeround_tripreturns — dispatch is eager; - settle it when the endpoint answers, the send fails or the transport’s
own timeout fires, driven by the transport and never by polling
round_trip’s future — on the host a spawned task, onwasm32thefetchpromise’s settlement callback; - settle it when that future is dropped unanswered, or leave it to settle when the abandoned request does.
A transport whose I/O advances only while its round_trip future is
polled deadlocks an append behind a read the caller polled once
and set aside. The adapter cannot detect that. ReadLedger is the
bookkeeping; ReadLedger::settled is this method’s body. A transport
that never dispatches anything, as NullTransport, returns a ready
future.
The ordering domain is the transport value: a transport whose clones
share one ReadLedger orders every store built over those clones. Two
transports with separate ledgers are not ordered against each other,
and that is the stated limit of this crate’s ES-11 claim (ADR-0087).
A transport that omits this method does not compile:
use core::future::Future;
use happenstance_neon::transport::ReadLedger;
use happenstance_neon::{HttpResponse, SqlRequest, SqlTransport};
struct OnlyRoundTrips {
ledger: ReadLedger,
}
impl SqlTransport for OnlyRoundTrips {
type Error = std::io::Error;
fn round_trip(
&self,
_request: SqlRequest,
) -> impl Future<Output = Result<HttpResponse, Self::Error>> {
core::future::ready(Err(std::io::Error::other("no client")))
}
}Stable rustdoc does not check a compile_fail error code, so the block
above alone would pass on any error. This one is the same impl with the
method added, and it compiles, so the omission is what fails above:
use core::future::Future;
use happenstance_neon::transport::ReadLedger;
use happenstance_neon::{HttpResponse, SqlRequest, SqlTransport};
struct OnlyRoundTrips {
ledger: ReadLedger,
}
impl SqlTransport for OnlyRoundTrips {
type Error = std::io::Error;
fn round_trip(
&self,
_request: SqlRequest,
) -> impl Future<Output = Result<HttpResponse, Self::Error>> {
core::future::ready(Err(std::io::Error::other("no client")))
}
fn reads_settled(&self) -> impl Future<Output = ()> {
self.ledger.settled()
}
}Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".