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: no second download.
421                                if self
422                                    .meta
423                                    .applied
424                                    .get(id)
425                                    .is_some_and(|ids| ids.contains(segment_id))
426                                {
427                                    continue;
428                                }
429                                // §5.3 client memory: two image bodies per batch;
430                                // the unit's section stops before the next one.
431                                if *media_type == MediaType::Sqlite {
432                                    if images == 2 {
433                                        self.meta
434                                            .deferred
435                                            .insert((id.to_owned(), segment_id.clone()));
436                                        scope = None;
437                                        continue;
438                                    }
439                                    images += 1;
440                                }
441                                // A negative byteLength admits no body (§5.4).
442                                let cap = u64::try_from(*byte_length).unwrap_or(0);
443                                let expired = url.is_some()
444                                    && url_expires_at_ms
445                                        .is_some_and(|expiry| expiry <= batch_started_at);
446                                let (key, fetch) = match url {
447                                    Some(url) => (
448                                        DownloadKey::Url(url.clone()),
449                                        if expired {
450                                            None
451                                        } else {
452                                            Some(SegmentFetch::Url {
453                                                url: url.clone(),
454                                                byte_length: cap,
455                                            })
456                                        },
457                                    ),
458                                    None => (
459                                        DownloadKey::Segment(
460                                            segment_id.clone(),
461                                            table.clone(),
462                                            scopes.to_owned(),
463                                        ),
464                                        Some(SegmentFetch::Direct(SegmentRequest {
465                                            segment_id: segment_id.clone(),
466                                            table: table.clone(),
467                                            requested_scopes_json: scopes.to_owned(),
468                                            byte_length: cap,
469                                        })),
470                                    ),
471                                };
472                                planned.push(PlannedFetch {
473                                    key,
474                                    unit_id: id.to_owned(),
475                                    table: table.clone(),
476                                    segment_id: segment_id.clone(),
477                                    bytes_total: u64::try_from(*byte_length).ok(),
478                                    rows_total: u64::try_from(*row_count).ok(),
479                                    fetch,
480                                });
481                                if expired {
482                                    break;
483                                }
484                            }
485                            _ => {}
486                        }
487                    }
488                    if !planned.is_empty() {
489                        let progress = self.progress.clone();
490                        let on_progress = |index: usize, bytes: u64| {
491                            let Some(planned_fetch) = planned.get(index) else {
492                                return;
493                            };
494                            progress.update(|p| {
495                                p.phase = ProgressPhase::Download;
496                                p.unit_id = Some(planned_fetch.unit_id.clone());
497                                p.table = Some(planned_fetch.table.clone());
498                                p.segment_id = Some(planned_fetch.segment_id.clone());
499                                p.bytes_received = bytes;
500                                p.bytes_total = planned_fetch.bytes_total;
501                                p.rows_processed = 0;
502                                p.rows_total = planned_fetch.rows_total;
503                            });
504                        };
505                        // Announce the download phase before the first byte lands.
506                        on_progress(0, 0);
507                        let fetches: Vec<SegmentFetch> = planned
508                            .iter()
509                            .filter_map(|planned_fetch| planned_fetch.fetch.clone())
510                            .collect();
511                        self.phase = RoundPhase::Downloads {
512                            planned,
513                            fetches,
514                            response,
515                            batch_started_at,
516                        };
517                        return Ok(());
518                    }
519                }
520                self.completed = Some(ExchangeResult::Reply {
521                    response: Ok(response),
522                    transport_failed,
523                    downloads: DownloadResults::default(),
524                });
525            }
526            (
527                RoundPhase::Downloads {
528                    planned,
529                    batch_started_at,
530                    response,
531                    ..
532                },
533                RoundReply::Downloads(results),
534            ) => {
535                let mut downloads = DownloadResults::default();
536                let progress = self.progress.clone();
537                let mut results = results.into_iter();
538                for planned_fetch in planned {
539                    let result = match planned_fetch.fetch {
540                        None => Err(TransportError::new(
541                            "sync.segment_expired",
542                            "signed segment URL expired before fetch",
543                        )),
544                        // A shorter result list means the batch stopped after an
545                        // earlier error, and apply aborts there.
546                        Some(_) => match results.next() {
547                            Some(result) => result,
548                            None => break,
549                        },
550                    };
551                    if let Ok(bytes) = &result {
552                        progress.update(|p| {
553                            p.phase = ProgressPhase::Download;
554                            p.unit_id = Some(planned_fetch.unit_id.clone());
555                            p.table = Some(planned_fetch.table.clone());
556                            p.segment_id = Some(planned_fetch.segment_id.clone());
557                            p.bytes_received = bytes.len() as u64;
558                            p.bytes_total = planned_fetch.bytes_total;
559                            p.rows_processed = 0;
560                            p.rows_total = planned_fetch.rows_total;
561                        });
562                    }
563                    let failed = result.is_err();
564                    downloads
565                        .entries
566                        .push_back((planned_fetch.key, batch_started_at, result));
567                    if failed {
568                        break;
569                    }
570                }
571                self.completed = Some(ExchangeResult::Reply {
572                    response: Ok(response),
573                    transport_failed: false,
574                    downloads,
575                });
576            }
577            (phase, _) => {
578                self.phase = phase;
579                return Err(TransportError::new(
580                    "client.invalid_round_reply",
581                    "the reply does not answer the pending operation",
582                ));
583            }
584        }
585        Ok(())
586    }
587
588    /// The completed round once every operation is answered, ready for
589    /// `SyncClient::apply_sync_round`.
590    pub fn finish(mut self) -> Option<CompletedSyncRound> {
591        let mut exchange = self.completed.take()?;
592        // §7.8: a network deadline the idle drive bound set is the drive's
593        // timeout, whichever call reached it.
594        if let Some((timeout_ms, rounds)) = self.idle_bound {
595            let errors: Vec<&mut TransportError> = match &mut exchange {
596                ExchangeResult::Upload { result, .. } => {
597                    result.as_mut().err().into_iter().collect()
598                }
599                ExchangeResult::Reply {
600                    response,
601                    downloads,
602                    ..
603                } => response
604                    .as_mut()
605                    .err()
606                    .into_iter()
607                    .chain(
608                        downloads
609                            .entries
610                            .iter_mut()
611                            .filter_map(|(_, _, result)| result.as_mut().err()),
612                    )
613                    .collect(),
614            };
615            for error in errors {
616                if error
617                    .details
618                    .as_ref()
619                    .and_then(|details| details.get("causeKind"))
620                    .and_then(serde_json::Value::as_str)
621                    == Some("round_deadline")
622                {
623                    *error = TransportError::new(
624                        "sync.idle_timeout",
625                        "syncUntilIdle exceeded its deadline",
626                    );
627                    error.details =
628                        Some(serde_json::json!({ "timeoutMs": timeout_ms, "rounds": rounds }));
629                }
630            }
631        }
632        Some(CompletedSyncRound {
633            prepared: self,
634            exchange,
635        })
636    }
637
638    fn upload_complete(&mut self) {
639        let upload = self
640            .uploads
641            .pop_front()
642            .expect("an upload phase owns an upload");
643        self.completed = Some(ExchangeResult::Upload {
644            id: upload.id,
645            result: Ok(()),
646        });
647        self.continuation = Some(if self.uploads.is_empty() {
648            RoundPhase::Sync
649        } else {
650            RoundPhase::UploadGrant
651        });
652    }
653
654    fn ensure_encoded(&mut self) {
655        if self.encoded.is_none() {
656            #[cfg(feature = "bench-internals")]
657            let _phase = self
658                .benchmark_phases
659                .start(crate::bench::Phase::RequestEncode);
660            self.encoded = Some(encode_message(&self.message));
661        }
662    }
663
664    fn next_operation_scoped<'a>(
665        &'a mut self,
666        transport: &mut dyn Transport,
667        scoped: &mut bool,
668    ) -> Option<RoundOperation<'a>> {
669        self.next_operation_impl(Some(transport), scoped)
670    }
671
672    fn next_operation_impl<'a>(
673        &'a mut self,
674        mut scope: Option<&mut dyn Transport>,
675        scoped: &mut bool,
676    ) -> Option<RoundOperation<'a>> {
677        if self.completed.is_some() {
678            return None;
679        }
680        // The previous exchange ended with an upload; the owner has applied it.
681        if let Some(next) = self.continuation.take() {
682            self.phase = next;
683        }
684        if matches!(self.phase, RoundPhase::UploadGrant) && self.uploads.is_empty() {
685            self.phase = RoundPhase::Sync;
686        }
687        // A staged body that failed to read locally performs no network I/O,
688        // so it cannot be the round's first network call and must not anchor
689        // the round deadline either.
690        if matches!(self.phase, RoundPhase::UploadGrant)
691            && self
692                .uploads
693                .front()
694                .is_some_and(|upload| upload.bytes.is_err())
695        {
696            let upload = self
697                .uploads
698                .pop_front()
699                .expect("the failed upload is staged");
700            self.completed = Some(ExchangeResult::Upload {
701                id: upload.id,
702                result: Err(upload.bytes.unwrap_err()),
703            });
704            return None;
705        }
706        if matches!(self.phase, RoundPhase::Sync) {
707            self.ensure_encoded();
708        }
709        let needs_network = !matches!(self.phase, RoundPhase::Downloads { .. });
710        // The round's first network call anchors the deadline after the
711        // encode; a continuation reuses the carried anchor instead of
712        // refreshing it.
713        if needs_network && !*scoped {
714            *scoped = true;
715            if let Some(transport) = scope.as_mut() {
716                if let Err(error) = self.scope_round_deadline(&mut **transport) {
717                    if matches!(
718                        self.phase,
719                        RoundPhase::UploadGrant
720                            | RoundPhase::UploadPut { .. }
721                            | RoundPhase::UploadDirect
722                    ) {
723                        let upload = self
724                            .uploads
725                            .pop_front()
726                            .expect("an upload phase owns an upload");
727                        self.completed = Some(ExchangeResult::Upload {
728                            id: upload.id,
729                            result: Err(error),
730                        });
731                    } else {
732                        self.completed = Some(ExchangeResult::Reply {
733                            response: Err(error),
734                            transport_failed: false,
735                            downloads: DownloadResults::default(),
736                        });
737                    }
738                    return None;
739                }
740            }
741        }
742        match &self.phase {
743            RoundPhase::UploadGrant => {
744                let upload = self
745                    .uploads
746                    .front()
747                    .expect("an upload phase owns an upload");
748                let bytes = upload
749                    .bytes
750                    .as_ref()
751                    .expect("a staged body that failed to read has no operation");
752                Some(RoundOperation::UploadGrant {
753                    blob_id: &upload.id,
754                    byte_length: bytes.len() as u64,
755                    media_type: upload.media_type.as_deref(),
756                })
757            }
758            RoundPhase::UploadPut { url, .. } => {
759                let upload = self
760                    .uploads
761                    .front()
762                    .expect("an upload phase owns an upload");
763                let bytes = upload
764                    .bytes
765                    .as_ref()
766                    .expect("a staged body that failed to read has no operation");
767                Some(RoundOperation::UploadPut {
768                    blob_id: &upload.id,
769                    url,
770                    bytes,
771                    media_type: upload.media_type.as_deref(),
772                })
773            }
774            RoundPhase::UploadDirect => {
775                let upload = self
776                    .uploads
777                    .front()
778                    .expect("an upload phase owns an upload");
779                let bytes = upload
780                    .bytes
781                    .as_ref()
782                    .expect("a staged body that failed to read has no operation");
783                Some(RoundOperation::Upload {
784                    blob_id: &upload.id,
785                    bytes,
786                    media_type: upload.media_type.as_deref(),
787                })
788            }
789            RoundPhase::Sync => Some(RoundOperation::Sync {
790                request: self.encoded.as_deref().expect("the request is encoded"),
791                realtime: self.realtime,
792            }),
793            RoundPhase::Downloads { fetches, .. } => Some(RoundOperation::Downloads(fetches)),
794        }
795    }
796}
797
798#[derive(PartialEq)]
799enum DownloadKey {
800    Url(String),
801    Segment(String, String, String),
802}
803
804/// One eligible `SEGMENT_REF` of the response, collected before the batch
805/// fetch so `download_segments` sees the whole page list at once.
806pub(crate) struct PlannedFetch {
807    key: DownloadKey,
808    unit_id: String,
809    table: String,
810    segment_id: String,
811    bytes_total: Option<u64>,
812    rows_total: Option<u64>,
813    /// `None` when the signed URL had already expired at the batch start: the
814    /// fetch is never attempted and its descriptor fails with
815    /// `sync.segment_expired`. Collection stops there, so only the last
816    /// collected fetch can be `None`.
817    fetch: Option<SegmentFetch>,
818}
819
820#[derive(Default)]
821pub(crate) struct DownloadResults {
822    entries: std::collections::VecDeque<(DownloadKey, i64, Result<Vec<u8>, TransportError>)>,
823    pub controls: Vec<String>,
824}
825
826impl DownloadResults {
827    fn take(&mut self, key: DownloadKey) -> Result<Vec<u8>, TransportError> {
828        let position = self
829            .entries
830            .iter()
831            .position(|(candidate, ..)| *candidate == key);
832        position
833            .and_then(|i| self.entries.remove(i))
834            .map(|(_, _, bytes)| bytes)
835            .unwrap_or_else(|| {
836                Err(TransportError::new(
837                    "client.round_download_missing",
838                    "round apply requested an uncaptured segment",
839                ))
840            })
841    }
842}
843
844impl Transport for DownloadResults {
845    fn sync(&mut self, _: &[u8]) -> Result<Vec<u8>, TransportError> {
846        Err(TransportError::new(
847            "client.round_network_on_owner",
848            "network requests must execute outside the client owner",
849        ))
850    }
851    fn realtime_sync(&mut self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
852        self.sync(request)
853    }
854    fn download_segment(
855        &mut self,
856        request: &SegmentRequest,
857        _: &mut dyn FnMut(u64),
858    ) -> Result<Vec<u8>, TransportError> {
859        self.take(DownloadKey::Segment(
860            request.segment_id.clone(),
861            request.table.clone(),
862            request.requested_scopes_json.clone(),
863        ))
864    }
865    fn fetch_url(
866        &mut self,
867        url: &str,
868        _: u64,
869        _: &mut dyn FnMut(u64),
870    ) -> Result<Vec<u8>, TransportError> {
871        self.take(DownloadKey::Url(url.to_owned()))
872    }
873    fn segment_fetch_started_at(&self, url: &str) -> Option<i64> {
874        self.entries
875            .iter()
876            .find_map(|(key, time, _)| (*key == DownloadKey::Url(url.to_owned())).then_some(*time))
877    }
878    fn realtime_connect(&mut self) -> Result<(), TransportError> {
879        Err(TransportError::new(
880            "client.round_network_on_owner",
881            "network connections must execute outside the client owner",
882        ))
883    }
884    fn realtime_send(&mut self, text: &str) -> Result<(), TransportError> {
885        self.controls.push(text.to_owned());
886        Ok(())
887    }
888    fn realtime_close(&mut self) -> Result<(), TransportError> {
889        Ok(())
890    }
891}
892
893#[cfg(test)]
894pub(crate) mod test_support {
895    use super::*;
896
897    /// Drive one exchange through the split API, answering every operation
898    /// with the blocking transport under test.
899    pub(crate) fn drive_round(
900        mut prepared: PreparedSyncRound,
901        transport: &mut dyn Transport,
902    ) -> CompletedSyncRound {
903        while let Some(operation) = prepared.next_operation() {
904            let reply = match operation {
905                RoundOperation::UploadGrant {
906                    blob_id,
907                    byte_length,
908                    media_type,
909                } => RoundReply::UploadGrant(transport.blob_upload_grant(
910                    blob_id,
911                    byte_length,
912                    media_type,
913                )),
914                RoundOperation::UploadPut {
915                    blob_id,
916                    url,
917                    bytes,
918                    media_type,
919                } => RoundReply::Upload(transport.blob_put_url(blob_id, url, bytes, media_type)),
920                RoundOperation::Upload {
921                    blob_id,
922                    bytes,
923                    media_type,
924                } => RoundReply::Upload(transport.blob_upload(blob_id, bytes, media_type)),
925                RoundOperation::Sync { request, realtime } => RoundReply::Sync(if realtime {
926                    transport.realtime_sync(request)
927                } else {
928                    transport.sync(request)
929                }),
930                RoundOperation::Downloads(fetches) => {
931                    RoundReply::Downloads(transport.download_segments(fetches, &mut |_, _| {}))
932                }
933            };
934            prepared
935                .submit(reply)
936                .expect("the driver answers the pending operation");
937        }
938        prepared.finish().expect("the round has no work left")
939    }
940}
941
942#[cfg(test)]
943mod tests {
944    use super::*;
945    use crate::{BlobUploadGrant, SegmentRequest, SyncClient, TransportError};
946
947    /// Every upload call fails with the same typed timeout, modelling a round
948    /// whose deadline was spent before the signed upload. The fallback to the
949    /// direct endpoint must not replace the typed code with a generic one.
950    struct SpentDeadline;
951
952    impl Transport for SpentDeadline {
953        fn sync(&mut self, _: &[u8]) -> Result<Vec<u8>, TransportError> {
954            unreachable!()
955        }
956        fn realtime_sync(&mut self, _: &[u8]) -> Result<Vec<u8>, TransportError> {
957            unreachable!()
958        }
959        fn download_segment(
960            &mut self,
961            _: &SegmentRequest,
962            _: &mut dyn FnMut(u64),
963        ) -> Result<Vec<u8>, TransportError> {
964            unreachable!()
965        }
966        fn blob_upload_grant(
967            &mut self,
968            _: &str,
969            _: u64,
970            _: Option<&str>,
971        ) -> Result<BlobUploadGrant, TransportError> {
972            Ok(BlobUploadGrant::Url {
973                url: "https://storage.example/signed".into(),
974                url_expires_at_ms: None,
975            })
976        }
977        fn blob_put_url(
978            &mut self,
979            _: &str,
980            _: &str,
981            _: &[u8],
982            _: Option<&str>,
983        ) -> Result<(), TransportError> {
984            Err(TransportError::new(
985                "transport.timeout",
986                "signed upload timed out",
987            ))
988        }
989        fn blob_upload(
990            &mut self,
991            _: &str,
992            _: &[u8],
993            _: Option<&str>,
994        ) -> Result<(), TransportError> {
995            Err(TransportError::new(
996                "transport.timeout",
997                "direct upload timed out",
998            ))
999        }
1000        fn realtime_connect(&mut self) -> Result<(), TransportError> {
1001            Ok(())
1002        }
1003        fn realtime_send(&mut self, _: &str) -> Result<(), TransportError> {
1004            Ok(())
1005        }
1006        fn realtime_close(&mut self) -> Result<(), TransportError> {
1007            Ok(())
1008        }
1009    }
1010
1011    #[test]
1012    fn a_failed_presigned_put_falls_back_to_the_direct_endpoint() {
1013        let schema = serde_json::json!({"version":1,"tables":[{"name":"attachments","primaryKey":"id","columns":[
1014            {"name":"id","type":"string","nullable":false},
1015            {"name":"file","type":"blob_ref","nullable":true}],"scopes":[]}]});
1016        let mut client =
1017            SyncClient::new("spent-deadline".into(), &schema, Default::default()).unwrap();
1018        client
1019            .set_meta(crate::client::LOG_EPOCH_KEY, "epoch")
1020            .unwrap();
1021        client
1022            .upload_blob(b"body", Some("text/plain".into()), None)
1023            .unwrap();
1024        let mut prepared = client.prepare_sync_round(false).unwrap();
1025        let mut transport = SpentDeadline;
1026        let mut steps = Vec::new();
1027        while let Some(operation) = prepared.next_operation() {
1028            let reply = match operation {
1029                RoundOperation::UploadGrant {
1030                    blob_id,
1031                    byte_length,
1032                    media_type,
1033                } => {
1034                    steps.push("grant");
1035                    RoundReply::UploadGrant(transport.blob_upload_grant(
1036                        blob_id,
1037                        byte_length,
1038                        media_type,
1039                    ))
1040                }
1041                RoundOperation::UploadPut {
1042                    blob_id,
1043                    url,
1044                    bytes,
1045                    media_type,
1046                } => {
1047                    steps.push("put");
1048                    RoundReply::Upload(transport.blob_put_url(blob_id, url, bytes, media_type))
1049                }
1050                RoundOperation::Upload {
1051                    blob_id,
1052                    bytes,
1053                    media_type,
1054                } => {
1055                    steps.push("direct");
1056                    RoundReply::Upload(transport.blob_upload(blob_id, bytes, media_type))
1057                }
1058                _ => panic!("only upload operations precede the round message"),
1059            };
1060            prepared.submit(reply).unwrap();
1061        }
1062        assert_eq!(steps, ["grant", "put", "direct"]);
1063        let outcome = match client.apply_sync_round(prepared.finish().unwrap()) {
1064            AppliedSyncRound::Complete { outcome, .. } => outcome,
1065            AppliedSyncRound::Continue(_) => panic!("an upload failure does not continue"),
1066        };
1067        match outcome {
1068            SyncOutcome::Failed { error_code, .. } => {
1069                assert_eq!(error_code, "transport.timeout")
1070            }
1071            other => panic!("expected a typed upload failure, got {other:?}"),
1072        }
1073    }
1074
1075    /// Answers one response that references one segment and serves a body
1076    /// longer than the descriptor declares.
1077    struct OversizedSegment {
1078        unit_id: String,
1079        segment_id: String,
1080        body: Vec<u8>,
1081    }
1082
1083    impl Transport for OversizedSegment {
1084        fn sync(&mut self, _: &[u8]) -> Result<Vec<u8>, TransportError> {
1085            Ok(encode_message(&Message {
1086                wire_version: ssp2::decode::WIRE_VERSION,
1087                msg_kind: MsgKind::Response,
1088                frames: vec![
1089                    Frame::RespHeader {
1090                        required_schema_version: None,
1091                        latest_schema_version: None,
1092                        log_epoch: "epoch".into(),
1093                        reset_required: false,
1094                    },
1095                    Frame::SubStart {
1096                        id: self.unit_id.clone(),
1097                        status: SubStatus::Active,
1098                        reason_code: String::new(),
1099                        bootstrap: true,
1100                        fenced: Vec::new(),
1101                    },
1102                    Frame::SegmentRef {
1103                        segment_id: self.segment_id.clone(),
1104                        media_type: MediaType::Rows,
1105                        table: "tasks".into(),
1106                        byte_length: 4,
1107                        row_count: 1,
1108                        as_of_commit_seq: 1,
1109                        scope_digest: "digest".into(),
1110                        row_cursor: None,
1111                        next_row_cursor: None,
1112                        url: None,
1113                        url_expires_at_ms: None,
1114                    },
1115                    Frame::SubEnd {
1116                        next_cursor: 1,
1117                        bootstrap_state: None,
1118                    },
1119                ],
1120            }))
1121        }
1122        fn realtime_sync(&mut self, request: &[u8]) -> Result<Vec<u8>, TransportError> {
1123            self.sync(request)
1124        }
1125        fn download_segment(
1126            &mut self,
1127            _: &SegmentRequest,
1128            _: &mut dyn FnMut(u64),
1129        ) -> Result<Vec<u8>, TransportError> {
1130            Ok(self.body.clone())
1131        }
1132        fn realtime_connect(&mut self) -> Result<(), TransportError> {
1133            Ok(())
1134        }
1135        fn realtime_send(&mut self, _: &str) -> Result<(), TransportError> {
1136            Ok(())
1137        }
1138        fn realtime_close(&mut self) -> Result<(), TransportError> {
1139            Ok(())
1140        }
1141    }
1142
1143    #[test]
1144    fn a_segment_body_longer_than_its_byte_length_fails_before_the_content_check() {
1145        use sha2::Digest;
1146        let schema = serde_json::json!({"version":1,"tables":[{"name":"tasks","primaryKey":"id","columns":[
1147            {"name":"id","type":"string","nullable":false},
1148            {"name":"project_id","type":"string","nullable":false}],
1149            "scopes":[{"pattern":"project:{project_id}"}]}]});
1150        let mut client = SyncClient::new("oversized".into(), &schema, Default::default()).unwrap();
1151        client
1152            .set_meta(crate::client::LOG_EPOCH_KEY, "epoch")
1153            .unwrap();
1154        let unit_id = client
1155            .subscribe(crate::UnitScopes::from([(
1156                "project_id".into(),
1157                "p1".into(),
1158            )]))
1159            .unwrap();
1160        // The body hashes to its content address, so only the §5.4 cap can
1161        // refuse it.
1162        let body = b"twelve bytes".to_vec();
1163        let segment_id = format!(
1164            "sha256:{}",
1165            sha2::Sha256::digest(&body)
1166                .iter()
1167                .map(|byte| format!("{byte:02x}"))
1168                .collect::<String>()
1169        );
1170        let mut transport = OversizedSegment {
1171            unit_id,
1172            segment_id,
1173            body,
1174        };
1175        match client.sync(&mut transport) {
1176            SyncOutcome::Failed {
1177                error_code,
1178                message,
1179                ..
1180            } => {
1181                assert_eq!(error_code, "sync.invalid_request");
1182                assert_eq!(message, "segment exceeds its byteLength");
1183            }
1184            other => panic!("expected the byteLength cap to fail the round, got {other:?}"),
1185        }
1186    }
1187
1188    /// Records each single fetch the default batch runs and fails the second.
1189    #[derive(Default)]
1190    struct CountingFetches {
1191        calls: Vec<String>,
1192    }
1193
1194    impl Transport for CountingFetches {
1195        fn sync(&mut self, _: &[u8]) -> Result<Vec<u8>, TransportError> {
1196            unreachable!()
1197        }
1198        fn realtime_sync(&mut self, _: &[u8]) -> Result<Vec<u8>, TransportError> {
1199            unreachable!()
1200        }
1201        fn download_segment(
1202            &mut self,
1203            request: &SegmentRequest,
1204            on_progress: &mut dyn FnMut(u64),
1205        ) -> Result<Vec<u8>, TransportError> {
1206            self.calls.push(request.segment_id.clone());
1207            on_progress(4);
1208            if request.segment_id == "sha256:b" {
1209                Err(TransportError::new(
1210                    "transport.timeout",
1211                    "second fetch failed",
1212                ))
1213            } else {
1214                Ok(request.segment_id.clone().into_bytes())
1215            }
1216        }
1217        fn realtime_connect(&mut self) -> Result<(), TransportError> {
1218            Ok(())
1219        }
1220        fn realtime_send(&mut self, _: &str) -> Result<(), TransportError> {
1221            Ok(())
1222        }
1223        fn realtime_close(&mut self) -> Result<(), TransportError> {
1224            Ok(())
1225        }
1226    }
1227
1228    #[test]
1229    fn the_default_batch_runs_the_single_fetches_in_order_and_stops_at_the_first_error() {
1230        let mut transport = CountingFetches::default();
1231        let fetches: Vec<SegmentFetch> = ["a", "b", "c"]
1232            .into_iter()
1233            .map(|id| {
1234                SegmentFetch::Direct(SegmentRequest {
1235                    segment_id: format!("sha256:{id}"),
1236                    table: "tasks".to_owned(),
1237                    requested_scopes_json: "{}".to_owned(),
1238                    byte_length: 4,
1239                })
1240            })
1241            .collect();
1242        let mut reported = Vec::new();
1243        let results = transport.download_segments(&fetches, &mut |index, bytes| {
1244            reported.push((index, bytes));
1245        });
1246        assert_eq!(
1247            transport.calls,
1248            vec!["sha256:a", "sha256:b"],
1249            "the third fetch was never attempted"
1250        );
1251        assert_eq!(results.len(), 2, "one result per attempted fetch");
1252        assert_eq!(results[0].as_ref().unwrap(), b"sha256:a");
1253        assert_eq!(results[1].as_ref().unwrap_err().code, "transport.timeout");
1254        assert_eq!(reported, vec![(0, 4), (1, 4)]);
1255    }
1256}