cloud_sdk/transport/asynchronous.rs
1//! Runtime-neutral asynchronous transport contract.
2
3use core::future::Future;
4
5use super::{ResponseWriter, TransportRequest};
6
7/// Asynchronous transport over caller-owned request and response buffers.
8///
9/// The contract does not select an executor, allocator, HTTP client, TLS
10/// implementation, clock, or retry policy. Adapter crates document any runtime
11/// requirements they add.
12///
13/// The shared receiver does not create concurrency. Callers may overlap or
14/// spawn returned futures only when the concrete implementation and future
15/// satisfy their executor's `Sync`, `Send`, and lifetime requirements.
16///
17/// Implementations must treat cancellation as an error path: dropping the
18/// returned future must not expose a partially initialized response as a
19/// successful response. Implementations handling secret response
20/// data should also clear temporary owned storage when the future is dropped.
21pub trait AsyncTransport {
22 /// Transport-specific failure.
23 type Error;
24
25 /// Sends one request and initializes the complete response body in the
26 /// caller buffer.
27 ///
28 /// Implementations must use [`ResponseWriter::begin_attempt`]. Response
29 /// mutation and commitment are available only through the returned guard,
30 /// which clears state when the future is cancelled.
31 fn send<'transport, 'request, 'writer>(
32 &'transport self,
33 request: TransportRequest<'request>,
34 response: &'writer mut ResponseWriter<'_>,
35 ) -> impl Future<Output = Result<(), Self::Error>> + Send + 'writer
36 where
37 'transport: 'writer,
38 'request: 'writer;
39}