foundry_common/provider/
runtime_transport.rs

1//! Runtime transport that connects on first request, which can take either of an HTTP,
2//! WebSocket, or IPC transport. Retries are handled by a client layer (e.g.,
3//! `RetryBackoffLayer`) when used.
4
5use crate::{
6    DEFAULT_USER_AGENT, REQUEST_TIMEOUT,
7    provider::{
8        mpp::transport::{LazyMppHttpTransport, lazy_mpp_ws_connect},
9        redact_url,
10    },
11};
12use alloy_json_rpc::{RequestPacket, ResponsePacket};
13use alloy_pubsub::{PubSubConnect, PubSubFrontend};
14use alloy_rpc_types_engine::{Claims, JwtSecret};
15use alloy_transport::{
16    Authorization, BoxTransport, TransportError, TransportErrorKind, TransportFut,
17    utils::guess_local_url,
18};
19use alloy_transport_ipc::IpcConnect;
20use alloy_transport_ws::WsConnect;
21use regex::{Captures, Regex};
22use reqwest::header::{HeaderName, HeaderValue};
23use std::{
24    error::Error as StdError,
25    fmt,
26    path::PathBuf,
27    str::FromStr,
28    sync::{Arc, LazyLock},
29};
30use thiserror::Error;
31use tokio::{
32    runtime::{Handle, Id},
33    sync::RwLock,
34};
35use tower::Service;
36use url::Url;
37
38/// Known MPP-enabled RPC host suffixes.
39///
40/// Endpoints matching these patterns always use the MPP WebSocket transport,
41/// regardless of whether local MPP keys have been discovered.
42const KNOWN_MPP_HOSTS: &[&str] = &[".mpp.tempo.xyz", ".mpp.moderato.tempo.xyz"];
43
44static HTTP_URL_RE: LazyLock<Regex> =
45    LazyLock::new(|| Regex::new(r#"(?i)https?://[^\s<>"']+"#).expect("valid URL regex"));
46
47/// An enum representing the different transports that can be used to connect to a runtime.
48/// Only meant to be used internally by [RuntimeTransport].
49#[derive(Clone, Debug)]
50pub enum InnerTransport {
51    /// HTTP transport with lazy MPP 402 handling.
52    ///
53    /// For known Tempo endpoints, the MPP layer additionally runs the
54    /// `wallet.tempo.xyz` device-code flow on a 402 when no local access key
55    /// is configured (see [`crate::tempo::ensure_access_key`]).
56    Http(LazyMppHttpTransport),
57    /// WebSocket transport
58    Ws(PubSubFrontend),
59    /// IPC transport
60    Ipc(PubSubFrontend),
61}
62
63/// Error type for the runtime transport.
64#[derive(Error, Debug)]
65pub enum RuntimeTransportError {
66    /// Internal transport error
67    #[error("Internal transport error: {0} with {1}")]
68    TransportError(TransportError, String),
69
70    /// Invalid URL scheme
71    #[error("URL scheme is not supported: {0}")]
72    BadScheme(String),
73
74    /// Invalid HTTP header
75    #[error("Invalid HTTP header: {0}")]
76    BadHeader(String),
77
78    /// Invalid file path
79    #[error("Invalid IPC file path: {0}")]
80    BadPath(String),
81
82    /// Invalid construction of Http provider
83    #[error(transparent)]
84    HttpConstructionError(#[from] reqwest::Error),
85
86    /// Invalid JWT
87    #[error("Invalid JWT: {0}")]
88    InvalidJwt(String),
89}
90
91/// Runtime transport that only connects on first request.
92///
93/// A runtime transport is a custom [`alloy_transport::Transport`] that only connects when the
94/// *first* request is made. When the first request is made, it will connect to the runtime using
95/// either an HTTP WebSocket, or IPC transport depending on the URL used.
96/// Retries for rate-limiting and timeout-related errors are handled by an external
97/// client layer (e.g., `RetryBackoffLayer`) when configured.
98#[derive(Clone, Debug)]
99pub struct RuntimeTransport {
100    /// The inner actual transport used.
101    inner: Arc<RwLock<Option<(Id, InnerTransport)>>>,
102    /// The URL to connect to.
103    url: Url,
104    /// The headers to use for requests.
105    headers: Vec<String>,
106    /// The JWT to use for requests.
107    jwt: Option<String>,
108    /// The timeout for requests.
109    timeout: std::time::Duration,
110    /// Whether to accept invalid certificates.
111    accept_invalid_certs: bool,
112    /// Whether to disable automatic proxy detection.
113    no_proxy: bool,
114}
115
116/// A builder for [RuntimeTransport].
117#[derive(Debug)]
118pub struct RuntimeTransportBuilder {
119    url: Url,
120    headers: Vec<String>,
121    jwt: Option<String>,
122    timeout: std::time::Duration,
123    accept_invalid_certs: bool,
124    no_proxy: bool,
125}
126
127impl RuntimeTransportBuilder {
128    /// Create a new builder with the given URL.
129    pub const fn new(url: Url) -> Self {
130        Self {
131            url,
132            headers: vec![],
133            jwt: None,
134            timeout: REQUEST_TIMEOUT,
135            accept_invalid_certs: false,
136            no_proxy: false,
137        }
138    }
139
140    /// Set the URL for the transport.
141    pub fn with_headers(mut self, headers: Vec<String>) -> Self {
142        self.headers = headers;
143        self
144    }
145
146    /// Set the JWT for the transport.
147    pub fn with_jwt(mut self, jwt: Option<String>) -> Self {
148        self.jwt = jwt;
149        self
150    }
151
152    /// Set the timeout for the transport.
153    pub const fn with_timeout(mut self, timeout: std::time::Duration) -> Self {
154        self.timeout = timeout;
155        self
156    }
157
158    /// Set whether to accept invalid certificates.
159    pub const fn accept_invalid_certs(mut self, accept_invalid_certs: bool) -> Self {
160        self.accept_invalid_certs = accept_invalid_certs;
161        self
162    }
163
164    /// Set whether to disable automatic proxy detection.
165    ///
166    /// This can help in sandboxed environments (e.g., Cursor IDE sandbox, macOS App Sandbox)
167    /// where system proxy detection via SCDynamicStore causes crashes.
168    pub const fn no_proxy(mut self, no_proxy: bool) -> Self {
169        self.no_proxy = no_proxy;
170        self
171    }
172
173    /// Builds the [RuntimeTransport] and returns it in a disconnected state.
174    /// The runtime transport will then connect when the first request happens.
175    pub fn build(self) -> RuntimeTransport {
176        RuntimeTransport {
177            inner: Arc::new(RwLock::new(None)),
178            url: self.url,
179            headers: self.headers,
180            jwt: self.jwt,
181            timeout: self.timeout,
182            accept_invalid_certs: self.accept_invalid_certs,
183            no_proxy: self.no_proxy,
184        }
185    }
186}
187
188impl fmt::Display for RuntimeTransport {
189    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
190        write!(f, "RuntimeTransport {}", redact_url(self.url.as_str()))
191    }
192}
193
194impl RuntimeTransport {
195    /// Connects the underlying transport, depending on the URL scheme.
196    pub async fn connect(&self) -> Result<InnerTransport, RuntimeTransportError> {
197        match self.url.scheme() {
198            "http" | "https" => self.connect_http(),
199            "ws" | "wss" => self.connect_ws().await,
200            "file" => self.connect_ipc().await,
201            _ => Err(RuntimeTransportError::BadScheme(self.url.scheme().to_string())),
202        }
203    }
204
205    fn reqwest_headers(&self) -> Result<reqwest::header::HeaderMap, RuntimeTransportError> {
206        let mut headers = reqwest::header::HeaderMap::new();
207
208        // If there's a JWT, add it to the headers if we can decode it.
209        if let Some(jwt) = self.jwt.clone() {
210            let auth =
211                build_auth(jwt).map_err(|e| RuntimeTransportError::InvalidJwt(e.to_string()))?;
212
213            let mut auth_value: HeaderValue =
214                HeaderValue::from_str(&auth.to_string()).expect("Header should be valid string");
215            auth_value.set_sensitive(true);
216
217            headers.insert(reqwest::header::AUTHORIZATION, auth_value);
218        };
219
220        // Add any custom headers.
221        for header in &self.headers {
222            let make_err = || RuntimeTransportError::BadHeader(header.clone());
223
224            let (key, val) = header.split_once(':').ok_or_else(make_err)?;
225
226            headers.insert(
227                HeaderName::from_str(key.trim()).map_err(|_| make_err())?,
228                HeaderValue::from_str(val.trim()).map_err(|_| make_err())?,
229            );
230        }
231
232        if !headers.contains_key(reqwest::header::USER_AGENT) {
233            headers.insert(
234                reqwest::header::USER_AGENT,
235                HeaderValue::from_str(DEFAULT_USER_AGENT)
236                    .expect("User-Agent should be valid string"),
237            );
238        }
239
240        // If MPP_API_KEY is set, attach it as x-api-key for gated MPP proxies.
241        // Does not override an explicit x-api-key header from the user.
242        if !headers.contains_key(HeaderName::from_static("x-api-key"))
243            && let Ok(api_key) = std::env::var("MPP_API_KEY")
244        {
245            let api_key = api_key.trim();
246            if !api_key.is_empty() {
247                let mut value = HeaderValue::from_str(api_key)
248                    .map_err(|_| RuntimeTransportError::BadHeader("MPP_API_KEY".to_string()))?;
249                value.set_sensitive(true);
250                headers.insert(HeaderName::from_static("x-api-key"), value);
251            }
252        }
253
254        Ok(headers)
255    }
256
257    fn reqwest_client_with_headers(
258        &self,
259        headers: reqwest::header::HeaderMap,
260    ) -> Result<reqwest::Client, RuntimeTransportError> {
261        let mut client_builder = reqwest::Client::builder()
262            .timeout(self.timeout)
263            .danger_accept_invalid_certs(self.accept_invalid_certs);
264
265        // Disable automatic proxy detection if requested. This helps in sandboxed environments
266        // (e.g., Cursor IDE sandbox, macOS App Sandbox) where system proxy detection via
267        // SCDynamicStore causes crashes. See: https://github.com/foundry-rs/foundry/issues/12733
268        if self.no_proxy || guess_local_url(self.url.as_str()) {
269            client_builder = client_builder.no_proxy();
270        }
271
272        client_builder = client_builder.default_headers(headers);
273
274        Ok(client_builder.build()?)
275    }
276
277    /// Creates a new reqwest client from this transport.
278    pub fn reqwest_client(&self) -> Result<reqwest::Client, RuntimeTransportError> {
279        self.reqwest_client_with_headers(self.reqwest_headers()?)
280    }
281
282    /// Connects to an HTTP transport with lazy MPP 402 handling.
283    fn connect_http(&self) -> Result<InnerTransport, RuntimeTransportError> {
284        let headers = self.reqwest_headers()?;
285        let client = self.reqwest_client_with_headers(headers.clone())?;
286        Ok(InnerTransport::Http(LazyMppHttpTransport::lazy(client, self.url.clone(), headers)))
287    }
288
289    /// Connects to a WS transport.
290    ///
291    /// Uses the canonical Alloy MPP WebSocket transport when the endpoint is a
292    /// known MPP service.
293    /// Otherwise falls back to alloy's plain [`WsConnect`] with zero overhead.
294    async fn connect_ws(&self) -> Result<InnerTransport, RuntimeTransportError> {
295        let auth = self.jwt.as_ref().and_then(|jwt| build_auth(jwt.clone()).ok());
296
297        let service = if is_known_mpp_endpoint(&self.url) {
298            let mut ws = lazy_mpp_ws_connect(&self.url);
299            if let Some(auth) = auth {
300                ws = ws.with_auth(auth);
301            }
302            ws.into_service().await.map_err(|e| {
303                RuntimeTransportError::TransportError(e, redact_url(self.url.as_str()))
304            })?
305        } else {
306            let mut ws = WsConnect::new(self.url.to_string());
307            if let Some(auth) = auth {
308                ws = ws.with_auth(auth);
309            }
310            ws.into_service().await.map_err(|e| {
311                RuntimeTransportError::TransportError(e, redact_url(self.url.as_str()))
312            })?
313        };
314
315        Ok(InnerTransport::Ws(service))
316    }
317
318    /// Connects to an IPC transport.
319    async fn connect_ipc(&self) -> Result<InnerTransport, RuntimeTransportError> {
320        let path = url_to_file_path(&self.url)
321            .map_err(|_| RuntimeTransportError::BadPath(self.url.to_string()))?;
322        let ipc_connector = IpcConnect::new(path.clone());
323        let ipc = ipc_connector.into_service().await.map_err(|e| {
324            RuntimeTransportError::TransportError(e, path.clone().display().to_string())
325        })?;
326        Ok(InnerTransport::Ipc(ipc))
327    }
328
329    /// Sends a request using the underlying transport.
330    /// If this is the first request, it will connect to the appropriate transport depending on the
331    /// URL scheme. Retries are performed by an external client layer (e.g., `RetryBackoffLayer`),
332    /// if such a layer is configured by the caller.
333    /// For sending the actual request, this action is delegated down to the
334    /// underlying transport through Tower's [tower::Service::call]. See tower's [tower::Service]
335    /// trait for more information.
336    pub fn request(&self, req: RequestPacket) -> TransportFut<'static> {
337        let this = self.clone();
338        Box::pin(async move {
339            let runtime = Handle::current().id();
340            let inner = this.inner.read().await;
341            let transport = if let Some((id, transport)) = &*inner
342                && *id == runtime
343            {
344                transport.clone()
345            } else {
346                drop(inner);
347                let mut inner = this.inner.write().await;
348                // Connections may own tasks and I/O resources on their originating runtime.
349                // Reconnect when a shared client is used from another runtime.
350                if inner.as_ref().is_none_or(|(id, _)| *id != runtime) {
351                    *inner =
352                        Some((runtime, this.connect().await.map_err(TransportErrorKind::custom)?));
353                }
354                inner.as_ref().expect("transport is connected").1.clone()
355            };
356
357            match transport {
358                InnerTransport::Http(mut http) => http
359                    .call(req)
360                    .await
361                    .map_err(|error| redact_http_transport_error(error, &this.url)),
362                InnerTransport::Ws(mut ws) => ws.call(req).await,
363                InnerTransport::Ipc(mut ipc) => ipc.call(req).await,
364            }
365        })
366    }
367
368    /// Convert this transport into a boxed trait object.
369    pub fn boxed(self) -> BoxTransport
370    where
371        Self: Sized + Clone + Send + Sync + 'static,
372    {
373        BoxTransport::new(self)
374    }
375}
376
377/// Returns `true` if `url` points to a known MPP-enabled RPC service.
378fn is_known_mpp_endpoint(url: &Url) -> bool {
379    url.host_str().is_some_and(|host| KNOWN_MPP_HOSTS.iter().any(|suffix| host.ends_with(suffix)))
380}
381
382fn redact_http_transport_error(error: TransportError, endpoint: &Url) -> TransportError {
383    let alloy_json_rpc::RpcError::Transport(TransportErrorKind::Custom(source)) = &error else {
384        return error;
385    };
386    let safe_endpoint = redact_url(endpoint.as_str());
387
388    let mut message = String::new();
389    let mut error: Option<&(dyn StdError + 'static)> = Some(source.as_ref());
390    while let Some(source) = error {
391        if !message.is_empty() {
392            message.push_str(": ");
393        }
394        message.push_str(&source.to_string());
395        error = source.source();
396    }
397    let message = HTTP_URL_RE.replace_all(&message, |captures: &Captures<'_>| {
398        let candidate = &captures[0];
399        let Ok(url) = Url::parse(candidate) else { return candidate.to_owned() };
400        if url.host() == endpoint.host()
401            && url.port_or_known_default() == endpoint.port_or_known_default()
402        {
403            safe_endpoint.clone()
404        } else {
405            candidate.to_owned()
406        }
407    });
408    TransportErrorKind::custom_str(&message)
409}
410
411impl tower::Service<RequestPacket> for RuntimeTransport {
412    type Response = ResponsePacket;
413    type Error = TransportError;
414    type Future = TransportFut<'static>;
415
416    #[inline]
417    fn poll_ready(
418        &mut self,
419        _cx: &mut std::task::Context<'_>,
420    ) -> std::task::Poll<Result<(), Self::Error>> {
421        std::task::Poll::Ready(Ok(()))
422    }
423
424    #[inline]
425    fn call(&mut self, req: RequestPacket) -> Self::Future {
426        self.request(req)
427    }
428}
429
430impl tower::Service<RequestPacket> for &RuntimeTransport {
431    type Response = ResponsePacket;
432    type Error = TransportError;
433    type Future = TransportFut<'static>;
434
435    #[inline]
436    fn poll_ready(
437        &mut self,
438        _cx: &mut std::task::Context<'_>,
439    ) -> std::task::Poll<Result<(), Self::Error>> {
440        std::task::Poll::Ready(Ok(()))
441    }
442
443    #[inline]
444    fn call(&mut self, req: RequestPacket) -> Self::Future {
445        self.request(req)
446    }
447}
448
449fn build_auth(jwt: String) -> eyre::Result<Authorization> {
450    // Decode jwt from hex, then generate claims (iat with current timestamp)
451    let secret = JwtSecret::from_hex(jwt)?;
452    let claims = Claims::default();
453    let token = secret.encode(&claims)?;
454
455    let auth = Authorization::Bearer(token);
456
457    Ok(auth)
458}
459
460#[cfg(windows)]
461fn url_to_file_path(url: &Url) -> Result<PathBuf, ()> {
462    const PREFIX: &str = "file:///pipe/";
463
464    let url_str = url.as_str();
465
466    if let Some(pipe_name) = url_str.strip_prefix(PREFIX) {
467        let pipe_path = format!(r"\\.\pipe\{pipe_name}");
468        return Ok(PathBuf::from(pipe_path));
469    }
470
471    url.to_file_path()
472}
473
474#[cfg(not(windows))]
475fn url_to_file_path(url: &Url) -> Result<PathBuf, ()> {
476    url.to_file_path()
477}
478
479#[cfg(test)]
480mod tests {
481    use super::*;
482    use reqwest::header::HeaderMap;
483    use std::io;
484
485    #[derive(Debug, Error)]
486    #[error("request to https://example.com/private-api-key failed")]
487    struct ProviderError {
488        #[source]
489        source: io::Error,
490    }
491
492    #[test]
493    fn http_transport_errors_preserve_provider_guidance() {
494        let endpoint =
495            Url::parse("https://user:password@example.com/private-api-key?token=secret").unwrap();
496        let error = TransportErrorKind::custom(ProviderError {
497            source: io::Error::other(
498                "Authorize an access key with:\n  cast tempo login --no-browser",
499            ),
500        });
501
502        let report = redact_http_transport_error(error, &endpoint).to_string();
503
504        assert!(report.contains("https://example.com/"));
505        assert!(report.contains("cast tempo login --no-browser"));
506        assert!(!report.contains("password"));
507        assert!(!report.contains("private-api-key"));
508        assert!(!report.contains("secret"));
509    }
510
511    #[test]
512    fn http_transport_errors_redact_endpoint_paths() {
513        let endpoint =
514            Url::parse("https://user:password@example.com/private-api-key?token=secret").unwrap();
515        let error = TransportErrorKind::custom_str(concat!(
516            "request to https://example.com/private-api-key failed: connection refused\n\n",
517            "Authorize an access key with:\n  cast tempo login"
518        ));
519
520        let error = redact_http_transport_error(error, &endpoint);
521        let report = error.to_string();
522
523        assert!(report.contains("https://example.com/"));
524        assert!(!report.contains("password"));
525        assert!(!report.contains("private-api-key"));
526        assert!(!report.contains("secret"));
527        assert!(report.to_lowercase().contains("connection refused"));
528        assert!(report.contains("cast tempo login"));
529    }
530
531    #[test]
532    fn http_transport_errors_redact_normalized_endpoint_variants() {
533        let endpoint =
534            Url::parse("https://user:password@example.com/private-api-key?token=secret").unwrap();
535        let error = TransportErrorKind::custom_str(
536            "request to https://USER:normalized@example.com:443/different%2Fpath?key=other failed",
537        );
538
539        let report = redact_http_transport_error(error, &endpoint).to_string();
540
541        assert!(report.contains("https://example.com/"));
542        assert!(!report.contains("normalized"));
543        assert!(!report.contains("different"));
544        assert!(!report.contains("other"));
545    }
546
547    #[tokio::test]
548    async fn websocket_error_redacts_url_credentials() {
549        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
550        let address = listener.local_addr().unwrap();
551        drop(listener);
552        let url = Url::parse(&format!(
553            "ws://user:password@{address}/private-api-key?token=secret#fragment"
554        ))
555        .unwrap();
556        let transport = RuntimeTransportBuilder::new(url).build();
557
558        let error = transport.connect_ws().await.unwrap_err().to_string();
559
560        assert!(error.contains(&format!("ws://{address}/")));
561        assert!(!error.contains("user"));
562        assert!(!error.contains("password"));
563        assert!(!error.contains("private-api-key"));
564        assert!(!error.contains("secret"));
565    }
566
567    #[tokio::test]
568    async fn test_user_agent_header() {
569        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
570        let url = Url::parse(&format!("http://{}", listener.local_addr().unwrap())).unwrap();
571
572        let http_handler = axum::routing::get(|actual_headers: HeaderMap| {
573            let user_agent = HeaderName::from_str("User-Agent").unwrap();
574            assert_eq!(actual_headers[user_agent], HeaderValue::from_str("test-agent").unwrap());
575
576            async { "" }
577        });
578
579        let server_task = tokio::spawn(async move {
580            axum::serve(listener, http_handler.into_make_service()).await.unwrap()
581        });
582
583        let transport = RuntimeTransportBuilder::new(url.clone())
584            .with_headers(vec!["User-Agent: test-agent".to_string()])
585            .build();
586        let inner = transport.connect_http().unwrap();
587
588        match inner {
589            InnerTransport::Http(http) => {
590                let _ = http.client().get(url).send().await.unwrap();
591
592                // assert inside http_handler
593            }
594            _ => unreachable!(),
595        }
596
597        server_task.abort();
598    }
599}
foundry_common/provider/runtime_transport.rs

foundry_common/provider/
runtime_transport.rs
