Skip to main content

SqlTransport

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§

type Error: Error + 'static

How the transport fails before an HTTP answer exists: DNS, TLS, a rejected fetch, a timeout.

A non-2xx status is not one of these — it is an answer, and it is where Neon puts SQL errors, so it must reach the decoder intact.

Required Methods§

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 = ()>

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_only is set before round_trip returns — 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, on wasm32 the fetch promise’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".

Implementors§