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