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