Skip to main content

syncular_client/
round.rs

1//! Owned round inputs and network results. SQLite never leaves its owner.
2use std::collections::BTreeMap;
3
4use ssp2::model::{Frame, MediaType, Message, MsgKind, SubStatus};
5use ssp2::{decode_message, encode_message};
6
7use crate::client::RequestMeta;
8use crate::{
9    BlobUploadGrant, ProgressObserver, ProgressPhase, SegmentFetch, SegmentRequest, SyncOutcome,
10    Transport, TransportError,
11};
12
13pub(crate) fn now_ms(fixed: Option<i64>) -> i64 {
14    fixed.unwrap_or_else(crate::wall_clock_ms)
15}
16
17pub(crate) struct PendingUpload {
18    pub id: String,
19    pub bytes: Result<Vec<u8>, TransportError>,
20    pub media_type: Option<String>,
21}
22
23/// One network operation of a prepared round.
24///
25/// A host that cannot block (a browser worker with `fetch`, a single-threaded
26/// runtime) drives a round with [`PreparedSyncRound::next_operation`],
27/// performs the operation with its own I/O, and returns the result with
28/// [`PreparedSyncRound::submit`]. A host with a blocking [`Transport`] calls
29/// [`PreparedSyncRound::exchange`], which runs the same operations in order.
30#[derive(Debug)]
31pub enum RoundOperation<'a> {
32    /// `POST <mount>/blobs/{blob_id}/upload-grant` (§5.9.3).
33    UploadGrant {
34        blob_id: &'a str,
35        byte_length: u64,
36        media_type: Option<&'a str>,
37    },
38    /// `PUT` the presigned upload url the grant returned. A failure falls back
39    /// to [`RoundOperation::Upload`] with the same body.
40    UploadPut {
41        blob_id: &'a str,
42        url: &'a str,
43        bytes: &'a [u8],
44        media_type: Option<&'a str>,
45    },
46    /// `PUT <mount>/blobs/{blob_id}` through the direct endpoint.
47    Upload {
48        blob_id: &'a str,
49        bytes: &'a [u8],
50        media_type: Option<&'a str>,
51    },
52    /// The combined push+pull message. `realtime` selects the socket path
53    /// (§8.7, [`Transport::realtime_sync`]) instead of `POST /sync` (§1.5).
54    Sync { request: &'a [u8], realtime: bool },
55    /// Every eligible segment body of the response, in wire order (§5.4 /
56    /// §5.5). Fetch them in parallel if the host can; the core consumes the
57    /// results in order and stops at the first failure.
58    Downloads(&'a [SegmentFetch]),
59}
60
61/// The host's answer to a [`RoundOperation`].
62#[derive(Debug)]
63pub enum RoundReply {
64    /// Answers [`RoundOperation::UploadGrant`] with the grant endpoint's body.
65    UploadGrant(Result<BlobUploadGrant, TransportError>),
66    /// Answers [`RoundOperation::UploadPut`] or [`RoundOperation::Upload`]. A
67    /// failed PUT makes `submit` ask for `Upload` next.
68    Upload(Result<(), TransportError>),
69    /// Answers [`RoundOperation::Sync`] with the assembled response bytes.
70    Sync(Result<Vec<u8>, TransportError>),
71    /// Answers [`RoundOperation::Downloads`] with one result per fetch, in
72    /// order.
73    Downloads(Vec<Result<Vec<u8>, TransportError>>),
74}
75
76/// The phase of a host-driven round. Every variant except `Downloads` names
77/// one network operation; `Downloads` carries the captured response while the
78/// host fetches its segment bodies.
79pub(crate) enum RoundPhase {
80    UploadGrant,
81    UploadPut {
82        url: String,
83    },
84    UploadDirect,
85    Sync,
86    Downloads {
87        planned: Vec<PlannedFetch>,
88        fetches: Vec<SegmentFetch>,
89        response: Message,
90        batch_started_at: i64,
91    },
92}
93
94/// Immutable request and blob bodies captured by the mutable client owner.
95/// Send this value to an I/O executor; it contains no SQLite connection.
96pub struct PreparedSyncRound {
97    pub(crate) id: uuid::Uuid,
98    pub(crate) started_at_ms: i64,
99    pub(crate) attempt: u64,
100    pub(crate) meta: RequestMeta,
101    pub(crate) message: Message,
102    pub(crate) realtime: bool,
103    pub(crate) uploads: std::collections::VecDeque<PendingUpload>,
104    pub(crate) scopes: BTreeMap<String, String>,
105    #[cfg(feature = "bench-internals")]
106    pub(crate) benchmark_phases: crate::bench::Recorder,
107    pub(crate) progress: ProgressObserver,
108    pub(crate) fixed_now: Option<i64>,
109    /// Absolute whole-round network deadline, anchored from the transport's
110    /// `round_deadline` budget on the round's first network call and carried
111    /// across `Continue`s. `exchange` scopes it onto the transport for the
112    /// duration of each network call.
113    pub(crate) round_deadline_at: Option<std::time::Instant>,
114    /// §7.8: the idle drive bound (`timeoutMs`, rounds the drive ran before
115    /// this one). `exchange` scopes it onto the transport as a bound on time
116    /// without progress: a network call that moves no byte for `timeoutMs`
117    /// fails with `sync.idle_timeout`.
118    pub(crate) idle_bound: Option<(u64, u32)>,
119    /// When the round's first network call started; the `elapsedMs` of a
120    /// `sync.idle_timeout` counts from it.
121    pub(crate) network_started_at: Option<std::time::Instant>,
122    /// The encoded round message, filled on the first request that needs it.
123    pub(crate) encoded: Option<Vec<u8>>,
124    pub(crate) phase: RoundPhase,
125    /// The phase that follows the completed upload exchange; consumed by the
126    /// next drive of a round whose apply returned `Continue`.
127    pub(crate) continuation: Option<RoundPhase>,
128    /// Set when the current exchange has nothing left to fetch. `finish`
129    /// returns it; `apply_sync_round` reads it.
130    pub(crate) completed: Option<ExchangeResult>,
131}
132
133/// Network results returned to the same mutable owner that prepared the round.
134pub struct CompletedSyncRound {
135    pub(crate) prepared: PreparedSyncRound,
136    pub(crate) exchange: ExchangeResult,
137}
138
139pub(crate) enum ExchangeResult {
140    Upload {
141        id: String,
142        result: Result<(), TransportError>,
143    },
144    Reply {
145        response: Result<Message, TransportError>,
146        transport_failed: bool,
147        downloads: DownloadResults,
148    },
149}
150
151/// A completed upload returns to the owner to persist its pin removal before
152/// any metadata push. A completed response returns its durable apply outcome.
153// The prepared round is the continuation and stays by value so a host keeps
154// one type for both outcomes.
155#[allow(clippy::large_enum_variant)]
156pub enum AppliedSyncRound {
157    Continue(PreparedSyncRound),
158    Complete {
159        outcome: SyncOutcome,
160        controls: Vec<String>,
161        /// The same continuation predicate used by `sync_until_idle`.
162        more: bool,
163        /// A bootstrap page advanced, renewing an unbounded idle run's budget.
164        bootstrap_advanced: bool,
165    },
166}
167
168impl PreparedSyncRound {
169    /// §7.8: bound this round by an idle drive's `timeout_ms`; `rounds` is
170    /// the count the drive ran before it. The bound restarts on every byte the
171    /// round's network calls move; the transport's own `round_deadline` stays
172    /// an absolute deadline beside it.
173    pub fn set_idle_deadline(&mut self, timeout_ms: u64, rounds: u32) {
174        self.idle_bound = Some((timeout_ms, rounds));
175    }
176
177    /// Scope the round deadline for one network call. The round anchors its
178    /// deadline on its first network call, so local work before that call does
179    /// not consume the network budget; the anchor is absolute from then on, and
180    /// a continuation reuses the carried anchor instead of refreshing it.
181    fn scope_round_deadline(
182        &mut self,
183        transport: &mut dyn Transport,
184    ) -> Result<(), TransportError> {
185        if self.network_started_at.is_none() && self.round_deadline_at.is_none() {
186            // No `Instant` to measure the drive bound with (see below).
187            #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
188            {
189                self.idle_bound = None;
190            }
191            #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
192            {
193                self.network_started_at = Some(std::time::Instant::now());
194            }
195            if let Some(budget) = transport.round_deadline() {
196                // A wasm32-unknown-unknown host has no `Instant`, so there is
197                // nothing to anchor the budget to. Report that instead of
198                // panicking inside `Instant::now()`.
199                #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
200                {
201                    let _ = budget;
202                    return Err(TransportError::new(
203                        "sync.invalid_request",
204                        "transport round deadline is unsupported on wasm32-unknown-unknown",
205                    ));
206                }
207                #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
208                match std::time::Instant::now().checked_add(budget) {
209                    Some(deadline) => self.round_deadline_at = Some(deadline),
210                    // Reject an unrepresentable host budget before network I/O.
211                    None => {
212                        return Err(TransportError::new(
213                            "sync.invalid_request",
214                            "transport round deadline is out of range",
215                        ))
216                    }
217                }
218            }
219        }
220        transport.set_round_deadline(self.round_deadline_at);
221        transport.set_idle_bound(
222            self.idle_bound
223                .map(|(ms, _)| std::time::Duration::from_millis(ms)),
224        );
225        Ok(())
226    }
227
228    /// Run network I/O without accessing client state. Download errors stay at
229    /// their descriptor's position so apply retains the same completed prefix.
230    ///
231    /// This drives the same [`RoundOperation`] sequence that a non-blocking
232    /// host drives itself, so both paths share every decision the client
233    /// makes about uploads, segment fetches, and deadline state.
234    pub fn exchange(mut self, transport: &mut dyn Transport) -> CompletedSyncRound {
235        let mut scoped = false;
236        while self.completed.is_none() {
237            let reply = {
238                let Some(operation) = self.next_operation_scoped(transport, &mut scoped) else {
239                    break;
240                };
241                match operation {
242                    RoundOperation::UploadGrant {
243                        blob_id,
244                        byte_length,
245                        media_type,
246                    } => RoundReply::UploadGrant(transport.blob_upload_grant(
247                        blob_id,
248                        byte_length,
249                        media_type,
250                    )),
251                    RoundOperation::UploadPut {
252                        blob_id,
253                        url,
254                        bytes,
255                        media_type,
256                    } => {
257                        RoundReply::Upload(transport.blob_put_url(blob_id, url, bytes, media_type))
258                    }
259                    RoundOperation::Upload {
260                        blob_id,
261                        bytes,
262                        media_type,
263                    } => RoundReply::Upload(transport.blob_upload(blob_id, bytes, media_type)),
264                    RoundOperation::Sync { request, realtime } => RoundReply::Sync(if realtime {
265                        transport.realtime_sync(request)
266                    } else {
267                        transport.sync(request)
268                    }),
269                    RoundOperation::Downloads(fetches) => {
270                        RoundReply::Downloads(transport.download_segments(fetches, &mut |_, _| {}))
271                    }
272                }
273            };
274            self.submit(reply)
275                .expect("the exchange answers its own operation");
276        }
277        transport.set_round_deadline(None);
278        transport.set_idle_bound(None);
279        self.finish().expect("the exchange completed the round")
280    }
281
282    /// The encoded round message (§1.5). Uploads listed by
283    /// [`RoundOperation::UploadGrant`] precede it; a host that drives the round
284    /// with `exchange` never needs this call.
285    pub fn request_bytes(&self) -> Vec<u8> {
286        self.encoded
287            .clone()
288            .unwrap_or_else(|| encode_message(&self.message))
289    }
290
291    /// The next network operation a host must perform, or `None` once every
292    /// operation of the current exchange is answered. Call
293    /// [`PreparedSyncRound::submit`] with its result, then repeat.
294    ///
295    /// After an upload operation completes, the round is complete for this
296    /// exchange: call [`PreparedSyncRound::finish`] and apply it, so the owner
297    /// persists the pin removal before the metadata request. The applied
298    /// round's `Continue` returns the prepared round for the next exchange.
299    pub fn next_operation(&mut self) -> Option<RoundOperation<'_>> {
300        let mut scoped = false;
301        self.next_operation_impl(None, &mut scoped)
302    }
303
304    /// Hand the result of the last [`PreparedSyncRound::next_operation`] back.
305    /// A reply of the wrong kind fails with `client.invalid_round_reply` and
306    /// leaves the round where it was.
307    pub fn submit(&mut self, reply: RoundReply) -> Result<(), TransportError> {
308        if self.completed.is_some() {
309            return Err(TransportError::new(
310                "client.invalid_round_reply",
311                "the exchange already has its reply",
312            ));
313        }
314        let phase = std::mem::replace(&mut self.phase, RoundPhase::Sync);
315        match (phase, reply) {
316            (RoundPhase::UploadGrant, RoundReply::UploadGrant(Err(error))) => {
317                let upload = self
318                    .uploads
319                    .pop_front()
320                    .expect("an upload phase owns an upload");
321                self.completed = Some(ExchangeResult::Upload {
322                    id: upload.id,
323                    result: Err(error),
324                });
325            }
326            (RoundPhase::UploadGrant, RoundReply::UploadGrant(Ok(grant))) => match grant {
327                BlobUploadGrant::Present => self.upload_complete(),
328                BlobUploadGrant::Url {
329                    url,
330                    url_expires_at_ms,
331                } => {
332                    // §5.9.3: an expiry the host clock already passed skips the
333                    // PUT; the direct endpoint still carries the body.
334                    if url_expires_at_ms.is_none_or(|expiry| expiry > now_ms(self.fixed_now)) {
335                        self.phase = RoundPhase::UploadPut { url };
336                    } else {
337                        self.phase = RoundPhase::UploadDirect;
338                    }
339                }
340                BlobUploadGrant::None => self.phase = RoundPhase::UploadDirect,
341            },
342            (RoundPhase::UploadPut { .. }, RoundReply::Upload(Ok(()))) => self.upload_complete(),
343            // A failed presigned PUT falls back to the direct endpoint with the
344            // same body, exactly like `upload_one`.
345            (RoundPhase::UploadPut { .. }, RoundReply::Upload(Err(_))) => {
346                self.phase = RoundPhase::UploadDirect;
347            }
348            (RoundPhase::UploadDirect, RoundReply::Upload(Ok(()))) => self.upload_complete(),
349            (RoundPhase::UploadDirect, RoundReply::Upload(Err(error))) => {
350                let upload = self
351                    .uploads
352                    .pop_front()
353                    .expect("an upload phase owns an upload");
354                self.completed = Some(ExchangeResult::Upload {
355                    id: upload.id,
356                    result: Err(error),
357                });
358            }
359            (RoundPhase::Sync, RoundReply::Sync(reply)) => {
360                let transport_failed = reply.is_err();
361                let response = reply.and_then(|bytes| {
362                    #[cfg(feature = "bench-internals")]
363                    let _decode_phase = self
364                        .benchmark_phases
365                        .start(crate::bench::Phase::ResponseDecode);
366                    let response = decode_message(&bytes)
367                        .map_err(|e| TransportError::new(e.code.as_str(), e.detail))?;
368                    if response.msg_kind != MsgKind::Response {
369                        return Err(TransportError::new(
370                            "sync.invalid_request",
371                            "expected a response message",
372                        ));
373                    }
374                    Ok(response)
375                });
376                let Ok(response) = response else {
377                    self.completed = Some(ExchangeResult::Reply {
378                        response,
379                        transport_failed,
380                        downloads: DownloadResults::default(),
381                    });
382                    return Ok(());
383                };
384                let mut planned: Vec<PlannedFetch> = Vec::new();
385                // A reset/floor/invalid header cannot authorize any segment
386                // fetch.
387                if matches!(response.frames.first(), Some(Frame::RespHeader { required_schema_version: None, reset_required: false, log_epoch: epoch, .. }) if self.message.frames.first().is_some_and(|f| matches!(f, Frame::ReqHeader { log_epoch, .. } if log_epoch.as_ref().map_or(self.message.frames.contains(&Frame::AdoptEpoch), |request_epoch| request_epoch == epoch))))
388                {
389                    let mut scope: Option<(&str, &str)> = None;
390                    // §7.7: the section's UNIT_EXTENT as (rowsTotal, rowsDone).
391                    let mut extent: Option<(u64, u64)> = None;
392                    // §5.4 / §5.5: collect every eligible descriptor first so
393                    // the host can overlap the fetches. One batch start is the
394                    // fetch start for the expiry rule.
395                    let batch_started_at = now_ms(self.fixed_now);
396                    let mut images = 0;
397                    for frame in &response.frames {
398                        match frame {
399                            Frame::SubStart {
400                                id,
401                                status: SubStatus::Active,
402                                ..
403                            } => {
404                                scope = self
405                                    .scopes
406                                    .get(id)
407                                    .map(|scopes| (id.as_str(), scopes.as_str()));
408                                extent = None;
409                            }
410                            Frame::SubStart { .. } | Frame::SubEnd { .. } => scope = None,
411                            Frame::UnitExtent {
412                                rows_total,
413                                rows_done,
414                            } => {
415                                extent = u64::try_from(*rows_total)
416                                    .ok()
417                                    .zip(u64::try_from(*rows_done).ok());
418                            }
419                            Frame::Error { .. } => break,
420                            Frame::SegmentRef {
421                                segment_id,
422                                table,
423                                media_type,
424                                url,
425                                url_expires_at_ms,
426                                byte_length,
427                                row_count,
428                                ..
429                            } => {
430                                let Some((id, scopes)) = scope else { continue };
431                                let advertised = match media_type {
432                                    MediaType::Rows => self.meta.accept & 3 != 0,
433                                    MediaType::Sqlite => self.meta.accept & 4 != 0,
434                                };
435                                if !advertised || (url.is_some() && self.meta.accept & 8 == 0) {
436                                    break;
437                                }
438                                // §5.6 applied-segment rule: a complete segment
439                                // is not downloaded again.
440                                if self
441                                    .meta
442                                    .applied
443                                    .get(id)
444                                    .and_then(|record| record.get(segment_id))
445                                    == Some(row_count)
446                                {
447                                    continue;
448                                }
449                                // §5.3 client memory: two image bodies per batch;
450                                // the unit's section stops before the next one.
451                                if *media_type == MediaType::Sqlite {
452                                    if images == 2 {
453                                        self.meta
454                                            .deferred
455                                            .insert((id.to_owned(), segment_id.clone()));
456                                        scope = None;
457                                        continue;
458                                    }
459                                    images += 1;
460                                }
461                                // A negative byteLength admits no body (§5.4).
462                                let cap = u64::try_from(*byte_length).unwrap_or(0);
463                                let expired = url.is_some()
464                                    && url_expires_at_ms
465                                        .is_some_and(|expiry| expiry <= batch_started_at);
466                                let (key, fetch) = match url {
467                                    Some(url) => (
468                                        DownloadKey::Url(url.clone()),
469                                        if expired {
470                                            None
471                                        } else {
472                                            Some(SegmentFetch::Url {
473                                                url: url.clone(),
474                                                byte_length: cap,
475                                            })
476                                        },
477                                    ),
478                                    None => (
479                                        DownloadKey::Segment(
480                                            segment_id.clone(),
481                                            table.clone(),
482                                            scopes.to_owned(),
483                                        ),
484                                        Some(SegmentFetch::Direct(SegmentRequest {
485                                            segment_id: segment_id.clone(),
486                                            table: table.clone(),
487                                            requested_scopes_json: scopes.to_owned(),
488                                            byte_length: cap,
489                                        })),
490                                    ),
491                                };
492                                planned.push(PlannedFetch {
493                                    key,
494                                    unit_id: id.to_owned(),
495                                    table: table.clone(),
496                                    segment_id: segment_id.clone(),
497                                    bytes_total: u64::try_from(*byte_length).ok(),
498                                    rows_total: u64::try_from(*row_count).ok(),
499                                    extent,
500                                    fetch,
501                                });
502                                if expired {
503                                    break;
504                                }
505                            }
506                            _ => {}
507                        }
508                    }
509                    if !planned.is_empty() {
510                        let progress = self.progress.clone();
511                        let on_progress = |index: usize, bytes: u64| {
512                            let Some(planned_fetch) = planned.get(index) else {
513                                return;
514                            };
515                            progress.update(|p| {
516                                p.phase = ProgressPhase::Download;
517                                p.unit_id = Some(planned_fetch.unit_id.clone());
518                                p.table = Some(planned_fetch.table.clone());
519                                p.segment_id = Some(planned_fetch.segment_id.clone());
520                                p.bytes_received = bytes;
521                                p.bytes_total = planned_fetch.bytes_total;
522                                p.rows_processed = 0;
523                                p.rows_total = planned_fetch.rows_total;
524                                p.unit_rows_total = planned_fetch.extent.map(|(total, _)| total);
525                                p.unit_rows_processed = planned_fetch.extent.map(|(_, done)| done);
526                            });
527                        };
528                        // Announce the download phase before the first byte lands.
529                        on_progress(0, 0);
530                        let fetches: Vec<SegmentFetch> = planned
531                            .iter()
532                            .filter_map(|planned_fetch| planned_fetch.fetch.clone())
533                            .collect();
534                        self.phase = RoundPhase::Downloads {
535                            planned,
536                            fetches,
537                            response,
538                            batch_started_at,
539                        };
540                        return Ok(());
541                    }
542                }
543                self.completed = Some(ExchangeResult::Reply {
544                    response: Ok(response),
545                    transport_failed,
546                    downloads: DownloadResults::default(),
547                });
548            }
549            (
550                RoundPhase::Downloads {
551                    planned,
552                    batch_started_at,
553                    response,
554                    ..
555                },
556                RoundReply::Downloads(results),
557            ) => {
558                let mut downloads = DownloadResults::default();
559                let progress = self.progress.clone();
560                let mut results = results.into_iter();
561                for planned_fetch in planned {
562                    let result = match planned_fetch.fetch {
563                        None => Err(TransportError::new(
564                            "sync.segment_expired",
565                            "signed segment URL expired before fetch",
566                        )),
567                        // A shorter result list means the batch stopped after an
568                        // earlier error, and apply aborts there.
569                        Some(_) => match results.next() {
570                            Some(result) => result,
571                            None => break,
572                        },
573                    };
574                    if let Ok(bytes) = &result {
575                        progress.update(|p| {
576                            p.phase = ProgressPhase::Download;
577                            p.unit_id = Some(planned_fetch.unit_id.clone());
578                            p.table = Some(planned_fetch.table.clone());
579                            p.segment_id = Some(planned_fetch.segment_id.clone());
580                            p.bytes_received = bytes.len() as u64;
581                            p.bytes_total = planned_fetch.bytes_total;
582                            p.rows_processed = 0;
583                            p.rows_total = planned_fetch.rows_total;
584                            p.unit_rows_total = planned_fetch.extent.map(|(total, _)| total);
585                            p.unit_rows_processed = planned_fetch.extent.map(|(_, done)| done);
586                        });
587                    }
588                    let failed = result.is_err();
589                    downloads
590                        .entries
591                        .push_back((planned_fetch.key, batch_started_at, result));
592                    if failed {
593                        break;
594                    }
595                }
596                self.completed = Some(ExchangeResult::Reply {
597                    response: Ok(response),
598                    transport_failed: false,
599                    downloads,
600                });
601            }
602            (phase, _) => {
603                self.phase = phase;
604                return Err(TransportError::new(
605                    "client.invalid_round_reply",
606                    "the reply does not answer the pending operation",
607                ));
608            }
609        }
610        Ok(())
611    }
612
613    /// The completed round once every operation is answered, ready for
614    /// `SyncClient::apply_sync_round`.
615    pub fn finish(mut self) -> Option<CompletedSyncRound> {
616        let mut exchange = self.completed.take()?;
617        // §7.8: the drive bound ended a network call; the round reports the
618        // drive's timeout, whichever call reached it.
619        if let Some((timeout_ms, rounds)) = self.idle_bound {
620            let elapsed_ms = self
621                .network_started_at
622                .map_or(0, |started| started.elapsed().as_millis() as u64);
623            let errors: Vec<&mut TransportError> = match &mut exchange {
624                ExchangeResult::Upload { result, .. } => {
625                    result.as_mut().err().into_iter().collect()
626                }
627                ExchangeResult::Reply {
628                    response,
629                    downloads,
630                    ..
631                } => response
632                    .as_mut()
633                    .err()
634                    .into_iter()
635                    .chain(
636                        downloads
637                            .entries
638                            .iter_mut()
639                            .filter_map(|(_, _, result)| result.as_mut().err()),
640                    )
641                    .collect(),
642            };
643            for error in errors {
644                if error.code == "sync.idle_timeout" {
645                    error.details = Some(serde_json::json!({
646                        "timeoutMs": timeout_ms,
647                        "rounds": rounds,
648                        "elapsedMs": elapsed_ms,
649                    }));
650                }
651            }
652        }
653        Some(CompletedSyncRound {
654            prepared: self,
655            exchange,
656        })
657    }
658
659    fn upload_complete(&mut self) {
660        let upload = self
661            .uploads
662            .pop_front()
663            .expect("an upload phase owns an upload");
664        self.completed = Some(ExchangeResult::Upload {
665            id: upload.id,
666            result: Ok(()),
667        });
668        self.continuation = Some(if self.uploads.is_empty() {
669            RoundPhase::Sync
670        } else {
671            RoundPhase::UploadGrant
672        });
673    }
674
675    fn ensure_encoded(&mut self) {
676        if self.encoded.is_none() {
677            #[cfg(feature = "bench-internals")]
678            let _phase = self
679                .benchmark_phases
680                .start(crate::bench::Phase::RequestEncode);
681            self.encoded = Some(encode_message(&self.message));
682        }
683    }
684
685    fn next_operation_scoped<'a>(
686        &'a mut self,
687        transport: &mut dyn Transport,
688        scoped: &mut bool,
689    ) -> Option<RoundOperation<'a>> {
690        self.next_operation_impl(Some(transport), scoped)
691    }
692
693    fn next_operation_impl<'a>(
694        &'a mut self,
695        mut scope: Option<&mut dyn Transport>,
696        scoped: &mut bool,
697    ) -> Option<RoundOperation<'a>> {
698        if self.completed.is_some() {
699            return None;
700        }
701        // The previous exchange ended with an upload; the owner has applied it.
702        if let Some(next) = self.continuation.take() {
703            self.phase = next;
704        }
705        if matches!(self.phase, RoundPhase::UploadGrant) && self.uploads.is_empty() {
706            self.phase = RoundPhase::Sync;
707        }
708        // A staged body that failed to read locally performs no network I/O,
709        // so it cannot be the round's first network call and must not anchor
710        // the round deadline either.
711        if matches!(self.phase, RoundPhase::UploadGrant)
712            && self
713                .uploads
714                .front()
715                .is_some_and(|upload| upload.bytes.is_err())
716        {
717            let upload = self
718                .uploads
719                .pop_front()
720                .expect("the failed upload is staged");
721            self.completed = Some(ExchangeResult::Upload {
722                id: upload.id,
723                result: Err(upload.bytes.unwrap_err()),
724            });
725            return None;
726        }
727        if matches!(self.phase, RoundPhase::Sync) {
728            self.ensure_encoded();
729        }
730        let needs_network = !matches!(self.phase, RoundPhase::Downloads { .. });
731        // The round's first network call anchors the deadline after the
732        // encode; a continuation reuses the carried anchor instead of
733        // refreshing it.
734        if needs_network && !*scoped {
735            *scoped = true;
736            if let Some(transport) = scope.as_mut() {
737                if let Err(error) = self.scope_round_deadline(&mut **transport) {
738                    if matches!(
739                        self.phase,
740                        RoundPhase::UploadGrant
741                            | RoundPhase::UploadPut { .. }
742                            | RoundPhase::UploadDirect
743                    ) {
744                        let upload = self
745                            .uploads
746                            .pop_front()
747                            .expect("an upload phase owns an upload");
748                        self.completed = Some(ExchangeResult::Upload {
749                            id: upload.id,
750                            result: Err(error),
751                        });
752                    } else {
753                        self.completed = Some(ExchangeResult::Reply {
754                            response: Err(error),
755                            transport_failed: false,
756                            downloads: DownloadResults::default(),
757                        });
758                    }
759                    return None;
760                }
761            }
762        }
763        match &self.phase {
764            RoundPhase::UploadGrant => {
765                let upload = self
766                    .uploads
767                    .front()
768                    .expect("an upload phase owns an upload");
769                let bytes = upload
770                    .bytes
771                    .as_ref()
772                    .expect("a staged body that failed to read has no operation");
773                Some(RoundOperation::UploadGrant {
774                    blob_id: &upload.id,
775                    byte_length: bytes.len() as u64,
776                    media_type: upload.media_type.as_deref(),
777                })
778            }
779            RoundPhase::UploadPut { url, .. } => {
780                let upload = self
781                    .uploads
782                    .front()
783                    .expect("an upload phase owns an upload");
784                let bytes = upload
785                    .bytes
786                    .as_ref()
787                    .expect("a staged body that failed to read has no operation");
788                Some(RoundOperation::UploadPut {
789                    blob_id: &upload.id,
790                    url,
791                    bytes,
792                    media_type: upload.media_type.as_deref(),
793                })
794            }
795            RoundPhase::UploadDirect => {
796                let upload = self
797                    .uploads
798                    .front()
799                    .expect("an upload phase owns an upload");
800                let bytes = upload
801                    .bytes
802                    .as_ref()
803                    .expect("a staged body that failed to read has no operation");
804                Some(RoundOperation::Upload {
805                    blob_id: &upload.id,
806                    bytes,
807                    media_type: upload.media_type.as_deref(),
808                })
809            }
810            RoundPhase::Sync => Some(RoundOperation::Sync {
811                request: self.encoded.as_deref().expect("the request is encoded"),
812                realtime: self.realtime,
813            }),
814            RoundPhase::Downloads { fetches, .. } => Some(RoundOperation::Downloads(fetches)),
815        }
816    }
817}
818
819#[derive(PartialEq)]
820enum DownloadKey {
821    Url(String),
822    Segment(String, String, String),
823}
824
825/// One eligible `SEGMENT_REF` of the response, collected before the batch
826/// fetch so `download_segments` sees the whole page list at once.
827pub(crate) struct PlannedFetch {
828    key: DownloadKey,
829    unit_id: String,
830    table: String,
831    segment_id: String,
832    bytes_total: Option<u64>,
833    rows_total: Option<u64>,
834    /// The unit section's `UNIT_EXTENT` (rowsTotal, rowsDone), §7.7.
835    extent: Option<(u64, u64)>,
836    /// `None` when the signed URL had already expired at the batch start: the
837    /// fetch is never attempted and its descriptor fails with
838    /// `sync.segment_expired`. Collection stops there, so only the last
839    /// collected fetch can be `None`.
840    fetch: Option<SegmentFetch>,
841}
842
843#[derive(Default)]
844pub(crate) struct DownloadResults {
845    entries: std::collections::VecDeque<(DownloadKey, i64, Result<Vec<u8>, TransportError>)>,
846    pub controls: Vec<String>,
847}
848
849impl DownloadResults {
850    fn take(&mut self, key: DownloadKey) -> Result<Vec<u8>, TransportError> {
851        let position = self
852            .entries
853            .iter()
854            .position(|(candidate, ..)| *candidate == key);
855        position
856            .and_then(|i| self.entries.remove(i))
857            .map(|(_, _, bytes)| bytes)
858            .unwrap_or_else(|| {
859                Err(TransportError::new(
860                    "client.round_download_missing",
861                    "round apply requested an uncaptured segment",
862                ))
863            })
864    }
865}
866
867impl Transport for DownloadResults {
868    fn sync(&mut self, _: &[u8]) -> Result<Vec<u8>, TransportError> {
869        Err(TransportError::new(
870            "client.round_network_on_owner",
871            "network requests must execute outside the client owner",
872        ))
873    }
874    fn realtime_sync(&mut self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
875        self.sync(request)
876    }
877    fn download_segment(
878        &mut self,
879        request: &SegmentRequest,
880        _: &mut dyn FnMut(u64),
881    ) -> Result<Vec<u8>, TransportError> {
882        self.take(DownloadKey::Segment(
883            request.segment_id.clone(),
884            request.table.clone(),
885            request.requested_scopes_json.clone(),
886        ))
887    }
888    fn fetch_url(
889        &mut self,
890        url: &str,
891        _: u64,
892        _: &mut dyn FnMut(u64),
893    ) -> Result<Vec<u8>, TransportError> {
894        self.take(DownloadKey::Url(url.to_owned()))
895    }
896    fn segment_fetch_started_at(&self, url: &str) -> Option<i64> {
897        self.entries
898            .iter()
899            .find_map(|(key, time, _)| (*key == DownloadKey::Url(url.to_owned())).then_some(*time))
900    }
901    fn realtime_connect(&mut self, _client_id: &str) -> Result<(), TransportError> {
902        Err(TransportError::new(
903            "client.round_network_on_owner",
904            "network connections must execute outside the client owner",
905        ))
906    }
907    fn realtime_send(&mut self, text: &str) -> Result<(), TransportError> {
908        self.controls.push(text.to_owned());
909        Ok(())
910    }
911    fn realtime_close(&mut self) -> Result<(), TransportError> {
912        Ok(())
913    }
914}
915
916#[cfg(test)]
917pub(crate) mod test_support {
918    use super::*;
919
920    /// Drive one exchange through the split API, answering every operation
921    /// with the blocking transport under test.
922    pub(crate) fn drive_round(
923        mut prepared: PreparedSyncRound,
924        transport: &mut dyn Transport,
925    ) -> CompletedSyncRound {
926        while let Some(operation) = prepared.next_operation() {
927            let reply = match operation {
928                RoundOperation::UploadGrant {
929                    blob_id,
930                    byte_length,
931                    media_type,
932                } => RoundReply::UploadGrant(transport.blob_upload_grant(
933                    blob_id,
934                    byte_length,
935                    media_type,
936                )),
937                RoundOperation::UploadPut {
938                    blob_id,
939                    url,
940                    bytes,
941                    media_type,
942                } => RoundReply::Upload(transport.blob_put_url(blob_id, url, bytes, media_type)),
943                RoundOperation::Upload {
944                    blob_id,
945                    bytes,
946                    media_type,
947                } => RoundReply::Upload(transport.blob_upload(blob_id, bytes, media_type)),
948                RoundOperation::Sync { request, realtime } => RoundReply::Sync(if realtime {
949                    transport.realtime_sync(request)
950                } else {
951                    transport.sync(request)
952                }),
953                RoundOperation::Downloads(fetches) => {
954                    RoundReply::Downloads(transport.download_segments(fetches, &mut |_, _| {}))
955                }
956            };
957            prepared
958                .submit(reply)
959                .expect("the driver answers the pending operation");
960        }
961        prepared.finish().expect("the round has no work left")
962    }
963}
964
965#[cfg(test)]
966mod tests {
967    use super::*;
968    use crate::{BlobUploadGrant, SegmentRequest, SyncClient, TransportError};
969
970    /// Every upload call fails with the same typed timeout, modelling a round
971    /// whose deadline was spent before the signed upload. The fallback to the
972    /// direct endpoint must not replace the typed code with a generic one.
973    struct SpentDeadline;
974
975    impl Transport for SpentDeadline {
976        fn sync(&mut self, _: &[u8]) -> Result<Vec<u8>, TransportError> {
977            unreachable!()
978        }
979        fn realtime_sync(&mut self, _: &[u8]) -> Result<Vec<u8>, TransportError> {
980            unreachable!()
981        }
982        fn download_segment(
983            &mut self,
984            _: &SegmentRequest,
985            _: &mut dyn FnMut(u64),
986        ) -> Result<Vec<u8>, TransportError> {
987            unreachable!()
988        }
989        fn blob_upload_grant(
990            &mut self,
991            _: &str,
992            _: u64,
993            _: Option<&str>,
994        ) -> Result<BlobUploadGrant, TransportError> {
995            Ok(BlobUploadGrant::Url {
996                url: "https://storage.example/signed".into(),
997                url_expires_at_ms: None,
998            })
999        }
1000        fn blob_put_url(
1001            &mut self,
1002            _: &str,
1003            _: &str,
1004            _: &[u8],
1005            _: Option<&str>,
1006        ) -> Result<(), TransportError> {
1007            Err(TransportError::new(
1008                "transport.timeout",
1009                "signed upload timed out",
1010            ))
1011        }
1012        fn blob_upload(
1013            &mut self,
1014            _: &str,
1015            _: &[u8],
1016            _: Option<&str>,
1017        ) -> Result<(), TransportError> {
1018            Err(TransportError::new(
1019                "transport.timeout",
1020                "direct upload timed out",
1021            ))
1022        }
1023        fn realtime_connect(&mut self, _client_id: &str) -> Result<(), TransportError> {
1024            Ok(())
1025        }
1026        fn realtime_send(&mut self, _: &str) -> Result<(), TransportError> {
1027            Ok(())
1028        }
1029        fn realtime_close(&mut self) -> Result<(), TransportError> {
1030            Ok(())
1031        }
1032    }
1033
1034    #[test]
1035    fn a_failed_presigned_put_falls_back_to_the_direct_endpoint() {
1036        let schema = serde_json::json!({"version":1,"tables":[{"name":"attachments","primaryKey":"id","columns":[
1037            {"name":"id","type":"string","nullable":false},
1038            {"name":"file","type":"blob_ref","nullable":true}],"scopes":[]}]});
1039        let mut client =
1040            SyncClient::new("spent-deadline".into(), &schema, Default::default()).unwrap();
1041        client
1042            .set_meta(crate::client::LOG_EPOCH_KEY, "epoch")
1043            .unwrap();
1044        client
1045            .upload_blob(b"body", Some("text/plain".into()), None)
1046            .unwrap();
1047        let mut prepared = client.prepare_sync_round(false).unwrap();
1048        let mut transport = SpentDeadline;
1049        let mut steps = Vec::new();
1050        while let Some(operation) = prepared.next_operation() {
1051            let reply = match operation {
1052                RoundOperation::UploadGrant {
1053                    blob_id,
1054                    byte_length,
1055                    media_type,
1056                } => {
1057                    steps.push("grant");
1058                    RoundReply::UploadGrant(transport.blob_upload_grant(
1059                        blob_id,
1060                        byte_length,
1061                        media_type,
1062                    ))
1063                }
1064                RoundOperation::UploadPut {
1065                    blob_id,
1066                    url,
1067                    bytes,
1068                    media_type,
1069                } => {
1070                    steps.push("put");
1071                    RoundReply::Upload(transport.blob_put_url(blob_id, url, bytes, media_type))
1072                }
1073                RoundOperation::Upload {
1074                    blob_id,
1075                    bytes,
1076                    media_type,
1077                } => {
1078                    steps.push("direct");
1079                    RoundReply::Upload(transport.blob_upload(blob_id, bytes, media_type))
1080                }
1081                _ => panic!("only upload operations precede the round message"),
1082            };
1083            prepared.submit(reply).unwrap();
1084        }
1085        assert_eq!(steps, ["grant", "put", "direct"]);
1086        let outcome = match client.apply_sync_round(prepared.finish().unwrap()) {
1087            AppliedSyncRound::Complete { outcome, .. } => outcome,
1088            AppliedSyncRound::Continue(_) => panic!("an upload failure does not continue"),
1089        };
1090        match outcome {
1091            SyncOutcome::Failed { error_code, .. } => {
1092                assert_eq!(error_code, "transport.timeout")
1093            }
1094            other => panic!("expected a typed upload failure, got {other:?}"),
1095        }
1096    }
1097
1098    /// Answers one response that references one segment and serves a body
1099    /// longer than the descriptor declares.
1100    struct OversizedSegment {
1101        unit_id: String,
1102        segment_id: String,
1103        body: Vec<u8>,
1104    }
1105
1106    impl Transport for OversizedSegment {
1107        fn sync(&mut self, _: &[u8]) -> Result<Vec<u8>, TransportError> {
1108            Ok(encode_message(&Message {
1109                wire_version: ssp2::decode::WIRE_VERSION,
1110                msg_kind: MsgKind::Response,
1111                frames: vec![
1112                    Frame::RespHeader {
1113                        required_schema_version: None,
1114                        latest_schema_version: None,
1115                        log_epoch: "epoch".into(),
1116                        reset_required: false,
1117                    },
1118                    Frame::SubStart {
1119                        id: self.unit_id.clone(),
1120                        status: SubStatus::Active,
1121                        reason_code: String::new(),
1122                        bootstrap: true,
1123                        fenced: Vec::new(),
1124                    },
1125                    Frame::SegmentRef {
1126                        segment_id: self.segment_id.clone(),
1127                        media_type: MediaType::Rows,
1128                        table: "tasks".into(),
1129                        byte_length: 4,
1130                        row_count: 1,
1131                        as_of_commit_seq: 1,
1132                        scope_digest: "digest".into(),
1133                        row_cursor: None,
1134                        next_row_cursor: None,
1135                        url: None,
1136                        url_expires_at_ms: None,
1137                    },
1138                    Frame::SubEnd {
1139                        next_cursor: 1,
1140                        bootstrap_state: None,
1141                    },
1142                ],
1143            }))
1144        }
1145        fn realtime_sync(&mut self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
1146            self.sync(request)
1147        }
1148        fn download_segment(
1149            &mut self,
1150            _: &SegmentRequest,
1151            _: &mut dyn FnMut(u64),
1152        ) -> Result<Vec<u8>, TransportError> {
1153            Ok(self.body.clone())
1154        }
1155        fn realtime_connect(&mut self, _client_id: &str) -> Result<(), TransportError> {
1156            Ok(())
1157        }
1158        fn realtime_send(&mut self, _: &str) -> Result<(), TransportError> {
1159            Ok(())
1160        }
1161        fn realtime_close(&mut self) -> Result<(), TransportError> {
1162            Ok(())
1163        }
1164    }
1165
1166    #[test]
1167    fn a_segment_body_longer_than_its_byte_length_fails_before_the_content_check() {
1168        use sha2::Digest;
1169        let schema = serde_json::json!({"version":1,"tables":[{"name":"tasks","primaryKey":"id","columns":[
1170            {"name":"id","type":"string","nullable":false},
1171            {"name":"project_id","type":"string","nullable":false}],
1172            "scopes":[{"pattern":"project:{project_id}"}]}]});
1173        let mut client = SyncClient::new("oversized".into(), &schema, Default::default()).unwrap();
1174        client
1175            .set_meta(crate::client::LOG_EPOCH_KEY, "epoch")
1176            .unwrap();
1177        let unit_id = client
1178            .subscribe(crate::UnitScopes::from([(
1179                "project_id".into(),
1180                "p1".into(),
1181            )]))
1182            .unwrap();
1183        // The body hashes to its content address, so only the §5.4 cap can
1184        // refuse it.
1185        let body = b"twelve bytes".to_vec();
1186        let segment_id = format!(
1187            "sha256:{}",
1188            sha2::Sha256::digest(&body)
1189                .iter()
1190                .map(|byte| format!("{byte:02x}"))
1191                .collect::<String>()
1192        );
1193        let mut transport = OversizedSegment {
1194            unit_id,
1195            segment_id,
1196            body,
1197        };
1198        match client.sync(&mut transport) {
1199            SyncOutcome::Failed {
1200                error_code,
1201                message,
1202                ..
1203            } => {
1204                assert_eq!(error_code, "sync.invalid_request");
1205                assert_eq!(message, "segment exceeds its byteLength");
1206            }
1207            other => panic!("expected the byteLength cap to fail the round, got {other:?}"),
1208        }
1209    }
1210
1211    /// Records each single fetch the default batch runs and fails the second.
1212    #[derive(Default)]
1213    struct CountingFetches {
1214        calls: Vec<String>,
1215    }
1216
1217    impl Transport for CountingFetches {
1218        fn sync(&mut self, _: &[u8]) -> Result<Vec<u8>, TransportError> {
1219            unreachable!()
1220        }
1221        fn realtime_sync(&mut self, _: &[u8]) -> Result<Vec<u8>, TransportError> {
1222            unreachable!()
1223        }
1224        fn download_segment(
1225            &mut self,
1226            request: &SegmentRequest,
1227            on_progress: &mut dyn FnMut(u64),
1228        ) -> Result<Vec<u8>, TransportError> {
1229            self.calls.push(request.segment_id.clone());
1230            on_progress(4);
1231            if request.segment_id == "sha256:b" {
1232                Err(TransportError::new(
1233                    "transport.timeout",
1234                    "second fetch failed",
1235                ))
1236            } else {
1237                Ok(request.segment_id.clone().into_bytes())
1238            }
1239        }
1240        fn realtime_connect(&mut self, _client_id: &str) -> Result<(), TransportError> {
1241            Ok(())
1242        }
1243        fn realtime_send(&mut self, _: &str) -> Result<(), TransportError> {
1244            Ok(())
1245        }
1246        fn realtime_close(&mut self) -> Result<(), TransportError> {
1247            Ok(())
1248        }
1249    }
1250
1251    #[test]
1252    fn the_default_batch_runs_the_single_fetches_in_order_and_stops_at_the_first_error() {
1253        let mut transport = CountingFetches::default();
1254        let fetches: Vec<SegmentFetch> = ["a", "b", "c"]
1255            .into_iter()
1256            .map(|id| {
1257                SegmentFetch::Direct(SegmentRequest {
1258                    segment_id: format!("sha256:{id}"),
1259                    table: "tasks".to_owned(),
1260                    requested_scopes_json: "{}".to_owned(),
1261                    byte_length: 4,
1262                })
1263            })
1264            .collect();
1265        let mut reported = Vec::new();
1266        let results = transport.download_segments(&fetches, &mut |index, bytes| {
1267            reported.push((index, bytes));
1268        });
1269        assert_eq!(
1270            transport.calls,
1271            vec!["sha256:a", "sha256:b"],
1272            "the third fetch was never attempted"
1273        );
1274        assert_eq!(results.len(), 2, "one result per attempted fetch");
1275        assert_eq!(results[0].as_ref().unwrap(), b"sha256:a");
1276        assert_eq!(results[1].as_ref().unwrap_err().code, "transport.timeout");
1277        assert_eq!(reported, vec![(0, 4), (1, 4)]);
1278    }
1279}