Skip to main content

syncular_client/
round.rs

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