Skip to main content

tycho_client/
stream.rs

1use std::{
2    cmp::max,
3    collections::{HashMap, HashSet},
4    env,
5    time::Duration,
6};
7
8use thiserror::Error;
9use tokio::{
10    sync::{mpsc::Receiver, Semaphore},
11    task::JoinHandle,
12    time::timeout,
13};
14use tracing::{info, warn};
15use tycho_common::{
16    dto::{PaginationLimits, ProtocolSystemsRequestBody},
17    models::{
18        chain_config::{init_chain_registry, ChainConfigRegistry},
19        Chain, ExtractorIdentity,
20    },
21};
22
23use crate::{
24    client_metadata::serialize_client_metadata,
25    deltas::{DeltasClient, DeltasError, DEFAULT_RECONNECTING_SUBSCRIPTION_BUFFER_SIZE},
26    feed::{
27        component_tracker::ComponentFilter,
28        synchronizer::{ProtocolStateSynchronizer, StateSynchronizer, DEFAULT_SNAPSHOT_JITTER},
29        BlockHeader, BlockSynchronizer, BlockSynchronizerError, FeedMessage,
30    },
31    rpc::{HttpRPCClientOptions, ProtocolSystemsParams, RPCClient},
32    HttpRPCClient, WsDeltasClient,
33};
34
35#[derive(Error, Debug)]
36pub enum StreamError {
37    #[error("Error during stream set up: {0}")]
38    SetUpError(String),
39
40    #[error("WebSocket client connection error: {0}")]
41    WebSocketConnectionError(String),
42
43    #[error("BlockSynchronizer error: {0}")]
44    BlockSynchronizerError(String),
45}
46
47#[non_exhaustive]
48#[derive(Clone, Debug)]
49pub enum RetryConfiguration {
50    Constant(ConstantRetryConfiguration),
51}
52
53impl RetryConfiguration {
54    pub fn constant(max_attempts: u64, cooldown: Duration) -> Self {
55        RetryConfiguration::Constant(ConstantRetryConfiguration { max_attempts, cooldown })
56    }
57}
58
59#[derive(Clone, Debug)]
60pub struct ConstantRetryConfiguration {
61    max_attempts: u64,
62    cooldown: Duration,
63}
64
65/// Loads and validates the custom-chain config once, before the stream starts. A missing or
66/// malformed `TYCHO_CHAINS_CONFIG` fails here with an actionable error, rather than degrading to
67/// an empty registry and resurfacing later as a confusing unknown-chain error mid-stream. An unset
68/// env var yields an empty registry (Ok), so built-in-only consumers are unaffected. The validated
69/// registry is best-effort installed as the process-wide one; a prior lazy access may already have
70/// initialised it, in which case the install is a no-op.
71fn validate_chain_config() -> Result<(), StreamError> {
72    let registry = ChainConfigRegistry::load_default()
73        .map_err(|e| StreamError::SetUpError(format!("failed to load custom chain config: {e}")))?;
74    let _ = init_chain_registry(registry);
75    Ok(())
76}
77
78fn validate_subscription_buffer_size(subscription_buffer_size: usize) -> Result<(), StreamError> {
79    if subscription_buffer_size == 0 {
80        return Err(StreamError::SetUpError(
81            "subscription buffer size must be greater than zero".to_string(),
82        ));
83    }
84
85    if subscription_buffer_size > Semaphore::MAX_PERMITS {
86        return Err(StreamError::SetUpError(format!(
87            "subscription buffer size must not exceed {} (Tokio's maximum channel capacity); \
88             choose a value between 1 and {}",
89            Semaphore::MAX_PERMITS,
90            Semaphore::MAX_PERMITS,
91        )));
92    }
93
94    Ok(())
95}
96
97pub struct TychoStreamBuilder {
98    tycho_url: String,
99    chain: Chain,
100    exchanges: HashMap<String, ComponentFilter>,
101    blocklisted_ids: HashSet<String>,
102    block_time: u64,
103    timeout: u64,
104    startup_timeout: Duration,
105    max_missed_blocks: u64,
106    state_sync_retry_config: RetryConfiguration,
107    websockets_retry_config: RetryConfiguration,
108    snapshot_jitter: Duration,
109    no_state: bool,
110    auth_key: Option<String>,
111    no_tls: bool,
112    include_tvl: bool,
113    compression: bool,
114    partial_blocks: bool,
115    max_messages: Option<usize>,
116    client_metadata: HashMap<String, String>,
117    subscription_buffer_size: usize,
118}
119
120impl TychoStreamBuilder {
121    /// Creates a new `TychoStreamBuilder` with the given Tycho URL and blockchain network.
122    /// Initializes the builder with default values for block time and timeout based on the chain.
123    pub fn new(tycho_url: &str, chain: Chain) -> Self {
124        let (block_time, timeout, max_missed_blocks, startup_timeout) =
125            Self::default_timing(&chain);
126        Self {
127            tycho_url: tycho_url.to_string(),
128            chain,
129            exchanges: HashMap::new(),
130            blocklisted_ids: HashSet::new(),
131            block_time,
132            timeout,
133            startup_timeout: Duration::from_secs(startup_timeout),
134            max_missed_blocks,
135            state_sync_retry_config: RetryConfiguration::constant(
136                32,
137                Duration::from_secs(max(block_time / 4, 2)),
138            ),
139            websockets_retry_config: RetryConfiguration::constant(
140                128,
141                Duration::from_secs(max(block_time / 6, 1)),
142            ),
143            snapshot_jitter: DEFAULT_SNAPSHOT_JITTER,
144            no_state: false,
145            auth_key: None,
146            no_tls: true,
147            include_tvl: false,
148            compression: true,
149            partial_blocks: false,
150            max_messages: None,
151            client_metadata: HashMap::new(),
152            subscription_buffer_size: DEFAULT_RECONNECTING_SUBSCRIPTION_BUFFER_SIZE,
153        }
154    }
155
156    /// Returns the default `(block_time, timeout, max_missed_blocks, startup_timeout)` for the
157    /// given blockchain network. Times are in seconds.
158    ///
159    /// A silent synchronizer holds every round while it is Delayed, and stays Delayed for
160    /// `block_time * max_missed_blocks`. The consumer falls about that far behind the chain head
161    /// before the synchronizer goes stale and stops holding rounds. Chains whose blocks come
162    /// faster than their one-second `block_time` therefore use 20 missed blocks, keeping that
163    /// lag near 20 s. The startup timeout is set apart, so large first snapshots keep their time.
164    fn default_timing(chain: &Chain) -> (u64, u64, u64, u64) {
165        match chain {
166            Chain::Ethereum => (12, 36, 50, 600),
167            Chain::Starknet => (2, 8, 50, 100),
168            Chain::ZkSync => (3, 12, 50, 150),
169            Chain::Arbitrum => (1, 9, 20, 100), // Typically closer to 0.25s
170            Chain::Base => (2, 12, 50, 100),
171            Chain::Bsc => (1, 12, 50, 50),
172            Chain::Unichain => (1, 10, 20, 100),
173            Chain::Polygon => (2, 12, 50, 100),  // ~2s block time
174            Chain::Plasma => (1, 10, 20, 100),   // ~1s block time
175            Chain::Robinhood => (1, 5, 20, 100), // Typically closer to 0.1s
176            Chain::Arc => (1, 5, 20, 100),       // Typically closer to 0.5s
177            _ => {
178                let block_time = chain.block_time_secs();
179                (block_time, block_time * 3, 50, block_time * 50)
180            }
181        }
182    }
183
184    /// Adds an exchange and its corresponding filter to the Tycho client.
185    pub fn exchange(mut self, name: &str, filter: ComponentFilter) -> Self {
186        self.exchanges
187            .insert(name.to_string(), filter);
188        self
189    }
190
191    /// Sets the block time for the Tycho client.
192    pub fn block_time(mut self, block_time: u64) -> Self {
193        self.block_time = block_time;
194        self
195    }
196
197    /// Sets the timeout duration for network operations.
198    pub fn timeout(mut self, timeout: u64) -> Self {
199        self.timeout = timeout;
200        self
201    }
202
203    pub fn startup_timeout(mut self, timeout: Duration) -> Self {
204        self.startup_timeout = timeout;
205        self
206    }
207
208    pub fn max_missed_blocks(mut self, max_missed_blocks: u64) -> Self {
209        self.max_missed_blocks = max_missed_blocks;
210        self
211    }
212
213    pub fn websockets_retry_config(mut self, retry_config: &RetryConfiguration) -> Self {
214        self.websockets_retry_config = retry_config.clone();
215        self.warn_on_potential_timing_issues();
216        self
217    }
218
219    pub fn state_synchronizer_retry_config(mut self, retry_config: &RetryConfiguration) -> Self {
220        self.state_sync_retry_config = retry_config.clone();
221        self.warn_on_potential_timing_issues();
222        self
223    }
224
225    /// Sets the maximum random delay before a restarted synchronizer requests a snapshot.
226    ///
227    /// After a restart that needs a snapshot, each synchronizer waits a random time in
228    /// `[0, jitter]` before it requests the snapshot. The first start has no delay. Defaults to
229    /// 60 seconds. A `jitter` below 5 seconds is raised to 5 seconds.
230    pub fn snapshot_jitter(mut self, jitter: Duration) -> Self {
231        self.snapshot_jitter = jitter;
232        self
233    }
234
235    fn warn_on_potential_timing_issues(&self) {
236        let (RetryConfiguration::Constant(state_config), RetryConfiguration::Constant(ws_config)) =
237            (&self.state_sync_retry_config, &self.websockets_retry_config);
238
239        if ws_config.cooldown >= state_config.cooldown {
240            warn!(
241                "Websocket cooldown should be < than state syncronizer cooldown \
242                to avoid spending retries due to disconnected websocket."
243            )
244        }
245    }
246
247    /// Configures the client to exclude state updates from the stream.
248    pub fn no_state(mut self, no_state: bool) -> Self {
249        self.no_state = no_state;
250        self
251    }
252
253    /// Sets the API key for authenticating with the Tycho server.
254    ///
255    /// Optionally you can set the TYCHO_AUTH_TOKEN env var instead. Make sure to set no_tsl
256    /// to false if you do this.
257    pub fn auth_key(mut self, auth_key: Option<String>) -> Self {
258        self.auth_key = auth_key;
259        self.no_tls = false;
260        self
261    }
262
263    /// Adds client-metadata entries sent to the server in the `X-Tycho-Client-Metadata` header.
264    ///
265    /// The metadata is opaque to tycho-client; consumers supply their own keys. Accepts any
266    /// iterator of key/value pairs and inserts each entry, keeping previously set metadata. An
267    /// empty map sends no header. Invalid keys/values and oversized metadata are dropped with a
268    /// warning at `build()` time, sending no header.
269    ///
270    /// Values are self-reported and may surface in the server's metrics and logs. Do not include
271    /// secrets or personally identifiable information.
272    pub fn add_client_metadata<I, K, V>(mut self, metadata: I) -> Self
273    where
274        I: IntoIterator<Item = (K, V)>,
275        K: Into<String>,
276        V: Into<String>,
277    {
278        self.client_metadata.extend(
279            metadata
280                .into_iter()
281                .map(|(k, v)| (k.into(), v.into())),
282        );
283        self
284    }
285
286    /// Disables TLS/SSL for the connection, using `http` and `ws` protocols.
287    pub fn no_tls(mut self, no_tls: bool) -> Self {
288        self.no_tls = no_tls;
289        self
290    }
291
292    /// Configures the client to include TVL in the stream.
293    ///
294    /// If set to true, this will increase start-up time due to additional requests.
295    pub fn include_tvl(mut self, include_tvl: bool) -> Self {
296        self.include_tvl = include_tvl;
297        self
298    }
299
300    /// Disables compression for RPC and WebSocket communication.
301    /// By default, messages are compressed using zstd.
302    pub fn disable_compression(mut self) -> Self {
303        self.compression = false;
304        self
305    }
306
307    /// Enables the client to receive partial block updates (flashblocks).
308    pub fn enable_partial_blocks(mut self) -> Self {
309        self.partial_blocks = true;
310        self
311    }
312
313    /// Sets the number of deltas buffered for each WebSocket subscription.
314    ///
315    /// The default is 128. Values outside Tokio's supported channel range are rejected as setup
316    /// errors when [`build`](Self::build) is called, before any network I/O begins.
317    pub fn subscription_buffer_size(mut self, subscription_buffer_size: usize) -> Self {
318        self.subscription_buffer_size = subscription_buffer_size;
319        self
320    }
321
322    /// Stops the stream after emitting this many messages. Useful for testing or
323    /// triggering a periodic restart after a fixed number of blocks.
324    pub fn max_messages(mut self, n: usize) -> Self {
325        self.max_messages = Some(n);
326        self
327    }
328
329    /// Overrides the maximum number of retry attempts for state synchronizer startup.
330    /// The retry cooldown is derived from the chain's block time and is not affected.
331    pub fn max_retries(mut self, max_retries: u64) -> Self {
332        let cooldown = match &self.state_sync_retry_config {
333            RetryConfiguration::Constant(c) => c.cooldown,
334        };
335        self.state_sync_retry_config = RetryConfiguration::constant(max_retries, cooldown);
336        self
337    }
338
339    /// Blocklist specific component IDs across all registered exchanges.
340    ///
341    /// Blocklisted components are never tracked, regardless of TVL or other
342    /// filter criteria.
343    pub fn blocklisted_ids(mut self, ids: impl IntoIterator<Item = String>) -> Self {
344        self.blocklisted_ids.extend(ids);
345        self
346    }
347
348    /// Constructs the WebSocket delta client from this builder's retry, buffer, and metadata
349    /// configuration.
350    pub(crate) fn build_ws_deltas_client(
351        &self,
352        ws_uri: &str,
353        auth_key: Option<&str>,
354        client_metadata_header: Option<String>,
355    ) -> Result<WsDeltasClient, StreamError> {
356        validate_subscription_buffer_size(self.subscription_buffer_size)?;
357
358        let ws_client = match &self.websockets_retry_config {
359            RetryConfiguration::Constant(config) => WsDeltasClient::new_with_reconnects(
360                ws_uri,
361                auth_key,
362                config.max_attempts,
363                config.cooldown,
364            ),
365        }
366        .map_err(|e| StreamError::SetUpError(e.to_string()))?
367        .with_subscription_buffer_size(self.subscription_buffer_size)
368        .with_client_metadata_header(client_metadata_header);
369
370        Ok(ws_client)
371    }
372
373    /// Builds and starts the Tycho client, connecting to the Tycho server and
374    /// setting up the synchronization of exchange components.
375    pub async fn build(
376        self,
377    ) -> Result<
378        (JoinHandle<()>, Receiver<Result<FeedMessage<BlockHeader>, BlockSynchronizerError>>),
379        StreamError,
380    > {
381        validate_subscription_buffer_size(self.subscription_buffer_size)?;
382
383        if self.exchanges.is_empty() {
384            return Err(StreamError::SetUpError(
385                "At least one exchange must be registered.".to_string(),
386            ));
387        }
388
389        // Serialize client metadata once, before any network I/O. Metadata is best-effort
390        // telemetry, so invalid input is dropped with a warning rather than failing the stream.
391        let metadata_header =
392            serialize_client_metadata(&self.client_metadata).unwrap_or_else(|e| {
393                warn!("Ignoring invalid client metadata: {e}");
394                None
395            });
396
397        // Fail fast on a broken custom-chain config, before any network I/O.
398        validate_chain_config()?;
399
400        // Attempt to read the authentication key from the environment variable if not provided
401        let auth_key = self
402            .auth_key
403            .clone()
404            .or_else(|| env::var("TYCHO_AUTH_TOKEN").ok());
405
406        info!("Running with version: {}", option_env!("CARGO_PKG_VERSION").unwrap_or("unknown"));
407
408        // Determine the URLs based on the TLS setting
409        let (tycho_ws_url, tycho_rpc_url) = if self.no_tls {
410            info!("Using non-secure connection: ws:// and http://");
411            let tycho_ws_url = format!("ws://{}", self.tycho_url);
412            let tycho_rpc_url = format!("http://{}", self.tycho_url);
413            (tycho_ws_url, tycho_rpc_url)
414        } else {
415            info!("Using secure connection: wss:// and https://");
416            let tycho_ws_url = format!("wss://{}", self.tycho_url);
417            let tycho_rpc_url = format!("https://{}", self.tycho_url);
418            (tycho_ws_url, tycho_rpc_url)
419        };
420
421        let ws_client = self.build_ws_deltas_client(
422            &tycho_ws_url,
423            auth_key.as_deref(),
424            metadata_header.clone(),
425        )?;
426        let rpc_client = HttpRPCClient::new(
427            &tycho_rpc_url,
428            HttpRPCClientOptions::new()
429                .with_auth_key(auth_key)
430                .with_compression(self.compression)
431                .with_client_metadata_header(metadata_header),
432        )
433        .map_err(|e| StreamError::SetUpError(e.to_string()))?;
434
435        // Create and configure the BlockSynchronizer
436        let mut block_sync = BlockSynchronizer::new(
437            Duration::from_secs(self.block_time),
438            Duration::from_secs(self.timeout),
439            self.max_missed_blocks,
440        );
441        block_sync.startup_timeout(self.startup_timeout);
442        if let Some(n) = self.max_messages {
443            block_sync.max_messages(n);
444        }
445
446        let requested: HashSet<_> = self.exchanges.keys().cloned().collect();
447        let info = ProtocolSystemsInfo::fetch(&rpc_client, self.chain, &requested).await;
448        info.log_other_available();
449        let dci_protocols = info.dci_protocols;
450
451        // Register each exchange with the BlockSynchronizer
452        for (name, filter) in self
453            .exchanges
454            .into_iter()
455            .map(|(name, filter)| {
456                let filter = if self.blocklisted_ids.is_empty() {
457                    filter
458                } else {
459                    filter.blocklist(self.blocklisted_ids.iter().cloned())
460                };
461                (name, filter)
462            })
463        {
464            info!("Registering exchange: {}", name);
465            let id = ExtractorIdentity { chain: self.chain, name: name.clone() };
466            let uses_dci = dci_protocols.contains(&name);
467            let sync = match &self.state_sync_retry_config {
468                RetryConfiguration::Constant(retry_config) => ProtocolStateSynchronizer::new(
469                    id.clone(),
470                    true,
471                    filter,
472                    retry_config.max_attempts,
473                    retry_config.cooldown,
474                    !self.no_state,
475                    self.include_tvl,
476                    self.compression,
477                    rpc_client.clone(),
478                    ws_client.clone(),
479                    self.block_time + self.timeout,
480                )
481                .with_dci(uses_dci)
482                .with_partial_blocks(self.partial_blocks)
483                .with_snapshot_jitter(self.snapshot_jitter),
484            };
485            block_sync = block_sync.register_synchronizer(id, sync);
486        }
487
488        Self::start_stream(ws_client, block_sync).await
489    }
490
491    /// Connects `ws_client`, starts `block_sync` over it, and spawns a task that closes the
492    /// websocket once it or the block synchronizer ends.
493    ///
494    /// Returns the monitor task and the feed receiver. When the block synchronizer fails to
495    /// start, the websocket is closed before the error is returned.
496    async fn start_stream<S: StateSynchronizer>(
497        ws_client: WsDeltasClient,
498        block_sync: BlockSynchronizer<S>,
499    ) -> Result<
500        (JoinHandle<()>, Receiver<Result<FeedMessage<BlockHeader>, BlockSynchronizerError>>),
501        StreamError,
502    > {
503        let mut ws_jh = ws_client
504            .connect()
505            .await
506            .map_err(|e| StreamError::WebSocketConnectionError(e.to_string()))?;
507
508        // Only the `Err` arm closes the websocket. A caller that drops this future while `run`
509        // is pending, for example under `tokio::time::timeout`, still leaks the connection.
510        let (sync_jh, rx) = match block_sync.run().await {
511            Ok(started) => started,
512            Err(e) => {
513                Self::close_websocket(&ws_client, ws_jh).await;
514                return Err(StreamError::BlockSynchronizerError(e.to_string()));
515            }
516        };
517
518        let handle = tokio::spawn(async move {
519            tokio::select! {
520                res = &mut ws_jh => {
521                    let _ = res.map_err(|e| StreamError::WebSocketConnectionError(e.to_string()));
522                    // The task has ended, so its handle must not be polled again.
523                    if let Err(e) = ws_client.close().await {
524                        warn!(?e, "Failed to close WebSocket client");
525                    }
526                }
527                res = sync_jh => {
528                    Self::close_websocket(&ws_client, ws_jh).await;
529                    res.map_err(|e| StreamError::BlockSynchronizerError(e.to_string())).unwrap();
530                }
531            }
532        });
533
534        Ok((handle, rx))
535    }
536
537    /// Closes the websocket and waits up to one second for its task to end, then aborts it.
538    ///
539    /// The close command only reaches the task while it is connected; one between reconnection
540    /// attempts is aborted instead, so it cannot open another connection after the caller has
541    /// given up on it.
542    async fn close_websocket(
543        ws_client: &WsDeltasClient,
544        mut ws_jh: JoinHandle<Result<(), DeltasError>>,
545    ) {
546        if let Err(e) = ws_client.close().await {
547            warn!(?e, "Failed to close WebSocket client");
548        }
549        match timeout(Duration::from_secs(1), &mut ws_jh).await {
550            Ok(Ok(Ok(()))) => {}
551            Ok(Ok(Err(e))) => warn!(?e, "WebSocket task ended with an error"),
552            Ok(Err(e)) => warn!(?e, "WebSocket task panicked"),
553            Err(_) => {
554                warn!("WebSocket task did not stop after close; aborting it");
555                ws_jh.abort();
556            }
557        }
558    }
559}
560
561/// Result of fetching protocol systems: which protocols use DCI, and which
562/// available protocols on the server were not requested by the client.
563pub struct ProtocolSystemsInfo {
564    pub dci_protocols: HashSet<String>,
565    pub other_available: HashSet<String>,
566}
567
568impl ProtocolSystemsInfo {
569    /// Fetches protocol systems from the server and classifies them: which use DCI,
570    /// and which are available but not in `requested_exchanges`.
571    pub async fn fetch(
572        rpc_client: &HttpRPCClient,
573        chain: Chain,
574        requested_exchanges: &HashSet<String>,
575    ) -> Self {
576        let page_size =
577            ProtocolSystemsRequestBody::effective_max_page_size(rpc_client.compression());
578        let params = ProtocolSystemsParams::new(chain).with_pagination(0, page_size);
579        let response = rpc_client
580            .get_protocol_systems(params)
581            .await
582            .map_err(|e| {
583                warn!(
584                    "Failed to fetch protocol systems: {e}. Skipping protocol availability check."
585                );
586                e
587            })
588            .ok();
589
590        let Some(response) = response else {
591            return Self { dci_protocols: HashSet::new(), other_available: HashSet::new() };
592        };
593
594        if response.total() > page_size {
595            warn!(
596                "Server has {} protocol systems but only {} were fetched (page_size={page_size}). \
597                 Availability info may be incomplete.",
598                response.total(),
599                response.data().protocol_systems().len(),
600            );
601        }
602
603        let available: HashSet<_> = response
604            .data()
605            .protocol_systems()
606            .iter()
607            .cloned()
608            .collect();
609        let other_available = available
610            .difference(requested_exchanges)
611            .cloned()
612            .collect();
613        let mut dci_protocols: HashSet<String> = response
614            .data()
615            .dci_protocols()
616            .iter()
617            .cloned()
618            .collect();
619
620        // TODO(ENG-5302): Remove this fallback once all environments serve
621        // the `dci_protocols` field. Old servers omit the field, which
622        // deserialises as empty — causing clients to skip entrypoint
623        // fetches for DCI protocols.
624        if dci_protocols.is_empty() {
625            const LEGACY_DCI: &[&str] = &[
626                "uniswap_v4_hooks",
627                "vm:curve",
628                "vm:balancer_v2",
629                "vm:balancer_v3",
630                "fluid_v1",
631                "erc4626",
632            ];
633            for name in requested_exchanges {
634                if LEGACY_DCI.contains(&name.as_str()) {
635                    dci_protocols.insert(name.clone());
636                }
637            }
638        }
639
640        Self { dci_protocols, other_available }
641    }
642
643    /// Logs the protocols available on the server that the client didn't subscribe to.
644    pub fn log_other_available(&self) {
645        if !self.other_available.is_empty() {
646            let names: Vec<_> = self
647                .other_available
648                .iter()
649                .cloned()
650                .collect();
651            info!("Other available protocols: {}", names.join(", "));
652        }
653    }
654}
655
656#[cfg(test)]
657mod tests {
658    use std::net::SocketAddr;
659
660    use futures03::StreamExt;
661    use tokio::{net::TcpListener, sync::oneshot};
662
663    use super::*;
664
665    /// Accepts one websocket connection and reports when the client closes it.
666    async fn mock_ws_reporting_close() -> (SocketAddr, oneshot::Receiver<()>) {
667        let server = TcpListener::bind("127.0.0.1:0")
668            .await
669            .expect("localhost bind failed");
670        let addr = server.local_addr().unwrap();
671        let (closed_tx, closed_rx) = oneshot::channel();
672
673        tokio::spawn(async move {
674            let (stream, _) = server
675                .accept()
676                .await
677                .expect("accept failed");
678            let mut websocket = tokio_tungstenite::accept_async(stream)
679                .await
680                .expect("websocket handshake failed");
681            while let Some(Ok(msg)) = websocket.next().await {
682                if msg.is_close() {
683                    break;
684                }
685            }
686            let _ = closed_tx.send(());
687        });
688        (addr, closed_rx)
689    }
690
691    /// A failed `start_stream` must close the websocket it opened. Nothing else can reach it
692    /// once `build` has returned.
693    #[tokio::test]
694    async fn test_start_stream_run_failure() {
695        let (addr, closed_rx) = mock_ws_reporting_close().await;
696        let ws_client = WsDeltasClient::new(&format!("ws://{addr}"), None).unwrap();
697        // No synchronizers registered, so `run` fails with `NoSynchronizers`.
698        let block_sync: BlockSynchronizer<
699            ProtocolStateSynchronizer<HttpRPCClient, WsDeltasClient>,
700        > = BlockSynchronizer::new(Duration::from_secs(1), Duration::from_secs(1), 1);
701
702        let start = tokio::spawn(TychoStreamBuilder::start_stream(ws_client, block_sync));
703
704        // Timed from the start of `start_stream` and shorter than the one-second abort window, so
705        // only a graceful close passes.
706        timeout(Duration::from_millis(500), closed_rx)
707            .await
708            .expect("server should observe the websocket closing")
709            .expect("mock server exited without reporting");
710        let res = start.await.unwrap();
711        assert!(matches!(res, Err(StreamError::BlockSynchronizerError(_))), "got {res:?}");
712    }
713
714    /// A websocket task that ignores the close command, as one between reconnection attempts
715    /// does, is aborted.
716    #[tokio::test(start_paused = true)]
717    async fn test_close_websocket_aborts_unresponsive_task() {
718        let ws_client = WsDeltasClient::new("ws://127.0.0.1:1", None).unwrap();
719        let (alive_tx, alive_rx) = oneshot::channel::<()>();
720        let ws_jh = tokio::spawn(async move {
721            let _alive_tx = alive_tx;
722            std::future::pending::<Result<(), DeltasError>>().await
723        });
724
725        TychoStreamBuilder::close_websocket(&ws_client, ws_jh).await;
726
727        let res = timeout(Duration::from_secs(5), alive_rx)
728            .await
729            .expect("the task should be aborted");
730        assert!(res.is_err(), "the aborted task should drop its sender");
731    }
732
733    #[test]
734    fn test_validate_chain_config_errors_on_broken_file() {
735        // Relies on nextest process isolation: this mutates the process-global env var.
736        std::env::set_var("TYCHO_CHAINS_CONFIG", "/nonexistent/does-not-exist.yaml");
737        let result = validate_chain_config();
738        std::env::remove_var("TYCHO_CHAINS_CONFIG");
739
740        let err = result.expect_err("a missing config file must fail validation");
741        assert!(matches!(err, StreamError::SetUpError(_)));
742        assert!(
743            err.to_string()
744                .contains("custom chain config"),
745            "error should name the custom chain config: {err}"
746        );
747    }
748
749    #[test]
750    fn test_validate_chain_config_ok_when_env_unset() {
751        std::env::remove_var("TYCHO_CHAINS_CONFIG");
752        assert!(
753            validate_chain_config().is_ok(),
754            "an unset env var means no custom chains, which is valid"
755        );
756    }
757
758    #[test]
759    fn test_retry_configuration_constant() {
760        let config = RetryConfiguration::constant(5, Duration::from_secs(10));
761        match config {
762            RetryConfiguration::Constant(c) => {
763                assert_eq!(c.max_attempts, 5);
764                assert_eq!(c.cooldown, Duration::from_secs(10));
765            }
766        }
767    }
768
769    #[test]
770    fn test_stream_builder_retry_configs() {
771        let mut builder = TychoStreamBuilder::new("localhost:4242", Chain::Ethereum);
772        let ws_config = RetryConfiguration::constant(10, Duration::from_secs(2));
773        let state_config = RetryConfiguration::constant(20, Duration::from_secs(5));
774
775        builder = builder
776            .websockets_retry_config(&ws_config)
777            .state_synchronizer_retry_config(&state_config);
778
779        // Verify configs are stored correctly by checking they match expected values
780        match (&builder.websockets_retry_config, &builder.state_sync_retry_config) {
781            (RetryConfiguration::Constant(ws), RetryConfiguration::Constant(state)) => {
782                assert_eq!(ws.max_attempts, 10);
783                assert_eq!(ws.cooldown, Duration::from_secs(2));
784                assert_eq!(state.max_attempts, 20);
785                assert_eq!(state.cooldown, Duration::from_secs(5));
786            }
787        }
788    }
789
790    #[test]
791    fn test_stream_builder_snapshot_jitter() {
792        let builder = TychoStreamBuilder::new("localhost:4242", Chain::Ethereum);
793        assert_eq!(builder.snapshot_jitter, Duration::from_secs(60));
794
795        let builder = builder.snapshot_jitter(Duration::from_secs(10));
796        assert_eq!(builder.snapshot_jitter, Duration::from_secs(10));
797    }
798
799    #[test]
800    fn test_default_stream_builder() {
801        let builder = TychoStreamBuilder::new("localhost:4242", Chain::Ethereum);
802        assert!(builder.compression, "Compression should be enabled by default.");
803        assert!(!builder.partial_blocks, "partial_blocks should be disabled by default.");
804    }
805
806    #[test]
807    fn arc_uses_fast_chain_default_timing() {
808        assert_eq!(TychoStreamBuilder::default_timing(&Chain::Arc), (1, 5, 20, 100));
809    }
810
811    #[test]
812    fn arbitrum_default_timing_outlasts_substreams_reconnect() {
813        assert_eq!(TychoStreamBuilder::default_timing(&Chain::Arbitrum), (1, 9, 20, 100));
814    }
815
816    #[tokio::test]
817    async fn test_no_exchanges() {
818        let receiver = TychoStreamBuilder::new("localhost:4242", Chain::Ethereum)
819            .auth_key(Some("my_api_key".into()))
820            .build()
821            .await;
822        assert!(receiver.is_err(), "Client should fail to build when no exchanges are registered.");
823    }
824
825    #[tokio::test]
826    async fn test_zero_subscription_buffer_size_fails_before_network_io() {
827        let error = TychoStreamBuilder::new("not a valid endpoint", Chain::Ethereum)
828            .exchange("uniswap_v2", ComponentFilter::with_tvl_range(100.0, 100.0))
829            .subscription_buffer_size(0)
830            .build()
831            .await
832            .expect_err("a zero subscription buffer size must be rejected during setup");
833
834        assert!(matches!(error, StreamError::SetUpError(_)));
835        assert!(
836            error
837                .to_string()
838                .contains("subscription buffer size must be greater than zero"),
839            "error should explain how to correct the configuration: {error}"
840        );
841    }
842
843    #[tokio::test]
844    async fn test_too_large_subscription_buffer_size_fails_before_network_io() {
845        let error = TychoStreamBuilder::new("not a valid endpoint", Chain::Ethereum)
846            .exchange("uniswap_v2", ComponentFilter::with_tvl_range(100.0, 100.0))
847            .subscription_buffer_size(usize::MAX)
848            .build()
849            .await
850            .expect_err("an oversized subscription buffer size must be rejected during setup");
851
852        assert!(matches!(error, StreamError::SetUpError(_)));
853        assert!(
854            error
855                .to_string()
856                .contains("subscription buffer size must not exceed"),
857            "error should name the maximum supported capacity: {error}"
858        );
859    }
860
861    #[test]
862    fn test_add_client_metadata_accumulates() {
863        let builder = TychoStreamBuilder::new("localhost:4242", Chain::Ethereum)
864            .add_client_metadata([("fynd_version", "0.57.0")])
865            .add_client_metadata([("preset", "best")]);
866        assert_eq!(
867            builder
868                .client_metadata
869                .get("fynd_version")
870                .map(String::as_str),
871            Some("0.57.0")
872        );
873        assert_eq!(
874            builder
875                .client_metadata
876                .get("preset")
877                .map(String::as_str),
878            Some("best")
879        );
880    }
881
882    #[ignore = "require tycho gateway"]
883    #[tokio::test]
884    async fn test_simple_build() {
885        let token = env::var("TYCHO_AUTH_TOKEN").unwrap();
886        let receiver = TychoStreamBuilder::new("tycho-beta.propellerheads.xyz", Chain::Ethereum)
887            .exchange("uniswap_v2", ComponentFilter::with_tvl_range(100.0, 100.0))
888            .auth_key(Some(token))
889            .build()
890            .await;
891
892        dbg!(&receiver);
893
894        assert!(receiver.is_ok(), "Client should build successfully with exchanges registered.");
895    }
896}