Skip to main content

tycho_simulation/price_level_stream/
stream.rs

1use std::{
2    collections::{HashMap, HashSet},
3    pin::Pin,
4    time::{Duration, Instant, SystemTime, UNIX_EPOCH},
5};
6
7use async_stream::stream;
8use num_bigint::BigUint;
9use tokio_stream::{Stream, StreamExt};
10use tycho_common::{models::token::Token, Bytes};
11
12use super::{
13    config::{
14        canonical_pamm_address, default_denied_pamms, default_served_pamms, PriceLevelStreamConfig,
15        DEFAULT_AUTO_DETECTED_GAS_COST,
16    },
17    titan::{
18        self, ConnectionSettings, TitanQuoteStreamMessage, TITAN_PRICE_LEVEL_URL,
19        TITAN_PRICE_LEVEL_URL_ENV, TITAN_QUOTE_STREAM_URL, TITAN_QUOTE_STREAM_URL_ENV,
20    },
21    tracker::{FreshnessTracker, Now, TrackerSettings, DEFAULT_STALE_AFTER},
22};
23use crate::protocol::models::Update;
24
25/// Static attribute under which each emitted component carries its pAMM venue address.
26pub const PAMM_ADDRESS_ATTRIBUTE: &str = "pamm_address";
27
28/// The longest [`stale_after`](PriceLevelStreamBuilder::stale_after) the builder accepts;
29/// longer values are capped to it. Quotes target the block being built, so serving quotes for
30/// longer than this is never intended, and deadlines this far ahead stay representable on the
31/// monotonic clock.
32pub const MAX_STALE_AFTER: Duration = Duration::from_secs(3600);
33
34/// Builds a stream of [`Update`]s from the Titan pAMM price level WebSocket.
35///
36/// A new builder serves no pAMMs: register the known venues via
37/// [`with_known_pamms`](Self::with_known_pamms), individual ones via
38/// [`add_pamm`](Self::add_pamm), or opt into serving unknown streamed venues via
39/// [`auto_detect`](Self::auto_detect); [`with_tokens`](Self::with_tokens) provides the token
40/// metadata pairs are interpreted with.
41///
42/// One component is emitted per (pAMM, token pair), identified by the concatenation
43/// `pamm ++ token0 ++ token1` (tokens sorted ascending), under the protocol system
44/// `fallback:{pamm}` — or `pricelevelstream:{pamm}` after
45/// [`without_fallback_router`](Self::without_fallback_router). The venue address is exposed
46/// through the [`PAMM_ADDRESS_ATTRIBUTE`] static attribute for downstream encoding.
47#[expect(
48    clippy::struct_excessive_bools,
49    reason = "public API; the independent builder switches replaced by enums are a breaking change"
50)]
51pub struct PriceLevelStreamBuilder {
52    /// The venues to serve, keyed by canonical public identity.
53    registry: HashMap<Bytes, PriceLevelStreamConfig>,
54    /// The venues not to serve, by canonical public identity.
55    denied: HashSet<Bytes>,
56    tokens: HashMap<Bytes, Token>,
57    url: Option<String>,
58    /// See [`quote_stream_endpoint`](Self::quote_stream_endpoint).
59    quote_stream_url: Option<String>,
60    /// See [`without_simulation_overrides`](Self::without_simulation_overrides).
61    simulation_overrides: bool,
62    auto_detect: bool,
63    auto_detected_gas_cost: Option<BigUint>,
64    connection: ConnectionSettings,
65    /// Whether components are emitted under the `fallback:` family, executed through
66    /// `TychoFallbackRouter`, instead of the direct `pricelevelstream:` family.
67    fallback_router: bool,
68    /// See [`stale_after`](Self::stale_after).
69    stale_after: Duration,
70    /// See [`without_quote_guard`](Self::without_quote_guard).
71    quote_guard: bool,
72}
73
74impl Default for PriceLevelStreamBuilder {
75    fn default() -> Self {
76        Self {
77            registry: HashMap::new(),
78            denied: HashSet::new(),
79            tokens: HashMap::new(),
80            url: None,
81            quote_stream_url: None,
82            simulation_overrides: true,
83            auto_detect: false,
84            auto_detected_gas_cost: None,
85            connection: ConnectionSettings::default(),
86            fallback_router: true,
87            stale_after: DEFAULT_STALE_AFTER,
88            quote_guard: true,
89        }
90    }
91}
92
93impl PriceLevelStreamBuilder {
94    pub fn new() -> Self {
95        Self::default()
96    }
97
98    /// Enables serving pAMMs that are not registered via
99    /// [`with_known_pamms`](Self::with_known_pamms) or [`add_pamm`](Self::add_pamm)
100    /// (disabled by default).
101    ///
102    /// When enabled, any unknown streamed venue — except denied ones (see
103    /// [`deny_pamm`](Self::deny_pamm)) — is served under its full lowercase hex address
104    /// as the name, with the default gas cost. A venue's protocol system therefore changes from
105    /// the address form (`pricelevelstream:{0xaddress}`) to a name (`pricelevelstream:{name}`)
106    /// once it gets registered — via [`add_pamm`](Self::add_pamm) or a release's
107    /// [`default_served_pamms`] recognizing it; the name-independent identifiers — the component id
108    /// and the [`PAMM_ADDRESS_ATTRIBUTE`] — stay stable across such renames.
109    pub fn auto_detect(mut self, enabled: bool) -> Self {
110        self.auto_detect = enabled;
111        self
112    }
113
114    /// Overrides the per-swap gas cost that auto-detected pAMMs (see
115    /// [`auto_detect`](Self::auto_detect)) are served with. Defaults to the maximum over the
116    /// known venue profiles, as the conservative choice. Registered venues are unaffected —
117    /// their gas cost comes from their [`PriceLevelStreamConfig`].
118    pub fn auto_detected_gas_cost(mut self, gas_cost: BigUint) -> Self {
119        self.auto_detected_gas_cost = Some(gas_cost);
120        self
121    }
122
123    /// Overrides the stream endpoint, e.g. to connect to a closer Titan region than the default
124    /// (see <https://docs.titanbuilder.xyz/propamms/takers>). Without it, the
125    /// `TITAN_PAMM_PRICE_LEVEL_URL` environment variable is used when set, else the built-in
126    /// default.
127    ///
128    /// This sets the price level socket only; the quote stream socket has its own
129    /// [`quote_stream_endpoint`](Self::quote_stream_endpoint) and its own default. To change
130    /// region, set both: a region's quote stream matches that region's price levels, and nobody
131    /// has tested whether it matches another region's. `build` logs a WARN when only one of the
132    /// two is customized.
133    pub fn endpoint(mut self, url: impl Into<String>) -> Self {
134        self.url = Some(url.into());
135        self
136    }
137
138    /// Sets the endpoint of the quote stream socket, which carries the account state Titan priced
139    /// the books on. Point it at the same Titan region as [`endpoint`](Self::endpoint). Without
140    /// it, the stream uses the `TITAN_PAMM_QUOTE_STREAM_URL` environment variable when set, else
141    /// the built-in default. [`without_simulation_overrides`](Self::without_simulation_overrides)
142    /// wins in either call order: with it, this setting has no effect.
143    pub fn quote_stream_endpoint(mut self, url: impl Into<String>) -> Self {
144        self.quote_stream_url = Some(url.into());
145        self
146    }
147
148    /// Emits states without simulation overrides, and connects no quote stream socket.
149    ///
150    /// By default the stream also reads Titan's quote stream, which publishes the account state
151    /// Titan simulated each venue on to price its books, and attaches it to the matching states
152    /// (see [`simulation_overrides`](super::state::PriceLevelStreamState::simulation_overrides)).
153    /// A consumer that never simulates a swap with `eth_call` does not need it; opting out spares
154    /// the second connection and the memory the held entries use. Quoting is the same either way:
155    /// overrides never change a quote.
156    pub fn without_simulation_overrides(mut self) -> Self {
157        self.simulation_overrides = false;
158        self
159    }
160
161    /// Overrides how long a single connection attempt may take before it is aborted and retried
162    /// (default: 10s), so a hung TCP/TLS handshake cannot block the stream forever. Applies to
163    /// both Titan sockets, which are connected and maintained independently.
164    pub fn connect_timeout(mut self, timeout: Duration) -> Self {
165        self.connection.connect_timeout = timeout;
166        self
167    }
168
169    /// Overrides the longest gap between parsed Titan messages tolerated before the connection is
170    /// treated as dead and re-established (default: 10s). Titan pushes one message per second and
171    /// sends no keepalives, so a multi-second silence means a stalled or half-open connection.
172    /// Control frames and unparsable text do not reset this timeout, and neither does the time
173    /// the consumer spends between polls: the gap is measured while the stream waits on the
174    /// socket. Applies to both Titan sockets, each measured on its own traffic.
175    pub fn read_idle_timeout(mut self, timeout: Duration) -> Self {
176        self.connection.read_idle_timeout = timeout;
177        self
178    }
179
180    /// Overrides the cap on the exponential reconnect backoff of `2^attempt` seconds
181    /// (default: 32s). Applies to both Titan sockets, each backing off on its own failures.
182    pub fn max_backoff(mut self, max_backoff: Duration) -> Self {
183        self.connection.max_backoff = max_backoff;
184        self
185    }
186
187    /// Registers a pAMM to be served under the given configuration, overriding any default,
188    /// denied, or auto-detected one for the same venue.
189    ///
190    /// The configured address may be either of a venue's addresses — the one Titan streams its
191    /// books under or its canonical public identity (see
192    /// [`PAMM_ADDRESS_ALIASES`](super::config::PAMM_ADDRESS_ALIASES)) — because it is normalized
193    /// to the public identity, which is what the emitted components then carry. Between
194    /// [`add_pamm`](Self::add_pamm) and [`deny_pamm`](Self::deny_pamm) for the same venue, the
195    /// later call wins, whichever of its addresses each named; the defaults applied by
196    /// [`with_known_pamms`](Self::with_known_pamms) never override either, in any call order.
197    pub fn add_pamm(mut self, config: PriceLevelStreamConfig) -> Self {
198        let config =
199            PriceLevelStreamConfig { address: canonical_pamm_address(&config.address), ..config };
200        self.denied.remove(&config.address);
201        self.registry
202            .insert(config.address.clone(), config);
203        self
204    }
205
206    /// Excludes a venue from being served: drops its current registration (default or explicit)
207    /// and blocks auto-detecting it.
208    ///
209    /// As for [`add_pamm`](Self::add_pamm), `address` may be either of the venue's addresses, so
210    /// denying a venue by its public identity also denies the books it streams under another
211    /// one. Between [`add_pamm`](Self::add_pamm) and [`deny_pamm`](Self::deny_pamm) for the same
212    /// venue, the later call wins; the defaults applied by
213    /// [`with_known_pamms`](Self::with_known_pamms) never override either, in any call order —
214    /// so denying a venue from the default set works whether the denial comes before or after
215    /// [`with_known_pamms`](Self::with_known_pamms).
216    #[expect(
217        clippy::needless_pass_by_value,
218        reason = "public API; taking &Bytes is a breaking change"
219    )]
220    pub fn deny_pamm(mut self, address: Bytes) -> Self {
221        let address = canonical_pamm_address(&address);
222        self.registry.remove(&address);
223        self.denied.insert(address);
224        self
225    }
226
227    /// Applies what is known about the streamed venues: registers the known-good ones
228    /// ([`default_served_pamms`]) to be served and denies the known-bad ones
229    /// ([`default_denied_pamms`]) — venues that stream quotes but whose swaps are not executable.
230    ///
231    /// These defaults never override an explicit [`add_pamm`](Self::add_pamm) or
232    /// [`deny_pamm`](Self::deny_pamm) for the same venue, regardless of call order.
233    pub fn with_known_pamms(mut self) -> Self {
234        for config in default_served_pamms() {
235            let config = PriceLevelStreamConfig {
236                address: canonical_pamm_address(&config.address),
237                ..config
238            };
239            if self.denied.contains(&config.address) {
240                continue;
241            }
242            self.registry
243                .entry(config.address.clone())
244                .or_insert(config);
245        }
246        for address in default_denied_pamms() {
247            let address = canonical_pamm_address(&address);
248            if self.registry.contains_key(&address) {
249                continue;
250            }
251            self.denied.insert(address);
252        }
253        self
254    }
255
256    /// Provides the token metadata used to build components and interpret amounts, and the set of
257    /// assets the stream may price at all: a book is served only if both addresses it names are
258    /// present here, and those tokens supply the decimals its price levels are converted with.
259    /// Books naming any other asset are skipped.
260    pub fn with_tokens(mut self, tokens: HashMap<Bytes, Token>) -> Self {
261        self.tokens = tokens;
262        self
263    }
264
265    /// Keeps every venue on the direct `pricelevelstream:{name}` path, so swaps execute on the
266    /// venues themselves and a stale maker quote reverts the route.
267    ///
268    /// By default components are emitted under `fallback:{name}`, so tycho-execution routes
269    /// their swaps through `TychoFallbackRouter`. Opt out when the direct call is what you want
270    /// to measure or execute.
271    pub fn without_fallback_router(mut self) -> Self {
272        self.fallback_router = false;
273        self
274    }
275
276    /// Overrides how long a component stays served after the last accepted message that carried
277    /// it (default: 24s, two slots). A component no accepted message has carried for this long
278    /// turns stale and is emitted in `removed_pairs`; the next accepted message carrying it
279    /// re-adds it in `new_pairs`. Messages whose `ts` is this old or older are rejected.
280    /// Independent of this setting, a state refuses to quote once its message is one slot old
281    /// (see [`without_quote_guard`](Self::without_quote_guard)).
282    ///
283    /// Values above [`MAX_STALE_AFTER`] are capped to it. A value shorter than the age messages
284    /// arrive with rejects every message as `too_old`, which the
285    /// `price_level_stream_frames_rejected_total` counter and a WARN log show.
286    pub fn stale_after(mut self, duration: Duration) -> Self {
287        self.stale_after = duration.min(MAX_STALE_AFTER);
288        self
289    }
290
291    /// Emits states that never refuse to quote.
292    ///
293    /// By default every emitted state refuses `spot_price`, `get_amount_out` and `get_limits`
294    /// once its message is one slot ([`QUOTE_TTL`](super::state::QUOTE_TTL)) old: Titan prices
295    /// the block being built, so after one slot the quotes were priced for a block already built
296    /// and may no longer match what the venue fills. Opt out only for a consumer that quotes a
297    /// state more than one slot after it arrived by design — a batch simulator, a validation
298    /// harness — and that accepts a quote the venue may no longer fill. The component still
299    /// turns stale and is removed after [`stale_after`](Self::stale_after), which then becomes
300    /// the only bound on how old served quotes can be. Never disable it on a live router.
301    pub fn without_quote_guard(mut self) -> Self {
302        self.quote_guard = false;
303        self
304    }
305
306    /// Consumes the builder and opens the stream.
307    ///
308    /// Components are emitted under `fallback:{name}`, so tycho-execution routes their swaps
309    /// through `TychoFallbackRouter`, which retries a reverted pAMM swap — a stale maker quote
310    /// reverts in any simulation against a mined block — on the fallback pool the solver names.
311    /// [`without_fallback_router`](Self::without_fallback_router) keeps them on the direct
312    /// `pricelevelstream:` path.
313    ///
314    /// The stream connects the price level socket, and the quote stream socket unless
315    /// [`without_simulation_overrides`](Self::without_simulation_overrides) turned it off, on the
316    /// first poll. It reconnects both for as long as it is polled; neither ends on its own, and
317    /// dropping the stream closes both. A quote stream message produces no update of its own: the
318    /// tracker holds its entries until a later price level message's books name them. A quote
319    /// stream that is refused, silent or malformed costs the states their overrides and nothing
320    /// else: the stream never waits on the quote stream socket to serve a price level message or
321    /// a stale removal.
322    ///
323    /// Every accepted message yields an update with the states of the served pairs it carries,
324    /// with `new_pairs` for pairs not currently served. The update does not mention pairs the
325    /// message does not carry, so consumers keep their previous state. A component no accepted
326    /// message has carried for [`stale_after`](Self::stale_after) turns stale and is emitted in
327    /// `removed_pairs`, together with every other component turning stale at that instant, and
328    /// re-added by the next accepted message carrying it. Messages that are too old, from the
329    /// future, out of order, or whose block regresses or jumps more than one block per elapsed
330    /// slot plus 2 are rejected without effect. Messages that contain no served pAMM produce no
331    /// update. Books naming an address absent from the provided token metadata are skipped, as is
332    /// any one book side whose levels do not state a usable price function — leaving that
333    /// direction unquotable.
334    ///
335    /// Every update carries the block its message targets, and a removal carries the newest
336    /// accepted block. Block numbers never decrease while something is served. Once every
337    /// component has turned stale, the next accepted message is judged as a first message and may
338    /// carry a lower block than the removal did: that is how the stream recovers from a message
339    /// with an implausible block, so consumers must not rely on the block number to order
340    /// updates across such a gap. See the [module documentation](super) for the full contract.
341    pub fn build(self) -> impl Stream<Item = Update> + Send {
342        let Self {
343            registry,
344            denied,
345            tokens,
346            url,
347            quote_stream_url,
348            simulation_overrides,
349            auto_detect,
350            auto_detected_gas_cost,
351            connection,
352            fallback_router,
353            stale_after,
354            quote_guard,
355        } = self;
356        if registry.is_empty() && !auto_detect {
357            tracing::warn!(
358                "No pAMMs registered and auto-detection is off; the stream will never produce \
359                 an update"
360            );
361        }
362        if tokens.is_empty() {
363            tracing::warn!(
364                "No token metadata provided; every streamed book will be skipped and the stream \
365                 will never produce an update"
366            );
367        }
368        let url = url.unwrap_or_else(|| {
369            std::env::var(TITAN_PRICE_LEVEL_URL_ENV)
370                .unwrap_or_else(|_| TITAN_PRICE_LEVEL_URL.to_string())
371        });
372        let quote_stream_url = simulation_overrides.then(|| {
373            quote_stream_url.unwrap_or_else(|| {
374                std::env::var(TITAN_QUOTE_STREAM_URL_ENV)
375                    .unwrap_or_else(|_| TITAN_QUOTE_STREAM_URL.to_string())
376            })
377        });
378        if let Some(quote_stream_url) = &quote_stream_url {
379            if (url == TITAN_PRICE_LEVEL_URL) != (quote_stream_url == TITAN_QUOTE_STREAM_URL) {
380                tracing::warn!(
381                    price_level_url = url,
382                    quote_stream_url,
383                    "Only one of the two Titan endpoints is customized; the quote stream of one \
384                     region may not match the price levels of another, which costs states their \
385                     simulation overrides"
386                );
387            }
388        }
389        let auto_detected_gas_cost =
390            auto_detected_gas_cost.unwrap_or_else(|| BigUint::from(DEFAULT_AUTO_DETECTED_GAS_COST));
391        let mut tracker = FreshnessTracker::new(TrackerSettings {
392            registry,
393            denied,
394            tokens,
395            auto_detect,
396            auto_detected_gas_cost,
397            stale_after,
398            via_fallback_router: fallback_router,
399            quote_guard,
400            simulation_overrides,
401        });
402
403        stream! {
404            let messages = titan::messages(url, connection);
405            tokio::pin!(messages);
406            // A stream that never yields stands in for the quote stream socket when it is off.
407            let mut quote_stream_messages: Pin<
408                Box<dyn Stream<Item = TitanQuoteStreamMessage> + Send>,
409            > = match quote_stream_url {
410                Some(url) => {
411                    Box::pin(titan::messages::<TitanQuoteStreamMessage>(url, connection))
412                }
413                None => Box::pin(tokio_stream::pending()),
414            };
415            loop {
416                let deadline = tracker.stale_deadline();
417                let sleep_until_deadline = tokio::time::sleep_until(
418                    deadline.map_or_else(tokio::time::Instant::now, tokio::time::Instant::from_std),
419                );
420                let update = tokio::select! {
421                    Some(message) = messages.next() => {
422                        tracker.on_price_level_message(message, now())
423                    }
424                    Some(message) = quote_stream_messages.next() => {
425                        tracker.on_quote_stream_message(message);
426                        None
427                    }
428                    () = sleep_until_deadline, if deadline.is_some() => {
429                        tracker.on_stale_deadline(timer_now())
430                    }
431                };
432                if let Some(update) = update {
433                    yield update;
434                }
435            }
436        }
437    }
438}
439
440/// The clocks a message is judged against: the wall clock for Titan's `ts`, and the
441/// timer's clock for every deadline. This is the only place the stream reads a clock; the
442/// tracker only ever sees the values it is handed.
443fn now() -> Now {
444    Now { wall_nanos: wall_clock_nanos(), monotonic: timer_now() }
445}
446
447/// Nanoseconds since the Unix epoch. A system clock unrepresentable as unix nanoseconds yields
448/// 0, which rejects every message as `in_future`.
449fn wall_clock_nanos() -> u64 {
450    let since_epoch = SystemTime::now()
451        .duration_since(UNIX_EPOCH)
452        .ok()
453        .and_then(|since_epoch| u64::try_from(since_epoch.as_nanos()).ok());
454    match since_epoch {
455        Some(wall_nanos) => wall_nanos,
456        None => {
457            tracing::error!(
458                "System clock unrepresentable as unix nanoseconds; every price level message will \
459                 be rejected as in_future"
460            );
461            0
462        }
463    }
464}
465
466/// The clock the deadline timer runs on. Deadlines are set and swept with it so that a sweep
467/// fired by the timer finds the component due, also under `tokio::time::pause()`, where the
468/// runtime's virtual time and `std::time::Instant` diverge.
469fn timer_now() -> Instant {
470    tokio::time::Instant::now().into_std()
471}
472
473#[cfg(test)]
474mod tests {
475    use std::{
476        pin::Pin,
477        str::FromStr,
478        sync::{
479            atomic::{AtomicBool, AtomicUsize, Ordering},
480            Arc,
481        },
482        time::Duration,
483    };
484
485    use futures::{future::BoxFuture, SinkExt};
486    use num_bigint::BigUint;
487    use rstest::rstest;
488    use tokio_tungstenite::tungstenite::Message;
489
490    use super::{
491        super::{
492            config::{default_denied_pamms, PriceLevelStreamConfig},
493            state::PriceLevelStreamState,
494            telemetry::{
495                recorded::{counter_value, record_async},
496                RECONNECTS,
497            },
498            test_support::{
499                address, captured_message_text, captured_quote_stream_text, captured_tokens,
500                fermiswap, matching_message_text, message_text, message_then_repeat, token,
501                token_map, tokens, wall_nanos_now, FakeConnection, FakeTitan, KIPSELI,
502                KIPSELI_STREAMED, PAMM, USDC, WBTC, WETH,
503            },
504        },
505        *,
506    };
507
508    #[test]
509    fn explicit_add_and_deny_are_last_wins() {
510        let address = Bytes::from_str(PAMM).unwrap();
511        let custom =
512            || PriceLevelStreamConfig::new("custom", Bytes::from_str(PAMM).unwrap(), 1u64.into());
513
514        let builder = PriceLevelStreamBuilder::new()
515            .add_pamm(custom())
516            .deny_pamm(address.clone());
517        assert!(!builder.registry.contains_key(&address));
518        assert!(builder.denied.contains(&address));
519
520        let builder = PriceLevelStreamBuilder::new()
521            .deny_pamm(address.clone())
522            .add_pamm(custom());
523        assert_eq!(builder.registry[&address].protocol, "custom");
524        assert!(builder.denied.is_empty());
525    }
526
527    #[test]
528    fn quote_guard_is_on_unless_opted_out() {
529        assert!(PriceLevelStreamBuilder::new().quote_guard);
530        assert!(
531            !PriceLevelStreamBuilder::new()
532                .without_quote_guard()
533                .quote_guard
534        );
535    }
536
537    /// Short timings for a test: `stale_after` 2 s, `read_idle_timeout` 100 ms, `max_backoff`
538    /// 20 ms, reading price level messages from `fake`.
539    ///
540    /// It leaves the quote stream socket at its default, Titan's live endpoint, so no test builds
541    /// on it directly: tests use [`fast_timings`], which turns that socket off, or
542    /// [`two_socket_timings`], which points it at a second fake.
543    fn timings(fake: &FakeTitan) -> PriceLevelStreamBuilder {
544        PriceLevelStreamBuilder::new()
545            .endpoint(fake.url())
546            .stale_after(STALE_AFTER)
547            .connect_timeout(Duration::from_secs(1))
548            .read_idle_timeout(Duration::from_millis(100))
549            .max_backoff(Duration::from_millis(20))
550    }
551
552    /// [`timings`] with no quote stream socket, for everything that socket has no part in.
553    fn fast_timings(fake: &FakeTitan) -> PriceLevelStreamBuilder {
554        timings(fake).without_simulation_overrides()
555    }
556
557    /// [`timings`] with the quote stream socket pointed at a second fake: the default shape of the
558    /// stream, with both endpoints local.
559    fn two_socket_timings(prices: &FakeTitan, overrides: &FakeTitan) -> PriceLevelStreamBuilder {
560        timings(prices).quote_stream_endpoint(overrides.url())
561    }
562
563    /// A [`fast_timings`] builder serving the FermiSwap venue with the bound assets' metadata.
564    fn fast_builder(fake: &FakeTitan) -> PriceLevelStreamBuilder {
565        fast_timings(fake)
566            .add_pamm(fermiswap())
567            .with_tokens(tokens())
568    }
569
570    /// The `stale_after` of [`fast_builder`]: long enough that a loaded runner does not reject
571    /// the first message as too old, short enough that a removal arrives within [`WAIT`].
572    const STALE_AFTER: Duration = Duration::from_secs(2);
573
574    /// How long a test waits for one update.
575    const WAIT: Duration = Duration::from_secs(5);
576
577    async fn next_within(
578        stream: &mut Pin<&mut impl Stream<Item = Update>>,
579        limit: Duration,
580    ) -> Option<Update> {
581        tokio::time::timeout(limit, stream.next())
582            .await
583            .ok()
584            .flatten()
585    }
586
587    /// Waits for the first update and checks that it adds the one served component.
588    async fn expect_first_update(stream: &mut Pin<&mut impl Stream<Item = Update>>) -> Update {
589        let first = next_within(stream, WAIT)
590            .await
591            .expect("first update");
592        assert_eq!(first.new_pairs.len(), 1);
593        assert!(first.removed_pairs.is_empty());
594        first
595    }
596
597    /// Waits up to [`WAIT`] for an update that removes components, skipping the updates that
598    /// only refresh served ones; an update that re-adds a component before the removal fails.
599    async fn expect_removal(stream: &mut Pin<&mut impl Stream<Item = Update>>) -> Update {
600        tokio::time::timeout(WAIT, async {
601            loop {
602                let update = stream
603                    .next()
604                    .await
605                    .expect("stream ended");
606                if !update.removed_pairs.is_empty() {
607                    return update;
608                }
609                assert!(update.new_pairs.is_empty(), "component re-added before the removal");
610            }
611        })
612        .await
613        .expect("removal")
614    }
615
616    fn assert_removal_only(update: &Update, expected_removed: usize) {
617        assert!(update.states.is_empty());
618        assert!(update.new_pairs.is_empty());
619        assert!(update.sync_states.is_empty());
620        assert!(update.is_partial);
621        assert_eq!(update.removed_pairs.len(), expected_removed);
622    }
623
624    fn fresh_message() -> Message {
625        Message::Text(message_text(100, wall_nanos_now()).into())
626    }
627
628    /// Sends one fresh message on the first connection only; later connections stay silent.
629    async fn first_connection_sends_one_message(index: usize, mut socket: FakeConnection) {
630        if index == 0 {
631            #[expect(
632                clippy::let_underscore_must_use,
633                reason = "the fake peer may already be gone; that is not a test failure"
634            )]
635            let _ = socket.send(fresh_message()).await;
636        }
637        std::future::pending::<()>().await;
638    }
639
640    #[tokio::test]
641    async fn silence_past_stale_after_removes_every_served_component() {
642        let fake = FakeTitan::spawn(first_connection_sends_one_message).await;
643        let stream = fast_builder(&fake).build();
644        tokio::pin!(stream);
645
646        expect_first_update(&mut stream).await;
647        // The stream reconnects on idle timeout, but the later connections send no message, so no
648        // component deadline moves.
649        let removal = next_within(&mut stream, WAIT)
650            .await
651            .expect("removal");
652
653        assert_removal_only(&removal, 1);
654        assert_eq!(removal.block_number, 100);
655        assert!(fake.connections.load(Ordering::SeqCst) >= 2, "no reconnect on idle timeout");
656    }
657
658    #[tokio::test]
659    async fn repeated_immediate_closes_remove_within_stale_after() {
660        let fake = FakeTitan::spawn(|index, mut socket| async move {
661            if index == 0 {
662                #[expect(
663                    clippy::let_underscore_must_use,
664                    reason = "the fake peer may already be gone; that is not a test failure"
665                )]
666                let _ = socket.send(fresh_message()).await;
667                tokio::time::sleep(Duration::from_millis(20)).await;
668            }
669            #[expect(
670                clippy::let_underscore_must_use,
671                reason = "the fake peer may already be gone; that is not a test failure"
672            )]
673            let _ = socket.close(None).await;
674        })
675        .await;
676        let stream = fast_builder(&fake).build();
677        tokio::pin!(stream);
678
679        expect_first_update(&mut stream).await;
680        let removal = next_within(&mut stream, WAIT)
681            .await
682            .expect("removal");
683
684        assert_removal_only(&removal, 1);
685    }
686
687    #[test]
688    fn refused_reconnects_remove_within_stale_after() {
689        let (removal, snapshot) = record_async(async {
690            let mut fake = FakeTitan::spawn(|_, mut socket| async move {
691                #[expect(
692                    clippy::let_underscore_must_use,
693                    reason = "the fake peer may already be gone; that is not a test failure"
694                )]
695                let _ = socket.send(fresh_message()).await;
696                tokio::time::sleep(Duration::from_millis(20)).await;
697                #[expect(
698                    clippy::let_underscore_must_use,
699                    reason = "the fake peer may already be gone; that is not a test failure"
700                )]
701                let _ = socket.close(None).await;
702            })
703            .await;
704            let stream = fast_builder(&fake).build();
705            tokio::pin!(stream);
706
707            expect_first_update(&mut stream).await;
708            // From here every connect is refused at TCP level. The fake closes 20 ms in and the
709            // backoff is capped at 20 ms, so one reconnect can be accepted before `shutdown`
710            // drops the listener; its fresh message refreshes the component without re-adding it.
711            fake.shutdown();
712            expect_removal(&mut stream).await
713        });
714
715        assert_removal_only(&removal, 1);
716        assert!(
717            counter_value(
718                &snapshot,
719                RECONNECTS,
720                &[("reason", "connect_failed"), ("socket", "price_levels")]
721            ) >= 1,
722            "no connect was refused"
723        );
724    }
725
726    #[tokio::test]
727    async fn replayed_messages_remove_within_stale_after_and_never_re_add() {
728        // One message, with one `ts`, replayed every 50 ms forever.
729        let replay = fresh_message();
730        let fake = FakeTitan::spawn(message_then_repeat(
731            replay.clone(),
732            replay,
733            Duration::from_millis(50),
734        ))
735        .await;
736        let stream = fast_builder(&fake)
737            .read_idle_timeout(Duration::from_secs(5))
738            .build();
739        tokio::pin!(stream);
740
741        expect_first_update(&mut stream).await;
742        // Replays are accepted while fresh but cannot extend the deadline; the deadline fires
743        // even though a message is ready on every poll.
744        let removal = expect_removal(&mut stream).await;
745
746        assert_removal_only(&removal, 1);
747        // Every later replay is too old to be accepted: nothing comes back.
748        assert!(next_within(&mut stream, Duration::from_millis(500))
749            .await
750            .is_none());
751    }
752
753    #[tokio::test]
754    async fn fresh_message_after_removal_re_adds_the_component() {
755        let fake = FakeTitan::spawn(|_, mut socket| async move {
756            #[expect(
757                clippy::let_underscore_must_use,
758                reason = "the fake peer may already be gone; that is not a test failure"
759            )]
760            let _ = socket.send(fresh_message()).await;
761            tokio::time::sleep(STALE_AFTER + Duration::from_millis(500)).await;
762            #[expect(
763                clippy::let_underscore_must_use,
764                reason = "the fake peer may already be gone; that is not a test failure"
765            )]
766            let _ = socket
767                .send(Message::Text(message_text(101, wall_nanos_now()).into()))
768                .await;
769            std::future::pending::<()>().await;
770        })
771        .await;
772        let stream = fast_builder(&fake)
773            .read_idle_timeout(Duration::from_secs(5))
774            .build();
775        tokio::pin!(stream);
776
777        expect_first_update(&mut stream).await;
778        let removal = next_within(&mut stream, WAIT)
779            .await
780            .expect("removal");
781        let re_added = next_within(&mut stream, WAIT)
782            .await
783            .expect("re-add");
784
785        assert_removal_only(&removal, 1);
786        assert_eq!(re_added.new_pairs.len(), 1);
787        assert!(re_added.removed_pairs.is_empty());
788        assert_eq!(re_added.block_number, 101);
789    }
790
791    #[tokio::test]
792    async fn messages_are_forwarded_without_waiting_on_timers() {
793        let fake = FakeTitan::spawn(fresh_message_every(Duration::from_millis(50))).await;
794        let stream = fast_builder(&fake)
795            .stale_after(Duration::from_secs(24))
796            .build();
797        tokio::pin!(stream);
798
799        expect_first_update(&mut stream).await;
800        for _ in 0..5 {
801            let update = next_within(&mut stream, Duration::from_secs(1))
802                .await
803                .expect("steady-state message");
804            assert!(update.removed_pairs.is_empty());
805        }
806    }
807
808    #[tokio::test]
809    async fn no_connection_before_first_poll() {
810        let fake = FakeTitan::spawn(first_connection_sends_one_message).await;
811        let stream = fast_builder(&fake).build();
812        tokio::pin!(stream);
813
814        tokio::time::sleep(Duration::from_millis(150)).await;
815
816        assert_eq!(fake.connections.load(Ordering::SeqCst), 0, "connected before first poll");
817    }
818
819    #[tokio::test]
820    async fn drop_closes_the_socket() {
821        let server_saw_close = Arc::new(AtomicBool::new(false));
822        let fake = {
823            let server_saw_close = server_saw_close.clone();
824            FakeTitan::spawn(move |_, mut socket| {
825                let server_saw_close = server_saw_close.clone();
826                async move {
827                    #[expect(
828                        clippy::let_underscore_must_use,
829                        reason = "the fake peer may already be gone; that is not a test failure"
830                    )]
831                    let _ = socket.send(fresh_message()).await;
832                    // Read until the client goes away.
833                    while let Some(Ok(message)) = socket.next().await {
834                        if matches!(message, Message::Close(_)) {
835                            break;
836                        }
837                    }
838                    server_saw_close.store(true, Ordering::SeqCst);
839                }
840            })
841            .await
842        };
843        // `Box::pin` rather than `tokio::pin!`, so that `drop` below drops the stream itself
844        // rather than a `Pin<&mut _>` pointing at a value that outlives the assertion.
845        let mut stream = Box::pin(
846            fast_builder(&fake)
847                .read_idle_timeout(Duration::from_secs(5))
848                .build(),
849        );
850        expect_first_update(&mut stream.as_mut()).await;
851
852        drop(stream);
853        tokio::time::sleep(Duration::from_millis(200)).await;
854
855        assert!(server_saw_close.load(Ordering::SeqCst), "socket not closed on drop");
856        assert_eq!(fake.connections.load(Ordering::SeqCst), 1, "reconnected after drop");
857    }
858
859    /// `Instant + Duration` panics on overflow, so an absurd `stale_after` must be capped before
860    /// the first accepted message computes a deadline from it.
861    #[tokio::test]
862    async fn stale_after_above_the_cap_still_serves() {
863        assert_eq!(
864            PriceLevelStreamBuilder::new()
865                .stale_after(Duration::MAX)
866                .stale_after,
867            MAX_STALE_AFTER
868        );
869        let fake = FakeTitan::spawn(first_connection_sends_one_message).await;
870        let stream = fast_builder(&fake)
871            .stale_after(Duration::MAX)
872            .build();
873        tokio::pin!(stream);
874
875        expect_first_update(&mut stream).await;
876    }
877
878    #[tokio::test]
879    async fn without_quote_guard_emits_states_that_never_expire() {
880        let fake = FakeTitan::spawn(first_connection_sends_one_message).await;
881        let stream = fast_builder(&fake)
882            .without_quote_guard()
883            .build();
884        tokio::pin!(stream);
885
886        let first = expect_first_update(&mut stream).await;
887
888        let state = first
889            .states
890            .values()
891            .next()
892            .expect("one state")
893            .as_any()
894            .downcast_ref::<PriceLevelStreamState>()
895            .expect("price level state");
896        assert!(state.quotable_until().is_none());
897    }
898
899    /// A [`FakeTitan`] handler that sends a message with a current `ts` every `interval` until the
900    /// socket closes.
901    fn fresh_message_every(
902        interval: Duration,
903    ) -> impl Fn(usize, FakeConnection) -> BoxFuture<'static, ()> + Send + Sync + 'static {
904        move |_, mut socket| {
905            Box::pin(async move {
906                while socket
907                    .send(fresh_message())
908                    .await
909                    .is_ok()
910                {
911                    tokio::time::sleep(interval).await;
912                }
913            })
914        }
915    }
916
917    /// The fallback router path is the default; `without_fallback_router` is the way off it.
918    #[test]
919    fn fallback_router_is_on_unless_opted_out() {
920        assert!(PriceLevelStreamBuilder::new().fallback_router);
921        assert!(
922            !PriceLevelStreamBuilder::new()
923                .without_fallback_router()
924                .fallback_router
925        );
926    }
927
928    #[test]
929    fn defaults_never_override_explicit_calls() {
930        // Denying a venue from the default set works in either call order.
931        let fermiswap_router = Bytes::from_str(PAMM).unwrap();
932        for builder in [
933            PriceLevelStreamBuilder::new()
934                .deny_pamm(fermiswap_router.clone())
935                .with_known_pamms(),
936            PriceLevelStreamBuilder::new()
937                .with_known_pamms()
938                .deny_pamm(fermiswap_router.clone()),
939        ] {
940            assert!(!builder
941                .registry
942                .contains_key(&fermiswap_router));
943            assert!(builder
944                .denied
945                .contains(&fermiswap_router));
946            // The other defaults are unaffected.
947            assert!(!builder.registry.is_empty());
948        }
949
950        // Registering a venue from the default deny set works in either call order. Any one of
951        // them exercises that; the set is empty while every streamed venue is executable.
952        let Some(denied_venue) = default_denied_pamms().pop() else { return };
953        let custom = || PriceLevelStreamConfig::new("custom", denied_venue.clone(), 1u64.into());
954        for builder in [
955            PriceLevelStreamBuilder::new()
956                .add_pamm(custom())
957                .with_known_pamms(),
958            PriceLevelStreamBuilder::new()
959                .with_known_pamms()
960                .add_pamm(custom()),
961        ] {
962            assert_eq!(builder.registry[&denied_venue].protocol, "custom");
963            assert!(!builder.denied.contains(&denied_venue));
964        }
965    }
966
967    #[test]
968    fn with_known_pamms_registers_known_venues() {
969        // PAMM is the FermiSwap router, one of the default venues.
970        let fermiswap_router = Bytes::from_str(PAMM).unwrap();
971
972        let builder = PriceLevelStreamBuilder::new();
973        assert!(builder.registry.is_empty());
974        assert!(builder.denied.is_empty());
975
976        let builder = builder.with_known_pamms();
977        assert_eq!(builder.registry[&fermiswap_router].protocol, "fermiswap");
978        // The known-bad venues get denied alongside, and never overlap the served defaults.
979        assert_eq!(
980            builder.denied,
981            default_denied_pamms()
982                .into_iter()
983                .collect()
984        );
985        assert!(builder.denied.is_disjoint(
986            &builder
987                .registry
988                .keys()
989                .cloned()
990                .collect()
991        ));
992
993        // An `add_pamm` entry wins over the default for the same address, in either call order.
994        let custom =
995            || PriceLevelStreamConfig::new("custom", fermiswap_router.clone(), BigUint::from(1u64));
996        for builder in [
997            PriceLevelStreamBuilder::new()
998                .add_pamm(custom())
999                .with_known_pamms(),
1000            PriceLevelStreamBuilder::new()
1001                .with_known_pamms()
1002                .add_pamm(custom()),
1003        ] {
1004            assert_eq!(builder.registry[&fermiswap_router].protocol, "custom");
1005            assert_eq!(builder.registry[&fermiswap_router].gas_cost, BigUint::from(1u64));
1006        }
1007    }
1008
1009    /// The families this stream emits are the ones tycho-execution resolves an encoder for. A
1010    /// drift between the two makes every route through a pAMM fail to encode.
1011    #[test]
1012    fn families_match_the_execution_side_prefixes() {
1013        use tycho_execution::encoding::evm::{FALLBACK_PREFIX, PRICE_LEVEL_STREAM_PREFIX};
1014
1015        use super::super::config::{FALLBACK_FAMILY, PRICE_LEVEL_STREAM_FAMILY};
1016
1017        assert_eq!(format!("{PRICE_LEVEL_STREAM_FAMILY}:"), PRICE_LEVEL_STREAM_PREFIX);
1018        assert_eq!(format!("{FALLBACK_FAMILY}:"), FALLBACK_PREFIX);
1019    }
1020
1021    /// A registration may name either of a venue's addresses: the streamed one normalizes to the
1022    /// public identity, which the registry is keyed by and the configuration then carries, so the
1023    /// components of an aliased venue execute against the public identity either way.
1024    #[rstest]
1025    #[case::by_public_identity(KIPSELI)]
1026    #[case::by_streamed_address(KIPSELI_STREAMED)]
1027    fn registering_a_venue_registers_its_public_identity(#[case] registered: &str) {
1028        let public = address(KIPSELI);
1029
1030        let builder = PriceLevelStreamBuilder::new().add_pamm(PriceLevelStreamConfig::new(
1031            "custom",
1032            address(registered),
1033            1u64.into(),
1034        ));
1035
1036        assert_eq!(builder.registry[&public].protocol, "custom");
1037        assert_eq!(builder.registry[&public].address, public);
1038        assert_eq!(builder.registry.len(), 1);
1039    }
1040
1041    /// Denial is on the public identity too, so denying a venue by the address its swaps go to
1042    /// also drops the default registration of the books it streams under another address.
1043    #[rstest]
1044    #[case::by_public_identity(KIPSELI)]
1045    #[case::by_streamed_address(KIPSELI_STREAMED)]
1046    fn denying_a_venue_denies_its_public_identity(#[case] denied: &str) {
1047        let public = address(KIPSELI);
1048
1049        let builder = PriceLevelStreamBuilder::new()
1050            .with_known_pamms()
1051            .deny_pamm(address(denied));
1052
1053        assert!(!builder.registry.contains_key(&public));
1054        assert!(!builder
1055            .registry
1056            .contains_key(&address(KIPSELI_STREAMED)));
1057        assert!(builder.denied.contains(&public));
1058        // The other default venues are unaffected.
1059        assert!(builder
1060            .registry
1061            .contains_key(&address(PAMM)));
1062    }
1063
1064    /// Mixed calls naming different addresses of one venue land on one canonical key, so the
1065    /// later call still wins — as it does when both name the same address.
1066    #[rstest]
1067    #[case::add_public_then_deny_streamed(KIPSELI, KIPSELI_STREAMED)]
1068    #[case::add_streamed_then_deny_public(KIPSELI_STREAMED, KIPSELI)]
1069    fn mixed_address_forms_are_last_wins(#[case] added: &str, #[case] denied: &str) {
1070        let public = address(KIPSELI);
1071        let custom = || PriceLevelStreamConfig::new("custom", address(added), 1u64.into());
1072
1073        let builder = PriceLevelStreamBuilder::new()
1074            .add_pamm(custom())
1075            .deny_pamm(address(denied));
1076        assert!(builder.registry.is_empty());
1077        assert!(builder.denied.contains(&public));
1078
1079        let builder = PriceLevelStreamBuilder::new()
1080            .deny_pamm(address(denied))
1081            .add_pamm(custom());
1082        assert_eq!(builder.registry[&public].protocol, "custom");
1083        assert!(builder.denied.is_empty());
1084    }
1085
1086    /// Synthetic: a token that calls itself `WBTC` at an address no default binding names.
1087    const IMPOSTOR_WBTC: &str = "0x00000000000000000000000000000000deadbeef";
1088
1089    /// Sends one message with a current `ts`, of Kipseli's captured books, on the first connection
1090    /// only.
1091    /// The books arrive under the address Titan streams them by, so serving them at all also
1092    /// exercises the alias on the live path.
1093    async fn first_connection_sends_captured_books(index: usize, mut socket: FakeConnection) {
1094        if index == 0 {
1095            let message = captured_message_text("Kipseli", 100, wall_nanos_now());
1096            #[expect(
1097                clippy::let_underscore_must_use,
1098                reason = "the fake peer may already be gone; that is not a test failure"
1099            )]
1100            let _ = socket
1101                .send(Message::Text(message.into()))
1102                .await;
1103        }
1104        std::future::pending::<()>().await;
1105    }
1106
1107    /// The address Titan streams is the identity, so an impostor token calling itself `WBTC` is
1108    /// never priced and never blocks the real asset. Kipseli quoted WBTC/USDC and WETH/USDC in
1109    /// the capture, so the WETH/USDC component must survive every case.
1110    ///
1111    /// Every case admits USDC and WETH plus the `WBTC`-named tokens of its first parameter, as
1112    /// `(address, decimals)`; the second is the address expected to be priced for the book's
1113    /// WBTC leg, or `None` when the book stays unserved.
1114    #[rstest]
1115    #[case::canonical_asset(vec![(WBTC, 8)], Some(WBTC))]
1116    #[case::impostor_only(vec![(IMPOSTOR_WBTC, 18)], None)]
1117    #[case::both_present(vec![(WBTC, 8), (IMPOSTOR_WBTC, 18)], Some(WBTC))]
1118    #[tokio::test]
1119    async fn an_impostor_symbol_is_never_priced(
1120        #[case] bitcoins: Vec<(&str, u32)>,
1121        #[case] expected_btc: Option<&str>,
1122    ) {
1123        let admitted = [token(USDC, "USDC", 6), token(WETH, "WETH", 18)]
1124            .into_iter()
1125            .chain(
1126                bitcoins
1127                    .into_iter()
1128                    .map(|(address, decimals)| token(address, "WBTC", decimals)),
1129            );
1130        let fake = FakeTitan::spawn(first_connection_sends_captured_books).await;
1131        let stream = fast_timings(&fake)
1132            .add_pamm(PriceLevelStreamConfig::new("kipseli", address(KIPSELI), 1u64.into()))
1133            .with_tokens(token_map(admitted))
1134            .build();
1135        tokio::pin!(stream);
1136
1137        let update = next_within(&mut stream, WAIT)
1138            .await
1139            .expect("first update");
1140
1141        // Every served component, as the addresses of its token pair in component order.
1142        let mut served: Vec<Vec<String>> = update
1143            .new_pairs
1144            .values()
1145            .map(|component| {
1146                component
1147                    .tokens
1148                    .iter()
1149                    .map(|token| token.address.to_string())
1150                    .collect()
1151            })
1152            .collect();
1153        served.sort();
1154        let mut expected = vec![vec![USDC.to_string(), WETH.to_string()]];
1155        if let Some(btc) = expected_btc {
1156            let mut pair = vec![btc.to_string(), USDC.to_string()];
1157            pair.sort();
1158            expected.push(pair);
1159        }
1160        expected.sort();
1161        assert_eq!(served, expected);
1162        // Whichever assets were priced, the venue executes against its public identity.
1163        for component in update.new_pairs.values() {
1164            assert_eq!(component.static_attributes[PAMM_ADDRESS_ATTRIBUTE], address(KIPSELI));
1165        }
1166    }
1167
1168    /// Traffic that is not a parsed message keeps neither the socket nor the component alive: the
1169    /// idle timeout reconnects, every reconnect resends the same message, which refreshes the
1170    /// component but cannot move its deadline, and the removal follows.
1171    #[rstest]
1172    #[case::ping_only(Message::Ping(Vec::new().into()))]
1173    #[case::malformed_text(Message::Text("nonsense".into()))]
1174    #[tokio::test]
1175    async fn traffic_that_is_not_a_message_removes_within_stale_after(#[case] filler: Message) {
1176        let fake = FakeTitan::spawn(message_then_repeat(
1177            fresh_message(),
1178            filler,
1179            Duration::from_millis(10),
1180        ))
1181        .await;
1182        let stream = fast_builder(&fake).build();
1183        tokio::pin!(stream);
1184
1185        expect_first_update(&mut stream).await;
1186        let removal = expect_removal(&mut stream).await;
1187
1188        assert_removal_only(&removal, 1);
1189        assert!(fake.connections.load(Ordering::SeqCst) >= 2, "no reconnect on idle timeout");
1190    }
1191
1192    /// How long a two-socket test waits for the quote stream socket to have been read before it
1193    /// sends the price level message whose books name its entries. Both sockets connect on the
1194    /// first poll, so this orders the two messages rather than racing them.
1195    const SOCKET_HEAD_START: Duration = Duration::from_millis(250);
1196
1197    /// A builder serving the known venues, which are every venue of the 2026-10-16 captures,
1198    /// reading both captures from `prices` and `overrides`. Registered up front rather than
1199    /// auto-detected, because entries are only stored for venues already served when they arrive.
1200    fn capture_builder(prices: &FakeTitan, overrides: &FakeTitan) -> PriceLevelStreamBuilder {
1201        two_socket_timings(prices, overrides)
1202            .with_known_pamms()
1203            .with_tokens(captured_tokens())
1204    }
1205
1206    /// The price level capture whose books match the captured quote stream message, with its `ts`
1207    /// set to now so that it passes the freshness checks.
1208    fn matching_message() -> Message {
1209        Message::Text(matching_message_text(100, wall_nanos_now()).into())
1210    }
1211
1212    /// The captured quote stream message, verbatim: matching reads no clock, so its timestamps can
1213    /// stay as captured.
1214    fn quote_stream_message() -> Message {
1215        Message::Text(captured_quote_stream_text().into())
1216    }
1217
1218    /// A [`FakeTitan`] handler that sends `message` after `delay` on the first connection only,
1219    /// then holds the socket open: a message the stream must see exactly once, at a known point
1220    /// relative to the other socket's.
1221    fn send_once_after(
1222        delay: Duration,
1223        message: Message,
1224    ) -> impl Fn(usize, FakeConnection) -> BoxFuture<'static, ()> + Send + Sync + 'static {
1225        move |index, mut socket| {
1226            let message = message.clone();
1227            Box::pin(async move {
1228                if index == 0 {
1229                    tokio::time::sleep(delay).await;
1230                    #[expect(
1231                        clippy::let_underscore_must_use,
1232                        reason = "the fake peer may already be gone; that is not a test failure"
1233                    )]
1234                    let _ = socket.send(message).await;
1235                }
1236                std::future::pending::<()>().await;
1237            })
1238        }
1239    }
1240
1241    /// How many connections `fake` has accepted.
1242    fn connections(fake: &FakeTitan) -> usize {
1243        fake.connections.load(Ordering::SeqCst)
1244    }
1245
1246    /// The states of `update` that carry simulation overrides.
1247    fn states_with_overrides(update: &Update) -> Vec<&PriceLevelStreamState> {
1248        update
1249            .states
1250            .values()
1251            .map(|state| {
1252                state
1253                    .as_any()
1254                    .downcast_ref::<PriceLevelStreamState>()
1255                    .expect("price level state")
1256            })
1257            .filter(|state| state.simulation_overrides().is_some())
1258            .collect()
1259    }
1260
1261    /// Both captures, read from two local sockets with the quote stream message arriving first:
1262    /// the 27 served pairs whose venue's entry carries the pair in the book's slot come out with
1263    /// overrides, and the other 3 without. The count comes from the fixtures themselves, worked
1264    /// out independently of this code.
1265    #[tokio::test]
1266    async fn a_quote_stream_message_attaches_overrides_to_the_books_it_priced() {
1267        let overrides =
1268            FakeTitan::spawn(send_once_after(Duration::ZERO, quote_stream_message())).await;
1269        let prices = FakeTitan::spawn(send_once_after(SOCKET_HEAD_START, matching_message())).await;
1270        let stream = capture_builder(&prices, &overrides)
1271            .read_idle_timeout(Duration::from_secs(5))
1272            .build();
1273        tokio::pin!(stream);
1274
1275        let update = next_within(&mut stream, WAIT)
1276            .await
1277            .expect("first update");
1278
1279        assert_eq!(update.states.len(), 30);
1280        let with_overrides = states_with_overrides(&update);
1281        assert_eq!(with_overrides.len(), 27);
1282        for state in with_overrides {
1283            let overrides = state
1284                .simulation_overrides()
1285                .expect("overrides");
1286            assert!(!overrides.accounts.is_empty(), "overrides with no account");
1287            assert_eq!(overrides.block_number, Some(26_201_954));
1288        }
1289    }
1290
1291    /// An entry that arrives after the books it priced changes nothing already served: the update
1292    /// the consumer holds keeps the states it was given. The next message with the same books gets
1293    /// overrides, which shows the first one's lack of them is about ordering, not matching.
1294    #[tokio::test]
1295    async fn a_late_quote_stream_message_leaves_served_states_without_overrides() {
1296        let overrides =
1297            FakeTitan::spawn(send_once_after(SOCKET_HEAD_START, quote_stream_message())).await;
1298        let prices = FakeTitan::spawn(move |index, mut socket| async move {
1299            if index == 0 {
1300                #[expect(
1301                    clippy::let_underscore_must_use,
1302                    reason = "the fake peer may already be gone; that is not a test failure"
1303                )]
1304                let _ = socket.send(matching_message()).await;
1305                tokio::time::sleep(2 * SOCKET_HEAD_START).await;
1306                #[expect(
1307                    clippy::let_underscore_must_use,
1308                    reason = "the fake peer may already be gone; that is not a test failure"
1309                )]
1310                let _ = socket.send(matching_message()).await;
1311            }
1312            std::future::pending::<()>().await;
1313        })
1314        .await;
1315        let stream = capture_builder(&prices, &overrides)
1316            .read_idle_timeout(Duration::from_secs(5))
1317            .build();
1318        tokio::pin!(stream);
1319
1320        let first = next_within(&mut stream, WAIT).await;
1321        let second = next_within(&mut stream, WAIT).await;
1322
1323        let first = first.expect("first update");
1324        assert_eq!(first.new_pairs.len(), 30);
1325        assert!(states_with_overrides(&first).is_empty(), "overrides before any entry arrived");
1326        assert_eq!(states_with_overrides(&second.expect("second update")).len(), 27);
1327    }
1328
1329    /// Opting out connects no quote stream socket at all, so no state gets overrides and nothing
1330    /// is read from an endpoint the consumer never wanted, whichever of the opt-out and
1331    /// `quote_stream_endpoint` is called first.
1332    #[rstest]
1333    #[case::opt_out_after_the_endpoint(false)]
1334    #[case::opt_out_before_the_endpoint(true)]
1335    #[tokio::test]
1336    async fn without_simulation_overrides_connects_no_quote_stream_socket(
1337        #[case] opt_out_first: bool,
1338    ) {
1339        let overrides =
1340            FakeTitan::spawn(send_once_after(Duration::ZERO, quote_stream_message())).await;
1341        let prices = FakeTitan::spawn(send_once_after(SOCKET_HEAD_START, matching_message())).await;
1342        let builder = if opt_out_first {
1343            timings(&prices)
1344                .without_simulation_overrides()
1345                .quote_stream_endpoint(overrides.url())
1346        } else {
1347            timings(&prices)
1348                .quote_stream_endpoint(overrides.url())
1349                .without_simulation_overrides()
1350        };
1351        let stream = builder
1352            .with_known_pamms()
1353            .with_tokens(captured_tokens())
1354            .read_idle_timeout(Duration::from_secs(5))
1355            .build();
1356        tokio::pin!(stream);
1357
1358        let update = next_within(&mut stream, WAIT)
1359            .await
1360            .expect("first update");
1361
1362        assert_eq!(update.states.len(), 30);
1363        assert!(states_with_overrides(&update).is_empty());
1364        assert_eq!(connections(&overrides), 0, "connected the quote stream socket");
1365    }
1366
1367    /// Whatever the quote stream socket does, the price level socket keeps serving: the states lose
1368    /// their overrides and nothing else. A silent socket reconnects on the idle timeout, malformed
1369    /// text is skipped and then reconnected for the same reason, a close is reconnected, and a
1370    /// flood is read without starving the other two arms of the select. In every case the first
1371    /// update arrives and the stale removal that follows the price level socket's silence still
1372    /// fires on time.
1373    ///
1374    /// `connects` is the least number of connections the quote stream socket must have made by
1375    /// then: 2 for the cases that test recovery, so a socket that gives up after one failure fails
1376    /// them; 1 for the flood, whose messages parse and keep the connection alive.
1377    #[rstest]
1378    #[case::silent(None, 2)]
1379    #[case::malformed(Some(Message::Text("nonsense".into())), 2)]
1380    #[case::closed(Some(Message::Close(None)), 2)]
1381    #[case::flooding(Some(quote_stream_message()), 1)]
1382    #[tokio::test]
1383    async fn the_price_level_socket_survives_any_quote_stream_socket(
1384        #[case] repeat: Option<Message>,
1385        #[case] connects: usize,
1386    ) {
1387        let overrides = FakeTitan::spawn(move |_, mut socket| {
1388            let repeat = repeat.clone();
1389            async move {
1390                while let Some(message) = repeat.clone() {
1391                    if socket.send(message).await.is_err() {
1392                        return;
1393                    }
1394                    tokio::time::sleep(Duration::from_millis(5)).await;
1395                }
1396                std::future::pending::<()>().await;
1397            }
1398        })
1399        .await;
1400        let prices = FakeTitan::spawn(first_connection_sends_one_message).await;
1401        let stream = two_socket_timings(&prices, &overrides)
1402            .add_pamm(fermiswap())
1403            .with_tokens(tokens())
1404            .build();
1405        tokio::pin!(stream);
1406
1407        expect_first_update(&mut stream).await;
1408        let removal = expect_removal(&mut stream).await;
1409
1410        assert_removal_only(&removal, 1);
1411        assert!(
1412            connections(&overrides) >= connects,
1413            "the quote stream socket connected {} times, expected at least {connects}",
1414            connections(&overrides)
1415        );
1416    }
1417
1418    /// A refused quote stream socket does not stall the price level socket, which serves and
1419    /// expires on its own schedule.
1420    #[tokio::test]
1421    async fn a_refused_quote_stream_socket_does_not_stall_the_price_level_socket() {
1422        let mut overrides =
1423            FakeTitan::spawn(send_once_after(Duration::ZERO, quote_stream_message())).await;
1424        let url = overrides.url();
1425        overrides.shutdown();
1426        let prices = FakeTitan::spawn(first_connection_sends_one_message).await;
1427        let stream = timings(&prices)
1428            .quote_stream_endpoint(url)
1429            .add_pamm(fermiswap())
1430            .with_tokens(tokens())
1431            .build();
1432        tokio::pin!(stream);
1433
1434        expect_first_update(&mut stream).await;
1435        let removal = expect_removal(&mut stream).await;
1436
1437        assert_removal_only(&removal, 1);
1438    }
1439
1440    /// A quote stream socket whose handshake never completes does not stall the price level
1441    /// socket, which serves and expires on its own schedule. The quote stream socket's connect
1442    /// timeout fires and it is retried; without the timeout the stream would wait on the hung
1443    /// handshake for as long as the peer keeps the connection open.
1444    #[tokio::test]
1445    async fn a_hung_quote_stream_socket_does_not_stall_the_price_level_socket() {
1446        let overrides = FakeTitan::spawn_hung().await;
1447        let prices = FakeTitan::spawn(first_connection_sends_one_message).await;
1448        let stream = two_socket_timings(&prices, &overrides)
1449            .connect_timeout(Duration::from_millis(200))
1450            .add_pamm(fermiswap())
1451            .with_tokens(tokens())
1452            .build();
1453        tokio::pin!(stream);
1454
1455        expect_first_update(&mut stream).await;
1456        let removal = expect_removal(&mut stream).await;
1457
1458        assert_removal_only(&removal, 1);
1459        assert!(
1460            connections(&overrides) >= 2,
1461            "the hung socket was connected to {} times, expected a retry",
1462            connections(&overrides)
1463        );
1464    }
1465
1466    /// Isolation holds the other way too: with the price level socket refused the stream yields
1467    /// nothing, and the quote stream socket is still read. The captured quote stream message names
1468    /// venues this stream does not serve, which it counts as it reads them.
1469    #[test]
1470    fn a_refused_price_level_socket_does_not_stall_the_quote_stream_socket() {
1471        let (update, snapshot) = record_async(async {
1472            let overrides = FakeTitan::spawn(message_then_repeat(
1473                quote_stream_message(),
1474                quote_stream_message(),
1475                Duration::from_millis(20),
1476            ))
1477            .await;
1478            let mut prices = FakeTitan::spawn(first_connection_sends_one_message).await;
1479            prices.shutdown();
1480            let stream = two_socket_timings(&prices, &overrides)
1481                .add_pamm(fermiswap())
1482                .with_tokens(tokens())
1483                .build();
1484            tokio::pin!(stream);
1485            next_within(&mut stream, Duration::from_millis(500)).await
1486        });
1487
1488        assert!(update.is_none(), "an update without a price level message");
1489        assert!(
1490            counter_value(&snapshot, "price_level_stream_unserved_venue_entries_total", &[]) > 0,
1491            "the quote stream socket was never read"
1492        );
1493    }
1494
1495    /// Dropping the stream closes both sockets, and neither is reconnected afterwards.
1496    #[tokio::test]
1497    async fn drop_closes_both_sockets() {
1498        let closed = Arc::new(AtomicUsize::new(0));
1499        let spawn_watching = |closed: Arc<AtomicUsize>, first: Message| async move {
1500            FakeTitan::spawn(move |_, mut socket| {
1501                let closed = closed.clone();
1502                let first = first.clone();
1503                async move {
1504                    #[expect(
1505                        clippy::let_underscore_must_use,
1506                        reason = "the fake peer may already be gone; that is not a test failure"
1507                    )]
1508                    let _ = socket.send(first).await;
1509                    while let Some(Ok(message)) = socket.next().await {
1510                        if matches!(message, Message::Close(_)) {
1511                            break;
1512                        }
1513                    }
1514                    closed.fetch_add(1, Ordering::SeqCst);
1515                }
1516            })
1517            .await
1518        };
1519        let overrides = spawn_watching(closed.clone(), quote_stream_message()).await;
1520        let prices = spawn_watching(closed.clone(), matching_message()).await;
1521        let mut stream = Box::pin(
1522            capture_builder(&prices, &overrides)
1523                .read_idle_timeout(Duration::from_secs(5))
1524                .build(),
1525        );
1526        next_within(&mut stream.as_mut(), WAIT)
1527            .await
1528            .expect("first update");
1529
1530        drop(stream);
1531        tokio::time::sleep(Duration::from_millis(200)).await;
1532
1533        assert_eq!(closed.load(Ordering::SeqCst), 2, "a socket was not closed on drop");
1534        assert_eq!(connections(&prices), 1, "reconnected after drop");
1535        assert_eq!(connections(&overrides), 1, "reconnected after drop");
1536    }
1537}