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