Skip to main content

syncular_client/
round.rs

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