gproxy_channel_api/
transport.rs

1//! Host-provided upstream transport capability available to channel adapters.
2
3use bytes::Bytes;
4
5/// Per-request transport behavior carried through [`http::Request::extensions`].
6///
7/// All request entrypoints consume these options, including WebSocket ones. The
8/// built-in native wreq transport enforces redirect/version policy on the
9/// WebSocket handshake; a WebSocket `total_timeout` remains in force for the
10/// socket's sends and receives. A native WebSocket handshake never sends the
11/// request body, independently of `omit_body`.
12///
13/// The built-in Fetch transport enforces `total_timeout`, `omit_body`, and
14/// `max_redirects = Some(0)`. For its terminal WebSocket round trip, the timeout
15/// covers both Fetch and socket use, while `omit_body` suppresses the initial
16/// application frame. Fetch cannot select an HTTP version or guarantee an exact
17/// positive redirect bound, so it returns [`ClientError::Config`] when either
18/// unsupported constraint is set; callers may leave those fields as `None` to
19/// use the host Fetch policy.
20#[derive(Debug, Clone, Copy, Default)]
21pub struct TransportOptions {
22    pub total_timeout: Option<std::time::Duration>,
23    pub max_redirects: Option<usize>,
24    pub http_version: Option<http::Version>,
25    pub omit_body: bool,
26}
27
28/// Synchronous decoder for a chunked upstream byte stream.
29pub trait ByteStreamDecoder: Send {
30    /// Feed one raw upstream chunk and return any decoded bytes.
31    fn push(&mut self, chunk: &[u8]) -> Vec<u8>;
32
33    /// Flush trailing buffered state at end of stream.
34    fn finish(&mut self) -> Vec<u8>;
35}
36
37/// Transport-level error from the upstream client.
38#[derive(Debug, thiserror::Error)]
39pub enum ClientError {
40    #[error("upstream transport error: {0}")]
41    Transport(String),
42    /// Per-target client configuration is unusable. The host fails the attempt
43    /// instead of silently downgrading proxy or TLS policy.
44    #[error("upstream client config error: {0}")]
45    Config(String),
46}
47
48/// Streaming response body. Native streams are `Send`; wasm streams stay local
49/// because Fetch `ReadableStream` handles are JS-bound.
50#[cfg(not(target_arch = "wasm32"))]
51pub type RespStream =
52    std::pin::Pin<Box<dyn futures_core::Stream<Item = Result<Bytes, ClientError>> + Send>>;
53#[cfg(target_arch = "wasm32")]
54pub type RespStream =
55    std::pin::Pin<Box<dyn futures_core::Stream<Item = Result<Bytes, ClientError>>>>;
56
57/// One application frame received from an upstream WebSocket.
58#[cfg(not(target_arch = "wasm32"))]
59#[derive(Debug)]
60pub enum ConduitFrame {
61    Text(String),
62    Binary(Bytes),
63    Close,
64}
65
66/// An open upstream WebSocket (native only), kept minimal and object-safe.
67#[cfg(not(target_arch = "wasm32"))]
68#[async_trait::async_trait]
69pub trait ConduitSocket: Send {
70    async fn send_text(&mut self, text: String) -> Result<(), ClientError>;
71    async fn send_binary(&mut self, _bytes: Bytes) -> Result<(), ClientError> {
72        Err(ClientError::Config(
73            "binary upstream websocket frames not supported by this client".into(),
74        ))
75    }
76    async fn recv_text(&mut self) -> Option<Result<String, ClientError>>;
77    async fn recv_frame(&mut self) -> Option<Result<ConduitFrame, ClientError>> {
78        self.recv_text()
79            .await
80            .map(|result| result.map(ConduitFrame::Text))
81    }
82    async fn close(&mut self) -> Result<(), ClientError> {
83        Ok(())
84    }
85}
86
87/// Host-owned upstream capability. Implementations apply the resolved proxy,
88/// TLS profile, capture policy, and platform transport; channels only construct
89/// requests and interpret responses.
90#[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)]
91#[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))]
92pub trait UpstreamClient: Send + Sync {
93    async fn send(&self, req: http::Request<Bytes>) -> Result<http::Response<Bytes>, ClientError>;
94
95    async fn send_websocket(
96        &self,
97        _req: http::Request<Bytes>,
98    ) -> Result<http::Response<Bytes>, ClientError> {
99        Err(ClientError::Config(
100            "upstream websocket not supported by this client".into(),
101        ))
102    }
103
104    async fn send_streaming(
105        &self,
106        req: http::Request<Bytes>,
107    ) -> Result<(http::StatusCode, http::HeaderMap, RespStream), ClientError> {
108        let resp = self.send(req).await?;
109        let (parts, body) = resp.into_parts();
110        let once = futures_util::stream::once(async move { Ok::<Bytes, ClientError>(body) });
111        Ok((parts.status, parts.headers, Box::pin(once)))
112    }
113
114    #[cfg(not(target_arch = "wasm32"))]
115    async fn open_websocket(
116        &self,
117        _req: http::Request<Bytes>,
118    ) -> Result<Box<dyn ConduitSocket>, ClientError> {
119        Err(ClientError::Config(
120            "upstream websocket not supported by this client".into(),
121        ))
122    }
123}
gproxy_channel_api/transport.rs

gproxy_channel_api/
transport.rs
