Skip to main content

syncular_client/
native_transport.rs

1//! Shared native host transport for every Rust-backed Syncular binding.
2//!
3//! Two shapes behind one `HostTransport`:
4//!
5//! - `Null` (the dependency-lean default build): every network op fails loudly
6//!   with `transport.unavailable`. Client-local commands (create, subscribe,
7//!   mutate, readRows, conflicts, …) still run — enough for the C smoke test
8//!   and pure-logic tests, with zero HTTP/WS dependency compiled in.
9//! - `Native` (the `native-transport` feature): a real HTTP + WS client the
10//!   core drives itself, because a native app has no host loop to invert
11//!   transport into (unlike the conformance shim). `ureq` for blocking HTTP,
12//!   `tungstenite` for the WS socket; a reader thread buffers inbound frames.
13//!
14//! - `Local` (the `local-authority` feature, a `localAuthorityPath` config):
15//!   §12.4 routing over either shape above. Sync rounds reach the in-process
16//!   local authority until attach completes, then the remote transport.
17//!
18//! Inbound realtime frames land in a shared queue the host drains after each
19//! command. An optional wake callback lets mailbox-driven hosts react without
20//! polling. The queue is bounded by [`INBOUND_BUFFER_LIMIT_BYTES`]. The socket implementation is deliberately singular: fairness and
21//! wire fixes therefore reach FFI, Tauri, and future Rust hosts together.
22
23use std::sync::atomic::{AtomicU64, Ordering};
24use std::sync::{mpsc, Arc, Mutex};
25use std::time::{Duration, SystemTime};
26
27use crate::{
28    BlobDownload, BlobUploadGrant, SegmentFetch, SegmentRequest, Transport, TransportError,
29};
30
31/// Redirect handling for native HTTP requests and the WebSocket handshake.
32#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
33pub enum RedirectPolicy {
34    /// Never follow a 3xx. A redirected request would replay configured
35    /// headers, URL userinfo, or a signed capability to an unverified
36    /// destination, so refusal is the default. A refused redirect surfaces
37    /// `transport.redirect`.
38    #[default]
39    Deny,
40    /// Follow a redirect for a request that carries neither configured
41    /// headers, base-URL userinfo, nor a signed capability URL. A
42    /// credential-bearing request is still refused even under this policy,
43    /// because ureq forwards configured headers and URL userinfo to the
44    /// redirect target, and tungstenite forwards configured headers to a
45    /// WebSocket redirect target. A WebSocket handshake additionally may not
46    /// follow a redirect when its realtime URL carries userinfo or a query
47    /// (a signed capability). Enable only for a deployment whose
48    /// unauthenticated requests may safely move.
49    Follow,
50}
51
52/// Bounds and behavior for the native host transport. `Default` matches the
53/// reference HTTP binding: no deadline and no body cap, with redirects denied.
54#[derive(Debug, Clone, Default)]
55pub struct HostTransportPolicy {
56    /// End-to-end deadline for one request (DNS through response body).
57    pub request_timeout: Option<Duration>,
58    /// One monotonic deadline for a whole sync round: uploads, continuations,
59    /// the main request, and every segment fetch. Anchored once on the round's
60    /// first network call; a continuation never resets it. Independent of the
61    /// per-request deadline, which still bounds each individual call.
62    pub round_deadline: Option<Duration>,
63    /// Largest HTTP request body the transport will send. Checked before any
64    /// network I/O. Does not cap realtime socket buffers.
65    pub max_request_bytes: Option<u64>,
66    /// Largest decoded (post-decompression) HTTP response body the transport
67    /// will accept. Does not cap realtime socket buffers.
68    pub max_response_bytes: Option<u64>,
69    pub redirects: RedirectPolicy,
70    /// The server's §8.5 heartbeat interval; `None` is the suggested 30 s. An
71    /// established realtime socket that receives no frame for twice the
72    /// interval is lost.
73    pub realtime_heartbeat: Option<Duration>,
74}
75
76impl HostTransportPolicy {
77    /// Reject a bound the transport cannot honor: a zero or unrepresentable
78    /// duration, or a zero byte limit. Called on both the JSON and the
79    /// programmatic path, so `Follow`/`Deny` and every numeric field agree.
80    pub fn validate(&self) -> Result<(), String> {
81        let now = std::time::Instant::now();
82        if let Some(timeout) = self.request_timeout {
83            if timeout.is_zero() || now.checked_add(timeout).is_none() {
84                return Err(
85                    "sync.invalid_request: transport config requestTimeoutMs is out of range"
86                        .to_owned(),
87                );
88            }
89        }
90        if let Some(deadline) = self.round_deadline {
91            if deadline.is_zero() || now.checked_add(deadline).is_none() {
92                return Err(
93                    "sync.invalid_request: transport config roundDeadlineMs is out of range"
94                        .to_owned(),
95                );
96            }
97        }
98        if let Some(interval) = self.realtime_heartbeat {
99            if interval.is_zero()
100                || interval
101                    .checked_mul(2)
102                    .and_then(|silence| now.checked_add(silence))
103                    .is_none()
104            {
105                return Err(
106                    "sync.invalid_request: transport config realtimeHeartbeatMs is out of range"
107                        .to_owned(),
108                );
109            }
110        }
111        if self.max_request_bytes == Some(0) {
112            return Err(
113                "sync.invalid_request: transport config maxRequestBytes must be a positive integer"
114                    .to_owned(),
115            );
116        }
117        if self.max_response_bytes == Some(0) {
118            return Err("sync.invalid_request: transport config maxResponseBytes must be a positive integer".to_owned());
119        }
120        Ok(())
121    }
122
123    /// Parse the policy from the transport JSON config. Absent keys keep their
124    /// defaults; a wrong type or an out-of-range bound is rejected loudly.
125    pub fn from_config(config: &serde_json::Value) -> Result<Self, String> {
126        let bound = |key: &str, message: &'static str| -> Result<Option<u64>, String> {
127            match config.get(key) {
128                None | Some(serde_json::Value::Null) => Ok(None),
129                Some(value) => match value.as_u64() {
130                    Some(number) if number >= 1 => Ok(Some(number)),
131                    _ => Err(message.to_owned()),
132                },
133            }
134        };
135        let redirects = match config.get("redirects") {
136            None | Some(serde_json::Value::Null) => RedirectPolicy::Deny,
137            Some(serde_json::Value::String(value)) if value == "deny" => RedirectPolicy::Deny,
138            Some(serde_json::Value::String(value)) if value == "follow" => RedirectPolicy::Follow,
139            Some(_) => return Err(
140                "sync.invalid_request: transport config redirects must be \"deny\" or \"follow\""
141                    .to_owned(),
142            ),
143        };
144        let policy = Self {
145            request_timeout: bound(
146                "requestTimeoutMs",
147                "sync.invalid_request: transport config requestTimeoutMs must be a positive integer",
148            )?
149            .map(Duration::from_millis),
150            round_deadline: bound(
151                "roundDeadlineMs",
152                "sync.invalid_request: transport config roundDeadlineMs must be a positive integer",
153            )?
154            .map(Duration::from_millis),
155            max_request_bytes: bound(
156                "maxRequestBytes",
157                "sync.invalid_request: transport config maxRequestBytes must be a positive integer",
158            )?,
159            max_response_bytes: bound(
160                "maxResponseBytes",
161                "sync.invalid_request: transport config maxResponseBytes must be a positive integer",
162            )?,
163            redirects,
164            realtime_heartbeat: bound(
165                "realtimeHeartbeatMs",
166                "sync.invalid_request: transport config realtimeHeartbeatMs must be a positive integer",
167            )?
168            .map(Duration::from_millis),
169        };
170        policy.validate()?;
171        Ok(policy)
172    }
173}
174
175/// One inbound realtime frame buffered for the client's `on_realtime_*`.
176pub enum Inbound {
177    Text(String),
178    Binary(Vec<u8>),
179    /// The realtime connection ended without the host closing it (the peer closed an idle socket, a read or write failed, or a
180    /// send was abandoned). Pushed before any round or send waiter is woken, so the host drains it before it reconnects.
181    Disconnected(TransportError),
182}
183
184/// Metadata for one received WebSocket message. The byte count includes the
185/// Syncular channel tag for binary messages, but excludes WebSocket headers.
186#[derive(Debug, Clone, Copy, PartialEq, Eq)]
187pub struct RealtimeReceipt {
188    pub received_at: SystemTime,
189    pub bytes: usize,
190    pub kind: RealtimeReceiptKind,
191}
192
193#[derive(Debug, Clone, Copy, PartialEq, Eq)]
194pub enum RealtimeReceiptKind {
195    Text,
196    Delta,
197    Round,
198    OtherBinary,
199    Ping,
200    Pong,
201    Close,
202}
203
204/// Text and delta payload bytes the inbound buffer holds before the reader
205/// ends the connection (§8.8). Deltas are a latency path: the loss schedules a
206/// reconnect and a catch-up pull, so a host that drains late converges.
207pub const INBOUND_BUFFER_LIMIT_BYTES: usize = 16 * 1024 * 1024;
208
209/// Buffered inbound frames and their text/delta payload size.
210#[derive(Default)]
211struct InboundFrames {
212    list: Vec<Inbound>,
213    bytes: usize,
214}
215
216/// The shared inbound buffer the WS reader thread fills and the command path
217/// drains. The optional callback carries no data; it only wakes an owning
218/// mailbox so the host can drain the buffer promptly.
219pub struct InboundBuffer {
220    frames: Mutex<InboundFrames>,
221    notify: Option<Arc<dyn Fn() + Send + Sync>>,
222    receipts: Mutex<Option<mpsc::SyncSender<RealtimeReceipt>>>,
223    dropped_receipts: AtomicU64,
224}
225
226impl Default for InboundBuffer {
227    fn default() -> Self {
228        Self {
229            frames: Mutex::new(InboundFrames::default()),
230            notify: None,
231            receipts: Mutex::new(None),
232            dropped_receipts: AtomicU64::new(0),
233        }
234    }
235}
236
237impl InboundBuffer {
238    pub fn with_notify(notify: Arc<dyn Fn() + Send + Sync>) -> Self {
239        Self {
240            frames: Mutex::new(InboundFrames::default()),
241            notify: Some(notify),
242            receipts: Mutex::new(None),
243            dropped_receipts: AtomicU64::new(0),
244        }
245    }
246
247    pub fn push(&self, frame: Inbound) {
248        {
249            let mut frames = self.frames.lock().expect("inbound lock");
250            frames.bytes += match &frame {
251                Inbound::Text(text) => text.len(),
252                Inbound::Binary(bytes) => bytes.len(),
253                Inbound::Disconnected(_) => 0,
254            };
255            frames.list.push(frame);
256        }
257        if let Some(notify) = &self.notify {
258            notify();
259        }
260    }
261
262    fn take(&self) -> Vec<Inbound> {
263        std::mem::take(&mut *self.frames.lock().expect("inbound lock")).list
264    }
265
266    /// Whether the undrained frames exceed [`INBOUND_BUFFER_LIMIT_BYTES`].
267    #[cfg(feature = "native-transport")]
268    fn overflowed(&self) -> bool {
269        self.frames.lock().expect("inbound lock").bytes > INBOUND_BUFFER_LIMIT_BYTES
270    }
271
272    #[cfg(feature = "native-transport")]
273    fn observe(&self, kind: RealtimeReceiptKind, bytes: usize) {
274        if let Some(sender) = self.receipts.lock().expect("receipt lock").as_ref() {
275            let receipt = RealtimeReceipt {
276                received_at: SystemTime::now(),
277                bytes,
278                kind,
279            };
280            if sender.try_send(receipt).is_err() {
281                self.dropped_receipts.fetch_add(1, Ordering::Relaxed);
282            }
283        }
284    }
285}
286
287// One transport is held per host, so the native arm's size is not worth an
288// indirection; boxing it would change the public variant's payload type.
289#[allow(clippy::large_enum_variant)]
290pub enum HostTransport {
291    /// No network: client-local commands only (dependency-lean default).
292    Null {
293        signed_urls: bool,
294        inbound: Arc<InboundBuffer>,
295    },
296    #[cfg(feature = "native-transport")]
297    Native(native::NativeTransport),
298    /// §12 local authority in front of the `Null` or `Native` remote.
299    #[cfg(feature = "local-authority")]
300    Local(Box<LocalAuthorityTransport<HostTransport>>),
301}
302
303impl HostTransport {
304    /// Build the transport from the `new` config. `{}` (or no `baseUrl`) →
305    /// `Null`; a `baseUrl` under the `native-transport` feature → `Native`.
306    pub fn from_config(config: &serde_json::Value) -> Result<Self, String> {
307        Self::from_config_with_notify(config, None)
308    }
309
310    /// Build a transport whose realtime reader wakes a mailbox/event loop.
311    /// The callback is invoked after a frame is buffered and never carries
312    /// protocol data itself.
313    pub fn from_config_with_notify(
314        config: &serde_json::Value,
315        notify: Option<Arc<dyn Fn() + Send + Sync>>,
316    ) -> Result<Self, String> {
317        let policy = HostTransportPolicy::from_config(config)?;
318        Self::from_config_with_policy(config, policy, notify)
319    }
320
321    /// Build the transport with an explicit programmatic policy, ignoring any
322    /// policy keys the JSON config carries. `baseUrl` selection is unchanged;
323    /// a `localAuthorityPath` puts the §12 local authority in front of it.
324    pub fn from_config_with_policy(
325        config: &serde_json::Value,
326        policy: HostTransportPolicy,
327        notify: Option<Arc<dyn Fn() + Send + Sync>>,
328    ) -> Result<Self, String> {
329        let local_authority_path = match config.get("localAuthorityPath") {
330            None | Some(serde_json::Value::Null) => None,
331            Some(serde_json::Value::String(path)) if !path.is_empty() => Some(path.clone()),
332            Some(_) => return Err("localAuthorityPath must be a non-empty string".to_owned()),
333        };
334        #[cfg(not(feature = "local-authority"))]
335        if local_authority_path.is_some() {
336            return Err(format!(
337                "{}: this build has no local authority (rebuild with --features local-authority)",
338                crate::LOCAL_AUTHORITY_UNCONFIGURED_CODE
339            ));
340        }
341        let remote = match config.get("baseUrl").and_then(|v| v.as_str()) {
342            #[cfg(feature = "native-transport")]
343            Some(base_url) => HostTransport::Native(native::NativeTransport::with_policy(
344                base_url, config, policy, notify,
345            )?),
346            _ => {
347                #[cfg(not(feature = "native-transport"))]
348                {
349                    policy.validate()?;
350                    if config.get("baseUrl").is_some() {
351                        return Err(
352                            "this build has no native transport (rebuild with --features native-transport)"
353                                .to_owned(),
354                        );
355                    }
356                }
357                HostTransport::Null {
358                    signed_urls: false,
359                    inbound: Arc::new(match notify {
360                        Some(notify) => InboundBuffer::with_notify(notify),
361                        None => InboundBuffer::default(),
362                    }),
363                }
364            }
365        };
366        #[cfg(feature = "local-authority")]
367        if let Some(path) = local_authority_path {
368            let remote_configured = !matches!(remote, HostTransport::Null { .. });
369            return Ok(HostTransport::Local(Box::new(
370                LocalAuthorityTransport::new(path, remote, remote_configured),
371            )));
372        }
373        Ok(remote)
374    }
375
376    /// Network view for one I/O executor. The mutable owner keeps the reader
377    /// and inbound queue; no SQLite state or new socket is created.
378    pub fn fork_round(&self) -> Self {
379        match self {
380            Self::Null {
381                signed_urls,
382                inbound,
383            } => Self::Null {
384                signed_urls: *signed_urls,
385                inbound: inbound.clone(),
386            },
387            #[cfg(feature = "native-transport")]
388            Self::Native(t) => Self::Native(t.fork_round()),
389            #[cfg(feature = "local-authority")]
390            Self::Local(t) => Self::Local(Box::new(t.fork_round())),
391        }
392    }
393
394    pub fn set_signed_urls(&mut self, value: bool) {
395        match self {
396            HostTransport::Null { signed_urls, .. } => *signed_urls = value,
397            #[cfg(feature = "native-transport")]
398            HostTransport::Native(t) => t.signed_urls = value,
399            #[cfg(feature = "local-authority")]
400            HostTransport::Local(t) => t.remote.set_signed_urls(value),
401        }
402    }
403
404    /// Replace auth/application headers for subsequent HTTP requests and the
405    /// next realtime connection. A live socket retains its handshake headers.
406    pub fn set_headers(&mut self, headers: Vec<(String, String)>) {
407        match self {
408            HostTransport::Null { .. } => drop(headers),
409            #[cfg(feature = "native-transport")]
410            HostTransport::Native(t) => t.set_headers(headers),
411            #[cfg(feature = "local-authority")]
412            HostTransport::Local(t) => t.remote.set_headers(headers),
413        }
414    }
415
416    /// Replace the transport's bounds for subsequent network calls. A round
417    /// past its first exchange keeps its anchored deadline; every other bound
418    /// takes effect on the next call. An invalid policy is rejected and the
419    /// current policy stays in force.
420    pub fn set_policy(&mut self, policy: HostTransportPolicy) -> Result<(), String> {
421        policy.validate()?;
422        match self {
423            HostTransport::Null { .. } => {}
424            #[cfg(feature = "native-transport")]
425            HostTransport::Native(t) => t.set_policy(policy)?,
426            #[cfg(feature = "local-authority")]
427            HostTransport::Local(t) => t.remote.set_policy(policy)?,
428        }
429        Ok(())
430    }
431
432    /// Drain the inbound realtime frames buffered since the last call.
433    pub fn take_inbound(&mut self) -> Vec<Inbound> {
434        match self {
435            HostTransport::Null { inbound, .. } => inbound.take(),
436            #[cfg(feature = "native-transport")]
437            HostTransport::Native(t) => t.inbound.take(),
438            #[cfg(feature = "local-authority")]
439            HostTransport::Local(t) => t.remote.take_inbound(),
440        }
441    }
442
443    /// Observe received WebSocket messages without blocking the socket reader.
444    /// Supply a bounded `sync_channel` and drain it on a separate thread. The
445    /// observer is shared by round forks and survives reconnects. Replacing it
446    /// resets the dropped-receipt count.
447    pub fn set_realtime_receipt_observer(
448        &mut self,
449        sender: Option<mpsc::SyncSender<RealtimeReceipt>>,
450    ) {
451        let inbound = match self {
452            HostTransport::Null { inbound, .. } => inbound,
453            #[cfg(feature = "native-transport")]
454            HostTransport::Native(t) => &t.inbound,
455            #[cfg(feature = "local-authority")]
456            HostTransport::Local(t) => {
457                t.remote.set_realtime_receipt_observer(sender);
458                return;
459            }
460        };
461        let mut current = inbound.receipts.lock().expect("receipt lock");
462        *current = sender;
463        inbound.dropped_receipts.store(0, Ordering::Relaxed);
464    }
465
466    /// Return and clear the number of receipts lost to a full or closed channel.
467    pub fn take_dropped_realtime_receipts(&mut self) -> u64 {
468        let inbound = match self {
469            HostTransport::Null { inbound, .. } => inbound,
470            #[cfg(feature = "native-transport")]
471            HostTransport::Native(t) => &t.inbound,
472            #[cfg(feature = "local-authority")]
473            HostTransport::Local(t) => return t.remote.take_dropped_realtime_receipts(),
474        };
475        inbound.dropped_receipts.swap(0, Ordering::Relaxed)
476    }
477
478    /// Release the socket/reader thread and close the local authority.
479    /// Idempotent.
480    pub fn shutdown(&mut self) {
481        match self {
482            HostTransport::Null { .. } => {}
483            #[cfg(feature = "native-transport")]
484            HostTransport::Native(t) => t.shutdown(),
485            #[cfg(feature = "local-authority")]
486            HostTransport::Local(t) => t.shutdown(),
487        }
488    }
489}
490
491fn unavailable(op: &str) -> TransportError {
492    TransportError::new(
493        "transport.unavailable",
494        format!("{op} needs the native transport (build with --features native-transport)"),
495    )
496}
497
498// Without the native transport the `Null` arm ignores every request payload;
499// the params are only consumed by the feature-gated `Native` arm.
500#[cfg_attr(not(feature = "native-transport"), allow(unused_variables))]
501impl Transport for HostTransport {
502    fn sync(&mut self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
503        match self {
504            HostTransport::Null { .. } => Err(unavailable("sync")),
505            #[cfg(feature = "native-transport")]
506            HostTransport::Native(t) => t.sync(request),
507            #[cfg(feature = "local-authority")]
508            HostTransport::Local(t) => t.sync(request),
509        }
510    }
511
512    fn remote_operation(&mut self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
513        match self {
514            HostTransport::Null { .. } => Err(unavailable("remoteOperation")),
515            #[cfg(feature = "native-transport")]
516            HostTransport::Native(t) => t.remote_operation(request),
517            #[cfg(feature = "local-authority")]
518            HostTransport::Local(t) => t.remote_operation(request),
519        }
520    }
521
522    fn realtime_sync(&mut self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
523        match self {
524            HostTransport::Null { .. } => Err(unavailable("realtimeSync")),
525            #[cfg(feature = "native-transport")]
526            HostTransport::Native(t) => t.realtime_sync(request),
527            #[cfg(feature = "local-authority")]
528            HostTransport::Local(t) => t.realtime_sync(request),
529        }
530    }
531
532    fn download_segment(
533        &mut self,
534        request: &SegmentRequest,
535        on_progress: &mut dyn FnMut(u64),
536    ) -> Result<Vec<u8>, TransportError> {
537        match self {
538            HostTransport::Null { .. } => Err(unavailable("downloadSegment")),
539            #[cfg(feature = "native-transport")]
540            HostTransport::Native(t) => t.download_segment(request, on_progress),
541            #[cfg(feature = "local-authority")]
542            HostTransport::Local(t) => t.download_segment(request, on_progress),
543        }
544    }
545
546    fn supports_url_fetch(&self) -> bool {
547        match self {
548            HostTransport::Null { signed_urls, .. } => *signed_urls,
549            #[cfg(feature = "native-transport")]
550            HostTransport::Native(t) => t.signed_urls,
551            #[cfg(feature = "local-authority")]
552            HostTransport::Local(t) => t.supports_url_fetch(),
553        }
554    }
555
556    fn download_segments(
557        &mut self,
558        fetches: &[SegmentFetch],
559        on_progress: &mut (dyn FnMut(usize, u64) + Send),
560    ) -> Vec<Result<Vec<u8>, TransportError>> {
561        match self {
562            HostTransport::Null { .. } => fetches
563                .first()
564                .map(|_| Err(unavailable("downloadSegments")))
565                .into_iter()
566                .collect(),
567            #[cfg(feature = "native-transport")]
568            HostTransport::Native(t) => t.download_segments(fetches, on_progress),
569            #[cfg(feature = "local-authority")]
570            HostTransport::Local(t) => t.download_segments(fetches, on_progress),
571        }
572    }
573
574    fn fetch_url(
575        &mut self,
576        url: &str,
577        byte_length: u64,
578        on_progress: &mut dyn FnMut(u64),
579    ) -> Result<Vec<u8>, TransportError> {
580        match self {
581            HostTransport::Null { .. } => Err(unavailable("fetchUrl")),
582            #[cfg(feature = "native-transport")]
583            HostTransport::Native(t) => t.fetch_url(url, byte_length, on_progress),
584            #[cfg(feature = "local-authority")]
585            HostTransport::Local(t) => t.fetch_url(url, byte_length, on_progress),
586        }
587    }
588
589    fn blob_upload(
590        &mut self,
591        blob_id: &str,
592        bytes: &[u8],
593        media_type: Option<&str>,
594    ) -> Result<(), TransportError> {
595        match self {
596            HostTransport::Null { .. } => Err(unavailable("blobUpload")),
597            #[cfg(feature = "native-transport")]
598            HostTransport::Native(t) => t.blob_upload(blob_id, bytes, media_type),
599            #[cfg(feature = "local-authority")]
600            HostTransport::Local(t) => t.blob_upload(blob_id, bytes, media_type),
601        }
602    }
603
604    fn blob_download(
605        &mut self,
606        blob_id: &str,
607        byte_length: Option<u64>,
608    ) -> Result<BlobDownload, TransportError> {
609        match self {
610            HostTransport::Null { .. } => Err(unavailable("blobDownload")),
611            #[cfg(feature = "native-transport")]
612            HostTransport::Native(t) => t.blob_download(blob_id, byte_length),
613            #[cfg(feature = "local-authority")]
614            HostTransport::Local(t) => t.blob_download(blob_id, byte_length),
615        }
616    }
617
618    fn fetch_blob_url(
619        &mut self,
620        url: &str,
621        byte_length: Option<u64>,
622    ) -> Result<Vec<u8>, TransportError> {
623        match self {
624            HostTransport::Null { .. } => Err(unavailable("fetchBlobUrl")),
625            #[cfg(feature = "native-transport")]
626            HostTransport::Native(t) => t.fetch_blob_url(url, byte_length),
627            #[cfg(feature = "local-authority")]
628            HostTransport::Local(t) => t.fetch_blob_url(url, byte_length),
629        }
630    }
631
632    fn blob_upload_grant(
633        &mut self,
634        blob_id: &str,
635        byte_length: u64,
636        media_type: Option<&str>,
637    ) -> Result<BlobUploadGrant, TransportError> {
638        match self {
639            // No grant available ⇒ the client streams through the direct
640            // upload endpoint (§5.9.3 capability, not fallback).
641            HostTransport::Null { .. } => Ok(BlobUploadGrant::None),
642            #[cfg(feature = "native-transport")]
643            HostTransport::Native(t) => t.blob_upload_grant(blob_id, byte_length, media_type),
644            #[cfg(feature = "local-authority")]
645            HostTransport::Local(t) => t.blob_upload_grant(blob_id, byte_length, media_type),
646        }
647    }
648
649    fn blob_put_url(
650        &mut self,
651        blob_id: &str,
652        url: &str,
653        bytes: &[u8],
654        media_type: Option<&str>,
655    ) -> Result<(), TransportError> {
656        match self {
657            HostTransport::Null { .. } => Err(unavailable("blobPutUrl")),
658            #[cfg(feature = "native-transport")]
659            HostTransport::Native(t) => t.blob_put_url(blob_id, url, bytes, media_type),
660            #[cfg(feature = "local-authority")]
661            HostTransport::Local(t) => t.blob_put_url(blob_id, url, bytes, media_type),
662        }
663    }
664
665    fn realtime_connect(&mut self, client_id: &str) -> Result<(), TransportError> {
666        match self {
667            HostTransport::Null { .. } => Err(unavailable("realtimeConnect")),
668            #[cfg(feature = "native-transport")]
669            HostTransport::Native(t) => t.realtime_connect(client_id),
670            #[cfg(feature = "local-authority")]
671            HostTransport::Local(t) => t.realtime_connect(client_id),
672        }
673    }
674
675    fn realtime_send(&mut self, text: &str) -> Result<(), TransportError> {
676        match self {
677            HostTransport::Null { .. } => Err(unavailable("realtimeSend")),
678            #[cfg(feature = "native-transport")]
679            HostTransport::Native(t) => t.realtime_send(text),
680            #[cfg(feature = "local-authority")]
681            HostTransport::Local(t) => t.realtime_send(text),
682        }
683    }
684
685    fn realtime_close(&mut self) -> Result<(), TransportError> {
686        match self {
687            HostTransport::Null { .. } => Ok(()),
688            #[cfg(feature = "native-transport")]
689            HostTransport::Native(t) => t.realtime_close(),
690            #[cfg(feature = "local-authority")]
691            HostTransport::Local(t) => t.realtime_close(),
692        }
693    }
694
695    fn round_deadline(&self) -> Option<std::time::Duration> {
696        match self {
697            HostTransport::Null { .. } => None,
698            #[cfg(feature = "native-transport")]
699            HostTransport::Native(t) => t.round_deadline(),
700            #[cfg(feature = "local-authority")]
701            HostTransport::Local(t) => t.round_deadline(),
702        }
703    }
704
705    fn set_round_deadline(&mut self, deadline: Option<std::time::Instant>) {
706        match self {
707            HostTransport::Null { .. } => {}
708            #[cfg(feature = "native-transport")]
709            HostTransport::Native(t) => t.set_round_deadline(deadline),
710            #[cfg(feature = "local-authority")]
711            HostTransport::Local(t) => t.set_round_deadline(deadline),
712        }
713    }
714
715    fn set_idle_bound(&mut self, bound: Option<std::time::Duration>) {
716        match self {
717            HostTransport::Null { .. } => {}
718            #[cfg(feature = "native-transport")]
719            HostTransport::Native(t) => t.set_idle_bound(bound),
720            #[cfg(feature = "local-authority")]
721            HostTransport::Local(t) => t.set_idle_bound(bound),
722        }
723    }
724
725    #[cfg(feature = "local-authority")]
726    fn open_local_authority(
727        &mut self,
728        schema: &serde_json::Value,
729        replica_path: Option<&str>,
730    ) -> Result<(), TransportError> {
731        match self {
732            HostTransport::Local(t) => t.open_local_authority(schema, replica_path),
733            _ => Ok(()),
734        }
735    }
736
737    #[cfg(feature = "local-authority")]
738    fn local_authority_state(&self) -> Option<&'static str> {
739        match self {
740            HostTransport::Local(t) => t.local_authority_state(),
741            _ => None,
742        }
743    }
744
745    #[cfg(feature = "local-authority")]
746    fn attach_local_authority(&mut self) -> Result<(), TransportError> {
747        match self {
748            HostTransport::Local(t) => t.attach_local_authority(),
749            _ => Err(local::unconfigured("this transport has no local authority")),
750        }
751    }
752
753    #[cfg(feature = "local-authority")]
754    fn abandon_local_authority_attach(&mut self) -> Result<(), TransportError> {
755        match self {
756            HostTransport::Local(t) => t.abandon_local_authority_attach(),
757            _ => Err(local::unconfigured("this transport has no local authority")),
758        }
759    }
760}
761
762#[cfg(feature = "local-authority")]
763pub use local::LocalAuthorityTransport;
764
765#[cfg(feature = "local-authority")]
766mod local {
767    //! §12.4 routing: sync rounds reach the in-process local authority until
768    //! attach completes, then the remote transport. The replica rebinds to the
769    //! remote server through the §2.1 log-epoch reset, so the client core adds
770    //! no logic. While the authority serves the client there is no realtime
771    //! channel and no segment endpoint: the authority delivers bootstrap rows
772    //! inline (§5.7).
773
774    use std::sync::{Arc, Mutex};
775
776    use syncular_authority::{AuthorityError, AuthorityState, LocalAuthority};
777
778    use super::HostTransport;
779    use crate::{
780        BlobDownload, BlobUploadGrant, SegmentFetch, SegmentRequest, Transport, TransportError,
781        LOCAL_AUTHORITY_UNCONFIGURED_CODE,
782    };
783
784    pub(super) fn unconfigured(message: &'static str) -> TransportError {
785        TransportError::new(LOCAL_AUTHORITY_UNCONFIGURED_CODE, message)
786    }
787
788    fn transport_error(error: AuthorityError) -> TransportError {
789        TransportError {
790            code: error.code,
791            message: error.message,
792            details: error.details,
793        }
794    }
795
796    fn authority_error(error: TransportError) -> AuthorityError {
797        AuthorityError {
798            code: error.code,
799            message: error.message,
800            details: error.details,
801        }
802    }
803
804    fn refused(message: &'static str) -> TransportError {
805        TransportError::new("sync.invalid_request", message)
806    }
807
808    /// The §12 local authority in front of a remote transport `R`.
809    pub struct LocalAuthorityTransport<R> {
810        path: String,
811        /// Opened by `create` with the client's schema. Every round view
812        /// (`fork_round`) shares it, so attach and rounds serialize on it.
813        authority: Arc<Mutex<Option<LocalAuthority>>>,
814        pub(super) remote: R,
815        /// A remote server is configured (`baseUrl`): attach and abandon
816        /// need it.
817        remote_configured: bool,
818    }
819
820    impl<R> LocalAuthorityTransport<R> {
821        /// `path` is the authority's own SQLite file (`":memory:"` for
822        /// tests), never the replica's: the client's schema reset drops
823        /// every replica table outside `_syncular_*`.
824        pub fn new(path: impl Into<String>, remote: R, remote_configured: bool) -> Self {
825            Self {
826                path: path.into(),
827                authority: Arc::new(Mutex::new(None)),
828                remote,
829                remote_configured,
830            }
831        }
832
833        fn local_active(&self) -> bool {
834            self.authority
835                .lock()
836                .expect("local authority lock")
837                .as_ref()
838                .is_none_or(|authority| authority.state() != AuthorityState::Attached)
839        }
840    }
841
842    impl LocalAuthorityTransport<HostTransport> {
843        pub(super) fn fork_round(&self) -> Self {
844            Self {
845                path: self.path.clone(),
846                authority: self.authority.clone(),
847                remote: self.remote.fork_round(),
848                remote_configured: self.remote_configured,
849            }
850        }
851
852        pub(super) fn shutdown(&mut self) {
853            self.remote.shutdown();
854            *self.authority.lock().expect("local authority lock") = None;
855        }
856    }
857
858    impl<R: Transport> Transport for LocalAuthorityTransport<R> {
859        fn sync(&mut self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
860            let mut authority = self.authority.lock().expect("local authority lock");
861            match authority.as_mut() {
862                None => Err(unconfigured(
863                    "the local authority opens with create; create a client first",
864                )),
865                Some(local) if local.state() != AuthorityState::Attached => {
866                    local.sync(request).map_err(transport_error)
867                }
868                Some(_) => {
869                    drop(authority);
870                    self.remote.sync(request)
871                }
872            }
873        }
874
875        fn remote_operation(&mut self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
876            self.remote.remote_operation(request)
877        }
878
879        fn realtime_sync(&mut self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
880            if self.local_active() {
881                return Err(refused("the local authority has no realtime channel"));
882            }
883            self.remote.realtime_sync(request)
884        }
885
886        fn download_segment(
887            &mut self,
888            request: &SegmentRequest,
889            on_progress: &mut dyn FnMut(u64),
890        ) -> Result<Vec<u8>, TransportError> {
891            if self.local_active() {
892                return Err(refused("the local authority has no segment endpoint"));
893            }
894            self.remote.download_segment(request, on_progress)
895        }
896
897        fn download_segments(
898            &mut self,
899            fetches: &[SegmentFetch],
900            on_progress: &mut (dyn FnMut(usize, u64) + Send),
901        ) -> Vec<Result<Vec<u8>, TransportError>> {
902            if self.local_active() {
903                return fetches
904                    .first()
905                    .map(|_| Err(refused("the local authority has no segment endpoint")))
906                    .into_iter()
907                    .collect();
908            }
909            self.remote.download_segments(fetches, on_progress)
910        }
911
912        fn supports_url_fetch(&self) -> bool {
913            self.remote.supports_url_fetch()
914        }
915
916        fn fetch_url(
917            &mut self,
918            url: &str,
919            byte_length: u64,
920            on_progress: &mut dyn FnMut(u64),
921        ) -> Result<Vec<u8>, TransportError> {
922            if self.local_active() {
923                return Err(refused("the local authority has no segment endpoint"));
924            }
925            self.remote.fetch_url(url, byte_length, on_progress)
926        }
927
928        fn blob_upload(
929            &mut self,
930            blob_id: &str,
931            bytes: &[u8],
932            media_type: Option<&str>,
933        ) -> Result<(), TransportError> {
934            self.remote.blob_upload(blob_id, bytes, media_type)
935        }
936
937        fn blob_download(
938            &mut self,
939            blob_id: &str,
940            byte_length: Option<u64>,
941        ) -> Result<BlobDownload, TransportError> {
942            self.remote.blob_download(blob_id, byte_length)
943        }
944
945        fn fetch_blob_url(
946            &mut self,
947            url: &str,
948            byte_length: Option<u64>,
949        ) -> Result<Vec<u8>, TransportError> {
950            self.remote.fetch_blob_url(url, byte_length)
951        }
952
953        fn blob_upload_grant(
954            &mut self,
955            blob_id: &str,
956            byte_length: u64,
957            media_type: Option<&str>,
958        ) -> Result<BlobUploadGrant, TransportError> {
959            self.remote
960                .blob_upload_grant(blob_id, byte_length, media_type)
961        }
962
963        fn blob_put_url(
964            &mut self,
965            blob_id: &str,
966            url: &str,
967            bytes: &[u8],
968            media_type: Option<&str>,
969        ) -> Result<(), TransportError> {
970            self.remote.blob_put_url(blob_id, url, bytes, media_type)
971        }
972
973        fn realtime_connect(&mut self, client_id: &str) -> Result<(), TransportError> {
974            if self.local_active() {
975                return Err(refused("the local authority has no realtime channel"));
976            }
977            self.remote.realtime_connect(client_id)
978        }
979
980        fn round_deadline(&self) -> Option<std::time::Duration> {
981            self.remote.round_deadline()
982        }
983
984        fn set_round_deadline(&mut self, deadline: Option<std::time::Instant>) {
985            self.remote.set_round_deadline(deadline);
986        }
987
988        fn set_idle_bound(&mut self, bound: Option<std::time::Duration>) {
989            self.remote.set_idle_bound(bound);
990        }
991
992        fn realtime_send(&mut self, text: &str) -> Result<(), TransportError> {
993            self.remote.realtime_send(text)
994        }
995
996        fn realtime_close(&mut self) -> Result<(), TransportError> {
997            self.remote.realtime_close()
998        }
999
1000        fn open_local_authority(
1001            &mut self,
1002            schema: &serde_json::Value,
1003            replica_path: Option<&str>,
1004        ) -> Result<(), TransportError> {
1005            if self.path != ":memory:" && replica_path == Some(self.path.as_str()) {
1006                return Err(TransportError::new(
1007                    "sync.invalid_request",
1008                    "localAuthorityPath must name a file other than the replica's dbPath",
1009                ));
1010            }
1011            let mut authority = self.authority.lock().expect("local authority lock");
1012            // Close the previous authority before reopening its file.
1013            *authority = None;
1014            *authority = Some(LocalAuthority::open(&self.path, schema).map_err(transport_error)?);
1015            Ok(())
1016        }
1017
1018        fn local_authority_state(&self) -> Option<&'static str> {
1019            self.authority
1020                .lock()
1021                .expect("local authority lock")
1022                .as_ref()
1023                .map(|authority| match authority.state() {
1024                    AuthorityState::Local => "local",
1025                    AuthorityState::Attaching => "attaching",
1026                    AuthorityState::Attached => "attached",
1027                })
1028        }
1029
1030        fn attach_local_authority(&mut self) -> Result<(), TransportError> {
1031            if !self.remote_configured {
1032                return Err(unconfigured(
1033                    "attachLocalAuthority needs a baseUrl for the remote server",
1034                ));
1035            }
1036            let remote = &mut self.remote;
1037            let mut authority = self.authority.lock().expect("local authority lock");
1038            authority
1039                .as_mut()
1040                .ok_or_else(|| {
1041                    unconfigured("the local authority opens with create; create a client first")
1042                })?
1043                .attach(&mut |request: &[u8]| remote.sync(request).map_err(authority_error))
1044                .map_err(transport_error)
1045        }
1046
1047        fn abandon_local_authority_attach(&mut self) -> Result<(), TransportError> {
1048            if !self.remote_configured {
1049                return Err(unconfigured(
1050                    "abandonLocalAuthorityAttach needs a baseUrl for the remote server",
1051                ));
1052            }
1053            let remote = &mut self.remote;
1054            let mut authority = self.authority.lock().expect("local authority lock");
1055            authority
1056                .as_mut()
1057                .ok_or_else(|| {
1058                    unconfigured("the local authority opens with create; create a client first")
1059                })?
1060                .abandon_attach(Some(&mut |request: &[u8]| {
1061                    remote.sync(request).map_err(authority_error)
1062                }))
1063                .map_err(transport_error)
1064        }
1065    }
1066}
1067
1068#[cfg(feature = "native-transport")]
1069mod native {
1070    //! The real native HTTP + WS transport. HTTP via `ureq` (blocking, no
1071    //! async runtime — matches the client's synchronous API); WS via
1072    //! `tungstenite`, with a reader thread pushing inbound frames into the
1073    //! shared `InboundBuffer`.
1074    //!
1075    //! Wire contract mirrors the reference HTTP+WS bindings (§1.1, §8.7):
1076    //! `POST {baseUrl}/sync` (application/vnd.syncular.sync.v2, `X-Syncular-Scopes`
1077    //! not needed here — the native app authenticates via configured headers),
1078    //! `GET {baseUrl}/segments/{id}`, `PUT/GET {baseUrl}/blobs/{id}`, and the
1079    //! realtime socket at `{wsUrl}` (ws(s):// derived from baseUrl).
1080
1081    use std::io::{self, Read, Write};
1082    use std::net::{TcpStream, ToSocketAddrs};
1083    use std::sync::atomic::{AtomicBool, Ordering};
1084    use std::sync::{mpsc, Arc, Condvar, Mutex};
1085    use std::thread::JoinHandle;
1086    use std::time::{Duration, Instant};
1087
1088    use polling::{Event, Events, Poller};
1089    use tungstenite::stream::MaybeTlsStream;
1090    use tungstenite::Message;
1091    use ureq::unversioned::resolver::DefaultResolver;
1092    use ureq::unversioned::transport::{
1093        time::Duration as UreqDuration, ConnectionDetails, Connector, DefaultConnector,
1094        NextTimeout, Transport as UreqTransport,
1095    };
1096    use ureq::Timeout as UreqTimeout;
1097
1098    use super::{HostTransportPolicy, Inbound, InboundBuffer, RealtimeReceiptKind, RedirectPolicy};
1099    use crate::{
1100        BlobDownload, BlobUploadGrant, RealtimeRound, RoundInbound, SegmentFetch, SegmentRequest,
1101        Transport, TransportError,
1102    };
1103
1104    // Unregister before the cloned socket handle is closed, including on unwind.
1105    struct SocketRegistration {
1106        poller: Arc<Poller>,
1107        stream: TcpStream,
1108    }
1109
1110    impl Drop for SocketRegistration {
1111        fn drop(&mut self) {
1112            let _ = self.poller.delete(&self.stream);
1113        }
1114    }
1115
1116    #[derive(Clone)]
1117    struct SocketSender {
1118        queue: mpsc::SyncSender<Outgoing>,
1119        poller: Arc<Poller>,
1120    }
1121
1122    struct Outgoing {
1123        message: Message,
1124        completed: mpsc::Sender<Result<(), TransportError>>,
1125    }
1126
1127    /// How long a socket round tolerates silence: no inbound byte of the
1128    /// response, or no outbound request chunk flushed, for this long fails the
1129    /// round (§1.8). The bound restarts on every chunk of progress, so a slow
1130    /// link that keeps delivering never trips it; the host's whole-round
1131    /// deadline is the only ceiling on total transfer time.
1132    const ROUND_IDLE_TIMEOUT: Duration = Duration::from_secs(30);
1133    /// Largest `0x01` chunk of a request. Each chunk's flush is one unit of
1134    /// outbound progress; chunk boundaries carry no meaning (§8.7).
1135    const REQUEST_CHUNK_BYTES: usize = 64 * 1024;
1136
1137    /// The bound that ends a socket round first.
1138    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
1139    enum Expiry {
1140        /// The fixed socket silence bound (§1.8).
1141        Silence,
1142        /// The §7.8 drive bound, which also restarts on progress.
1143        Drive,
1144        /// The host's absolute whole-round deadline.
1145        Ceiling,
1146    }
1147
1148    /// When a round with `last_progress`, a silence bound `idle` and an
1149    /// optional drive bound expires, and which bound binds. The host's
1150    /// whole-round `ceiling` is absolute.
1151    fn round_expiry(
1152        last_progress: Instant,
1153        idle: Duration,
1154        drive: Option<Duration>,
1155        ceiling: Option<Instant>,
1156    ) -> (Instant, Expiry) {
1157        let mut expiry = (last_progress + idle, Expiry::Silence);
1158        if let Some(at) = drive.and_then(|drive| last_progress.checked_add(drive)) {
1159            if at < expiry.0 {
1160                expiry = (at, Expiry::Drive);
1161            }
1162        }
1163        match ceiling {
1164            Some(ceiling) if ceiling < expiry.0 => (ceiling, Expiry::Ceiling),
1165            _ => expiry,
1166        }
1167    }
1168    /// The §8.7 round rendezvous shared between the reader thread (which
1169    /// demuxes inbound `0x01` chunks into the round via [`RealtimeRound`]) and
1170    /// `realtime_sync` (which begins the round, sends the request, and blocks
1171    /// here for the reassembled response). The transport-agnostic framing
1172    /// logic lives in [`RealtimeRound`] (the lean client crate, shared with
1173    /// the Tauri plugin); this struct is just the thread rendezvous.
1174    #[derive(Default)]
1175    pub(super) struct RoundChannel {
1176        state: Mutex<RoundState>,
1177        ready: Condvar,
1178    }
1179
1180    #[derive(Default)]
1181    struct RoundState {
1182        round: RealtimeRound,
1183        /// When the round last moved: its request was framed, a request chunk
1184        /// flushed, or a response chunk arrived.
1185        last_progress: Option<Instant>,
1186        /// The connection ended; no round can ever complete on it.
1187        lost: bool,
1188        /// The completed round outcome, taken by `realtime_sync` once set.
1189        outcome: Option<Result<Vec<u8>, TransportError>>,
1190    }
1191
1192    impl RoundChannel {
1193        /// Begin a round: frame the request (`0x01` tag + envelope) for the
1194        /// socket and mark it in flight. Errors if one is already in flight
1195        /// (§8.7 one-in-flight, enforced client-side).
1196        fn begin(&self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
1197            let mut state = self.state.lock().expect("round lock");
1198            state.outcome = None;
1199            let framed = state.round.begin(request)?;
1200            state.last_progress = Some(Instant::now());
1201            Ok(framed)
1202        }
1203
1204        /// Record that a request chunk flushed.
1205        fn progressed(&self) {
1206            self.state.lock().expect("round lock").last_progress = Some(Instant::now());
1207        }
1208
1209        /// Whether the connection already ended. The reader thread publishes
1210        /// `Inbound::Disconnected` itself in that case.
1211        fn lost(&self) -> bool {
1212            self.state.lock().expect("round lock").lost
1213        }
1214
1215        /// Route one inbound binary frame from the reader thread. Returns the
1216        /// delta payload to enqueue on the inbound buffer, if any; a completed
1217        /// or failed round is stored and the waiting `realtime_sync` woken.
1218        fn route_binary(&self, frame: &[u8]) -> Option<Vec<u8>> {
1219            let mut state = self.state.lock().expect("round lock");
1220            match state.round.route_binary(frame) {
1221                Ok(RoundInbound::Delta(body)) => Some(body),
1222                Ok(RoundInbound::RoundProgress) => {
1223                    state.last_progress = Some(Instant::now());
1224                    None
1225                }
1226                Ok(RoundInbound::Ignored) => None,
1227                Ok(RoundInbound::RoundComplete(bytes)) => {
1228                    state.outcome = Some(Ok(bytes));
1229                    self.ready.notify_all();
1230                    None
1231                }
1232                Err(error) => {
1233                    state.outcome = Some(Err(error));
1234                    self.ready.notify_all();
1235                    None
1236                }
1237            }
1238        }
1239
1240        /// Fail any in-flight round (socket dropped) and wake the waiter.
1241        fn fail_in_flight(&self, error: TransportError) {
1242            let mut state = self.state.lock().expect("round lock");
1243            state.lost = true;
1244            if state.round.in_flight() && state.outcome.is_none() {
1245                state.round.abort();
1246                state.outcome = Some(Err(error));
1247                self.ready.notify_all();
1248            }
1249        }
1250
1251        /// Block until the round completes, fails, goes `idle` or the `drive`
1252        /// bound without progress, or reaches the host's whole-round `ceiling`.
1253        fn wait(
1254            &self,
1255            ceiling: Option<Instant>,
1256            idle: Duration,
1257            drive: Option<Duration>,
1258        ) -> Result<Vec<u8>, TransportError> {
1259            let mut state = self.state.lock().expect("round lock");
1260            while state.outcome.is_none() {
1261                let (deadline, expiry) = round_expiry(
1262                    state.last_progress.unwrap_or_else(Instant::now),
1263                    idle,
1264                    drive,
1265                    ceiling,
1266                );
1267                let now = Instant::now();
1268                if now >= deadline {
1269                    state.round.abort();
1270                    return Err(match expiry {
1271                        Expiry::Ceiling => {
1272                            timeout_error("sync round deadline exceeded", "round_deadline")
1273                        }
1274                        Expiry::Drive => {
1275                            timeout_error("realtime sync round made no progress", "drive")
1276                        }
1277                        Expiry::Silence => TransportError::new(
1278                            "sync.transport_failed",
1279                            "realtime sync round made no progress (§8.7)",
1280                        ),
1281                    });
1282                }
1283                let (guard, _timeout) = self
1284                    .ready
1285                    .wait_timeout(state, deadline - now)
1286                    .expect("round wait");
1287                state = guard;
1288            }
1289            state.outcome.take().expect("outcome present")
1290        }
1291    }
1292
1293    fn transfer_error(
1294        message: &'static str,
1295        cause_kind: &'static str,
1296        http_status: Option<u16>,
1297    ) -> TransportError {
1298        let mut details = serde_json::json!({ "causeKind": cause_kind });
1299        if let Some(status) = http_status {
1300            details["httpStatus"] = status.into();
1301        }
1302        let mut error = TransportError::new("transport.failed", message);
1303        error.details = Some(details);
1304        error
1305    }
1306
1307    /// A configured deadline elapsed. `cause_kind` distinguishes the
1308    /// per-request timeout from the whole-round deadline; `drive` is the §7.8
1309    /// drive bound, which fails the call with `sync.idle_timeout` (the round
1310    /// adds its details).
1311    fn timeout_error(message: &'static str, cause_kind: &'static str) -> TransportError {
1312        if cause_kind == "drive" {
1313            return TransportError::new("sync.idle_timeout", message);
1314        }
1315        let mut error = TransportError::new("transport.timeout", message);
1316        error.details = Some(serde_json::json!({ "causeKind": cause_kind }));
1317        error
1318    }
1319
1320    /// A 3xx was refused (either by policy or by exhausting the follow budget).
1321    fn redirect_error(message: &'static str, http_status: Option<u16>) -> TransportError {
1322        let mut details = serde_json::json!({ "causeKind": "redirect" });
1323        if let Some(status) = http_status {
1324            details["httpStatus"] = status.into();
1325        }
1326        let mut error = TransportError::new("transport.redirect", message);
1327        error.details = Some(details);
1328        error
1329    }
1330
1331    /// A 3xx that reached the caller means the redirect was refused (the
1332    /// request was credential bearing or the policy denies redirects). ureq
1333    /// returns such a response as-is when the ceiling is zero, so the refusal
1334    /// is detected here rather than in the error classifier.
1335    fn redirect_refused(resp: &ureq::http::Response<ureq::Body>) -> Result<(), TransportError> {
1336        let status = resp.status().as_u16();
1337        if (300..400).contains(&status) {
1338            return Err(redirect_error("redirect refused", Some(status)));
1339        }
1340        Ok(())
1341    }
1342
1343    /// The `causeKind` of a body-read timeout, or `None` for another error,
1344    /// classified through ureq's wrapping chain without formatting it:
1345    /// `Error::into_io` boxes a non-io ureq error as `io::Error::other`, and
1346    /// the gzip decoder re-wraps a plain io error as `Error::Decompress("gzip",
1347    /// e)`. Direct, nested, and plain shapes all count. Only the round
1348    /// deadline sets ureq's global timeout (`finish_request`), so a global
1349    /// timeout is the round deadline's (§1.8).
1350    /// Only the drive bound sets the per-read and per-write timeouts.
1351    fn timeout_cause(error: &std::io::Error) -> Option<&'static str> {
1352        let ureq_error = error
1353            .get_ref()
1354            .and_then(|inner| inner.downcast_ref::<ureq::Error>());
1355        match ureq_error {
1356            Some(ureq::Error::Timeout(ureq::Timeout::Global)) => Some("round_deadline"),
1357            Some(ureq::Error::Timeout(ureq::Timeout::PerRead | ureq::Timeout::PerWrite)) => {
1358                Some("drive")
1359            }
1360            Some(ureq::Error::Timeout(_)) => Some("timeout"),
1361            Some(ureq::Error::Io(nested) | ureq::Error::Decompress(_, nested)) => {
1362                timeout_cause(nested)
1363            }
1364            _ => (error.kind() == std::io::ErrorKind::TimedOut).then_some("timeout"),
1365        }
1366    }
1367
1368    fn http_err(message: &'static str, error: ureq::Error) -> TransportError {
1369        let (kind, status) = match error {
1370            ureq::Error::StatusCode(status) if (300..400).contains(&status) => {
1371                return redirect_error(message, Some(status))
1372            }
1373            ureq::Error::StatusCode(status) => ("status", Some(status)),
1374            ureq::Error::Timeout(ureq::Timeout::Global) => {
1375                return timeout_error(message, "round_deadline")
1376            }
1377            ureq::Error::Timeout(ureq::Timeout::PerRead | ureq::Timeout::PerWrite) => {
1378                return timeout_error(message, "drive")
1379            }
1380            ureq::Error::Timeout(_) => return timeout_error(message, "timeout"),
1381            ureq::Error::Io(error) => return io_err(message, error),
1382            ureq::Error::HostNotFound
1383            | ureq::Error::ConnectionFailed
1384            | ureq::Error::ConnectProxyFailed(_) => ("connect", None),
1385            ureq::Error::Tls(_)
1386            | ureq::Error::Rustls(_)
1387            | ureq::Error::Pem(_)
1388            | ureq::Error::TlsRequired => ("tls", None),
1389            ureq::Error::BadUri(_)
1390            | ureq::Error::Http(_)
1391            | ureq::Error::RequireHttpsOnly(_)
1392            | ureq::Error::InvalidProxyUrl => ("request", None),
1393            ureq::Error::Protocol(_) => ("protocol", None),
1394            ureq::Error::BodyExceedsLimit(_)
1395            | ureq::Error::BodyStalled
1396            | ureq::Error::Decompress(_, _) => ("body", None),
1397            ureq::Error::RedirectFailed | ureq::Error::TooManyRedirects => {
1398                return redirect_error(message, None)
1399            }
1400            _ => ("unknown", None),
1401        };
1402        transfer_error(message, kind, status)
1403    }
1404
1405    fn io_err(message: &'static str, error: std::io::Error) -> TransportError {
1406        if let Some(cause) = timeout_cause(&error) {
1407            return timeout_error(message, cause);
1408        }
1409        let kind = match error.kind() {
1410            std::io::ErrorKind::ConnectionRefused
1411            | std::io::ErrorKind::ConnectionAborted
1412            | std::io::ErrorKind::ConnectionReset
1413            | std::io::ErrorKind::NotConnected => "connect",
1414            _ => "io",
1415        };
1416        transfer_error(message, kind, None)
1417    }
1418
1419    fn ws_err(message: &'static str, error: tungstenite::Error) -> TransportError {
1420        match error {
1421            tungstenite::Error::Io(error) => io_err(message, error),
1422            tungstenite::Error::Tls(_) => transfer_error(message, "tls", None),
1423            // A 3xx that reached the caller was refused (the policy denies
1424            // redirects or the handshake request is credential bearing).
1425            tungstenite::Error::Http(response) if response.status().is_redirection() => {
1426                redirect_error(message, Some(response.status().as_u16()))
1427            }
1428            tungstenite::Error::Http(response) => {
1429                transfer_error(message, "status", Some(response.status().as_u16()))
1430            }
1431            tungstenite::Error::Url(_) | tungstenite::Error::HttpFormat(_) => {
1432                transfer_error(message, "request", None)
1433            }
1434            _ => transfer_error(message, "protocol", None),
1435        }
1436    }
1437
1438    const CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
1439
1440    fn remaining(deadline: Instant) -> io::Result<Duration> {
1441        deadline
1442            .checked_duration_since(Instant::now())
1443            .filter(|left| !left.is_zero())
1444            .ok_or_else(|| {
1445                io::Error::new(
1446                    io::ErrorKind::TimedOut,
1447                    "websocket establishment deadline exceeded",
1448                )
1449            })
1450    }
1451
1452    struct EstablishingStream {
1453        socket: TcpStream,
1454        deadline: Option<Instant>,
1455    }
1456
1457    impl EstablishingStream {
1458        fn timeout(&self) -> io::Result<Option<Duration>> {
1459            self.deadline.map(remaining).transpose()
1460        }
1461        fn established(&mut self) -> io::Result<TcpStream> {
1462            self.deadline = None;
1463            self.socket.set_read_timeout(None)?;
1464            self.socket.set_write_timeout(None)?;
1465            self.socket.try_clone()
1466        }
1467    }
1468
1469    fn establishment_io<T>(result: io::Result<T>, establishing: bool) -> io::Result<T> {
1470        result.map_err(|error| {
1471            if establishing
1472                && matches!(
1473                    error.kind(),
1474                    io::ErrorKind::WouldBlock | io::ErrorKind::TimedOut
1475                )
1476            {
1477                io::Error::new(
1478                    io::ErrorKind::TimedOut,
1479                    "websocket establishment deadline exceeded",
1480                )
1481            } else {
1482                error
1483            }
1484        })
1485    }
1486
1487    impl Read for EstablishingStream {
1488        fn read(&mut self, bytes: &mut [u8]) -> io::Result<usize> {
1489            if self.deadline.is_some() {
1490                self.socket.set_read_timeout(self.timeout()?)?;
1491            }
1492            establishment_io(self.socket.read(bytes), self.deadline.is_some())
1493        }
1494    }
1495    impl Write for EstablishingStream {
1496        fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
1497            if self.deadline.is_some() {
1498                self.socket.set_write_timeout(self.timeout()?)?;
1499            }
1500            establishment_io(self.socket.write(bytes), self.deadline.is_some())
1501        }
1502        fn flush(&mut self) -> io::Result<()> {
1503            if self.deadline.is_some() {
1504                self.socket.set_write_timeout(self.timeout()?)?;
1505            }
1506            establishment_io(self.socket.flush(), self.deadline.is_some())
1507        }
1508    }
1509
1510    fn connect_websocket(
1511        request: tungstenite::handshake::client::Request,
1512        deadline: Instant,
1513    ) -> Result<tungstenite::WebSocket<MaybeTlsStream<EstablishingStream>>, TransportError> {
1514        let host = request
1515            .uri()
1516            .host()
1517            .ok_or_else(|| transfer_error("realtime URL invalid", "request", None))?;
1518        let host = host.trim_start_matches('[').trim_end_matches(']');
1519        let port = match request.uri().scheme_str() {
1520            Some("ws") => request.uri().port_u16().unwrap_or(80),
1521            Some("wss") => request.uri().port_u16().unwrap_or(443),
1522            _ => return Err(transfer_error("realtime URL invalid", "request", None)),
1523        };
1524        // System DNS has no cancellable deadline. Only resolution runs here:
1525        // a late result cannot open a socket or issue an authenticated request.
1526        let host = host.to_owned();
1527        let (resolved, addresses) = mpsc::sync_channel(1);
1528        std::thread::Builder::new()
1529            .name("syncular-dns".to_owned())
1530            .spawn(move || {
1531                let result = (host.as_str(), port)
1532                    .to_socket_addrs()
1533                    .map(|items| items.collect::<Vec<_>>());
1534                let _ = resolved.send(result);
1535            })
1536            .map_err(|e| io_err("realtime DNS failed", e))?;
1537        let addresses = addresses
1538            .recv_timeout(remaining(deadline).map_err(|e| io_err("realtime DNS failed", e))?)
1539            .map_err(|e| match e {
1540                mpsc::RecvTimeoutError::Timeout => {
1541                    timeout_error("realtime DNS timed out", "timeout")
1542                }
1543                mpsc::RecvTimeoutError::Disconnected => {
1544                    transfer_error("realtime DNS failed", "io", None)
1545                }
1546            })?
1547            .map_err(|e| io_err("realtime DNS failed", e))?;
1548        let mut last_error = io::Error::new(io::ErrorKind::NotFound, "DNS returned no addresses");
1549        let mut socket = None;
1550        for address in addresses {
1551            match TcpStream::connect_timeout(
1552                &address,
1553                remaining(deadline).map_err(|e| io_err("realtime TCP connect failed", e))?,
1554            ) {
1555                Ok(stream) => {
1556                    socket = Some(stream);
1557                    break;
1558                }
1559                Err(error) => last_error = error,
1560            }
1561        }
1562        let socket = socket.ok_or_else(|| io_err("realtime TCP connect failed", last_error))?;
1563        socket
1564            .set_nodelay(true)
1565            .map_err(|e| io_err("realtime TCP connect failed", e))?;
1566        let stream = EstablishingStream {
1567            socket,
1568            deadline: Some(deadline),
1569        };
1570        // Same pinned rustls / WebPKI connector, certificate and hostname checks.
1571        // Redirects are errors: credentials stay bound to the configured endpoint.
1572        let (ws, _) = tungstenite::client_tls_with_config(request, stream, None, None).map_err(
1573            |e| match e {
1574                tungstenite::HandshakeError::Failure(error) => {
1575                    ws_err("realtime connection failed", error)
1576                }
1577                // The establishment socket is blocking with a deadline, so the
1578                // handshake cannot report an interrupted (would-block) state.
1579                tungstenite::HandshakeError::Interrupted(_) => {
1580                    transfer_error("realtime connection failed", "protocol", None)
1581                }
1582            },
1583        )?;
1584        remaining(deadline).map_err(|e| io_err("realtime connection failed", e))?;
1585        Ok(ws)
1586    }
1587
1588    #[cfg(test)]
1589    mod establishment_tests {
1590        use super::*;
1591        use std::net::{Shutdown, TcpListener};
1592        use tungstenite::client::IntoClientRequest;
1593
1594        // A peer consumes the initial request/ClientHello, then withholds its
1595        // upgrade/TLS response until released. Cleanup also unblocks the old path.
1596        fn withheld_response(tls: bool, old: bool) {
1597            let listener = TcpListener::bind("127.0.0.1:0").unwrap();
1598            let url = format!(
1599                "{}://{}/realtime",
1600                if tls { "wss" } else { "ws" },
1601                listener.local_addr().unwrap()
1602            );
1603            let (accepted_tx, accepted_rx) = mpsc::channel();
1604            let (release_tx, release_rx) = mpsc::channel();
1605            let peer = std::thread::spawn(move || {
1606                let (mut stream, _) = listener.accept().unwrap();
1607                stream
1608                    .set_read_timeout(Some(Duration::from_secs(2)))
1609                    .unwrap();
1610                let mut bytes = [0; 4096];
1611                assert!(stream.read(&mut bytes).unwrap() > 0);
1612                accepted_tx.send(()).unwrap();
1613                release_rx.recv_timeout(Duration::from_secs(3)).unwrap();
1614                let _ = stream.shutdown(Shutdown::Both);
1615            });
1616            let (done_tx, done_rx) = mpsc::channel();
1617            let worker = std::thread::spawn(move || {
1618                let result = if old {
1619                    tungstenite::connect(url)
1620                        .map(|_| ())
1621                        .map_err(|e| e.to_string())
1622                } else {
1623                    connect_websocket(
1624                        url.into_client_request().unwrap(),
1625                        Instant::now() + Duration::from_millis(250),
1626                    )
1627                    .map(|_| ())
1628                    .map_err(|e| format!("{}: {}", e.code, e.message))
1629                };
1630                done_tx.send(result).unwrap();
1631            });
1632            accepted_rx.recv_timeout(Duration::from_secs(2)).unwrap();
1633            if old {
1634                assert!(
1635                    matches!(
1636                        done_rx.recv_timeout(Duration::from_millis(500)),
1637                        Err(mpsc::RecvTimeoutError::Timeout)
1638                    ),
1639                    "original connect unexpectedly had a deadline"
1640                );
1641                release_tx.send(()).unwrap();
1642                assert!(done_rx
1643                    .recv_timeout(Duration::from_secs(2))
1644                    .unwrap()
1645                    .is_err());
1646            } else {
1647                let error = done_rx
1648                    .recv_timeout(Duration::from_secs(2))
1649                    .expect("establishment remained blocked")
1650                    .unwrap_err();
1651                assert_eq!(error, "transport.timeout: realtime connection failed");
1652                eprintln!(
1653                    "withheld {} produces {error}",
1654                    if tls { "TLS" } else { "upgrade" }
1655                );
1656                release_tx.send(()).unwrap();
1657            }
1658            worker.join().unwrap();
1659            peer.join().unwrap();
1660        }
1661
1662        #[test]
1663        fn original_connect_blocks_on_withheld_upgrade_and_tls() {
1664            withheld_response(false, true);
1665            withheld_response(true, true);
1666        }
1667        #[test]
1668        fn establishment_deadline_errors_on_withheld_upgrade_and_tls() {
1669            withheld_response(false, false);
1670            withheld_response(true, false);
1671        }
1672
1673        #[test]
1674        fn slow_upgrade_bytes_cannot_renew_the_absolute_deadline() {
1675            let listener = TcpListener::bind("127.0.0.1:0").unwrap();
1676            let url = format!("ws://{}", listener.local_addr().unwrap());
1677            let peer = std::thread::spawn(move || {
1678                let (mut stream, _) = listener.accept().unwrap();
1679                let mut bytes = [0; 4096];
1680                let _ = stream.read(&mut bytes).unwrap();
1681                for byte in b"HTTP/1.1 101 Switching Protocols\r\n" {
1682                    if stream.write_all(&[*byte]).is_err() {
1683                        break;
1684                    }
1685                    std::thread::sleep(Duration::from_millis(40));
1686                }
1687            });
1688            let started = Instant::now();
1689            assert!(connect_websocket(
1690                url.into_client_request().unwrap(),
1691                started + Duration::from_millis(250)
1692            )
1693            .is_err());
1694            assert!(started.elapsed() < Duration::from_secs(1));
1695            peer.join().unwrap();
1696        }
1697
1698        #[test]
1699        fn saturated_tcp_accept_queue_returns_an_observable_error() {
1700            // Fill a loopback listener's kernel accept queue without accepting.
1701            // No unroutable external host or firewall mutation is needed.
1702            let listener = TcpListener::bind("127.0.0.1:0").unwrap();
1703            let address = listener.local_addr().unwrap();
1704            let mut queued = Vec::new();
1705            loop {
1706                match TcpStream::connect_timeout(&address, Duration::from_millis(50)) {
1707                    Ok(stream) => queued.push(stream),
1708                    Err(error) => {
1709                        assert!(
1710                            matches!(
1711                                error.kind(),
1712                                io::ErrorKind::TimedOut
1713                                    | io::ErrorKind::WouldBlock
1714                                    | io::ErrorKind::ConnectionRefused
1715                                    | io::ErrorKind::ConnectionReset
1716                            ),
1717                            "{error:?}"
1718                        );
1719                        break;
1720                    }
1721                }
1722                assert!(queued.len() < 4096, "listener queue did not saturate");
1723            }
1724            let started = Instant::now();
1725            let url = format!("ws://{address}");
1726            let error = match connect_websocket(
1727                url.into_client_request().unwrap(),
1728                started + Duration::from_millis(250),
1729            ) {
1730                Err(error) => error,
1731                Ok(_) => panic!("full accept queue unexpectedly connected"),
1732            };
1733            assert!(
1734                (error.code == "transport.timeout" || error.code == "transport.failed")
1735                    && (error.message == "realtime TCP connect failed"
1736                        || error.message == "realtime connection failed"),
1737                "{}: {}",
1738                error.code,
1739                error.message
1740            );
1741            assert!(started.elapsed() < Duration::from_secs(2));
1742        }
1743    }
1744
1745    /// Segment fetches keep their own generic surface (`sync.transport_failed`)
1746    /// but must not swallow a typed policy failure: a refused redirect or an
1747    /// exceeded deadline/byte budget survives to the caller.
1748    fn segment_error(mut error: TransportError) -> TransportError {
1749        if error.code == "transport.failed" {
1750            error.code = "sync.transport_failed".into();
1751            error.message = "segment transfer failed".into();
1752        }
1753        error
1754    }
1755
1756    /// Nonblocking I/O needs a readiness notification before it can continue.
1757    fn is_would_block(e: &tungstenite::Error) -> bool {
1758        matches!(
1759            e,
1760            tungstenite::Error::Io(io) if matches!(
1761                io.kind(),
1762                std::io::ErrorKind::WouldBlock | std::io::ErrorKind::TimedOut
1763            )
1764        )
1765    }
1766
1767    pub struct NativeTransport {
1768        base_url: String,
1769        ws_url: String,
1770        /// Extra request headers (auth, actor/project ids) as (name, value).
1771        headers: Vec<(String, String)>,
1772        /// The base URL carries `user:pass@`, which ureq turns into request
1773        /// credentials; a request to it is credential bearing even without
1774        /// configured headers.
1775        base_url_has_userinfo: bool,
1776        agent: ureq::Agent,
1777        policy: HostTransportPolicy,
1778        /// Absolute whole-round deadline scoped by `set_round_deadline` for
1779        /// one exchange; `None` outside a round or when the policy sets no
1780        /// round budget.
1781        round_deadline_at: Option<std::time::Instant>,
1782        /// §7.8 drive bound scoped by `set_idle_bound` for one exchange: no
1783        /// call may wait longer for a byte to move. `None` outside a drive.
1784        drive_bound: Option<Duration>,
1785        pub signed_urls: bool,
1786        pub inbound: Arc<InboundBuffer>,
1787        /// One I/O thread owns the socket; callers wait for their write to flush.
1788        outgoing: Option<Box<SocketSender>>,
1789        reader: Option<JoinHandle<()>>,
1790        reader_stop: Arc<AtomicBool>,
1791        /// §8.7 round rendezvous, shared with the reader thread.
1792        round: Arc<RoundChannel>,
1793    }
1794
1795    /// Enforces `request_timeout` as a silence bound. ureq measures each
1796    /// request phase from its start, so a body that keeps arriving still
1797    /// expires; this connector caps every socket read and write at the bound
1798    /// instead, which restarts with each byte moved. The remaining phases
1799    /// (resolve, connect, request head, response head) keep ureq's own
1800    /// per-phase deadlines.
1801    #[derive(Debug)]
1802    struct IdleConnector(Option<Duration>);
1803
1804    impl Connector<Box<dyn UreqTransport>> for IdleConnector {
1805        type Out = Box<dyn UreqTransport>;
1806
1807        fn connect(
1808            &self,
1809            _: &ConnectionDetails,
1810            chained: Option<Box<dyn UreqTransport>>,
1811        ) -> Result<Option<Self::Out>, ureq::Error> {
1812            Ok(chained.map(|inner| match self.0 {
1813                Some(idle) => IdleTransport { inner, idle }.boxed(),
1814                None => inner,
1815            }))
1816        }
1817    }
1818
1819    #[derive(Debug)]
1820    struct IdleTransport {
1821        inner: Box<dyn UreqTransport>,
1822        idle: Duration,
1823    }
1824
1825    /// Cap a wait at `idle`: a wait with no deadline or a longer one becomes
1826    /// `idle`; a shorter ceiling (the round deadline) stays. The bound edits
1827    /// the wait in place, so ureq's other limits (per-read and per-write
1828    /// caps) pass through unchanged.
1829    fn idle_bound(mut timeout: NextTimeout, idle: Duration) -> NextTimeout {
1830        let idle = UreqDuration::Exact(idle);
1831        if timeout.after.is_not_happening() || timeout.after.as_nanos() > idle.as_nanos() {
1832            timeout.after = idle;
1833            timeout.reason = UreqTimeout::RecvBody;
1834        }
1835        timeout
1836    }
1837
1838    impl UreqTransport for IdleTransport {
1839        fn buffers(&mut self) -> &mut dyn ureq::unversioned::transport::Buffers {
1840            self.inner.buffers()
1841        }
1842        fn transmit_output(
1843            &mut self,
1844            amount: usize,
1845            timeout: NextTimeout,
1846        ) -> Result<(), ureq::Error> {
1847            self.inner
1848                .transmit_output(amount, idle_bound(timeout, self.idle))
1849        }
1850        fn await_input(&mut self, timeout: NextTimeout) -> Result<bool, ureq::Error> {
1851            self.inner.await_input(idle_bound(timeout, self.idle))
1852        }
1853        fn is_open(&mut self) -> bool {
1854            self.inner.is_open()
1855        }
1856        fn is_tls(&self) -> bool {
1857            self.inner.is_tls()
1858        }
1859    }
1860
1861    fn build_agent(policy: &HostTransportPolicy) -> ureq::Agent {
1862        let config = ureq::Agent::config_builder()
1863            .timeout_resolve(policy.request_timeout)
1864            .timeout_connect(policy.request_timeout)
1865            .timeout_send_request(policy.request_timeout)
1866            .timeout_recv_response(policy.request_timeout)
1867            .max_redirects(match policy.redirects {
1868                RedirectPolicy::Deny => 0,
1869                RedirectPolicy::Follow => 10,
1870            })
1871            .max_redirects_will_error(matches!(policy.redirects, RedirectPolicy::Follow))
1872            .redirect_auth_headers(ureq::config::RedirectAuthHeaders::Never)
1873            // A 4xx/5xx carries the server's §10.1 JSON error body. Read it so
1874            // the code, recommendedAction, details and HTTP status can reach
1875            // the caller; read_body turns a non-2xx response into a typed
1876            // TransportError before any payload is treated as data.
1877            .http_status_as_error(false)
1878            .build();
1879        ureq::Agent::with_parts(
1880            config,
1881            DefaultConnector::new().chain(IdleConnector(policy.request_timeout)),
1882            DefaultResolver::default(),
1883        )
1884    }
1885
1886    fn derive_ws_url(base_url: &str) -> String {
1887        // {scheme}://host/path → ws(s)://host/path/realtime — the reference
1888        // realtime endpoint sits alongside /sync under the mount (§8.7).
1889        let ws = if let Some(rest) = base_url.strip_prefix("https://") {
1890            format!("wss://{rest}")
1891        } else if let Some(rest) = base_url.strip_prefix("http://") {
1892            format!("ws://{rest}")
1893        } else {
1894            base_url.to_owned()
1895        };
1896        let trimmed = ws.trim_end_matches('/');
1897        format!("{trimmed}/realtime")
1898    }
1899
1900    impl NativeTransport {
1901        pub fn fork_round(&self) -> Self {
1902            Self {
1903                base_url: self.base_url.clone(),
1904                ws_url: self.ws_url.clone(),
1905                headers: self.headers.clone(),
1906                base_url_has_userinfo: self.base_url_has_userinfo,
1907                agent: self.agent.clone(),
1908                policy: self.policy.clone(),
1909                round_deadline_at: None,
1910                drive_bound: None,
1911                signed_urls: self.signed_urls,
1912                inbound: self.inbound.clone(),
1913                outgoing: self.outgoing.clone(),
1914                reader: None,
1915                reader_stop: self.reader_stop.clone(),
1916                round: self.round.clone(),
1917            }
1918        }
1919
1920        pub fn new(
1921            base_url: &str,
1922            config: &serde_json::Value,
1923            notify: Option<Arc<dyn Fn() + Send + Sync>>,
1924        ) -> Result<Self, String> {
1925            let policy = HostTransportPolicy::from_config(config)?;
1926            Self::with_policy(base_url, config, policy, notify)
1927        }
1928
1929        pub fn with_policy(
1930            base_url: &str,
1931            config: &serde_json::Value,
1932            policy: HostTransportPolicy,
1933            notify: Option<Arc<dyn Fn() + Send + Sync>>,
1934        ) -> Result<Self, String> {
1935            policy.validate()?;
1936            let mut headers = Vec::new();
1937            if let Some(map) = config.get("headers").and_then(|v| v.as_object()) {
1938                for (k, v) in map {
1939                    if let Some(s) = v.as_str() {
1940                        headers.push((k.clone(), s.to_owned()));
1941                    }
1942                }
1943            }
1944            let ws_url = config
1945                .get("wsUrl")
1946                .and_then(|v| v.as_str())
1947                .map(str::to_owned)
1948                .unwrap_or_else(|| derive_ws_url(base_url));
1949            // ureq replays `user:pass@` as Basic auth, so a base URL with
1950            // userinfo is credential bearing even when no headers are set.
1951            let base_url_has_userinfo = url::Url::parse(base_url)
1952                .map(|url| !url.username().is_empty() || url.password().is_some())
1953                .unwrap_or(false);
1954            Ok(NativeTransport {
1955                base_url: base_url.trim_end_matches('/').to_owned(),
1956                ws_url,
1957                headers,
1958                base_url_has_userinfo,
1959                agent: build_agent(&policy),
1960                policy,
1961                round_deadline_at: None,
1962                drive_bound: None,
1963                signed_urls: false,
1964                inbound: Arc::new(match notify {
1965                    Some(notify) => InboundBuffer::with_notify(notify),
1966                    None => InboundBuffer::default(),
1967                }),
1968                outgoing: None,
1969                reader: None,
1970                reader_stop: Arc::new(AtomicBool::new(false)),
1971                round: Arc::new(RoundChannel::default()),
1972            })
1973        }
1974
1975        /// Replace the policy for subsequent calls; an invalid policy is
1976        /// rejected and the current policy stays in force. The agent is
1977        /// rebuilt so the new redirect ceiling and timeout defaults apply.
1978        pub fn set_policy(&mut self, policy: HostTransportPolicy) -> Result<(), String> {
1979            policy.validate()?;
1980            self.agent = build_agent(&policy);
1981            self.policy = policy;
1982            Ok(())
1983        }
1984
1985        pub fn round_deadline(&self) -> Option<Duration> {
1986            self.policy.round_deadline
1987        }
1988
1989        pub fn set_round_deadline(&mut self, deadline: Option<std::time::Instant>) {
1990            self.round_deadline_at = deadline;
1991        }
1992
1993        /// What remains of the whole-round deadline, or `None` without one.
1994        /// Fails before any network I/O once the deadline has passed. The
1995        /// per-request bound is not part of this: it restarts on every byte
1996        /// (see [`IdleConnector`]).
1997        fn round_remaining(&self) -> Result<Option<Duration>, TransportError> {
1998            match self.round_deadline_at {
1999                Some(deadline) => deadline
2000                    .checked_duration_since(std::time::Instant::now())
2001                    .map(Some)
2002                    .ok_or_else(|| timeout_error("sync round deadline exceeded", "round_deadline")),
2003                None => Ok(None),
2004            }
2005        }
2006
2007        /// Whether a request to the base URL carries credentials: configured
2008        /// headers, or `user:pass@` userinfo ureq replays as Basic auth.
2009        fn credentialed(&self) -> bool {
2010            !self.headers.is_empty() || self.base_url_has_userinfo
2011        }
2012
2013        /// Apply the per-call bounds to a request: the round's remaining time,
2014        /// the drive bound on every socket read and write (each restarts it), and
2015        /// a redirect ceiling of zero whenever the request is credential
2016        /// bearing or the policy denies redirects. A credential-bearing
2017        /// request is refused a redirect under every policy, because ureq
2018        /// forwards configured headers to the redirect target.
2019        fn finish_request<B>(
2020            &self,
2021            req: ureq::RequestBuilder<B>,
2022            credentialed: bool,
2023        ) -> Result<ureq::RequestBuilder<B>, TransportError> {
2024            let timeout = self.round_remaining()?;
2025            let follow = self.policy.redirects == RedirectPolicy::Follow && !credentialed;
2026            Ok(req
2027                .config()
2028                .timeout_global(timeout)
2029                .timeout_per_read(self.drive_bound)
2030                .timeout_per_write(self.drive_bound)
2031                .max_redirects(if follow { 10 } else { 0 })
2032                .max_redirects_will_error(true)
2033                .build())
2034        }
2035
2036        /// Refuse an oversized request body before any network I/O.
2037        fn check_request_bytes(&self, len: u64) -> Result<(), TransportError> {
2038            match self.policy.max_request_bytes {
2039                Some(max) if len > max => {
2040                    let mut error = TransportError::new(
2041                        "transport.request_too_large",
2042                        "request body exceeds the configured transport limit",
2043                    );
2044                    error.details = Some(serde_json::json!({ "limit": max, "size": len }));
2045                    Err(error)
2046                }
2047                _ => Ok(()),
2048            }
2049        }
2050
2051        fn post_sync(&self, path: &str, body: &[u8]) -> Result<Vec<u8>, TransportError> {
2052            self.check_request_bytes(body.len() as u64)?;
2053            let credentialed = self.credentialed();
2054            let url = format!("{}{}", self.base_url, path);
2055            // SSP2 requests carry their own media type (SPEC 1.1); a stock
2056            // server answers 415 to anything else.
2057            let mut req = self
2058                .agent
2059                .post(&url)
2060                .header("content-type", "application/vnd.syncular.sync.v2");
2061            for (k, v) in &self.headers {
2062                req = req.header(k.as_str(), v.as_str());
2063            }
2064            let req = self.finish_request(req, credentialed)?;
2065            let resp = req
2066                .send(body)
2067                .map_err(|e| http_err("sync request failed", e))?;
2068            read_body(resp, None, self.policy.max_response_bytes, None)
2069        }
2070
2071        fn post_operation(&self, body: &[u8]) -> Result<Vec<u8>, TransportError> {
2072            self.check_request_bytes(body.len() as u64)?;
2073            let credentialed = self.credentialed();
2074            let url = format!("{}/operations", self.base_url);
2075            let mut req = self.agent.post(&url).header(
2076                "content-type",
2077                "application/vnd.syncular.operations.v1+json",
2078            );
2079            for (key, value) in &self.headers {
2080                req = req.header(key.as_str(), value.as_str());
2081            }
2082            let req = self.finish_request(req, credentialed)?;
2083            let response = req
2084                .send(body)
2085                .map_err(|error| http_err("remote operation request failed", error))?;
2086            read_body(response, None, self.policy.max_response_bytes, None)
2087        }
2088
2089        pub fn set_headers(&mut self, headers: Vec<(String, String)>) {
2090            self.headers = headers;
2091        }
2092
2093        pub fn shutdown(&mut self) {
2094            self.reader_stop.store(true, Ordering::SeqCst);
2095            // Wake any `realtime_sync` blocked on a round: the socket is going
2096            // away, so the round can never complete (§8.7 mid-round drop).
2097            self.round.fail_in_flight(TransportError::new(
2098                "sync.transport_failed",
2099                "realtime disconnected mid-round (§8.7)",
2100            ));
2101            if let Some(outgoing) = &self.outgoing {
2102                let _ = outgoing.poller.notify();
2103            }
2104            if let Some(handle) = self.reader.take() {
2105                let _ = handle.join();
2106            }
2107            self.outgoing = None;
2108        }
2109
2110        fn send_message(&mut self, message: Message) -> Result<(), TransportError> {
2111            // The whole-round deadline and the drive bound bound the write wait
2112            // too: intersect them with the socket's own ceiling and report the
2113            // bound that elapsed. The per-request HTTP deadline does not apply to a
2114            // socket send.
2115            let now = Instant::now();
2116            let (deadline, expiry) = round_expiry(
2117                now,
2118                ROUND_IDLE_TIMEOUT,
2119                self.drive_bound,
2120                self.round_deadline_at,
2121            );
2122            // The round is already spent: refuse before queuing the frame so a
2123            // later send cannot deliver it.
2124            if deadline <= now {
2125                return Err(timeout_error("realtime send timed out", "round_deadline"));
2126            }
2127            let wait = deadline - now;
2128            let result = (|| {
2129                let Some(outgoing) = &self.outgoing else {
2130                    return Err(TransportError::new(
2131                        "transport.failed",
2132                        "realtime not connected",
2133                    ));
2134                };
2135                let (completed, result) = mpsc::channel();
2136                outgoing
2137                    .queue
2138                    .try_send(Outgoing { message, completed })
2139                    .map_err(|_| {
2140                        TransportError::new("transport.failed", "realtime send queue unavailable")
2141                    })?;
2142                outgoing
2143                    .poller
2144                    .notify()
2145                    .map_err(|e| io_err("realtime wake failed", e))?;
2146                result.recv_timeout(wait).map_err(|_| match expiry {
2147                    Expiry::Ceiling => timeout_error("realtime send timed out", "round_deadline"),
2148                    Expiry::Drive => timeout_error("realtime send timed out", "drive"),
2149                    Expiry::Silence => {
2150                        TransportError::new("transport.failed", "realtime send did not complete")
2151                    }
2152                })?
2153            })();
2154            // A failed/timed-out write must not remain eligible for delivery
2155            // behind a later command on the same connection.
2156            if let Err(error) = &result {
2157                // Record the typed failure first: `shutdown` fails an
2158                // in-flight round with the generic mid-round loss, and the
2159                // first recorded outcome wins.
2160                self.round.fail_in_flight(error.clone());
2161                self.shutdown();
2162                // Some callers (delta acknowledgement) intentionally ignore a
2163                // send error. It still invalidates the connection for the host.
2164                self.inbound.push(Inbound::Disconnected(error.clone()));
2165            }
2166            result
2167        }
2168    }
2169
2170    /// A non-2xx response. Preserve the authenticated server catalog error
2171    /// body (§10.1) so callers see its code, recommendedAction, details and
2172    /// HTTP status; a non-JSON body keeps the transport classification.
2173    fn http_status_body_error(status: u16, body: &[u8]) -> TransportError {
2174        let mut error = TransportError::new("transport.failed", "HTTP request failed");
2175        let mut details = serde_json::Map::new();
2176        if let Ok(serde_json::Value::Object(parsed)) =
2177            serde_json::from_slice::<serde_json::Value>(body)
2178        {
2179            if let Some(code) = parsed.get("code").and_then(serde_json::Value::as_str) {
2180                if !code.is_empty() {
2181                    error.code = code.to_owned();
2182                }
2183            }
2184            if let Some(message) = parsed.get("message").and_then(serde_json::Value::as_str) {
2185                error.message = message.to_owned();
2186            }
2187            for key in ["category", "recommendedAction"] {
2188                if let Some(value) = parsed.get(key).and_then(serde_json::Value::as_str) {
2189                    details.insert(key.to_owned(), serde_json::Value::from(value));
2190                }
2191            }
2192            if let Some(retryable) = parsed.get("retryable").and_then(serde_json::Value::as_bool) {
2193                details.insert("retryable".to_owned(), serde_json::Value::from(retryable));
2194            }
2195            if let Some(serde_json::Value::Object(inner)) = parsed.get("details") {
2196                for (key, value) in inner {
2197                    details.insert(key.clone(), value.clone());
2198                }
2199            }
2200        }
2201        details.insert("causeKind".to_owned(), serde_json::Value::from("status"));
2202        details.insert("httpStatus".to_owned(), serde_json::Value::from(status));
2203        error.details = Some(serde_json::Value::Object(details));
2204        error
2205    }
2206
2207    /// Reads a response body. `max` is the transport limit, refused with
2208    /// `transport.response_too_large`; `stop` is a declared `byteLength`
2209    /// (§5.4): reading ends once the body exceeds it and the caller rejects
2210    /// the longer body.
2211    fn read_body(
2212        resp: ureq::http::Response<ureq::Body>,
2213        mut progress: Option<&mut dyn FnMut(u64)>,
2214        max: Option<u64>,
2215        stop: Option<u64>,
2216    ) -> Result<Vec<u8>, TransportError> {
2217        redirect_refused(&resp)?;
2218        use std::io::Read;
2219        let status = resp.status().as_u16();
2220        let mut reader = resp.into_body().into_with_config().reader();
2221        let mut bytes = Vec::new();
2222        let mut chunk = [0u8; 64 * 1024];
2223        let mut reported = 0;
2224        loop {
2225            let n = reader
2226                .read(&mut chunk)
2227                .map_err(|error| match timeout_cause(&error) {
2228                    Some(cause) => timeout_error("response body read times out", cause),
2229                    None => transfer_error("response body read failed", "body", Some(status)),
2230                })?;
2231            if n == 0 {
2232                break;
2233            }
2234            // The cap counts decoded bytes: ureq's reader decompresses before
2235            // this loop, so a gzip bomb hits the limit before the buffer grows.
2236            if let Some(max) = max {
2237                if bytes.len() as u64 + n as u64 > max {
2238                    return Err(response_too_large(max));
2239                }
2240            }
2241            bytes.extend_from_slice(&chunk[..n]);
2242            if stop.is_some_and(|stop| bytes.len() as u64 > stop) {
2243                break;
2244            }
2245            if bytes.len() - reported >= 64 * 1024 {
2246                if let Some(callback) = progress.as_mut() {
2247                    callback(bytes.len() as u64);
2248                }
2249                reported = bytes.len();
2250            }
2251        }
2252        if bytes.len() != reported {
2253            if let Some(callback) = progress {
2254                callback(bytes.len() as u64);
2255            }
2256        }
2257        if status >= 400 {
2258            return Err(http_status_body_error(status, &bytes));
2259        }
2260        Ok(bytes)
2261    }
2262
2263    fn response_too_large(max: u64) -> TransportError {
2264        let mut error = TransportError::new(
2265            "transport.response_too_large",
2266            "response body exceeds the configured transport limit",
2267        );
2268        error.details = Some(serde_json::json!({ "limit": max }));
2269        error
2270    }
2271
2272    impl Transport for NativeTransport {
2273        fn sync(&mut self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
2274            self.post_sync("/sync", request)
2275        }
2276
2277        fn remote_operation(&mut self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
2278            self.post_operation(request)
2279        }
2280
2281        fn realtime_sync(&mut self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
2282            // §8.7 socket round: send the request as a `0x01`-tagged chunk on
2283            // the connected socket and block for the reassembled response
2284            // stream (the reader thread demuxes `0x01` chunks to END, routing
2285            // any `0x00` delta / text that interleaves to the inbound queue).
2286            // When no socket is connected this is the client's "not connected"
2287            // path — the caller (client core) only calls `realtime_sync` while
2288            // `realtime_connected`, and connect established the socket; a
2289            // missing socket here means the round rides HTTP instead (same
2290            // rule as the TS client: `POST /sync` when the socket is absent).
2291            if self.outgoing.is_none() {
2292                return self.post_sync("/sync", request);
2293            }
2294            self.round_remaining()?;
2295            let framed = self.round.begin(request)?;
2296            let (tag, body) = framed.split_first().expect("framed request carries a tag");
2297            for chunk in body.chunks(REQUEST_CHUNK_BYTES) {
2298                let mut message = Vec::with_capacity(chunk.len() + 1);
2299                message.push(*tag);
2300                message.extend_from_slice(chunk);
2301                if let Err(error) = self.send_message(Message::Binary(message.into())) {
2302                    self.round.fail_in_flight(error);
2303                    break;
2304                }
2305                self.round.progressed();
2306            }
2307            let outcome =
2308                self.round
2309                    .wait(self.round_deadline_at, ROUND_IDLE_TIMEOUT, self.drive_bound);
2310            // A round that ends without its response END leaves the rest of
2311            // that response in flight on the socket, and the next round would
2312            // read it as its own (§8.7). Close the connection and report the
2313            // loss; the reader thread already did both when the peer ended it.
2314            if let Err(error) = &outcome {
2315                if !self.round.lost() {
2316                    self.shutdown();
2317                    self.inbound.push(Inbound::Disconnected(error.clone()));
2318                }
2319            }
2320            outcome
2321        }
2322
2323        fn download_segment(
2324            &mut self,
2325            request: &SegmentRequest,
2326            on_progress: &mut dyn FnMut(u64),
2327        ) -> Result<Vec<u8>, TransportError> {
2328            // The FULL content address (`sha256:<hex>`) is the path param —
2329            // the reference server keys its segment store by it (§5.1) and
2330            // answers `sync.not_found` to a bare hex id. The requested-scopes
2331            // header carries what the pull round granted; the server
2332            // re-authorizes the download against it (§5.5) and answers
2333            // `sync.forbidden` when it is missing.
2334            let url = format!("{}/segments/{}", self.base_url, request.segment_id);
2335            let credentialed = self.credentialed();
2336            let mut req = self
2337                .agent
2338                .get(&url)
2339                .header("x-syncular-scopes", &request.requested_scopes_json);
2340            for (k, v) in &self.headers {
2341                req = req.header(k.as_str(), v.as_str());
2342            }
2343            let req = self.finish_request(req, credentialed)?;
2344            let resp = req
2345                .call()
2346                .map_err(|error| segment_error(http_err("segment request failed", error)))?;
2347            read_body(
2348                resp,
2349                Some(on_progress),
2350                self.policy.max_response_bytes,
2351                Some(request.byte_length),
2352            )
2353            .map_err(segment_error)
2354        }
2355
2356        fn supports_url_fetch(&self) -> bool {
2357            self.signed_urls
2358        }
2359
2360        fn download_segments(
2361            &mut self,
2362            fetches: &[SegmentFetch],
2363            on_progress: &mut (dyn FnMut(usize, u64) + Send),
2364        ) -> Vec<Result<Vec<u8>, TransportError>> {
2365            // A segment GET is pure network I/O over immutable transport
2366            // state, so a page list downloads on a bounded pool instead of one
2367            // blocking request after the other: four pages of a paged
2368            // bootstrap overlap (§5.2). `fork_round` hands each worker the same
2369            // agent (a cheap clone) and headers; the round's anchored deadline
2370            // is copied over explicitly, because a fork starts without one.
2371            // Every fetch is attempted; the client stops consuming at the
2372            // first error in wire order.
2373            let workers = (0..fetches.len().min(4))
2374                .map(|_| {
2375                    let mut worker = self.fork_round();
2376                    worker.round_deadline_at = self.round_deadline_at;
2377                    worker.drive_bound = self.drive_bound;
2378                    worker
2379                })
2380                .collect::<Vec<_>>();
2381            let slots = fetches.iter().map(|_| Mutex::new(None)).collect::<Vec<_>>();
2382            let progress = Mutex::new(on_progress);
2383            let next = std::sync::atomic::AtomicUsize::new(0);
2384            std::thread::scope(|scope| {
2385                for worker in workers {
2386                    let (slots, progress, next) = (&slots, &progress, &next);
2387                    scope.spawn(move || {
2388                        let mut worker = worker;
2389                        loop {
2390                            let index = next.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
2391                            let Some(fetch) = fetches.get(index) else {
2392                                break;
2393                            };
2394                            let mut report = |bytes: u64| {
2395                                (*progress.lock().expect("segment progress lock"))(index, bytes);
2396                            };
2397                            let result = match fetch {
2398                                SegmentFetch::Direct(request) => {
2399                                    worker.download_segment(request, &mut report)
2400                                }
2401                                SegmentFetch::Url { url, byte_length } => {
2402                                    worker.fetch_url(url, *byte_length, &mut report)
2403                                }
2404                            };
2405                            *slots[index].lock().expect("segment result slot") = Some(result);
2406                        }
2407                    });
2408                }
2409            });
2410            slots
2411                .into_iter()
2412                .map(|slot| slot.into_inner().expect("segment result slot"))
2413                .map(|result| result.expect("every fetch is attempted"))
2414                .collect()
2415        }
2416
2417        fn fetch_url(
2418            &mut self,
2419            url: &str,
2420            byte_length: u64,
2421            on_progress: &mut dyn FnMut(u64),
2422        ) -> Result<Vec<u8>, TransportError> {
2423            // §5.4: the URL is the entire grant — no host credentials attached.
2424            let req = self.finish_request(self.agent.get(url), true)?;
2425            let resp = req
2426                .call()
2427                .map_err(|error| segment_error(http_err("segment request failed", error)))?;
2428            read_body(
2429                resp,
2430                Some(on_progress),
2431                self.policy.max_response_bytes,
2432                Some(byte_length),
2433            )
2434            .map_err(segment_error)
2435        }
2436
2437        fn blob_upload(
2438            &mut self,
2439            blob_id: &str,
2440            bytes: &[u8],
2441            media_type: Option<&str>,
2442        ) -> Result<(), TransportError> {
2443            // Full `sha256:<hex>` id in the path — the reference server's
2444            // isBlobId check rejects a bare hex id (§5.9.1).
2445            self.check_request_bytes(bytes.len() as u64)?;
2446            let credentialed = self.credentialed();
2447            let url = format!("{}/blobs/{}", self.base_url, blob_id);
2448            let mut req = self.agent.put(&url).header(
2449                "content-type",
2450                media_type.unwrap_or("application/octet-stream"),
2451            );
2452            for (k, v) in &self.headers {
2453                req = req.header(k.as_str(), v.as_str());
2454            }
2455            let req = self.finish_request(req, credentialed)?;
2456            let resp = req
2457                .send(bytes)
2458                .map_err(|e| http_err("blob upload failed", e))?;
2459            read_body(resp, None, self.policy.max_response_bytes, None)?;
2460            Ok(())
2461        }
2462
2463        fn blob_download(
2464            &mut self,
2465            blob_id: &str,
2466            byte_length: Option<u64>,
2467        ) -> Result<BlobDownload, TransportError> {
2468            // Full `sha256:<hex>` id in the path — the reference server's
2469            // isBlobId check rejects a bare hex id (§5.9.1).
2470            let credentialed = self.credentialed();
2471            let url = format!("{}/blobs/{}", self.base_url, blob_id);
2472            let mut req = self.agent.get(&url);
2473            for (k, v) in &self.headers {
2474                req = req.header(k.as_str(), v.as_str());
2475            }
2476            let req = self.finish_request(req, credentialed)?;
2477            let resp = req.call().map_err(|cause| {
2478                let status = match &cause {
2479                    ureq::Error::StatusCode(status) => Some(*status),
2480                    _ => None,
2481                };
2482                let mut error = http_err("blob download failed", cause);
2483                match status {
2484                    Some(404) => {
2485                        error.code = "blob.not_found".into();
2486                        error.message = "blob not found".into();
2487                    }
2488                    Some(403) => {
2489                        error.code = "blob.forbidden".into();
2490                        error.message = "blob download forbidden".into();
2491                    }
2492                    Some(401) => {
2493                        error.code = "sync.auth_required".into();
2494                        error.message = "host authentication required".into();
2495                    }
2496                    _ => {}
2497                }
2498                error
2499            })?;
2500            // §5.9.5 always-issue: a JSON body carries a presigned `url`; an
2501            // octet-stream body is inline bytes.
2502            let is_json = resp
2503                .headers()
2504                .get(ureq::http::header::CONTENT_TYPE)
2505                .and_then(|value| value.to_str().ok())
2506                .is_some_and(|value| value.contains("application/json"));
2507            // A JSON envelope is not the blob body, so the declared size caps
2508            // inline bytes only.
2509            let stop = byte_length.filter(|_| !is_json);
2510            let body = read_body(resp, None, self.policy.max_response_bytes, stop).map_err(
2511                |mut error| {
2512                    // The blob endpoint keeps its status classification: an
2513                    // error body supplies details, but the HTTP status decides
2514                    // the code.
2515                    let status = error
2516                        .details
2517                        .as_ref()
2518                        .filter(|details| {
2519                            details.get("causeKind").and_then(serde_json::Value::as_str)
2520                                == Some("status")
2521                        })
2522                        .and_then(|details| details.get("httpStatus"))
2523                        .and_then(serde_json::Value::as_u64);
2524                    match status {
2525                        Some(404) => {
2526                            error.code = "blob.not_found".into();
2527                            error.message = "blob not found".into();
2528                        }
2529                        Some(403) => {
2530                            error.code = "blob.forbidden".into();
2531                            error.message = "blob download forbidden".into();
2532                        }
2533                        Some(401) => {
2534                            error.code = "sync.auth_required".into();
2535                            error.message = "host authentication required".into();
2536                        }
2537                        Some(_) => {
2538                            error.code = "transport.failed".into();
2539                            error.message = "blob download failed".into();
2540                        }
2541                        None => {}
2542                    }
2543                    error
2544                },
2545            )?;
2546            if is_json {
2547                if let Ok(parsed) = serde_json::from_slice::<serde_json::Value>(&body) {
2548                    if let Some(u) = parsed.get("url").and_then(|v| v.as_str()) {
2549                        return Ok(BlobDownload::Url {
2550                            url: u.to_owned(),
2551                            url_expires_at_ms: parsed
2552                                .get("urlExpiresAtMs")
2553                                .and_then(|v| v.as_i64()),
2554                        });
2555                    }
2556                }
2557            }
2558            Ok(BlobDownload::Bytes(body))
2559        }
2560
2561        fn fetch_blob_url(
2562            &mut self,
2563            url: &str,
2564            byte_length: Option<u64>,
2565        ) -> Result<Vec<u8>, TransportError> {
2566            // §5.9.5: the URL is the entire grant — no host credentials, and
2567            // the URL capability makes the request credential bearing.
2568            let req = self.finish_request(self.agent.get(url), true)?;
2569            let resp = req.call().map_err(|e| http_err("URL fetch failed", e))?;
2570            read_body(resp, None, self.policy.max_response_bytes, byte_length)
2571        }
2572
2573        fn blob_upload_grant(
2574            &mut self,
2575            blob_id: &str,
2576            byte_length: u64,
2577            media_type: Option<&str>,
2578        ) -> Result<BlobUploadGrant, TransportError> {
2579            let url = format!("{}/blobs/{}/upload-grant", self.base_url, blob_id);
2580            let body = serde_json::json!({
2581                "byteLength": byte_length,
2582                "mediaType": media_type,
2583            })
2584            .to_string();
2585            self.check_request_bytes(body.len() as u64)?;
2586            let credentialed = self.credentialed();
2587            let mut req = self
2588                .agent
2589                .post(&url)
2590                .header("content-type", "application/json");
2591            for (k, v) in &self.headers {
2592                req = req.header(k.as_str(), v.as_str());
2593            }
2594            let req = self.finish_request(req, credentialed)?;
2595            let resp = req
2596                .send(body)
2597                .map_err(|e| http_err("blob upload grant request failed", e))?;
2598            let grant_body = read_body(resp, None, self.policy.max_response_bytes, None)?;
2599            let parsed: serde_json::Value = serde_json::from_slice(&grant_body)
2600                .map_err(|_| transfer_error("blob upload grant decode failed", "decode", None))?;
2601            if let Some(u) = parsed.get("url").and_then(|v| v.as_str()) {
2602                return Ok(BlobUploadGrant::Url {
2603                    url: u.to_owned(),
2604                    url_expires_at_ms: parsed.get("urlExpiresAtMs").and_then(|v| v.as_i64()),
2605                });
2606            }
2607            if parsed.get("present").and_then(|v| v.as_bool()) == Some(true) {
2608                return Ok(BlobUploadGrant::Present);
2609            }
2610            Ok(BlobUploadGrant::None)
2611        }
2612
2613        fn blob_put_url(
2614            &mut self,
2615            blob_id: &str,
2616            url: &str,
2617            bytes: &[u8],
2618            media_type: Option<&str>,
2619        ) -> Result<(), TransportError> {
2620            // §5.9.3: the presigned URL is the entire grant — no host auth.
2621            // The grant signs content-length (ureq sets it from the body) and
2622            // the checksum, the blob id's digest, so the object store rejects
2623            // any other bytes without the client hashing the body again.
2624            let digest = blob_id
2625                .strip_prefix("sha256:")
2626                .filter(|hex| {
2627                    hex.len() == 64
2628                        && hex
2629                            .bytes()
2630                            .all(|b| b.is_ascii_hexdigit() && !b.is_ascii_uppercase())
2631                })
2632                .map(|hex| {
2633                    (0..64)
2634                        .step_by(2)
2635                        .map(|i| u8::from_str_radix(&hex[i..i + 2], 16).expect("hex digits"))
2636                        .collect::<Vec<u8>>()
2637                })
2638                .ok_or_else(|| {
2639                    TransportError::new(
2640                        "sync.invalid_request",
2641                        "the blob id is not a sha256 blob id (§5.9.1)",
2642                    )
2643                })?;
2644            self.check_request_bytes(bytes.len() as u64)?;
2645            let req = self.finish_request(
2646                self.agent
2647                    .put(url)
2648                    .header(
2649                        "content-type",
2650                        media_type.unwrap_or("application/octet-stream"),
2651                    )
2652                    .header("x-amz-checksum-sha256", ssp2::util::base64(&digest)),
2653                true,
2654            )?;
2655            let resp = req
2656                .send(bytes)
2657                .map_err(|e| http_err("signed blob upload failed", e))?;
2658            read_body(resp, None, self.policy.max_response_bytes, None)?;
2659            Ok(())
2660        }
2661
2662        fn realtime_connect(&mut self, client_id: &str) -> Result<(), TransportError> {
2663            if self.outgoing.is_some() {
2664                if self.reader_stop.load(Ordering::SeqCst)
2665                    || self
2666                        .reader
2667                        .as_ref()
2668                        .is_some_and(|reader| reader.is_finished())
2669                {
2670                    self.shutdown();
2671                } else {
2672                    return Ok(());
2673                }
2674            }
2675            // Build the client request VIA `IntoClientRequest` so tungstenite
2676            // fills the mandatory handshake headers (Host / Connection /
2677            // Upgrade / Sec-WebSocket-Version / Sec-WebSocket-Key); a
2678            // hand-built `http::Request` is taken as-is and would omit them.
2679            // Then layer the configured auth/actor headers on top.
2680            use tungstenite::client::IntoClientRequest;
2681            let mut url = url::Url::parse(&self.ws_url)
2682                .map_err(|_| transfer_error("realtime URL invalid", "request", None))?;
2683            let retained_query: Vec<(String, String)> = url
2684                .query_pairs()
2685                .filter(|(key, _)| key != "clientId")
2686                .map(|(key, value)| (key.into_owned(), value.into_owned()))
2687                .collect();
2688            url.set_query(None);
2689            url.query_pairs_mut()
2690                .extend_pairs(retained_query)
2691                .append_pair("clientId", client_id);
2692            let mut request = url
2693                .as_str()
2694                .into_client_request()
2695                .map_err(|error| ws_err("realtime request failed", error))?;
2696            {
2697                let out = request.headers_mut();
2698                for (k, v) in &self.headers {
2699                    if let (Ok(name), Ok(value)) = (
2700                        tungstenite::http::HeaderName::try_from(k.as_str()),
2701                        tungstenite::http::HeaderValue::try_from(v.as_str()),
2702                    ) {
2703                        out.insert(name, value);
2704                    }
2705                }
2706            }
2707            // The bounded establishment never follows a redirect, so a transport configured with
2708            // `RedirectPolicy::Follow` fails here instead of having the policy silently ignored.
2709            if self.policy.redirects == RedirectPolicy::Follow {
2710                return Err(redirect_error(
2711                    "realtime establishment does not follow redirects",
2712                    None,
2713                ));
2714            }
2715            let mut ws = connect_websocket(request, Instant::now() + CONNECT_TIMEOUT)?;
2716            let stream = match ws.get_mut() {
2717                MaybeTlsStream::Plain(stream) => stream.established(),
2718                MaybeTlsStream::Rustls(stream) => stream.get_mut().established(),
2719                _ => {
2720                    return Err(TransportError::new(
2721                        "transport.failed",
2722                        "unsupported websocket stream",
2723                    ))
2724                }
2725            }
2726            .map_err(|e| io_err("realtime clone failed", e))?;
2727            stream
2728                .set_nonblocking(true)
2729                .map_err(|e| io_err("realtime nonblocking failed", e))?;
2730            let poller = Arc::new(Poller::new().map_err(|e| io_err("realtime poller failed", e))?);
2731            // SAFETY: SocketRegistration owns this handle and unregisters it before drop.
2732            unsafe { poller.add(&stream, Event::readable(0)) }
2733                .map_err(|e| io_err("realtime register failed", e))?;
2734            let registration = SocketRegistration {
2735                poller: Arc::clone(&poller),
2736                stream,
2737            };
2738            let (outgoing, queued) = mpsc::sync_channel::<Outgoing>(1);
2739            self.outgoing = Some(Box::new(SocketSender {
2740                queue: outgoing,
2741                poller,
2742            }));
2743            self.reader_stop = Arc::new(AtomicBool::new(false));
2744            self.round = Arc::new(RoundChannel::default());
2745            let inbound = Arc::clone(&self.inbound);
2746            let stop = Arc::clone(&self.reader_stop);
2747            let round = Arc::clone(&self.round);
2748            // §8.5: the connection's first heartbeat arms the watchdog; once
2749            // armed, any inbound frame proves the socket and twice the
2750            // heartbeat interval of silence loses it. A server that sends no
2751            // heartbeats never arms it.
2752            let silence = 2 * self
2753                .policy
2754                .realtime_heartbeat
2755                .unwrap_or(Duration::from_secs(30));
2756            self.reader = Some(std::thread::spawn(move || {
2757                let mut events = Events::new();
2758                let mut pending: Option<mpsc::Sender<Result<(), TransportError>>> = None;
2759                let mut heard: Option<Instant> = None;
2760                let failure = 'io: loop {
2761                    if stop.load(Ordering::SeqCst) {
2762                        let _ = ws.close(None);
2763                        let _ = ws.flush();
2764                        break TransportError::new(
2765                            "sync.transport_failed",
2766                            "realtime disconnected mid-round (§8.7)",
2767                        );
2768                    }
2769                    if pending.is_none() {
2770                        if let Ok(outgoing) = queued.try_recv() {
2771                            pending = Some(outgoing.completed);
2772                            // WouldBlock retains the frame in tungstenite's write buffer.
2773                            if let Err(error) = ws.write(outgoing.message) {
2774                                if !is_would_block(&error) {
2775                                    break ws_err("realtime write failed", error);
2776                                }
2777                            }
2778                        }
2779                    }
2780                    // Bound receive work so a continuously readable peer cannot starve sends.
2781                    let mut drained = false;
2782                    for _ in 0..64 {
2783                        let received = ws.read();
2784                        if let Ok(message) = &received {
2785                            let armed = heard.is_some()
2786                                || matches!(message, Message::Text(text)
2787                                    if serde_json::from_str::<serde_json::Value>(text)
2788                                        .is_ok_and(|event| event["event"] == "heartbeat"));
2789                            if armed {
2790                                heard = Some(Instant::now());
2791                            }
2792                            let kind = match message {
2793                                Message::Text(_) => Some(RealtimeReceiptKind::Text),
2794                                Message::Binary(bytes) => Some(match bytes.first() {
2795                                    Some(&crate::REALTIME_TAG_DELTA) => RealtimeReceiptKind::Delta,
2796                                    Some(&crate::REALTIME_TAG_ROUND) => RealtimeReceiptKind::Round,
2797                                    _ => RealtimeReceiptKind::OtherBinary,
2798                                }),
2799                                Message::Ping(_) => Some(RealtimeReceiptKind::Ping),
2800                                Message::Pong(_) => Some(RealtimeReceiptKind::Pong),
2801                                Message::Close(_) => Some(RealtimeReceiptKind::Close),
2802                                Message::Frame(_) => None,
2803                            };
2804                            if let Some(kind) = kind {
2805                                let bytes = match message {
2806                                    Message::Close(Some(close)) => 2 + close.reason.len(),
2807                                    _ => message.len(),
2808                                };
2809                                inbound.observe(kind, bytes);
2810                            }
2811                        }
2812                        match received {
2813                            Ok(Message::Text(text)) => {
2814                                inbound.push(Inbound::Text(text.to_string()))
2815                            }
2816                            Ok(Message::Binary(bytes)) => {
2817                                if let Some(delta) = round.route_binary(&bytes) {
2818                                    inbound.push(Inbound::Binary(delta));
2819                                }
2820                            }
2821                            Err(error) if is_would_block(&error) => {
2822                                drained = true;
2823                                break;
2824                            }
2825                            Ok(Message::Close(_)) => {
2826                                let _ = ws.flush();
2827                                break 'io TransportError::new(
2828                                    "sync.transport_failed",
2829                                    "realtime disconnected mid-round (§8.7)",
2830                                );
2831                            }
2832                            Err(_) => {
2833                                break 'io TransportError::new(
2834                                    "sync.transport_failed",
2835                                    "realtime disconnected mid-round (§8.7)",
2836                                );
2837                            }
2838                            Ok(_) => {}
2839                        }
2840                        // A host that does not drain loses the socket instead
2841                        // of growing the buffer (§8.8).
2842                        if inbound.overflowed() {
2843                            let _ = ws.close(None);
2844                            let _ = ws.flush();
2845                            let mut error = TransportError::new(
2846                                "transport.failed",
2847                                "realtime inbound buffer is full",
2848                            );
2849                            error.details = Some(serde_json::json!({
2850                                "causeKind": "inbound_overflow",
2851                                "limit": super::INBOUND_BUFFER_LIMIT_BYTES,
2852                            }));
2853                            break 'io error;
2854                        }
2855                    }
2856                    let interest = match ws.flush() {
2857                        Ok(()) => {
2858                            if let Some(completed) = pending.take() {
2859                                let _ = completed.send(Ok(()));
2860                            }
2861                            Event::readable(0)
2862                        }
2863                        Err(error) if is_would_block(&error) => Event::all(0),
2864                        Err(error) => break ws_err("realtime flush failed", error),
2865                    };
2866                    if !drained {
2867                        continue;
2868                    }
2869                    if let Err(error) = registration.poller.modify(&registration.stream, interest) {
2870                        break io_err("realtime rearm failed", error);
2871                    }
2872                    let wait = heard
2873                        .map(|heard| (heard + silence).saturating_duration_since(Instant::now()));
2874                    if wait.is_some_and(|wait| wait.is_zero()) {
2875                        break timeout_error("realtime heartbeat missed", "heartbeat");
2876                    }
2877                    events.clear();
2878                    if let Err(error) = registration.poller.wait(&mut events, wait) {
2879                        if error.kind() != std::io::ErrorKind::Interrupted {
2880                            break io_err("realtime wait failed", error);
2881                        }
2882                    }
2883                };
2884                // Publish before waking a round/send waiter: the host must
2885                // drain this old connection's event before it can reconnect.
2886                // An idle close has no round waiter at all. Explicit shutdown
2887                // is owned by its caller and must not leave a stale close.
2888                if !stop.load(Ordering::SeqCst) {
2889                    inbound.push(Inbound::Disconnected(failure.clone()));
2890                }
2891                if let Some(completed) = pending {
2892                    let _ = completed.send(Err(failure.clone()));
2893                }
2894                while let Ok(outgoing) = queued.try_recv() {
2895                    let _ = outgoing.completed.send(Err(failure.clone()));
2896                }
2897                round.fail_in_flight(failure);
2898            }));
2899            Ok(())
2900        }
2901
2902        fn realtime_send(&mut self, text: &str) -> Result<(), TransportError> {
2903            self.send_message(Message::Text(text.to_owned().into()))
2904        }
2905
2906        fn realtime_close(&mut self) -> Result<(), TransportError> {
2907            self.shutdown();
2908            Ok(())
2909        }
2910
2911        fn round_deadline(&self) -> Option<Duration> {
2912            NativeTransport::round_deadline(self)
2913        }
2914
2915        fn set_round_deadline(&mut self, deadline: Option<std::time::Instant>) {
2916            NativeTransport::set_round_deadline(self, deadline);
2917        }
2918
2919        fn set_idle_bound(&mut self, bound: Option<Duration>) {
2920            self.drive_bound = bound;
2921        }
2922    }
2923    #[cfg(test)]
2924    mod transfer_tests {
2925        use super::*;
2926        use ureq::unversioned::resolver::DefaultResolver;
2927        use ureq::unversioned::transport::{ConnectionDetails, Connector};
2928
2929        const SECRET: &str = "https://user:password@cdn.example/secret-capability-path?secret-query=value#secret-fragment";
2930
2931        #[derive(Debug)]
2932        struct SecretError;
2933        impl std::fmt::Display for SecretError {
2934            fn fmt(&self, _: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2935                panic!("transport error must never be formatted")
2936            }
2937        }
2938        impl std::error::Error for SecretError {}
2939
2940        #[derive(Debug)]
2941        struct FailingConnector(&'static str);
2942        impl Connector for FailingConnector {
2943            type Out = ();
2944            fn connect(
2945                &self,
2946                _: &ConnectionDetails,
2947                _: Option<()>,
2948            ) -> Result<Option<()>, ureq::Error> {
2949                Err(match self.0 {
2950                    "io" => ureq::Error::Io(std::io::Error::new(
2951                        std::io::ErrorKind::ConnectionRefused,
2952                        format!("404 {SECRET}"),
2953                    )),
2954                    "tls" => ureq::Error::Tls(SECRET),
2955                    "request" => ureq::Error::BadUri(SECRET.into()),
2956                    "timeout" => ureq::Error::Timeout(ureq::Timeout::RecvResponse),
2957                    "round_deadline" => ureq::Error::Timeout(ureq::Timeout::Global),
2958                    "404" => ureq::Error::StatusCode(404),
2959                    "401" => ureq::Error::StatusCode(401),
2960                    "403" => ureq::Error::StatusCode(403),
2961                    "503" => ureq::Error::StatusCode(503),
2962                    _ => ureq::Error::Other(Box::new(SecretError)),
2963                })
2964            }
2965        }
2966
2967        #[test]
2968        fn injected_http_failures_never_expose_capabilities_or_format_the_cause() {
2969            for kind in [
2970                "io",
2971                "tls",
2972                "request",
2973                "timeout",
2974                "round_deadline",
2975                "unknown",
2976                "404",
2977                "401",
2978                "403",
2979                "503",
2980            ] {
2981                for operation in [
2982                    "sync",
2983                    "remote",
2984                    "segment",
2985                    "signed_segment",
2986                    "blob",
2987                    "signed_blob",
2988                    "upload",
2989                    "grant",
2990                    "signed_put",
2991                ] {
2992                    let mut transport =
2993                        NativeTransport::new("http://127.0.0.1", &serde_json::json!({}), None)
2994                            .unwrap();
2995                    transport.agent = ureq::Agent::with_parts(
2996                        ureq::Agent::config_builder().build(),
2997                        FailingConnector(kind),
2998                        DefaultResolver::default(),
2999                    );
3000                    let mut progress = |_| {};
3001                    let result = match operation {
3002                        "sync" => transport.sync(&[]).map(|_| ()),
3003                        "remote" => transport.remote_operation(&[]).map(|_| ()),
3004                        "segment" => transport.download_segment(&SegmentRequest { segment_id: "sha256:test".into(), table: "tasks".into(), requested_scopes_json: "{}".into(), byte_length: 1 << 20 }, &mut progress).map(|_| ()),
3005                        "signed_segment" => transport.fetch_url("http://127.0.0.1/secret-capability-path?secret-query=value#secret-fragment", 1 << 20, &mut progress).map(|_| ()),
3006                        "blob" => transport.blob_download("sha256:test", None).map(|_| ()),
3007                        "signed_blob" => transport.fetch_blob_url("http://127.0.0.1/secret-capability-path?secret-query=value#secret-fragment", None).map(|_| ()),
3008                        "upload" => transport.blob_upload("sha256:test", &[], None),
3009                        "grant" => transport.blob_upload_grant("sha256:test", 0, None).map(|_| ()),
3010                        _ => transport.blob_put_url(&format!("sha256:{}", "0".repeat(64)), "http://127.0.0.1/secret-capability-path?secret-query=value#secret-fragment", &[], None),
3011                    };
3012                    let error = result.unwrap_err();
3013                    let expected_code = match (operation, kind) {
3014                        (_, "timeout" | "round_deadline") => "transport.timeout",
3015                        ("segment" | "signed_segment", _) => "sync.transport_failed",
3016                        ("blob", "404") => "blob.not_found",
3017                        ("blob", "401") => "sync.auth_required",
3018                        ("blob", "403") => "blob.forbidden",
3019                        _ => "transport.failed",
3020                    };
3021                    assert_eq!(error.code, expected_code, "{operation} {kind}");
3022                    let details = error.details.unwrap();
3023                    assert_eq!(
3024                        details["causeKind"],
3025                        match kind {
3026                            "io" => "connect",
3027                            "404" | "401" | "403" | "503" => "status",
3028                            other => other,
3029                        }
3030                    );
3031                    assert_eq!(
3032                        details.get("httpStatus").and_then(|value| value.as_u64()),
3033                        kind.parse::<u64>().ok()
3034                    );
3035                    let rendered = format!("{}{}", error.message, details);
3036                    for secret in [
3037                        "http://",
3038                        "https://",
3039                        "password",
3040                        "secret-capability-path",
3041                        "secret-query",
3042                        "secret-fragment",
3043                    ] {
3044                        assert!(!rendered.contains(secret), "{operation} {kind}");
3045                    }
3046                    assert!(details.get("causeMessage").is_none());
3047                    assert!(details.get("path").is_none());
3048                }
3049            }
3050        }
3051
3052        #[test]
3053        fn injected_body_and_websocket_errors_do_not_expose_payloads_or_source_chains() {
3054            struct FailingRead;
3055            impl std::io::Read for FailingRead {
3056                fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
3057                    Err(std::io::Error::other(SECRET))
3058                }
3059            }
3060            let response = ureq::http::Response::builder()
3061                .status(200)
3062                .body(ureq::Body::builder().reader(FailingRead))
3063                .unwrap();
3064            let error = segment_error(read_body(response, None, None, None).unwrap_err());
3065            assert_eq!(error.code, "sync.transport_failed");
3066            assert_eq!(error.message, "segment transfer failed");
3067            assert_eq!(
3068                error.details,
3069                Some(serde_json::json!({ "causeKind": "body", "httpStatus": 200 }))
3070            );
3071            for cause in [
3072                tungstenite::Error::Io(std::io::Error::other(SecretError)),
3073                tungstenite::Error::Http(Box::new(
3074                    tungstenite::http::Response::builder()
3075                        .status(403)
3076                        .header("location", SECRET)
3077                        .body(Some(SECRET.as_bytes().to_vec()))
3078                        .unwrap(),
3079                )),
3080            ] {
3081                let error = ws_err("realtime connection failed", cause);
3082                assert_eq!(error.message, "realtime connection failed");
3083                let details = error.details.unwrap();
3084                assert!(details.get("path").is_none());
3085                assert!(details.get("causeMessage").is_none());
3086                assert!(!details.to_string().contains("secret"));
3087            }
3088        }
3089
3090        #[test]
3091        fn body_read_timeouts_are_classified_through_ureq_wrapping() {
3092            // Direct: Error::into_io boxes a non-io ureq error as io::Error::other.
3093            let direct = ureq::Error::Timeout(ureq::Timeout::RecvBody).into_io();
3094            assert_eq!(timeout_cause(&direct), Some("timeout"));
3095            // Compressed: gzip wraps the io error again as Error::Decompress.
3096            let wrapped = ureq::Error::Decompress(
3097                "gzip",
3098                ureq::Error::Timeout(ureq::Timeout::Global).into_io(),
3099            )
3100            .into_io();
3101            assert_eq!(timeout_cause(&wrapped), Some("round_deadline"));
3102            // Only the drive bound sets per-read and per-write timeouts.
3103            for reason in [ureq::Timeout::PerRead, ureq::Timeout::PerWrite] {
3104                assert_eq!(
3105                    timeout_cause(&ureq::Error::Timeout(reason).into_io()),
3106                    Some("drive")
3107                );
3108                let error = http_err("sync request failed", ureq::Error::Timeout(reason));
3109                assert_eq!(error.code, "sync.idle_timeout");
3110                assert_eq!(error.details, None, "the round adds the drive's details");
3111            }
3112            // A plain socket timeout and a non-timeout are handled too.
3113            assert_eq!(
3114                timeout_cause(&std::io::Error::new(std::io::ErrorKind::TimedOut, "plain")),
3115                Some("timeout")
3116            );
3117            assert_eq!(timeout_cause(&std::io::Error::other("other")), None);
3118            assert_eq!(timeout_cause(&ureq::Error::StatusCode(500).into_io()), None);
3119        }
3120
3121        #[test]
3122        fn body_read_wrapped_timeouts_surface_the_typed_code() {
3123            struct TimeoutRead(bool);
3124            impl std::io::Read for TimeoutRead {
3125                fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
3126                    Err(if self.0 {
3127                        ureq::Error::Timeout(ureq::Timeout::RecvBody).into_io()
3128                    } else {
3129                        ureq::Error::Decompress(
3130                            "gzip",
3131                            ureq::Error::Timeout(ureq::Timeout::RecvBody).into_io(),
3132                        )
3133                        .into_io()
3134                    })
3135                }
3136            }
3137            for compressed in [false, true] {
3138                let response = ureq::http::Response::builder()
3139                    .status(200)
3140                    .body(ureq::Body::builder().reader(TimeoutRead(compressed)))
3141                    .unwrap();
3142                let error = read_body(response, None, None, None).unwrap_err();
3143                assert_eq!(error.code, "transport.timeout", "{compressed}");
3144                assert_eq!(
3145                    error.details,
3146                    Some(serde_json::json!({ "causeKind": "timeout" }))
3147                );
3148            }
3149        }
3150
3151        #[test]
3152        fn policy_validation_rejects_zero_and_unrepresentable_bounds() {
3153            assert_eq!(
3154                HostTransportPolicy {
3155                    request_timeout: Some(Duration::ZERO),
3156                    ..Default::default()
3157                }
3158                .validate()
3159                .unwrap_err(),
3160                "sync.invalid_request: transport config requestTimeoutMs is out of range"
3161            );
3162            assert_eq!(
3163                HostTransportPolicy {
3164                    round_deadline: Some(Duration::MAX),
3165                    ..Default::default()
3166                }
3167                .validate()
3168                .unwrap_err(),
3169                "sync.invalid_request: transport config roundDeadlineMs is out of range"
3170            );
3171            for interval in [Duration::ZERO, Duration::MAX / 2 + Duration::from_secs(1)] {
3172                assert_eq!(
3173                    HostTransportPolicy {
3174                        realtime_heartbeat: Some(interval),
3175                        ..Default::default()
3176                    }
3177                    .validate()
3178                    .unwrap_err(),
3179                    "sync.invalid_request: transport config realtimeHeartbeatMs is out of range"
3180                );
3181            }
3182            assert!(HostTransportPolicy {
3183                max_request_bytes: Some(0),
3184                ..Default::default()
3185            }
3186            .validate()
3187            .is_err());
3188            assert!(HostTransportPolicy {
3189                max_response_bytes: Some(0),
3190                ..Default::default()
3191            }
3192            .validate()
3193            .is_err());
3194            // A programmatic zero or an unrepresentable duration matches the
3195            // JSON rejection instead of panicking at `Instant::now() + budget`.
3196            assert!(HostTransportPolicy::default().validate().is_ok());
3197            assert_eq!(
3198                HostTransportPolicy::from_config(&serde_json::json!({ "requestTimeoutMs": 0 }))
3199                    .unwrap_err(),
3200                "sync.invalid_request: transport config requestTimeoutMs must be a positive integer"
3201            );
3202        }
3203
3204        #[test]
3205        fn set_policy_rejects_invalid_and_preserves_the_current_policy() {
3206            let mut transport =
3207                NativeTransport::new("http://127.0.0.1", &serde_json::json!({}), None).unwrap();
3208            assert_eq!(transport.policy.max_response_bytes, None);
3209            let error = transport
3210                .set_policy(HostTransportPolicy {
3211                    max_response_bytes: Some(0),
3212                    ..Default::default()
3213                })
3214                .unwrap_err();
3215            assert_eq!(
3216                error,
3217                "sync.invalid_request: transport config maxResponseBytes must be a positive integer"
3218            );
3219            assert_eq!(transport.policy.max_response_bytes, None);
3220        }
3221
3222        #[test]
3223        fn an_expired_round_deadline_is_typed_and_cleared_for_the_next_round() {
3224            let mut transport =
3225                NativeTransport::new("http://127.0.0.1:9", &serde_json::json!({}), None).unwrap();
3226            transport.set_round_deadline(Some(std::time::Instant::now() - Duration::from_secs(1)));
3227            let error = transport.blob_download("sha256:test", None).unwrap_err();
3228            assert_eq!(error.code, "transport.timeout");
3229            assert_eq!(
3230                error.details,
3231                Some(serde_json::json!({ "causeKind": "round_deadline" }))
3232            );
3233            // Clearing the scope leaves no stale deadline for the next round.
3234            transport.set_round_deadline(None);
3235            assert!(transport.round_remaining().is_ok());
3236        }
3237
3238        #[test]
3239        fn an_expired_round_deadline_refuses_before_queuing_a_realtime_send() {
3240            let mut transport =
3241                NativeTransport::new("http://127.0.0.1:9", &serde_json::json!({}), None).unwrap();
3242            transport.set_round_deadline(Some(std::time::Instant::now() - Duration::from_secs(1)));
3243            // The refusal precedes the connection check, so a not-connected
3244            // transport reports the typed round timeout and leaves no frame
3245            // queued behind it for a later send.
3246            let error = transport.realtime_send("blocked").unwrap_err();
3247            assert_eq!(error.code, "transport.timeout");
3248            assert_eq!(
3249                error.details,
3250                Some(serde_json::json!({ "causeKind": "round_deadline" }))
3251            );
3252            // With the deadline cleared the same call reaches the connection
3253            // check instead.
3254            transport.set_round_deadline(None);
3255            let error = transport.realtime_send("blocked").unwrap_err();
3256            assert_eq!(error.code, "transport.failed");
3257        }
3258
3259        #[test]
3260        fn the_request_timeout_bounds_phases_and_the_round_deadline_bounds_the_call() {
3261            #[derive(Debug)]
3262            struct TimeoutRecording(Arc<Mutex<Vec<[Option<Duration>; 3]>>>);
3263            impl Connector for TimeoutRecording {
3264                type Out = ();
3265                fn connect(
3266                    &self,
3267                    details: &ConnectionDetails,
3268                    _: Option<()>,
3269                ) -> Result<Option<()>, ureq::Error> {
3270                    self.0.lock().unwrap().push([
3271                        details.config.timeouts().global,
3272                        details.config.timeout_per_read(),
3273                        details.config.timeout_per_write(),
3274                    ]);
3275                    Err(ureq::Error::ConnectionFailed)
3276                }
3277            }
3278            let mut transport =
3279                NativeTransport::new("http://127.0.0.1", &serde_json::json!({}), None).unwrap();
3280            transport
3281                .set_policy(HostTransportPolicy {
3282                    request_timeout: Some(Duration::from_millis(1234)),
3283                    ..Default::default()
3284                })
3285                .unwrap();
3286            let timeouts = transport.agent.config().timeouts();
3287            for phase in [
3288                timeouts.resolve,
3289                timeouts.connect,
3290                timeouts.send_request,
3291                timeouts.recv_response,
3292            ] {
3293                assert_eq!(phase, Some(Duration::from_millis(1234)));
3294            }
3295            assert_eq!(timeouts.global, None, "the request bound is not end to end");
3296            assert_eq!(timeouts.recv_body, None, "a body is bounded by silence");
3297            let seen = Arc::new(Mutex::new(Vec::new()));
3298            transport.agent = ureq::Agent::with_parts(
3299                ureq::Agent::config_builder().build(),
3300                TimeoutRecording(Arc::clone(&seen)),
3301                DefaultResolver::default(),
3302            );
3303            let _ = transport.blob_upload("sha256:test", &[0u8; 4], None);
3304            transport.set_round_deadline(Some(std::time::Instant::now() + Duration::from_secs(60)));
3305            let _ = transport.blob_upload("sha256:test", &[0u8; 4], None);
3306            // §7.8: the drive bound caps every read and write, which restarts it,
3307            // and leaves the host's absolute ceiling as it is.
3308            transport.set_idle_bound(Some(Duration::from_secs(60)));
3309            let _ = transport.sync(&[]);
3310            let seen = seen.lock().unwrap();
3311            assert_eq!(
3312                seen[0],
3313                [None, None, None],
3314                "no round deadline, no call ceiling"
3315            );
3316            assert!(seen[1][0].is_some_and(|ceiling| ceiling <= Duration::from_secs(60)));
3317            assert_eq!(seen[1][1..], [None, None]);
3318            assert!(seen[2][0].is_some_and(|ceiling| ceiling <= Duration::from_secs(60)));
3319            let drive = Some(Duration::from_secs(60));
3320            assert_eq!(seen[2][1..], [drive, drive]);
3321        }
3322
3323        #[test]
3324        fn the_idle_bound_replaces_an_unbounded_or_longer_wait_and_keeps_a_shorter_one() {
3325            let idle = Duration::from_secs(30);
3326            let unbounded = NextTimeout::default();
3327            assert_eq!(idle_bound(unbounded, idle).after, UreqDuration::Exact(idle));
3328            let longer = NextTimeout {
3329                after: UreqDuration::from_secs(90),
3330                per_read: Some(UreqDuration::from_secs(7)),
3331                ..NextTimeout::default()
3332            };
3333            let bounded = idle_bound(longer, idle);
3334            assert_eq!(bounded.after, UreqDuration::Exact(idle));
3335            assert_eq!(bounded.reason, UreqTimeout::RecvBody);
3336            assert_eq!(
3337                bounded.per_read, longer.per_read,
3338                "per-read cap passes through"
3339            );
3340            let shorter = NextTimeout {
3341                after: UreqDuration::from_secs(5),
3342                ..NextTimeout::default()
3343            };
3344            assert_eq!(idle_bound(shorter, idle), shorter);
3345        }
3346
3347        /// Arrival offsets of a response of `total` bytes in `chunk`-byte
3348        /// pieces over a link with a one-way `latency`, a `rate` in bytes per
3349        /// second, and `stalls` (start, length) windows in which nothing
3350        /// arrives. Virtual time: nothing sleeps.
3351        fn shaped_link(
3352            total: u64,
3353            chunk: u64,
3354            latency: Duration,
3355            rate: u64,
3356            stalls: &[(Duration, Duration)],
3357        ) -> Vec<Duration> {
3358            let mut at = latency;
3359            let mut arrivals = Vec::new();
3360            let mut left = total;
3361            while left > 0 {
3362                let piece = left.min(chunk);
3363                at += Duration::from_micros(piece * 1_000_000 / rate);
3364                for (start, length) in stalls {
3365                    if at > *start && at < *start + *length {
3366                        at = *start + *length;
3367                    }
3368                }
3369                arrivals.push(at);
3370                left -= piece;
3371            }
3372            arrivals
3373        }
3374
3375        /// Run `round_expiry` over a link: `Ok(finished_at)` when every chunk
3376        /// arrives before a bound, `Err((expired_at, expiry))` otherwise.
3377        fn round_over(
3378            arrivals: &[Duration],
3379            idle: Duration,
3380            drive: Option<Duration>,
3381            ceiling: Option<Duration>,
3382        ) -> Result<Duration, (Duration, Expiry)> {
3383            let base = Instant::now();
3384            let mut last = base;
3385            for arrival in arrivals {
3386                let (deadline, expiry) =
3387                    round_expiry(last, idle, drive, ceiling.map(|ceiling| base + ceiling));
3388                if base + *arrival > deadline {
3389                    return Err((deadline - base, expiry));
3390                }
3391                last = base + *arrival;
3392            }
3393            Ok(last - base)
3394        }
3395
3396        #[test]
3397        fn a_slow_link_that_keeps_delivering_never_trips_the_idle_bound() {
3398            // Nori's phone behind a relay: an 8.6 MB page at 100 KB/s, 80 ms.
3399            let link = shaped_link(
3400                8_600_000,
3401                64 * 1024,
3402                Duration::from_millis(80),
3403                100_000,
3404                &[],
3405            );
3406            let finished = round_over(&link, ROUND_IDLE_TIMEOUT, None, None).unwrap();
3407            assert!(
3408                finished > ROUND_IDLE_TIMEOUT * 2,
3409                "the transfer outlasts the old whole-transfer bound ({finished:?})"
3410            );
3411        }
3412
3413        #[test]
3414        fn a_stall_shorter_than_the_idle_bound_is_survived_and_a_longer_one_is_not() {
3415            let link = |length| {
3416                shaped_link(
3417                    4_000_000,
3418                    64 * 1024,
3419                    Duration::from_millis(80),
3420                    100_000,
3421                    &[(Duration::from_secs(10), length)],
3422                )
3423            };
3424            round_over(
3425                &link(Duration::from_secs(29)),
3426                ROUND_IDLE_TIMEOUT,
3427                None,
3428                None,
3429            )
3430            .unwrap();
3431            let (expired, expiry) = round_over(
3432                &link(Duration::from_secs(31)),
3433                ROUND_IDLE_TIMEOUT,
3434                None,
3435                None,
3436            )
3437            .unwrap_err();
3438            assert_eq!(expiry, Expiry::Silence);
3439            assert!(
3440                expired >= Duration::from_secs(30) && expired < Duration::from_secs(41),
3441                "the bound counts from the last chunk before the stall ({expired:?})"
3442            );
3443        }
3444
3445        #[test]
3446        fn the_host_ceiling_still_bounds_a_link_that_keeps_delivering() {
3447            let link = shaped_link(
3448                8_600_000,
3449                64 * 1024,
3450                Duration::from_millis(80),
3451                100_000,
3452                &[],
3453            );
3454            // The drive bound restarts with every chunk; the host ceiling does not.
3455            let (expired, expiry) = round_over(
3456                &link,
3457                ROUND_IDLE_TIMEOUT,
3458                Some(Duration::from_secs(60)),
3459                Some(Duration::from_secs(60)),
3460            )
3461            .unwrap_err();
3462            assert_eq!(expiry, Expiry::Ceiling);
3463            assert_eq!(expired, Duration::from_secs(60));
3464        }
3465
3466        #[test]
3467        fn keepalives_carry_a_round_through_a_server_build_under_the_drive_bound() {
3468            // §1.6: the server writes its header frames, then builds for 90 s
3469            // with a KEEPALIVE every 10 s, then writes the rest.
3470            let drive = Some(Duration::from_millis(
3471                crate::SyncClient::SYNC_IDLE_TIMEOUT_MS,
3472            ));
3473            let build = |keepalives: bool| {
3474                let mut arrivals = vec![Duration::from_millis(80)];
3475                if keepalives {
3476                    arrivals.extend((1..=8).map(|n| Duration::from_secs(10 * n)));
3477                }
3478                arrivals.push(Duration::from_secs(90));
3479                arrivals
3480            };
3481            assert_eq!(
3482                round_over(&build(true), ROUND_IDLE_TIMEOUT, drive, None).unwrap(),
3483                Duration::from_secs(90)
3484            );
3485            // Without keepalives the fixed 30 s socket silence bound ends it.
3486            let (expired, expiry) =
3487                round_over(&build(false), ROUND_IDLE_TIMEOUT, drive, None).unwrap_err();
3488            assert_eq!(expiry, Expiry::Silence);
3489            assert_eq!(expired, Duration::from_millis(30_080));
3490            // A drive bound under the silence bound ends a silent round first.
3491            let (expired, expiry) = round_over(
3492                &build(false),
3493                ROUND_IDLE_TIMEOUT,
3494                Some(Duration::from_secs(20)),
3495                None,
3496            )
3497            .unwrap_err();
3498            assert_eq!(expiry, Expiry::Drive);
3499            assert_eq!(expired, Duration::from_millis(20_080));
3500            // The host's absolute deadline ends a progressing round.
3501            let (expired, expiry) = round_over(
3502                &build(true),
3503                ROUND_IDLE_TIMEOUT,
3504                drive,
3505                Some(Duration::from_secs(45)),
3506            )
3507            .unwrap_err();
3508            assert_eq!(expiry, Expiry::Ceiling);
3509            assert_eq!(expired, Duration::from_secs(45));
3510        }
3511
3512        #[test]
3513        fn a_keepalive_chunk_restarts_the_socket_silence_bound() {
3514            let header = ssp2::Message {
3515                wire_version: ssp2::decode::WIRE_VERSION,
3516                msg_kind: ssp2::MsgKind::Response,
3517                frames: vec![ssp2::Frame::RespHeader {
3518                    required_schema_version: None,
3519                    latest_schema_version: None,
3520                    log_epoch: "epoch-1".to_owned(),
3521                    reset_required: false,
3522                }],
3523            };
3524            let mut message = header.clone();
3525            message.frames.push(ssp2::Frame::Keepalive);
3526            let response = ssp2::encode_message(&message);
3527            let header_len = ssp2::encode_message(&header).len() - 5;
3528            let channel = RoundChannel::default();
3529            channel.begin(&[0x00]).unwrap();
3530            let tagged = |bytes: &[u8]| [&[crate::REALTIME_TAG_ROUND][..], bytes].concat();
3531            let silent_since = Instant::now() - ROUND_IDLE_TIMEOUT;
3532            for chunk in [
3533                &response[..header_len],
3534                &response[header_len..header_len + 5],
3535            ] {
3536                // The previous chunk is a whole silence bound old.
3537                channel.state.lock().unwrap().last_progress = Some(silent_since);
3538                assert!(channel.route_binary(&tagged(chunk)).is_none());
3539                let last_progress = channel.state.lock().unwrap().last_progress.unwrap();
3540                assert!(
3541                    round_expiry(last_progress, ROUND_IDLE_TIMEOUT, None, None).0 > Instant::now(),
3542                    "the chunk restarted the silence bound"
3543                );
3544            }
3545            assert!(channel
3546                .route_binary(&tagged(&response[header_len + 5..]))
3547                .is_none());
3548            assert_eq!(
3549                channel.wait(None, ROUND_IDLE_TIMEOUT, None).unwrap(),
3550                response,
3551                "the round completes with the KEEPALIVE in its bytes"
3552            );
3553        }
3554
3555        #[test]
3556        fn an_expired_round_deadline_bounds_the_socket_wait() {
3557            let channel = RoundChannel::default();
3558            let error = channel
3559                .wait(
3560                    Some(std::time::Instant::now() - Duration::from_secs(1)),
3561                    ROUND_IDLE_TIMEOUT,
3562                    None,
3563                )
3564                .unwrap_err();
3565            assert_eq!(error.code, "transport.timeout");
3566            assert_eq!(
3567                error.details,
3568                Some(serde_json::json!({ "causeKind": "round_deadline" }))
3569            );
3570        }
3571    }
3572}
3573
3574#[cfg(all(test, feature = "native-transport"))]
3575mod tests {
3576    use super::*;
3577    use std::io::{BufRead, BufReader, Write};
3578
3579    #[test]
3580    fn an_undrained_inbound_buffer_past_its_limit_ends_the_connection() {
3581        const DELTA_BYTES: usize = 1024 * 1024;
3582        let deltas = INBOUND_BUFFER_LIMIT_BYTES / DELTA_BYTES + 1;
3583        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
3584        let base = format!("http://{}", listener.local_addr().unwrap());
3585        let server = std::thread::spawn(move || {
3586            let (socket, _) = listener.accept().unwrap();
3587            let mut socket = tungstenite::accept(socket).unwrap();
3588            for _ in 0..deltas {
3589                let mut frame = vec![crate::REALTIME_TAG_DELTA];
3590                frame.resize(DELTA_BYTES + 1, 7);
3591                socket
3592                    .send(tungstenite::Message::Binary(frame.into()))
3593                    .unwrap();
3594            }
3595            while !matches!(socket.read(), Ok(tungstenite::Message::Close(_)) | Err(_)) {}
3596        });
3597        let (woke, wakes) = mpsc::channel::<()>();
3598        let mut transport = HostTransport::from_config_with_notify(
3599            &serde_json::json!({"baseUrl": base}),
3600            Some(Arc::new(move || {
3601                let _ = woke.send(());
3602            })),
3603        )
3604        .unwrap();
3605        transport.realtime_connect("c1").unwrap();
3606        // One wake per buffered frame: every delta, then the loss.
3607        for _ in 0..=deltas {
3608            wakes.recv().unwrap();
3609        }
3610        let inbound = transport.take_inbound();
3611        assert_eq!(inbound.len(), deltas + 1);
3612        assert!(inbound[..deltas]
3613            .iter()
3614            .all(|frame| matches!(frame, Inbound::Binary(bytes) if bytes.len() == DELTA_BYTES)));
3615        assert!(matches!(
3616            &inbound[deltas],
3617            Inbound::Disconnected(error) if error.code == "transport.failed"
3618                && error.details.as_ref().and_then(|d| d.get("causeKind"))
3619                    == Some(&serde_json::json!("inbound_overflow"))
3620        ));
3621        transport.shutdown();
3622        server.join().unwrap();
3623    }
3624
3625    #[test]
3626    fn the_first_heartbeat_arms_silence_detection() {
3627        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
3628        let base = format!("http://{}", listener.local_addr().unwrap());
3629        let (beat, heartbeat) = mpsc::channel::<()>();
3630        let server = std::thread::spawn(move || {
3631            let (socket, _) = listener.accept().unwrap();
3632            let mut socket = tungstenite::accept(socket).unwrap();
3633            socket
3634                .send(tungstenite::Message::Text("{\"event\":\"hello\"}".into()))
3635                .unwrap();
3636            heartbeat.recv().unwrap();
3637            socket
3638                .send(tungstenite::Message::Text(
3639                    "{\"event\":\"heartbeat\",\"data\":{\"timestamp\":1}}".into(),
3640                ))
3641                .unwrap();
3642            // Then silence until the client gives up on the socket.
3643            while socket.read().is_ok() {}
3644        });
3645        let (woke, wakes) = mpsc::channel::<()>();
3646        let mut transport = HostTransport::from_config_with_notify(
3647            &serde_json::json!({"baseUrl": base, "realtimeHeartbeatMs": 50}),
3648            Some(Arc::new(move || {
3649                let _ = woke.send(());
3650            })),
3651        )
3652        .unwrap();
3653        transport.realtime_connect("c1").unwrap();
3654        wakes.recv_timeout(Duration::from_secs(10)).unwrap();
3655        // §8.5: before the first heartbeat no silence bound applies, so five
3656        // intervals of silence keep the socket.
3657        assert!(wakes.recv_timeout(Duration::from_millis(250)).is_err());
3658        beat.send(()).unwrap();
3659        for _ in 0..2 {
3660            wakes.recv_timeout(Duration::from_secs(10)).unwrap();
3661        }
3662        let inbound = transport.take_inbound();
3663        assert_eq!(inbound.len(), 3);
3664        assert!(matches!(&inbound[0], Inbound::Text(_)));
3665        assert!(matches!(&inbound[1], Inbound::Text(text) if text.contains("heartbeat")));
3666        assert!(matches!(
3667            &inbound[2],
3668            Inbound::Disconnected(error) if error.code == "transport.timeout"
3669                && error.details == Some(serde_json::json!({ "causeKind": "heartbeat" }))
3670        ));
3671        transport.shutdown();
3672        server.join().unwrap();
3673    }
3674
3675    #[test]
3676    fn segment_and_blob_reads_stop_past_the_declared_byte_length() {
3677        for case in ["segment", "signed_segment", "blob", "signed_blob"] {
3678            let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
3679            let base = format!("http://{}", listener.local_addr().unwrap());
3680            let server = std::thread::spawn(move || {
3681                let (mut socket, _) = listener.accept().unwrap();
3682                let mut reader = BufReader::new(socket.try_clone().unwrap());
3683                loop {
3684                    let mut line = String::new();
3685                    reader.read_line(&mut line).unwrap();
3686                    if line == "\r\n" {
3687                        break;
3688                    }
3689                }
3690                let body = vec![7u8; 4 << 20];
3691                // The client stops reading, so the rest of the write may fail.
3692                let _ = write!(
3693                    socket,
3694                    "HTTP/1.1 200 OK\r\nContent-Type: application/octet-stream\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
3695                    body.len()
3696                );
3697                let _ = socket.write_all(&body);
3698            });
3699            let mut transport =
3700                HostTransport::from_config(&serde_json::json!({ "baseUrl": base })).unwrap();
3701            let mut progress = |_| {};
3702            let bytes = match case {
3703                "segment" => transport.download_segment(
3704                    &SegmentRequest {
3705                        segment_id: "sha256:test".into(),
3706                        table: "tasks".into(),
3707                        requested_scopes_json: "{}".into(),
3708                        byte_length: 16,
3709                    },
3710                    &mut progress,
3711                ),
3712                "signed_segment" => {
3713                    transport.fetch_url(&format!("{base}/signed"), 16, &mut progress)
3714                }
3715                "blob" => transport
3716                    .blob_download("sha256:test", Some(16))
3717                    .map(|download| match download {
3718                        BlobDownload::Bytes(bytes) => bytes,
3719                        BlobDownload::Url { .. } => panic!("expected inline bytes"),
3720                    }),
3721                _ => transport.fetch_blob_url(&format!("{base}/signed"), Some(16)),
3722            }
3723            .unwrap();
3724            // §5.4: reading ends with the chunk that passes the cap; the
3725            // client rejects the longer body.
3726            assert!(
3727                bytes.len() > 16 && bytes.len() <= 16 + 64 * 1024,
3728                "{case} read {} bytes",
3729                bytes.len()
3730            );
3731            server.join().unwrap();
3732        }
3733    }
3734
3735    #[test]
3736    fn a_round_deadline_expiring_during_a_socket_send_is_the_typed_timeout() {
3737        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
3738        let base = format!("http://{}", listener.local_addr().unwrap());
3739        let (release, released) = mpsc::channel::<()>();
3740        // The peer completes the upgrade and never reads, so the request's
3741        // send can only end at the round deadline.
3742        let server = std::thread::spawn(move || {
3743            let (socket, _) = listener.accept().unwrap();
3744            let _socket = tungstenite::accept(socket).unwrap();
3745            let _ = released.recv();
3746        });
3747        let mut transport =
3748            HostTransport::from_config(&serde_json::json!({"baseUrl": base})).unwrap();
3749        transport.realtime_connect("c1").unwrap();
3750        transport.set_round_deadline(Some(std::time::Instant::now() + Duration::from_millis(200)));
3751        let error = transport
3752            .realtime_sync(&vec![0u8; 32 * 1024 * 1024])
3753            .unwrap_err();
3754        assert_eq!(error.code, "transport.timeout");
3755        assert_eq!(
3756            error.details,
3757            Some(serde_json::json!({ "causeKind": "round_deadline" }))
3758        );
3759        assert!(matches!(
3760            &transport.take_inbound()[..],
3761            [Inbound::Disconnected(lost)] if lost.code == "transport.timeout"
3762        ));
3763        transport.shutdown();
3764        release.send(()).unwrap();
3765        server.join().unwrap();
3766    }
3767
3768    #[test]
3769    fn receipt_observer_covers_round_chunks_wakes_reconnect_and_overflow() {
3770        use ssp2::model::{Frame, Message, MsgKind};
3771        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
3772        let base = format!("http://{}", listener.local_addr().unwrap());
3773        let response = ssp2::encode_message(&Message {
3774            wire_version: ssp2::decode::WIRE_VERSION,
3775            msg_kind: MsgKind::Response,
3776            frames: vec![Frame::RespHeader {
3777                required_schema_version: None,
3778                latest_schema_version: None,
3779                log_epoch: "epoch".into(),
3780                reset_required: false,
3781            }],
3782        });
3783        let server_response = response.clone();
3784        let server = std::thread::spawn(move || {
3785            for _ in 0..2 {
3786                let (socket, _) = listener.accept().unwrap();
3787                let mut socket = tungstenite::accept(socket).unwrap();
3788                assert!(matches!(
3789                    socket.read().unwrap(),
3790                    tungstenite::Message::Binary(_)
3791                ));
3792                socket
3793                    .send(tungstenite::Message::Binary(
3794                        vec![crate::REALTIME_TAG_DELTA, 7].into(),
3795                    ))
3796                    .unwrap();
3797                socket
3798                    .send(tungstenite::Message::Text("wake".into()))
3799                    .unwrap();
3800                let split = server_response.len() / 2;
3801                for part in [&server_response[..split], &server_response[split..]] {
3802                    let mut chunk = vec![crate::REALTIME_TAG_ROUND];
3803                    chunk.extend_from_slice(part);
3804                    socket
3805                        .send(tungstenite::Message::Binary(chunk.into()))
3806                        .unwrap();
3807                }
3808                assert!(matches!(
3809                    socket.read().unwrap(),
3810                    tungstenite::Message::Close(_)
3811                ));
3812            }
3813        });
3814        let mut transport =
3815            HostTransport::from_config(&serde_json::json!({"baseUrl": base})).unwrap();
3816        let (sender, receiver) = mpsc::sync_channel(4);
3817        let (small_sender, small_receiver) = mpsc::sync_channel(1);
3818        transport.set_realtime_receipt_observer(Some(sender));
3819        for round in 0..2 {
3820            transport.realtime_connect("c1").unwrap();
3821            let before = SystemTime::now();
3822            assert_eq!(transport.realtime_sync(b"request").unwrap(), response);
3823            let after = SystemTime::now();
3824            if round == 0 {
3825                let receipts = [
3826                    receiver.recv().unwrap(),
3827                    receiver.recv().unwrap(),
3828                    receiver.recv().unwrap(),
3829                    receiver.recv().unwrap(),
3830                ];
3831                assert_eq!(
3832                    receipts.map(|r| r.kind),
3833                    [
3834                        RealtimeReceiptKind::Delta,
3835                        RealtimeReceiptKind::Text,
3836                        RealtimeReceiptKind::Round,
3837                        RealtimeReceiptKind::Round
3838                    ]
3839                );
3840                assert_eq!(
3841                    receipts.map(|r| r.bytes),
3842                    [
3843                        2,
3844                        4,
3845                        1 + response.len() / 2,
3846                        1 + response.len() - response.len() / 2
3847                    ]
3848                );
3849                assert!(receipts
3850                    .iter()
3851                    .all(|r| r.received_at >= before && r.received_at <= after));
3852                assert!(
3853                    matches!(&transport.take_inbound()[..], [Inbound::Binary(bytes), Inbound::Text(text)] if bytes == &[7] && text == "wake")
3854                );
3855                assert_eq!(transport.take_dropped_realtime_receipts(), 0);
3856                // A capacity-one channel proves loss is visible without blocking
3857                // the reader or its round waiter.
3858                transport.set_realtime_receipt_observer(Some(small_sender.clone()));
3859            } else {
3860                assert_eq!(
3861                    small_receiver.recv().unwrap().kind,
3862                    RealtimeReceiptKind::Delta
3863                );
3864                assert_eq!(transport.take_dropped_realtime_receipts(), 3);
3865                assert_eq!(transport.take_dropped_realtime_receipts(), 0);
3866            }
3867            transport.shutdown();
3868        }
3869        server.join().unwrap();
3870    }
3871
3872    #[test]
3873    fn receipt_observer_reports_chunks_of_a_failed_round() {
3874        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
3875        let base = format!("http://{}", listener.local_addr().unwrap());
3876        let server = std::thread::spawn(move || {
3877            let (socket, _) = listener.accept().unwrap();
3878            let mut socket = tungstenite::accept(socket).unwrap();
3879            assert!(matches!(
3880                socket.read().unwrap(),
3881                tungstenite::Message::Binary(_)
3882            ));
3883            socket
3884                .send(tungstenite::Message::Binary(
3885                    vec![crate::REALTIME_TAG_ROUND, b'S'].into(),
3886                ))
3887                .unwrap();
3888            socket
3889                .close(Some(tungstenite::protocol::CloseFrame {
3890                    code: tungstenite::protocol::frame::coding::CloseCode::Normal,
3891                    reason: "bye".into(),
3892                }))
3893                .unwrap();
3894        });
3895        let mut transport =
3896            HostTransport::from_config(&serde_json::json!({"baseUrl": base})).unwrap();
3897        let (sender, receiver) = mpsc::sync_channel(2);
3898        transport.set_realtime_receipt_observer(Some(sender));
3899        transport.realtime_connect("c1").unwrap();
3900        assert!(transport.realtime_sync(b"request").is_err());
3901        assert_eq!(receiver.recv().unwrap().kind, RealtimeReceiptKind::Round);
3902        let close = receiver.recv().unwrap();
3903        assert_eq!(close.kind, RealtimeReceiptKind::Close);
3904        assert_eq!(close.bytes, 5);
3905        assert_eq!(transport.take_dropped_realtime_receipts(), 0);
3906        transport.shutdown();
3907        server.join().unwrap();
3908    }
3909
3910    #[test]
3911    fn detached_round_uses_the_owned_socket_and_shutdown_releases_it() {
3912        use ssp2::model::{Frame, Message, MsgKind};
3913        use std::sync::mpsc::channel;
3914        for cancelled in [false, true] {
3915            let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
3916            let base = format!("http://{}", listener.local_addr().unwrap());
3917            let (entered_tx, entered_rx) = channel();
3918            let (release_tx, release_rx) = channel();
3919            let server = std::thread::spawn(move || {
3920                let (socket, _) = listener.accept().unwrap();
3921                let mut socket = tungstenite::accept(socket).unwrap();
3922                let request = socket.read().unwrap().into_data();
3923                assert_eq!(request[0], crate::REALTIME_TAG_ROUND);
3924                assert_eq!(
3925                    ssp2::decode_message(&request[1..]).unwrap().msg_kind,
3926                    MsgKind::Request
3927                );
3928                entered_tx.send(()).unwrap();
3929                release_rx.recv().unwrap();
3930                if !cancelled {
3931                    let response = ssp2::encode_message(&Message {
3932                        wire_version: ssp2::decode::WIRE_VERSION,
3933                        msg_kind: MsgKind::Response,
3934                        frames: vec![Frame::RespHeader {
3935                            required_schema_version: None,
3936                            latest_schema_version: None,
3937                            log_epoch: "epoch".into(),
3938                            reset_required: true,
3939                        }],
3940                    });
3941                    let mut chunk = vec![crate::REALTIME_TAG_ROUND];
3942                    chunk.extend(response);
3943                    socket
3944                        .send(tungstenite::Message::Binary(chunk.into()))
3945                        .unwrap();
3946                }
3947            });
3948            let mut owner =
3949                HostTransport::from_config(&serde_json::json!({"baseUrl":base})).unwrap();
3950            owner.realtime_connect("detached-round").unwrap();
3951            let mut detached = owner.fork_round();
3952            let network = std::thread::spawn(move || {
3953                let request = ssp2::encode_message(&Message {
3954                    wire_version: ssp2::decode::WIRE_VERSION,
3955                    msg_kind: MsgKind::Request,
3956                    frames: vec![
3957                        Frame::ReqHeader {
3958                            client_id: "detached-round".into(),
3959                            schema_version: 1,
3960                            log_epoch: None,
3961                            outbox_id: None,
3962                        },
3963                        Frame::PullHeader {
3964                            limit_commits: 0,
3965                            limit_snapshot_rows: 0,
3966                            max_snapshot_pages: 0,
3967                            accept: 3,
3968                            cursor: -1,
3969                            registration_digest: ssp2::registration::registration_digest([]),
3970                            echo_digest: None,
3971                        },
3972                    ],
3973                });
3974                detached.realtime_sync(&request)
3975            });
3976            entered_rx.recv().unwrap();
3977            owner.set_headers(vec![("authorization".into(), "Bearer rotated".into())]);
3978            assert!(owner.take_inbound().is_empty());
3979            if cancelled {
3980                owner.shutdown();
3981            }
3982            release_tx.send(()).unwrap();
3983            let response = network.join().unwrap();
3984            if cancelled {
3985                assert!(response.is_err());
3986            } else {
3987                assert_eq!(
3988                    ssp2::decode_message(&response.unwrap()).unwrap().msg_kind,
3989                    MsgKind::Response
3990                );
3991                owner.shutdown();
3992            }
3993            server.join().unwrap();
3994        }
3995    }
3996
3997    fn minimal_response() -> Vec<u8> {
3998        use ssp2::model::{Frame, Message, MsgKind};
3999        ssp2::encode_message(&Message {
4000            wire_version: ssp2::decode::WIRE_VERSION,
4001            msg_kind: MsgKind::Response,
4002            frames: vec![Frame::RespHeader {
4003                required_schema_version: None,
4004                latest_schema_version: None,
4005                log_epoch: "epoch".into(),
4006                reset_required: true,
4007            }],
4008        })
4009    }
4010
4011    #[test]
4012    fn a_presigned_blob_put_sends_the_blob_id_digest_without_hashing_the_body() {
4013        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4014        let base = format!("http://{}", listener.local_addr().unwrap());
4015        let server = std::thread::spawn(move || {
4016            let (mut socket, _) = listener.accept().unwrap();
4017            let mut reader = BufReader::new(socket.try_clone().unwrap());
4018            let mut head = Vec::new();
4019            loop {
4020                let mut line = String::new();
4021                reader.read_line(&mut line).unwrap();
4022                if line == "\r\n" {
4023                    break;
4024                }
4025                let (name, value) = line.trim_end().split_once(": ").unwrap_or((&line, ""));
4026                head.push(format!("{}: {value}", name.to_ascii_lowercase()));
4027            }
4028            socket
4029                .write_all(b"HTTP/1.1 200 OK\r\nContent-Length: 0\r\n\r\n")
4030                .unwrap();
4031            head
4032        });
4033        let mut transport =
4034            HostTransport::from_config(&serde_json::json!({"baseUrl": base})).unwrap();
4035        let url = format!("{base}/bucket/key?X-Amz-Signature=x");
4036        // A blob id that is not a sha256 id is refused before any request.
4037        let error = transport
4038            .blob_put_url("sha256:AB", &url, b"body", None)
4039            .unwrap_err();
4040        assert_eq!(error.code, "sync.invalid_request");
4041        // The digest of the blob id differs from SHA-256("body"): the header
4042        // carries the given digest, so no body hash ran.
4043        transport
4044            .blob_put_url(&format!("sha256:{}", "ab".repeat(32)), &url, b"body", None)
4045            .unwrap();
4046        let head = server.join().unwrap();
4047        assert!(head.contains(
4048            &"x-amz-checksum-sha256: q6urq6urq6urq6urq6urq6urq6urq6urq6urq6urq6s=".to_owned()
4049        ));
4050        assert!(head.contains(&"content-length: 4".to_owned()));
4051    }
4052
4053    #[test]
4054    fn a_stalled_response_body_times_out_on_silence() {
4055        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4056        let base = format!("http://{}", listener.local_addr().unwrap());
4057        let server = std::thread::spawn(move || {
4058            let (mut socket, _) = listener.accept().unwrap();
4059            let mut reader = BufReader::new(socket.try_clone().unwrap());
4060            loop {
4061                let mut line = String::new();
4062                reader.read_line(&mut line).unwrap();
4063                if line == "\r\n" {
4064                    break;
4065                }
4066            }
4067            socket
4068                .write_all(b"HTTP/1.1 200 OK\r\nContent-Length: 1000\r\n\r\n0123456789")
4069                .unwrap();
4070            // Withhold the rest until the client gives up and closes.
4071            let mut rest = Vec::new();
4072            let _ = std::io::Read::read_to_end(&mut reader, &mut rest);
4073        });
4074        let mut transport = HostTransport::from_config(
4075            &serde_json::json!({"baseUrl": base, "requestTimeoutMs": 200}),
4076        )
4077        .unwrap();
4078        let mut received = 0;
4079        let error = transport
4080            .download_segment(
4081                &SegmentRequest {
4082                    segment_id: "sha256:test".into(),
4083                    table: "tasks".into(),
4084                    requested_scopes_json: "{}".into(),
4085                    byte_length: 1 << 20,
4086                },
4087                &mut |bytes| received = bytes,
4088            )
4089            .unwrap_err();
4090        assert_eq!(error.code, "transport.timeout");
4091        assert_eq!(
4092            error.details,
4093            Some(serde_json::json!({ "causeKind": "timeout" }))
4094        );
4095        server.join().unwrap();
4096    }
4097
4098    #[test]
4099    fn a_timed_out_socket_round_closes_the_socket_and_reports_the_loss() {
4100        use std::sync::mpsc::channel;
4101        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4102        let base = format!("http://{}", listener.local_addr().unwrap());
4103        let (closed_tx, closed_rx) = channel();
4104        let server = std::thread::spawn(move || {
4105            let (socket, _) = listener.accept().unwrap();
4106            let mut socket = tungstenite::accept(socket).unwrap();
4107            socket.read().unwrap();
4108            // The head of a response that never finishes.
4109            let response = minimal_response();
4110            let mut chunk = vec![crate::REALTIME_TAG_ROUND];
4111            chunk.extend_from_slice(&response[..response.len() / 2]);
4112            socket
4113                .send(tungstenite::Message::Binary(chunk.into()))
4114                .unwrap();
4115            // The client must close; the tail is never delivered to a round.
4116            while let Ok(message) = socket.read() {
4117                if matches!(message, tungstenite::Message::Close(_)) {
4118                    break;
4119                }
4120            }
4121            closed_tx.send(()).unwrap();
4122        });
4123        let mut transport =
4124            HostTransport::from_config(&serde_json::json!({"baseUrl": base})).unwrap();
4125        transport.realtime_connect("slow").unwrap();
4126        transport.set_round_deadline(Some(
4127            std::time::Instant::now() + std::time::Duration::from_millis(300),
4128        ));
4129        let error = transport.realtime_sync(b"request").unwrap_err();
4130        assert_eq!(error.code, "transport.timeout");
4131        closed_rx.recv().unwrap();
4132        let lost = transport
4133            .take_inbound()
4134            .into_iter()
4135            .filter(|inbound| matches!(inbound, Inbound::Disconnected(e) if e.code == "transport.timeout"))
4136            .count();
4137        assert_eq!(lost, 1, "the loss is reported once");
4138        server.join().unwrap();
4139    }
4140
4141    #[test]
4142    fn a_request_larger_than_a_chunk_rides_as_several_round_chunks() {
4143        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4144        let base = format!("http://{}", listener.local_addr().unwrap());
4145        let request: Vec<u8> = (0..3 * 64 * 1024 + 5).map(|i| (i % 251) as u8).collect();
4146        let expected = request.clone();
4147        let server = std::thread::spawn(move || {
4148            let (socket, _) = listener.accept().unwrap();
4149            let mut socket = tungstenite::accept(socket).unwrap();
4150            let mut body = Vec::new();
4151            let mut messages = 0;
4152            while body.len() < expected.len() {
4153                let message = socket.read().unwrap().into_data();
4154                assert_eq!(message[0], crate::REALTIME_TAG_ROUND);
4155                body.extend_from_slice(&message[1..]);
4156                messages += 1;
4157            }
4158            assert_eq!(body, expected);
4159            assert_eq!(messages, 4);
4160            let mut chunk = vec![crate::REALTIME_TAG_ROUND];
4161            chunk.extend(minimal_response());
4162            socket
4163                .send(tungstenite::Message::Binary(chunk.into()))
4164                .unwrap();
4165        });
4166        let mut transport =
4167            HostTransport::from_config(&serde_json::json!({"baseUrl": base})).unwrap();
4168        transport.realtime_connect("chunked").unwrap();
4169        let response = transport.realtime_sync(&request).unwrap();
4170        assert_eq!(response, minimal_response());
4171        transport.shutdown();
4172        server.join().unwrap();
4173    }
4174
4175    #[test]
4176    fn segment_http_failures_have_named_codes_and_safe_cause_details() {
4177        for signed in [false, true] {
4178            for body_failure in [false, true] {
4179                let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4180                let base = format!("http://{}", listener.local_addr().unwrap());
4181                let server = std::thread::spawn(move || {
4182                    let (mut socket, _) = listener.accept().unwrap();
4183                    let mut reader = BufReader::new(socket.try_clone().unwrap());
4184                    loop {
4185                        let mut line = String::new();
4186                        reader.read_line(&mut line).unwrap();
4187                        if line == "\r\n" {
4188                            break;
4189                        }
4190                        assert!(!line.is_empty());
4191                    }
4192                    socket.write_all(if body_failure {
4193                        b"HTTP/1.1 200 OK\r\nContent-Length: 999\r\nConnection: close\r\n\r\nshort"
4194                    } else {
4195                        b"HTTP/1.1 403 Forbidden\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
4196                    }).unwrap();
4197                });
4198                let mut transport =
4199                    HostTransport::from_config(&serde_json::json!({"baseUrl": base})).unwrap();
4200                let mut progress = |_| {};
4201                let error = if signed {
4202                    transport.fetch_url(
4203                        &format!("{base}/signed?signature=secret"),
4204                        1 << 20,
4205                        &mut progress,
4206                    )
4207                } else {
4208                    transport.download_segment(
4209                        &SegmentRequest {
4210                            segment_id: "sha256:test".into(),
4211                            table: "tasks".into(),
4212                            requested_scopes_json: "{}".into(),
4213                            byte_length: 1 << 20,
4214                        },
4215                        &mut progress,
4216                    )
4217                }
4218                .unwrap_err();
4219                assert_eq!(error.code, "sync.transport_failed");
4220                assert_eq!(error.message, "segment transfer failed");
4221                let details = error.details.unwrap();
4222                assert!(details.get("path").is_none());
4223                assert!(details.get("causeMessage").is_none());
4224                assert_eq!(
4225                    details["causeKind"],
4226                    if body_failure { "body" } else { "status" }
4227                );
4228                assert_eq!(details["httpStatus"], if body_failure { 200 } else { 403 });
4229                server.join().unwrap();
4230            }
4231        }
4232    }
4233
4234    #[test]
4235    fn blob_status_classification_uses_the_actual_http_response() {
4236        for (status, expected) in [
4237            (404, "blob.not_found"),
4238            (401, "sync.auth_required"),
4239            (403, "blob.forbidden"),
4240            (500, "transport.failed"),
4241        ] {
4242            let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4243            let base = format!("http://{}", listener.local_addr().unwrap());
4244            let server = std::thread::spawn(move || {
4245                let (mut socket, _) = listener.accept().unwrap();
4246                let mut reader = BufReader::new(socket.try_clone().unwrap());
4247                loop {
4248                    let mut line = String::new();
4249                    reader.read_line(&mut line).unwrap();
4250                    if line == "\r\n" {
4251                        break;
4252                    }
4253                    assert!(!line.is_empty());
4254                }
4255                let body = r#"{"code":"blob.not_found","message":"https://host/secret-path?secret-query#secret-fragment","retryable":false}"#;
4256                write!(socket, "HTTP/1.1 {status} Error\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}", body.len()).unwrap();
4257            });
4258            let mut transport =
4259                HostTransport::from_config(&serde_json::json!({"baseUrl":base})).unwrap();
4260            let error = transport.blob_download("sha256:test", None).unwrap_err();
4261            assert_eq!(error.code, expected);
4262            assert_eq!(
4263                error.details,
4264                Some(serde_json::json!({
4265                    "causeKind": "status",
4266                    "httpStatus": status,
4267                    "retryable": false
4268                }))
4269            );
4270            assert!(!error.message.contains("secret"));
4271            assert!(!error.message.contains("http"));
4272            server.join().unwrap();
4273        }
4274    }
4275
4276    #[test]
4277    fn refused_segment_connection_has_a_named_code_without_an_invented_status() {
4278        for signed in [false, true] {
4279            let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4280            let base = format!("http://{}", listener.local_addr().unwrap());
4281            drop(listener);
4282            let mut transport =
4283                HostTransport::from_config(&serde_json::json!({"baseUrl": base})).unwrap();
4284            let mut progress = |_| {};
4285            let error = if signed {
4286                transport.fetch_url(
4287                    &format!("{base}/signed?signature=secret"),
4288                    1 << 20,
4289                    &mut progress,
4290                )
4291            } else {
4292                transport.download_segment(
4293                    &SegmentRequest {
4294                        segment_id: "sha256:test".into(),
4295                        table: "tasks".into(),
4296                        requested_scopes_json: "{}".into(),
4297                        byte_length: 1 << 20,
4298                    },
4299                    &mut progress,
4300                )
4301            }
4302            .unwrap_err();
4303            assert_eq!(error.code, "sync.transport_failed");
4304            assert!(error.details.as_ref().unwrap().get("httpStatus").is_none());
4305        }
4306    }
4307
4308    #[test]
4309    fn segment_http_reports_intermediate_bytes_for_direct_and_signed_urls() {
4310        for signed in [false, true] {
4311            let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4312            let base = format!("http://{}", listener.local_addr().unwrap());
4313            let server = std::thread::spawn(move || {
4314                let (mut socket, _) = listener.accept().unwrap();
4315                let mut reader = BufReader::new(socket.try_clone().unwrap());
4316                let mut headers = String::new();
4317                loop {
4318                    let mut line = String::new();
4319                    reader.read_line(&mut line).unwrap();
4320                    if line == "\r\n" {
4321                        break;
4322                    }
4323                    assert!(!line.is_empty());
4324                    headers.push_str(&line.to_ascii_lowercase());
4325                }
4326                assert_eq!(headers.contains("authorization: bearer test"), !signed);
4327                assert_eq!(headers.contains("x-syncular-scopes:"), !signed);
4328                let bytes = vec![7; 128 * 1024 + 17];
4329                write!(
4330                    socket,
4331                    "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
4332                    bytes.len()
4333                )
4334                .unwrap();
4335                socket.write_all(&bytes).unwrap();
4336            });
4337            let mut transport = HostTransport::from_config(
4338                &serde_json::json!({"baseUrl": base, "headers": {"authorization": "Bearer test"}}),
4339            )
4340            .unwrap();
4341            let mut updates = Vec::new();
4342            let mut progress = |bytes| updates.push(bytes);
4343            let bytes = if signed {
4344                transport
4345                    .fetch_url(&format!("{base}/signed"), 1 << 20, &mut progress)
4346                    .unwrap()
4347            } else {
4348                transport
4349                    .download_segment(
4350                        &SegmentRequest {
4351                            segment_id: "sha256:test".into(),
4352                            table: "tasks".into(),
4353                            requested_scopes_json: "{}".into(),
4354                            byte_length: 1 << 20,
4355                        },
4356                        &mut progress,
4357                    )
4358                    .unwrap()
4359            };
4360            assert_eq!(bytes.len(), 128 * 1024 + 17);
4361            assert!(updates.iter().any(|n| *n > 0 && *n < bytes.len() as u64));
4362            assert_eq!(updates.last(), Some(&(bytes.len() as u64)));
4363            assert!(updates.windows(2).all(|pair| pair[0] < pair[1]));
4364            server.join().unwrap();
4365        }
4366    }
4367
4368    #[test]
4369    fn request_over_cap_is_refused_before_network() {
4370        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4371        listener.set_nonblocking(true).unwrap();
4372        let base = format!("http://{}", listener.local_addr().unwrap());
4373        let mut transport =
4374            HostTransport::from_config(&serde_json::json!({"baseUrl": base, "maxRequestBytes": 4}))
4375                .unwrap();
4376        let error = transport
4377            .blob_upload("sha256:test", &[0u8; 8], None)
4378            .unwrap_err();
4379        assert_eq!(error.code, "transport.request_too_large");
4380        assert_eq!(
4381            error.details,
4382            Some(serde_json::json!({ "limit": 4, "size": 8 }))
4383        );
4384        assert!(
4385            matches!(listener.accept(), Err(ref e) if e.kind() == std::io::ErrorKind::WouldBlock),
4386            "the request cap is checked before any connection"
4387        );
4388    }
4389
4390    #[test]
4391    fn credential_bearing_redirects_are_refused_without_contacting_the_destination() {
4392        for credentials in ["headers", "userinfo", "password"] {
4393            for redirects in ["deny", "follow"] {
4394                let destination = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4395                destination.set_nonblocking(true).unwrap();
4396                let location = format!("http://{}/landed", destination.local_addr().unwrap());
4397                let origin = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4398                let host = origin.local_addr().unwrap();
4399                let (base, headers) = match credentials {
4400                    "headers" => (
4401                        format!("http://{host}"),
4402                        serde_json::json!({"authorization": "Bearer secret"}),
4403                    ),
4404                    "userinfo" => (format!("http://user:secret@{host}"), serde_json::json!({})),
4405                    _ => (format!("http://:secret@{host}"), serde_json::json!({})),
4406                };
4407                let server = std::thread::spawn(move || {
4408                    let (mut socket, _) = origin.accept().unwrap();
4409                    let mut reader = BufReader::new(socket.try_clone().unwrap());
4410                    loop {
4411                        let mut line = String::new();
4412                        reader.read_line(&mut line).unwrap();
4413                        if line == "\r\n" {
4414                            break;
4415                        }
4416                    }
4417                    let _ = write!(
4418                        socket,
4419                        "HTTP/1.1 302 Found\r\nLocation: {location}\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
4420                    );
4421                });
4422                let mut transport = HostTransport::from_config(&serde_json::json!({
4423                    "baseUrl": base,
4424                    "redirects": redirects,
4425                    "headers": headers,
4426                }))
4427                .unwrap();
4428                let error = transport.blob_download("sha256:test", None).unwrap_err();
4429                assert_eq!(
4430                    error.code, "transport.redirect",
4431                    "{credentials} {redirects}"
4432                );
4433                let details = error.details.unwrap();
4434                assert_eq!(details["causeKind"], "redirect");
4435                assert_eq!(details["httpStatus"], 302);
4436                assert!(
4437                    matches!(destination.accept(), Err(ref e) if e.kind() == std::io::ErrorKind::WouldBlock),
4438                    "{credentials} {redirects}: the destination is never contacted"
4439                );
4440                server.join().unwrap();
4441            }
4442        }
4443    }
4444
4445    #[test]
4446    fn websocket_handshake_redirects_obey_the_redirect_policy() {
4447        // The handshake request carries the configured headers and the realtime
4448        // URL's query, so a redirect response is an error and never replays
4449        // them to the Location. The Location points at a second listener so
4450        // the test can prove it was never contacted. A `follow` policy cannot
4451        // establish at all and fails before any connection (see
4452        // `tests/realtime_disconnect.rs`).
4453        for credential in ["headers", "userinfo", "query", "none"] {
4454            let redirects = "deny";
4455            let destination = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4456            let destination_addr = destination.local_addr().unwrap();
4457            let location = format!("ws://{destination_addr}/realtime");
4458            // The redirect target answers every handshake with 400 and stops
4459            // on an explicit sentinel connection, so a leaked redirect fails
4460            // the assertions below instead of hanging the test.
4461            let landed = Arc::new(Mutex::new(Vec::new()));
4462            let landed_writer = Arc::clone(&landed);
4463            let destination_thread = std::thread::spawn(move || loop {
4464                let (mut socket, _) = destination.accept().unwrap();
4465                let mut reader = BufReader::new(socket.try_clone().unwrap());
4466                let mut head = String::new();
4467                loop {
4468                    let mut line = String::new();
4469                    reader.read_line(&mut line).unwrap();
4470                    if line == "\r\n" {
4471                        break;
4472                    }
4473                    head.push_str(&line);
4474                }
4475                let sentinel = head.starts_with("GET /sentinel");
4476                landed_writer.lock().unwrap().push(head);
4477                let _ = write!(
4478                    socket,
4479                    "HTTP/1.1 400 Bad Request\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
4480                );
4481                if sentinel {
4482                    break;
4483                }
4484            });
4485            let origin = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4486            let origin_addr = origin.local_addr().unwrap();
4487            let (headers, ws_url) = match credential {
4488                "headers" => (serde_json::json!({"authorization": "Bearer secret"}), None),
4489                "userinfo" => (
4490                    serde_json::json!({}),
4491                    Some(format!("ws://user:secret@{origin_addr}/realtime")),
4492                ),
4493                "query" => (
4494                    serde_json::json!({}),
4495                    Some(format!("ws://{origin_addr}/realtime?token=secret")),
4496                ),
4497                _ => (serde_json::json!({}), None),
4498            };
4499            let (head_tx, head_rx) = std::sync::mpsc::channel();
4500            let origin_thread = std::thread::spawn(move || {
4501                let (mut socket, _) = origin.accept().unwrap();
4502                let mut reader = BufReader::new(socket.try_clone().unwrap());
4503                let mut head = String::new();
4504                loop {
4505                    let mut line = String::new();
4506                    reader.read_line(&mut line).unwrap();
4507                    if line == "\r\n" {
4508                        break;
4509                    }
4510                    head.push_str(&line);
4511                }
4512                let _ = head_tx.send(head);
4513                let _ = write!(
4514                    socket,
4515                    "HTTP/1.1 302 Found\r\nLocation: {location}\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
4516                );
4517            });
4518            let mut config = serde_json::json!({
4519                "baseUrl": format!("http://{origin_addr}"),
4520                "headers": headers,
4521                "redirects": redirects,
4522            });
4523            if let Some(ws_url) = &ws_url {
4524                config["wsUrl"] = serde_json::json!(ws_url);
4525            }
4526            let mut transport = HostTransport::from_config(&config).unwrap();
4527            let result = transport.realtime_connect("c1");
4528            // Stop the responder even when the redirect was refused; the
4529            // sentinel is the only connection it may have seen.
4530            let mut sentinel = std::net::TcpStream::connect(destination_addr).unwrap();
4531            let _ = write!(sentinel, "GET /sentinel HTTP/1.1\r\nHost: sentinel\r\n\r\n");
4532            destination_thread.join().unwrap();
4533            let landed = landed.lock().unwrap().clone();
4534            origin_thread.join().unwrap();
4535            let error = result.unwrap_err();
4536            assert_eq!(
4537                error.code, "transport.redirect",
4538                "{credential}: a refused handshake redirect surfaces the redirect code"
4539            );
4540            let details = error.details.unwrap();
4541            assert_eq!(details["causeKind"], "redirect");
4542            assert_eq!(details["httpStatus"], 302);
4543            assert_eq!(
4544                landed.len(),
4545                1,
4546                "{credential}: the redirect target is never contacted: {landed:?}"
4547            );
4548            assert!(landed[0].starts_with("GET /sentinel"), "{landed:?}");
4549            let head = head_rx.recv().unwrap();
4550            if credential == "userinfo" {
4551                assert!(
4552                    !head.contains("secret"),
4553                    "the handshake request line drops URL userinfo"
4554                );
4555            }
4556            if credential == "query" {
4557                assert!(
4558                    head.contains("token=secret"),
4559                    "the handshake request line carries the realtime query"
4560                );
4561            }
4562        }
4563    }
4564
4565    // 200000 decoded bytes in 548 compressed bytes: a decompression bomb the
4566    // decoded cap must stop before the buffer grows.
4567    const GZIP_BOMB: [u8; 548] = [
4568        0x1f, 0x8b, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0xff, 0xed, 0xc9, 0xb1, 0x11, 0x80,
4569        0x20, 0x10, 0x00, 0xb0, 0x59, 0x1c, 0x80, 0xa1, 0xfe, 0x90, 0xb3, 0x41, 0xf0, 0x7c, 0x2d,
4570        0xd8, 0xde, 0x09, 0xdc, 0x20, 0x69, 0x93, 0x6b, 0xd4, 0xb7, 0xc7, 0x5d, 0xb2, 0x1d, 0x67,
4571        0x1b, 0x4f, 0xb9, 0x62, 0xf5, 0x19, 0xfb, 0x96, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4572        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4573        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4574        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4575        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4576        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4577        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4578        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4579        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4580        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4581        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4582        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4583        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4584        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4585        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4586        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4587        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4588        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4589        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4590        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4591        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4592        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4593        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4594        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4595        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4596        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4597        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4598        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4599        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4600        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4601        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4602        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08,
4603        0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0x10, 0x42, 0x08, 0x21, 0x84, 0xf8, 0x8b, 0x0f,
4604        0xdb, 0x82, 0xf4, 0xa9, 0x40, 0x0d, 0x03, 0x00,
4605    ];
4606
4607    #[test]
4608    fn decoded_response_cap_counts_decompressed_bytes() {
4609        for cap in [200000u64, 199999] {
4610            let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4611            let base = format!("http://{}", listener.local_addr().unwrap());
4612            let server = std::thread::spawn(move || {
4613                let (mut socket, _) = listener.accept().unwrap();
4614                let mut reader = BufReader::new(socket.try_clone().unwrap());
4615                loop {
4616                    let mut line = String::new();
4617                    reader.read_line(&mut line).unwrap();
4618                    if line == "\r\n" {
4619                        break;
4620                    }
4621                }
4622                let _ = write!(
4623                    socket,
4624                    "HTTP/1.1 200 OK\r\nContent-Encoding: gzip\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
4625                    GZIP_BOMB.len()
4626                );
4627                let _ = socket.write_all(&GZIP_BOMB);
4628            });
4629            let mut transport = HostTransport::from_config(
4630                &serde_json::json!({"baseUrl": base, "maxResponseBytes": cap}),
4631            )
4632            .unwrap();
4633            let result = transport.fetch_blob_url(&format!("{base}/signed"), None);
4634            if cap == 200000 {
4635                let body = result.expect("a cap equal to the decoded size admits the body");
4636                assert_eq!(body.len(), 200000);
4637            } else {
4638                let error = result.unwrap_err();
4639                assert_eq!(error.code, "transport.response_too_large");
4640                assert_eq!(error.details, Some(serde_json::json!({ "limit": cap })));
4641            }
4642            server.join().unwrap();
4643        }
4644    }
4645
4646    #[test]
4647    fn a_json_http_error_body_reaches_the_caller() {
4648        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
4649        let base = format!("http://{}", listener.local_addr().unwrap());
4650        let body = r#"{"code":"sync.invalid_client_id","category":"invalid-request","retryable":false,"recommendedAction":"resetClientId","message":"clientId is bound to a different actor in this partition (§1.5)","details":{"actorId":"actor-b"}}"#;
4651        let server = std::thread::spawn(move || {
4652            let (mut socket, _) = listener.accept().unwrap();
4653            let mut reader = BufReader::new(socket.try_clone().unwrap());
4654            loop {
4655                let mut line = String::new();
4656                reader.read_line(&mut line).unwrap();
4657                if line == "\r\n" {
4658                    break;
4659                }
4660            }
4661            let _ = write!(
4662                socket,
4663                "HTTP/1.1 400 Bad Request\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
4664                body.len(),
4665                body
4666            );
4667        });
4668        let mut transport =
4669            HostTransport::from_config(&serde_json::json!({"baseUrl": base})).unwrap();
4670        let error = transport.sync(&[]).unwrap_err();
4671        assert_eq!(error.code, "sync.invalid_client_id");
4672        assert_eq!(
4673            error.message,
4674            "clientId is bound to a different actor in this partition (§1.5)"
4675        );
4676        let details = error.details.unwrap();
4677        assert_eq!(details["recommendedAction"], "resetClientId");
4678        assert_eq!(details["category"], "invalid-request");
4679        assert_eq!(details["retryable"], false);
4680        assert_eq!(details["httpStatus"], 400);
4681        assert_eq!(details["actorId"], "actor-b");
4682        server.join().unwrap();
4683    }
4684}
4685
4686#[cfg(test)]
4687mod local_authority_tests {
4688    use super::HostTransport;
4689    use crate::Transport;
4690
4691    #[cfg(not(feature = "local-authority"))]
4692    #[test]
4693    fn a_local_authority_path_without_the_feature_fails_with_the_unconfigured_code() {
4694        let error = HostTransport::from_config(
4695            &serde_json::json!({ "localAuthorityPath": "authority.sqlite" }),
4696        )
4697        .err()
4698        .expect("a build without local-authority refuses localAuthorityPath");
4699        assert!(
4700            error.starts_with("client.local_authority_unconfigured:"),
4701            "{error}"
4702        );
4703    }
4704
4705    #[test]
4706    fn a_config_without_a_local_authority_reports_none() {
4707        let mut transport = HostTransport::from_config(&serde_json::json!({}))
4708            .ok()
4709            .unwrap();
4710        assert_eq!(transport.local_authority_state(), None);
4711        let error = transport.attach_local_authority().unwrap_err();
4712        assert_eq!(error.code, "client.local_authority_unconfigured");
4713        let error = transport.abandon_local_authority_attach().unwrap_err();
4714        assert_eq!(error.code, "client.local_authority_unconfigured");
4715    }
4716
4717    #[cfg(feature = "local-authority")]
4718    mod with_feature {
4719        use serde_json::{json, Map, Value};
4720        use syncular_authority::LocalAuthority;
4721
4722        use super::super::{HostTransport, LocalAuthorityTransport};
4723        use crate::{
4724            ClientLimits, Mutation, SegmentFetch, SegmentRequest, SyncClient, SyncOutcome,
4725            Transport, TransportError, UnitScopes,
4726        };
4727
4728        fn schema() -> Value {
4729            json!({
4730                "version": 1,
4731                "tables": [{
4732                    "name": "todos",
4733                    "columns": [
4734                        { "name": "id", "type": "string", "nullable": false },
4735                        { "name": "list_id", "type": "string", "nullable": false }
4736                    ],
4737                    "primaryKey": "id",
4738                    "scopes": [{ "pattern": "list:{list_id}", "column": "list_id" }]
4739                }]
4740            })
4741        }
4742
4743        /// The remote server: a second authority that serves the requests the
4744        /// first one's attach and the client's later rounds send it.
4745        struct AuthorityServer {
4746            server: LocalAuthority,
4747            syncs: usize,
4748        }
4749
4750        impl Transport for AuthorityServer {
4751            fn sync(&mut self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
4752                self.syncs += 1;
4753                self.server.sync(request).map_err(|error| TransportError {
4754                    code: error.code,
4755                    message: error.message,
4756                    details: error.details,
4757                })
4758            }
4759            fn realtime_sync(&mut self, _request: &[u8]) -> Result<Vec<u8>, TransportError> {
4760                Err(TransportError::new("sync.transport_failed", "no socket"))
4761            }
4762            fn download_segment(
4763                &mut self,
4764                _request: &SegmentRequest,
4765                _on_progress: &mut dyn FnMut(u64),
4766            ) -> Result<Vec<u8>, TransportError> {
4767                Err(TransportError::new("sync.transport_failed", "no segments"))
4768            }
4769            fn realtime_connect(&mut self, _client_id: &str) -> Result<(), TransportError> {
4770                Err(TransportError::new("sync.transport_failed", "no socket"))
4771            }
4772            fn realtime_send(&mut self, _text: &str) -> Result<(), TransportError> {
4773                Ok(())
4774            }
4775            fn realtime_close(&mut self) -> Result<(), TransportError> {
4776                Ok(())
4777            }
4778        }
4779
4780        #[test]
4781        fn a_configured_path_routes_to_the_authority_and_refuses_what_it_lacks() {
4782            let mut transport =
4783                HostTransport::from_config(&json!({ "localAuthorityPath": ":memory:" }))
4784                    .ok()
4785                    .unwrap();
4786            assert!(matches!(transport, HostTransport::Local(_)));
4787            // The authority opens with the client's schema at create.
4788            assert_eq!(transport.local_authority_state(), None);
4789            assert_eq!(
4790                transport.sync(b"").unwrap_err().code,
4791                "client.local_authority_unconfigured"
4792            );
4793            assert_eq!(
4794                transport.realtime_connect("device-1").unwrap_err().code,
4795                "sync.invalid_request"
4796            );
4797            let refused = transport.download_segments(
4798                &[SegmentFetch::Url {
4799                    url: "https://cdn.example.com/s1".to_owned(),
4800                    byte_length: 1 << 20,
4801                }],
4802                &mut |_, _| {},
4803            );
4804            assert_eq!(refused.len(), 1);
4805            assert_eq!(
4806                refused[0].as_ref().unwrap_err().code,
4807                "sync.invalid_request"
4808            );
4809            // Attach needs a remote server.
4810            let error = transport.attach_local_authority().unwrap_err();
4811            assert_eq!(error.code, "client.local_authority_unconfigured");
4812        }
4813
4814        /// The client's `crdt-yjs` feature gives the local authority its merger,
4815        /// so a crdt commit is accepted instead of `sync.crdt_merge_failed`.
4816        #[cfg(feature = "crdt-yjs")]
4817        #[test]
4818        fn a_crdt_commit_through_the_local_authority_is_merged() {
4819            let schema = json!({
4820                "version": 1,
4821                "tables": [{
4822                    "name": "notes",
4823                    "columns": [
4824                        { "name": "id", "type": "string", "nullable": false },
4825                        { "name": "list_id", "type": "string", "nullable": false },
4826                        { "name": "doc", "type": "crdt", "nullable": true, "crdtType": "yjs-doc" }
4827                    ],
4828                    "primaryKey": "id",
4829                    "scopes": [{ "pattern": "list:{list_id}", "column": "list_id" }]
4830                }]
4831            });
4832            let mut transport =
4833                HostTransport::from_config(&json!({ "localAuthorityPath": ":memory:" }))
4834                    .ok()
4835                    .unwrap();
4836            transport
4837                .open_local_authority(&schema, None)
4838                .expect("open the local authority");
4839            let mut client = SyncClient::new_with_identity(
4840                Some("device-1".to_owned()),
4841                &schema,
4842                ClientLimits::default(),
4843            )
4844            .expect("client");
4845            client
4846                .subscribe(UnitScopes::from([("list_id".to_owned(), "l1".to_owned())]))
4847                .expect("subscribe");
4848            client
4849                .mutate(vec![Mutation::Upsert {
4850                    table: "notes".to_owned(),
4851                    values: Map::from_iter([
4852                        ("id".to_owned(), json!("n1")),
4853                        ("list_id".to_owned(), json!("l1")),
4854                        ("doc".to_owned(), Value::Null),
4855                    ]),
4856                    base_version: None,
4857                }])
4858                .expect("mutate");
4859            client
4860                .crdt_insert_text("notes", "n1", "doc", "text", 0, "éa")
4861                .expect("crdt insert");
4862            let outcome = client.sync_until_idle(&mut transport, None);
4863            assert!(
4864                matches!(outcome, SyncOutcome::Ok(_)),
4865                "{:?}",
4866                outcome.to_json()
4867            );
4868            assert!(client.pending_commit_ids().is_empty());
4869            assert!(client.rejections().is_empty(), "{:?}", client.rejections());
4870            assert_eq!(
4871                client.crdt_text("notes", "n1", "doc", "text").unwrap(),
4872                "éa"
4873            );
4874        }
4875
4876        #[test]
4877        fn the_authority_path_must_differ_from_the_replica_and_be_a_string() {
4878            let mut transport =
4879                HostTransport::from_config(&json!({ "localAuthorityPath": "/data/app.sqlite" }))
4880                    .ok()
4881                    .unwrap();
4882            let error = transport
4883                .open_local_authority(&schema(), Some("/data/app.sqlite"))
4884                .unwrap_err();
4885            assert_eq!(error.code, "sync.invalid_request");
4886            for path in [json!(""), json!(7)] {
4887                assert!(
4888                    HostTransport::from_config(&json!({ "localAuthorityPath": path })).is_err()
4889                );
4890            }
4891        }
4892
4893        #[test]
4894        fn rounds_reach_the_authority_until_attach_then_the_remote_server() {
4895            let schema = schema();
4896            let remote = AuthorityServer {
4897                server: LocalAuthority::open(":memory:", &schema).expect("open the remote"),
4898                syncs: 0,
4899            };
4900            let mut transport = LocalAuthorityTransport::new(":memory:", remote, true);
4901            transport
4902                .open_local_authority(&schema, None)
4903                .expect("open the local authority");
4904            assert_eq!(transport.local_authority_state(), Some("local"));
4905
4906            let mut client = SyncClient::new_with_identity(
4907                Some("device-1".to_owned()),
4908                &schema,
4909                ClientLimits::default(),
4910            )
4911            .expect("client");
4912            client
4913                .subscribe(UnitScopes::from([("list_id".to_owned(), "l1".to_owned())]))
4914                .expect("subscribe");
4915            client
4916                .mutate(vec![Mutation::Upsert {
4917                    table: "todos".to_owned(),
4918                    values: Map::from_iter([
4919                        ("id".to_owned(), json!("t1")),
4920                        ("list_id".to_owned(), json!("l1")),
4921                    ]),
4922                    base_version: None,
4923                }])
4924                .expect("mutate");
4925            let outcome = client.sync_until_idle(&mut transport, None);
4926            assert!(
4927                matches!(outcome, SyncOutcome::Ok(_)),
4928                "{:?}",
4929                outcome.to_json()
4930            );
4931            assert!(client.pending_commit_ids().is_empty());
4932            assert_eq!(
4933                transport.remote.syncs, 0,
4934                "the local authority served the round"
4935            );
4936            let error = client.connect_realtime(&mut transport).unwrap_err();
4937            assert!(error.starts_with("sync.invalid_request:"), "{error}");
4938
4939            transport.attach_local_authority().expect("attach");
4940            assert_eq!(transport.local_authority_state(), Some("attached"));
4941            let uploads = transport.remote.syncs;
4942            assert!(uploads > 0, "attach uploaded through the remote transport");
4943
4944            // The remote server's log epoch differs, so the replica resets and
4945            // bootstraps the attached row from it.
4946            let outcome = client.sync_until_idle(&mut transport, None);
4947            assert!(
4948                matches!(outcome, SyncOutcome::Ok(_)),
4949                "{:?}",
4950                outcome.to_json()
4951            );
4952            assert!(transport.remote.syncs > uploads);
4953            let rows = client.read_rows("todos").expect("rows");
4954            assert_eq!(rows.len(), 1);
4955            assert_eq!(rows[0].row_id, "t1");
4956            assert!(rows[0].version >= 1);
4957        }
4958    }
4959}