1use std::collections::BTreeMap;
7
8use serde::{Deserialize, Serialize};
9use serde_json::{Map, Value};
10
11use crate::previous_version::PreviousVersionContextConfig;
12pub type QueryValue = Value;
14pub type QueryRow = Map<String, QueryValue>;
16
17#[derive(Debug, Clone, PartialEq, Eq)]
19pub struct FetchedBlob {
20 pub blob_id: String,
21 pub byte_length: i64,
22 pub bytes: Vec<u8>,
23 pub media_type: Option<String>,
24}
25
26#[derive(Debug, Clone, Copy, PartialEq, Eq)]
27pub enum TimeBucketUnit {
28 Month,
29}
30
31const MAX_TIME_BUCKET_MS: i64 = 253_402_300_799_999;
32
33fn utc_year_month(timestamp_ms: i64) -> Result<(i64, i64), String> {
34 if !(0..=MAX_TIME_BUCKET_MS).contains(×tamp_ms) {
35 return Err(
36 "sync.invalid_request: time bucket timestamps must fall from 1970 through 9999"
37 .to_owned(),
38 );
39 }
40 let z = timestamp_ms / 86_400_000 + 719_468;
41 let era = z.div_euclid(146_097);
42 let day_of_era = z - era * 146_097;
43 let year_of_era =
44 (day_of_era - day_of_era / 1_460 + day_of_era / 36_524 - day_of_era / 146_096) / 365;
45 let mut year = year_of_era + era * 400;
46 let day_of_year = day_of_era - (365 * year_of_era + year_of_era / 4 - year_of_era / 100);
47 let month_prime = (5 * day_of_year + 2) / 153;
48 let month = month_prime + if month_prime < 10 { 3 } else { -9 };
49 if month <= 2 {
50 year += 1;
51 }
52 Ok((year, month))
53}
54
55pub fn creation_time_bucket(created_at_ms: i64, unit: TimeBucketUnit) -> Result<String, String> {
57 match unit {
58 TimeBucketUnit::Month => {
59 let (year, month) = utc_year_month(created_at_ms)?;
60 Ok(format!("{year:04}-{month:02}"))
61 }
62 }
63}
64
65pub fn last(count: usize, unit: TimeBucketUnit, now_ms: i64) -> Result<Vec<String>, String> {
67 if !(1..=1_200).contains(&count) {
68 return Err(
69 "sync.invalid_request: time bucket count must be from 1 through 1200".to_owned(),
70 );
71 }
72 match unit {
73 TimeBucketUnit::Month => {
74 let (year, month) = utc_year_month(now_ms)?;
75 let current = year * 12 + month - 1;
76 if current - (count as i64 - 1) < 1970 * 12 {
77 return Err(
78 "sync.invalid_request: every returned UTC month must fall from 1970 through 9999"
79 .to_owned(),
80 );
81 }
82 Ok((0..count)
83 .rev()
84 .map(|offset| {
85 let value = current - offset as i64;
86 format!(
87 "{:04}-{:02}",
88 value.div_euclid(12),
89 value.rem_euclid(12) + 1
90 )
91 })
92 .collect())
93 }
94 }
95}
96
97pub type UnitScopes = BTreeMap<String, String>;
99
100#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
102#[serde(rename_all = "lowercase")]
103pub enum UnitStatus {
104 Active,
105 Revoked,
106 Failed,
107}
108
109impl UnitStatus {
110 pub fn name(self) -> &'static str {
111 match self {
112 UnitStatus::Active => "active",
113 UnitStatus::Revoked => "revoked",
114 UnitStatus::Failed => "failed",
115 }
116 }
117}
118
119#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
122pub struct EchoRecord {
123 pub table: String,
124 pub status: String,
126 pub scopes: BTreeMap<String, Vec<String>>,
127}
128
129#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
133pub struct UnitRestriction {
134 pub cursor: i64,
135 pub tables: Vec<String>,
136}
137
138#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
140#[serde(rename_all = "camelCase")]
141pub struct UnitRecord {
142 pub id: String,
144 pub scopes: UnitScopes,
145 pub explicit: bool,
148 pub status: UnitStatus,
149 #[serde(skip_serializing_if = "Option::is_none")]
151 pub reason_code: Option<String>,
152 #[serde(skip_serializing_if = "Option::is_none")]
155 pub cursor: Option<i64>,
156 #[serde(skip_serializing_if = "Option::is_none")]
158 pub bootstrap_state: Option<String>,
159 pub seeded: Vec<String>,
161 #[serde(skip_serializing_if = "Option::is_none")]
163 pub echo: Option<Vec<EchoRecord>>,
164 #[serde(skip_serializing_if = "Option::is_none")]
166 pub restriction: Option<UnitRestriction>,
167}
168
169impl UnitRecord {
170 pub fn bootstrapping(&self) -> bool {
172 self.cursor
173 .is_some_and(|cursor| cursor < 0 || self.bootstrap_state.is_some())
174 }
175}
176
177#[derive(Debug, Clone, Default)]
181pub struct WindowBase {
182 pub variable: String,
183 pub fixed_scopes: UnitScopes,
185}
186
187#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq, Eq)]
194#[serde(rename_all = "camelCase")]
195pub struct WindowState {
196 pub units: Vec<String>,
198 pub pending: Vec<String>,
200 #[serde(default)]
203 pub revoked: Vec<String>,
204}
205
206#[cfg(test)]
207mod time_bucket_tests {
208 use super::{creation_time_bucket, last, TimeBucketUnit};
209
210 #[test]
211 fn utc_month_buckets_cross_year_boundaries() {
212 let now = 1_770_508_800_000; assert_eq!(
214 creation_time_bucket(now, TimeBucketUnit::Month).unwrap(),
215 "2026-02"
216 );
217 assert_eq!(
218 last(3, TimeBucketUnit::Month, now).unwrap(),
219 vec!["2025-12", "2026-01", "2026-02"]
220 );
221 }
222
223 #[test]
224 fn utc_month_buckets_reject_unbounded_input() {
225 assert!(last(0, TimeBucketUnit::Month, 0).is_err());
226 assert!(last(1_201, TimeBucketUnit::Month, 0).is_err());
227 assert!(last(2, TimeBucketUnit::Month, 0).is_err());
228 assert!(creation_time_bucket(-1, TimeBucketUnit::Month).is_err());
229 }
230}
231
232#[derive(Debug, Clone, Serialize)]
233#[serde(rename_all = "camelCase")]
234pub struct TableChange {
235 pub table: String,
236 #[serde(skip_serializing_if = "Option::is_none")]
237 pub scope_keys: Option<Vec<String>>,
238}
239
240#[derive(Debug, Clone, Serialize)]
241#[serde(rename_all = "camelCase")]
242pub struct WindowChange {
243 pub base_key: String,
244 pub units: Vec<String>,
246}
247
248#[derive(Debug, Clone, Serialize)]
249#[serde(rename_all = "camelCase")]
250pub struct SyncStatusSnapshot {
251 pub current_schema_version: i32,
252 pub outbox: usize,
253 pub upgrading: bool,
254 pub upgrade_kept_tables: bool,
256 #[serde(skip_serializing_if = "Option::is_none")]
257 pub lease_state: Option<LeaseState>,
258 #[serde(skip_serializing_if = "Option::is_none")]
259 pub schema_floor: Option<SchemaFloor>,
260 pub sync_needed: bool,
261 pub previous_version_context: PreviousVersionStatus,
264 pub security_lifecycle: &'static str,
267}
268
269#[derive(Debug, Clone, Copy, Default, Serialize, PartialEq, Eq)]
271#[serde(rename_all = "camelCase")]
272pub struct PreviousVersionStatus {
273 pub present: bool,
274 #[serde(skip_serializing_if = "Option::is_none")]
275 pub created_at_ms: Option<i64>,
276}
277
278pub const CLIENT_DIAGNOSTICS_VERSION: u8 = 2;
279pub const MAX_DIAGNOSTIC_QUERY_FAILURES: usize = 256;
280
281pub const REALTIME_UNAVAILABLE_CODE: &str = "sync.realtime_unavailable";
284pub const REALTIME_LOST_CODE: &str = "client.realtime_lost";
287pub const LOCAL_AUTHORITY_UNCONFIGURED_CODE: &str = "client.local_authority_unconfigured";
291
292#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
293#[serde(rename_all = "camelCase")]
294pub struct ClientDiagnosticsHost {
295 pub kind: String,
296 pub role: String,
297 pub connectivity: String,
298 pub realtime: RealtimeState,
299 pub realtime_policy: RealtimePolicy,
300 #[serde(skip_serializing_if = "Option::is_none")]
301 pub realtime_reason_code: Option<String>,
302 #[serde(skip_serializing_if = "Option::is_none")]
303 pub realtime_retry_delay_ms: Option<u64>,
304}
305
306#[derive(Debug, Clone, Serialize, Default, PartialEq, Eq)]
308#[serde(rename_all = "camelCase")]
309pub struct DiagnosticUnits {
310 pub bootstrapping: usize,
311 pub complete: usize,
312 pub reset: usize,
313 pub revoked: usize,
314 pub failed: usize,
315 pub reason_codes: Vec<String>,
317}
318
319#[derive(Debug, Clone, Serialize, Default, PartialEq, Eq)]
320#[serde(rename_all = "camelCase")]
321pub struct DiagnosticRoundCounters {
322 pub pushed: u32,
323 pub applied: usize,
324 pub rejected: usize,
325 pub retryable: usize,
326 pub conflicts: u32,
327 pub commits_applied: u32,
328 pub segment_rows_applied: u32,
329 pub bootstrapping: usize,
330 pub resets: usize,
331 pub revoked: usize,
332 pub failed: usize,
333 pub deferred_commits: usize,
334}
335
336#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
338#[serde(rename_all = "snake_case")]
339pub enum TransportCauseKind {
340 Network,
341 Connect,
342 Tls,
343 Io,
344 Request,
345 Protocol,
346 Timeout,
347 RoundDeadline,
348 Aborted,
349 Body,
350 Status,
351 Redirect,
352 Unknown,
353}
354
355#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
356#[serde(rename_all = "camelCase")]
357pub struct DiagnosticLastRound {
358 pub epoch: String,
360 pub attempt: u64,
361 pub status: String,
362 pub started_at_ms: i64,
363 pub completed_at_ms: i64,
364 pub duration_ms: i64,
365 #[serde(skip_serializing_if = "Option::is_none")]
366 pub counters: Option<DiagnosticRoundCounters>,
367 #[serde(skip_serializing_if = "Option::is_none")]
368 pub error_code: Option<String>,
369 #[serde(skip_serializing_if = "Option::is_none")]
370 pub cause_kind: Option<TransportCauseKind>,
371 #[serde(skip_serializing_if = "Option::is_none")]
372 pub http_status: Option<u16>,
373}
374
375#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
376#[serde(rename_all = "camelCase")]
377pub struct DiagnosticLastChange {
378 pub revision: String,
379 pub recorded_at_ms: i64,
380 pub tables: Vec<String>,
381 pub windows: Vec<String>,
382 pub domains_truncated: bool,
383 pub status_changed: bool,
384 pub conflicts_changed: bool,
385 pub rejections_changed: bool,
386 pub outcomes_changed: bool,
387}
388
389#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
390#[serde(rename_all = "camelCase")]
391pub struct ClientDiagnosticsStorage {
392 pub status: String,
393 #[serde(skip_serializing_if = "Option::is_none")]
394 pub database_bytes_approx: Option<i64>,
395 #[serde(skip_serializing_if = "Option::is_none")]
396 pub pending_outbox_bytes_approx: Option<i64>,
397 #[serde(skip_serializing_if = "Option::is_none")]
398 pub retained_outcome_bytes_approx: Option<i64>,
399 #[serde(skip_serializing_if = "Option::is_none")]
400 pub retained_outcome_entries: Option<i64>,
401 #[serde(skip_serializing_if = "Option::is_none")]
402 pub blob_cache_bytes_approx: Option<i64>,
403 #[serde(skip_serializing_if = "Option::is_none")]
404 pub pressure_reason_code: Option<String>,
405}
406
407#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
409#[serde(rename_all = "camelCase")]
410pub struct DiagnosticQueryFailure {
411 pub id: String,
412 pub tables: Vec<String>,
414 pub code: String,
416 #[serde(skip_serializing_if = "Option::is_none")]
418 pub sqlite_code: Option<i32>,
419 pub at_ms: i64,
421}
422
423#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
424#[serde(rename_all = "camelCase")]
425pub struct ClientDiagnosticsSnapshot {
426 pub version: u8,
427 pub captured_at_ms: i64,
428 pub host: ClientDiagnosticsHost,
429 pub security_lifecycle: String,
430 pub schema: ClientDiagnosticsSchema,
431 pub replica: ClientDiagnosticsReplica,
432 pub lease: ClientDiagnosticsLease,
433 pub units: DiagnosticUnits,
434 pub active_units: usize,
437 pub replica_cursor: i64,
439 #[serde(skip_serializing_if = "Option::is_none")]
440 pub last_round: Option<DiagnosticLastRound>,
441 #[serde(skip_serializing_if = "Option::is_none")]
442 pub last_change: Option<DiagnosticLastChange>,
443 pub storage: ClientDiagnosticsStorage,
444 pub query_failures: Vec<DiagnosticQueryFailure>,
445}
446
447#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
448#[serde(rename_all = "camelCase")]
449pub struct ClientDiagnosticsSchema {
450 pub current_version: i32,
451 pub upgrading: bool,
452 #[serde(skip_serializing_if = "Option::is_none")]
453 pub required_version: Option<i32>,
454 #[serde(skip_serializing_if = "Option::is_none")]
455 pub latest_version: Option<i32>,
456}
457
458#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
459#[serde(rename_all = "camelCase")]
460pub struct ClientDiagnosticsReplica {
461 pub local_revision: String,
462 pub sync_needed: bool,
463 pub pending_outbox: usize,
464}
465
466#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize)]
468#[serde(rename_all = "lowercase")]
469pub enum RealtimePolicy {
470 Required,
471 #[default]
472 Optional,
473 Off,
474}
475
476impl RealtimePolicy {
477 #[must_use]
478 pub fn as_str(self) -> &'static str {
479 match self {
480 RealtimePolicy::Required => "required",
481 RealtimePolicy::Optional => "optional",
482 RealtimePolicy::Off => "off",
483 }
484 }
485}
486
487#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize)]
492#[serde(rename_all = "lowercase")]
493pub enum RealtimeState {
494 Connected,
495 Connecting,
496 #[default]
497 Disconnected,
498 Lost,
499 Refused,
500 Disabled,
501}
502
503#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
504#[serde(rename_all = "camelCase")]
505pub struct ClientDiagnosticsLease {
506 pub state: String,
507 #[serde(skip_serializing_if = "Option::is_none")]
508 pub expires_at_ms: Option<i64>,
509 #[serde(skip_serializing_if = "Option::is_none")]
510 pub error_code: Option<String>,
511}
512
513#[derive(Debug, Clone, Serialize)]
515#[serde(rename_all = "camelCase")]
516pub struct AppliedServerCommit {
517 pub table: String,
518 pub commit_seq: i64,
519 pub source: AppliedServerCommitSource,
520}
521
522#[derive(Debug, Clone, Copy, Serialize)]
523#[serde(rename_all = "camelCase")]
524pub enum AppliedServerCommitSource {
525 Delta,
526 Pull,
527}
528
529#[derive(Debug, Clone, Serialize)]
530#[serde(rename_all = "camelCase")]
531pub struct ClientChangeBatch {
532 pub revision: String,
533 pub tables: Vec<TableChange>,
534 pub windows: Vec<WindowChange>,
535 #[serde(skip_serializing_if = "Option::is_none")]
536 pub status: Option<SyncStatusSnapshot>,
537 pub conflicts_changed: bool,
538 pub rejections_changed: bool,
539 pub outcomes_changed: bool,
540 #[serde(skip_serializing_if = "Vec::is_empty")]
541 pub applied_commits: Vec<AppliedServerCommit>,
542}
543
544#[derive(Debug, Clone, Serialize)]
545#[serde(tag = "kind", rename_all = "camelCase")]
546pub enum SyncIntent {
547 None,
548 Interactive,
549 Background {
550 #[serde(rename = "delayMs")]
551 delay_ms: u64,
552 },
553}
554
555#[derive(Debug, Clone, Serialize)]
556pub struct CommandEffects {
557 pub sync: SyncIntent,
558}
559
560impl CommandEffects {
561 #[must_use]
562 pub fn none() -> Self {
563 Self {
564 sync: SyncIntent::None,
565 }
566 }
567
568 #[must_use]
569 pub fn interactive() -> Self {
570 Self {
571 sync: SyncIntent::Interactive,
572 }
573 }
574}
575
576#[derive(Debug, Clone)]
577pub struct WindowCoverage {
578 pub base: WindowBase,
579 pub units: Vec<String>,
580}
581
582#[derive(Debug, Clone, Serialize)]
583#[serde(rename_all = "camelCase")]
584pub struct WindowUnitRef {
585 pub base_key: String,
586 pub unit: String,
587}
588
589#[derive(Debug, Clone, Serialize)]
590#[serde(rename_all = "camelCase")]
591pub struct CoverageSnapshot {
592 pub complete: bool,
593 pub pending: Vec<WindowUnitRef>,
594 pub missing: Vec<WindowUnitRef>,
595 pub revoked: Vec<WindowUnitRef>,
597}
598
599#[derive(Debug, Clone, Copy)]
602pub struct QueryOwner<'a> {
603 pub id: &'a str,
604 pub tables: &'a [&'a str],
605}
606
607#[derive(Debug, Clone, PartialEq, Eq)]
612pub struct QueryReadFailure {
613 pub code: Option<&'static str>,
614 pub sqlite_code: Option<i32>,
615 pub sqlite_message: Option<String>,
616 pub rollback_failure: Option<Box<QueryReadFailure>>,
617 pub message: String,
618}
619
620impl std::fmt::Display for QueryReadFailure {
621 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
622 match self.code {
623 Some(code) => write!(f, "{code}: {}", self.message),
624 None => f.write_str(&self.message),
625 }
626 }
627}
628
629impl From<String> for QueryReadFailure {
630 fn from(message: String) -> Self {
631 Self {
632 code: None,
633 sqlite_code: None,
634 sqlite_message: None,
635 rollback_failure: None,
636 message,
637 }
638 }
639}
640
641impl From<rusqlite::Error> for QueryReadFailure {
642 fn from(error: rusqlite::Error) -> Self {
644 let sqlite_code = match &error {
645 rusqlite::Error::SqliteFailure(failure, _) => Some(failure.extended_code),
646 _ => None,
647 };
648 match sqlite_code.map(|code| code & 0xff) {
649 Some(11 | 26) => Self {
650 code: Some("client.storage_corrupt"),
651 sqlite_code,
652 sqlite_message: Some(error.to_string()),
653 rollback_failure: None,
654 message: "local SQLite storage is corrupt".to_owned(),
655 },
656 Some(13) => Self {
657 code: Some("client.storage_full"),
658 sqlite_code,
659 sqlite_message: Some(error.to_string()),
660 rollback_failure: None,
661 message: "local SQLite storage is full".to_owned(),
662 },
663 Some(10) => Self {
664 code: Some("client.storage_io"),
665 sqlite_code,
666 sqlite_message: Some(error.to_string()),
667 rollback_failure: None,
668 message: "local SQLite storage I/O failed".to_owned(),
669 },
670 Some(5 | 6) => Self {
674 code: Some("client.storage_busy"),
675 sqlite_code,
676 sqlite_message: Some(error.to_string()),
677 rollback_failure: None,
678 message: "local SQLite storage is busy".to_owned(),
679 },
680 _ => Self {
681 code: None,
682 sqlite_code,
683 sqlite_message: Some(error.to_string()),
684 rollback_failure: None,
685 message: error.to_string(),
686 },
687 }
688 }
689}
690
691impl QueryReadFailure {
692 pub fn retryable(&self) -> bool {
695 self.code == Some("client.storage_busy")
696 }
697
698 pub fn details(&self) -> Option<Value> {
699 self.sqlite_code.map(|code| {
700 let mut details =
701 serde_json::json!({ "sqliteCode": code, "sqliteMessage": self.sqlite_message });
702 if let Some(rollback) = &self.rollback_failure {
703 details["rollbackFailure"] = serde_json::json!({
704 "sqliteCode": rollback.sqlite_code, "message": rollback.sqlite_message
705 });
706 }
707 details
708 })
709 }
710}
711
712#[derive(Debug, Clone, PartialEq, Eq)]
719pub struct ClientError {
720 pub code: String,
721 pub message: String,
722 pub details: Option<Value>,
723 pub retryable: bool,
724}
725
726const DEFAULT_CLIENT_ERROR_CODE: &str = "client.failed";
728
729const GENERIC_AUTHORING_MESSAGE: &str = "the local authoring operation failed";
731
732fn static_authoring_message(code: &str) -> Option<&'static str> {
735 match code {
736 "sync.unknown_table" => Some("the commit targets an unknown table"),
737 "sync.invalid_request" => Some("the authoring request is invalid"),
738 "sync.row_missing" => Some("a sparse patch requires a local row"),
739 "sync.constraint_violation" => Some("local write violates a unique constraint"),
740 DEFAULT_CLIENT_ERROR_CODE => Some(GENERIC_AUTHORING_MESSAGE),
741 _ => None,
742 }
743}
744
745fn is_client_code(candidate: &str) -> bool {
746 candidate.starts_with("client.") || candidate.starts_with("sync.")
747}
748
749impl std::fmt::Display for ClientError {
750 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
751 write!(f, "{}: {}", self.code, self.message)
752 }
753}
754
755impl std::error::Error for ClientError {}
756
757impl From<QueryReadFailure> for ClientError {
758 fn from(failure: QueryReadFailure) -> Self {
759 match failure.code {
760 Some(code) => {
762 let details = failure.details();
763 let retryable = failure.retryable();
764 Self {
765 code: code.to_owned(),
766 message: failure.message,
767 details,
768 retryable,
769 }
770 }
771 None => {
772 let mut details = failure.details().unwrap_or_else(|| serde_json::json!({}));
773 if let Some(object) = details.as_object_mut() {
774 object.insert("legacyCause".to_owned(), Value::String(failure.message));
775 }
776 Self {
777 code: DEFAULT_CLIENT_ERROR_CODE.to_owned(),
778 message: GENERIC_AUTHORING_MESSAGE.to_owned(),
779 details: Some(details),
780 retryable: false,
781 }
782 }
783 }
784 }
785}
786
787impl From<String> for ClientError {
788 fn from(message: String) -> Self {
793 if !message.contains(": ") && is_client_code(&message) {
795 return Self {
796 code: message.clone(),
797 message: static_authoring_message(&message)
798 .unwrap_or(GENERIC_AUTHORING_MESSAGE)
799 .to_owned(),
800 details: None,
801 retryable: false,
802 };
803 }
804 let (code, rest) = match message.split_once(": ") {
805 Some((code, rest)) if is_client_code(code) => (code, Some(rest)),
806 _ => (DEFAULT_CLIENT_ERROR_CODE, None),
807 };
808 match static_authoring_message(code) {
809 Some(fixed) => Self {
810 code: code.to_owned(),
811 message: fixed.to_owned(),
812 details: (rest != Some(fixed))
813 .then(|| serde_json::json!({ "legacyCause": message })),
814 retryable: false,
815 },
816 None => Self {
817 code: code.to_owned(),
818 message: GENERIC_AUTHORING_MESSAGE.to_owned(),
819 details: Some(serde_json::json!({ "legacyCause": message })),
820 retryable: false,
821 },
822 }
823 }
824}
825
826#[derive(Debug, Clone, Serialize)]
827#[serde(rename_all = "camelCase")]
828pub struct QuerySnapshot {
829 pub revision: String,
830 pub rows: Vec<QueryRow>,
831 pub coverage: CoverageSnapshot,
832}
833
834impl WindowState {
835 #[must_use]
837 pub fn complete(&self, unit: &str) -> bool {
838 self.units.iter().any(|u| u == unit) && !self.pending.iter().any(|u| u == unit)
839 }
840}
841
842#[derive(Debug, Clone)]
844pub enum Mutation {
845 Patch {
846 table: String,
847 values: Map<String, Value>,
848 base_version: Option<i64>,
849 },
850 Upsert {
851 table: String,
852 values: Map<String, Value>,
853 base_version: Option<i64>,
854 },
855 Delete {
856 table: String,
857 row_id: String,
858 base_version: Option<i64>,
859 },
860}
861
862#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq, Eq)]
863#[serde(rename_all = "camelCase")]
864pub struct SchemaFloor {
865 #[serde(skip_serializing_if = "Option::is_none")]
866 pub required_schema_version: Option<i32>,
867 #[serde(skip_serializing_if = "Option::is_none")]
868 pub latest_schema_version: Option<i32>,
869}
870
871#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq, Eq)]
875#[serde(rename_all = "camelCase")]
876pub struct LeaseState {
877 #[serde(skip_serializing_if = "Option::is_none")]
878 pub lease_id: Option<String>,
879 #[serde(skip_serializing_if = "Option::is_none")]
880 pub expires_at_ms: Option<i64>,
881 #[serde(skip_serializing_if = "Option::is_none")]
882 pub error_code: Option<String>,
883}
884
885#[derive(Debug, Clone, Serialize)]
887#[serde(rename_all = "camelCase")]
888pub struct PresencePeer {
889 pub actor_id: String,
890 pub client_id: String,
891 pub doc: serde_json::Value,
892}
893
894#[derive(Debug, Clone, Serialize, Default)]
895#[serde(rename_all = "camelCase")]
896pub struct SyncReport {
897 pub pushed: u32,
898 pub applied: Vec<String>,
899 pub rejected: Vec<String>,
900 pub retryable: Vec<String>,
901 pub conflicts: u32,
902 pub commits_applied: u32,
903 pub segment_rows_applied: u32,
904 pub bootstrapping: Vec<String>,
905 pub resets: Vec<String>,
906 pub revoked: Vec<String>,
907 pub failed: Vec<String>,
908 pub deferred_commits: usize,
909 #[serde(skip_serializing_if = "Option::is_none")]
910 pub schema_floor: Option<SchemaFloor>,
911}
912
913impl SyncReport {
914 pub fn merge(&mut self, report: &Self) {
919 self.pushed += report.pushed;
920 self.applied.extend(report.applied.iter().cloned());
921 self.rejected.extend(report.rejected.iter().cloned());
922 self.retryable.extend(report.retryable.iter().cloned());
923 self.conflicts += report.conflicts;
924 self.commits_applied += report.commits_applied;
925 self.segment_rows_applied += report.segment_rows_applied;
926 self.bootstrapping = report.bootstrapping.clone();
927 self.resets.extend(report.resets.iter().cloned());
928 self.revoked.extend(report.revoked.iter().cloned());
929 self.failed.extend(report.failed.iter().cloned());
930 self.deferred_commits = report.deferred_commits;
931 self.schema_floor = report.schema_floor.clone();
932 }
933}
934
935#[derive(Debug, Clone)]
938pub enum SyncOutcome {
939 Ok(SyncReport),
940 Failed {
941 error_code: String,
942 message: String,
943 details: Option<Value>,
944 recommended_action: Option<String>,
948 },
949 RealtimeUnavailable {
954 state: RealtimeState,
955 reason_code: Option<String>,
956 retry_delay_ms: u64,
957 },
958 BudgetExhausted(SyncReport),
962}
963
964impl SyncOutcome {
965 pub fn to_json(&self) -> Value {
966 match self {
967 SyncOutcome::Ok(report) => {
968 let mut map = Map::new();
969 map.insert("ok".to_owned(), Value::Bool(true));
970 map.insert(
971 "report".to_owned(),
972 serde_json::to_value(report).expect("report serializes"),
973 );
974 Value::Object(map)
975 }
976 SyncOutcome::Failed {
977 error_code,
978 message,
979 details,
980 recommended_action,
981 } => {
982 let mut map = Map::new();
983 map.insert("ok".to_owned(), Value::Bool(false));
984 map.insert("errorCode".to_owned(), Value::from(error_code.clone()));
985 map.insert("message".to_owned(), Value::from(message.clone()));
986 if let Some(details) = details {
987 map.insert("details".to_owned(), details.clone());
988 }
989 if let Some(recommended_action) = recommended_action {
990 map.insert(
991 "recommendedAction".to_owned(),
992 Value::from(recommended_action.clone()),
993 );
994 }
995 Value::Object(map)
996 }
997 SyncOutcome::RealtimeUnavailable {
998 state,
999 reason_code,
1000 retry_delay_ms,
1001 } => {
1002 let mut map = Map::new();
1003 map.insert("ok".to_owned(), Value::Bool(false));
1004 map.insert(
1005 "errorCode".to_owned(),
1006 Value::from(REALTIME_UNAVAILABLE_CODE),
1007 );
1008 map.insert(
1009 "message".to_owned(),
1010 Value::from("realtime is required and the realtime socket is not connected"),
1011 );
1012 map.insert(
1013 "realtimeState".to_owned(),
1014 serde_json::to_value(state).expect("state serializes"),
1015 );
1016 if let Some(reason_code) = reason_code {
1017 map.insert(
1018 "realtimeReasonCode".to_owned(),
1019 Value::from(reason_code.clone()),
1020 );
1021 }
1022 map.insert("retryDelayMs".to_owned(), Value::from(*retry_delay_ms));
1023 Value::Object(map)
1024 }
1025 SyncOutcome::BudgetExhausted(report) => {
1026 let mut map = Map::new();
1027 map.insert("ok".to_owned(), Value::Bool(true));
1028 map.insert("budgetExhausted".to_owned(), Value::Bool(true));
1029 map.insert(
1030 "report".to_owned(),
1031 serde_json::to_value(report).expect("report serializes"),
1032 );
1033 Value::Object(map)
1034 }
1035 }
1036 }
1037}
1038
1039#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
1040#[serde(rename_all = "camelCase")]
1041pub struct ConflictRecord {
1042 pub client_commit_id: String,
1043 pub op_index: i32,
1044 pub table: String,
1045 pub row_id: String,
1046 pub code: String,
1047 pub message: String,
1048 pub server_version: i64,
1049 pub server_row: Map<String, Value>,
1052 #[serde(default, skip_serializing_if = "Vec::is_empty")]
1057 pub conflict_columns: Vec<String>,
1058 #[serde(skip_serializing_if = "Option::is_none")]
1059 pub operation: Option<CommitOperation>,
1060}
1061
1062#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1065#[serde(rename_all = "camelCase", deny_unknown_fields)]
1066pub struct RejectionDetails {
1067 #[serde(skip_serializing_if = "Option::is_none")]
1068 pub field_paths: Option<Vec<String>>,
1069 #[serde(skip_serializing_if = "Option::is_none")]
1070 pub reason: Option<String>,
1071 #[serde(skip_serializing_if = "Option::is_none")]
1072 pub required_action: Option<String>,
1073 #[serde(skip_serializing_if = "Option::is_none")]
1074 pub references: Option<BTreeMap<String, String>>,
1075}
1076
1077impl RejectionDetails {
1078 pub(crate) fn parse(raw: &str) -> Result<Self, String> {
1079 if raw.len() > 4_096 {
1080 return Err("rejection details exceed 4096 encoded bytes".to_owned());
1081 }
1082 let details: Self = serde_json::from_str(raw)
1083 .map_err(|error| format!("invalid rejection details: {error}"))?;
1084 details.validate()?;
1085 Ok(details)
1086 }
1087
1088 fn validate(&self) -> Result<(), String> {
1089 let mut members = 0;
1090 if let Some(paths) = &self.field_paths {
1091 members += 1;
1092 if paths.is_empty() || paths.len() > 32 {
1093 return Err("fieldPaths must contain 1-32 paths".to_owned());
1094 }
1095 let mut seen = std::collections::BTreeSet::new();
1096 for path in paths {
1097 if path.len() > 160 || !path.split('.').all(valid_identifier) || !seen.insert(path)
1098 {
1099 return Err("fieldPaths contains an invalid or duplicate path".to_owned());
1100 }
1101 }
1102 }
1103 if let Some(reason) = &self.reason {
1104 members += 1;
1105 if !valid_token(reason, 96) {
1106 return Err("reason must be a lowercase stable token".to_owned());
1107 }
1108 }
1109 if let Some(action) = &self.required_action {
1110 members += 1;
1111 if !valid_token(action, 96) {
1112 return Err("requiredAction must be a lowercase stable token".to_owned());
1113 }
1114 }
1115 if let Some(references) = &self.references {
1116 members += 1;
1117 if references.is_empty() || references.len() > 16 {
1118 return Err("references must contain 1-16 entries".to_owned());
1119 }
1120 for (key, value) in references {
1121 if !valid_token(key, 64)
1122 || value.is_empty()
1123 || value.len() > 256
1124 || value.trim() != value
1125 || value.chars().any(char::is_control)
1126 {
1127 return Err("references contains an invalid key or value".to_owned());
1128 }
1129 }
1130 }
1131 if members == 0 {
1132 return Err("rejection details must not be empty".to_owned());
1133 }
1134 Ok(())
1135 }
1136}
1137
1138fn valid_identifier(segment: &str) -> bool {
1139 let mut chars = segment.chars();
1140 matches!(chars.next(), Some(first) if first == '_' || first.is_ascii_alphabetic())
1141 && chars.all(|character| character == '_' || character.is_ascii_alphanumeric())
1142}
1143
1144fn valid_token(token: &str, max: usize) -> bool {
1145 if token.is_empty() || token.len() > max || !token.starts_with(|c: char| c.is_ascii_lowercase())
1146 {
1147 return false;
1148 }
1149 let mut previous_separator = false;
1150 for character in token.chars() {
1151 if character.is_ascii_lowercase() || character.is_ascii_digit() {
1152 previous_separator = false;
1153 } else if matches!(character, '.' | '_' | '-') && !previous_separator {
1154 previous_separator = true;
1155 } else {
1156 return false;
1157 }
1158 }
1159 !previous_separator
1160}
1161
1162#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
1163#[serde(rename_all = "camelCase")]
1164pub struct RejectionRecord {
1165 pub client_commit_id: String,
1166 pub op_index: i32,
1167 pub code: String,
1168 pub message: String,
1169 pub retryable: bool,
1170 #[serde(skip_serializing_if = "Option::is_none")]
1171 pub details: Option<RejectionDetails>,
1172 #[serde(skip_serializing_if = "Option::is_none")]
1173 pub operation: Option<CommitOperation>,
1174}
1175
1176#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
1178#[serde(rename_all = "camelCase")]
1179pub struct CommitOperation {
1180 pub table: String,
1181 pub row_id: String,
1182 pub op: String,
1183 #[serde(skip_serializing_if = "Option::is_none")]
1184 pub base_version: Option<i64>,
1185 #[serde(skip_serializing_if = "Option::is_none")]
1186 pub values: Option<Map<String, Value>>,
1187 #[serde(default, skip_serializing_if = "std::ops::Not::not")]
1189 pub insert: bool,
1190}
1191
1192#[derive(Debug, Clone, Serialize, PartialEq)]
1195#[serde(rename_all = "camelCase")]
1196pub struct PendingCommit {
1197 pub seq: i64,
1199 pub client_commit_id: String,
1200 pub created_at_ms: i64,
1202 pub operations: Vec<CommitOperation>,
1203}
1204
1205#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
1206#[serde(rename_all = "snake_case")]
1207pub enum CommitOutcomeStatus {
1208 Applied,
1209 Cached,
1210 Conflict,
1211 Rejected,
1212}
1213
1214#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
1215#[serde(rename_all = "snake_case")]
1216pub enum CommitOutcomeResolution {
1217 Active,
1218 ResolvedKeepServer,
1219 Superseded,
1220 Dismissed,
1221}
1222
1223#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
1224#[serde(tag = "status", rename_all = "snake_case")]
1225pub enum CommitOperationOutcome {
1226 Applied {
1227 #[serde(rename = "opIndex")]
1228 op_index: i32,
1229 },
1230 Conflict {
1231 conflict: ConflictRecord,
1232 },
1233 Error {
1234 rejection: RejectionRecord,
1235 },
1236}
1237
1238#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
1239#[serde(rename_all = "camelCase")]
1240pub struct RetainedUniqueConflict {
1241 pub index: String,
1242 pub columns: Vec<String>,
1243 pub row_id: String,
1244 pub server_row: Map<String, Value>,
1245 pub server_version: i64,
1246}
1247
1248#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
1249#[serde(rename_all = "camelCase")]
1250pub struct RetainedCommitRow {
1251 #[serde(default, skip_serializing_if = "Vec::is_empty")]
1252 pub unique_conflicts: Vec<RetainedUniqueConflict>,
1253 pub table: String,
1254 pub row_id: String,
1255 pub local_row: Option<Map<String, Value>>,
1256 pub server_row: Option<Map<String, Value>>,
1258 pub server_version: Option<i64>,
1259}
1260
1261#[derive(Debug, Clone, Serialize, PartialEq)]
1263#[serde(rename_all = "camelCase")]
1264pub struct CurrentBaseProof {
1265 pub proven: bool,
1266 #[serde(skip_serializing_if = "Option::is_none")]
1267 pub rows: Option<Vec<RetainedCommitRow>>,
1268 #[serde(skip_serializing_if = "Option::is_none")]
1269 pub reason: Option<CurrentBaseProofReason>,
1270}
1271
1272#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)]
1273#[serde(rename_all = "snake_case")]
1274pub enum CurrentBaseProofReason {
1275 Offline,
1276 SyncFailed,
1277 SchemaFloor,
1278 BudgetExhausted,
1279 SnapshotFailed,
1280 MissingCoverage,
1281 Revoked,
1282 OutcomeUnavailable,
1283}
1284
1285impl CurrentBaseProof {
1286 pub fn failure(reason: CurrentBaseProofReason) -> Self {
1287 Self {
1288 proven: false,
1289 rows: None,
1290 reason: Some(reason),
1291 }
1292 }
1293}
1294
1295#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
1296#[serde(rename_all = "camelCase")]
1297pub struct CommitOutcome {
1298 pub sequence: i64,
1299 pub client_commit_id: String,
1300 pub status: CommitOutcomeStatus,
1301 pub recorded_at_ms: i64,
1302 pub results: Vec<CommitOperationOutcome>,
1303 #[serde(skip_serializing_if = "Option::is_none")]
1306 pub operations: Option<Vec<CommitOperation>>,
1307 #[serde(skip_serializing_if = "Option::is_none")]
1308 pub retained_rows: Option<Vec<RetainedCommitRow>>,
1309 pub resolution: CommitOutcomeResolution,
1310 #[serde(skip_serializing_if = "Option::is_none")]
1311 pub resolved_at_ms: Option<i64>,
1312 #[serde(skip_serializing_if = "Option::is_none")]
1313 pub replacement_client_commit_id: Option<String>,
1314}
1315
1316#[derive(Debug, Clone, Deserialize, Default)]
1317#[serde(rename_all = "camelCase")]
1318pub struct CommitOutcomeQuery {
1319 pub limit: Option<usize>,
1320 #[serde(default)]
1321 pub active_only: bool,
1322}
1323
1324#[derive(Debug, Clone, Serialize)]
1328#[serde(
1329 tag = "state",
1330 rename_all = "camelCase",
1331 rename_all_fields = "camelCase"
1332)]
1333pub enum UnitCatchup {
1334 Unknown {
1335 id: String,
1336 },
1337 Known {
1338 id: String,
1339 status: UnitStatus,
1340 live: bool,
1341 cursor: i64,
1343 has_resume_token: bool,
1344 bootstrap_complete: bool,
1346 known_pending_pages: bool,
1348 #[serde(skip_serializing_if = "Option::is_none")]
1349 reason_code: Option<String>,
1350 },
1351}
1352
1353#[derive(Debug, Clone, Serialize)]
1361#[serde(tag = "status", rename_all = "snake_case")]
1362pub enum CommitDelivery {
1363 Pending {
1364 #[serde(rename = "clientCommitId")]
1365 client_commit_id: String,
1366 },
1367 Known {
1368 #[serde(rename = "clientCommitId")]
1369 client_commit_id: String,
1370 outcome: CommitOutcome,
1371 },
1372 Unknown {
1373 #[serde(rename = "clientCommitId")]
1374 client_commit_id: String,
1375 },
1376}
1377
1378#[derive(Debug, Clone, Serialize)]
1383#[serde(rename_all = "camelCase")]
1384pub struct SnapshotRead {
1385 pub revision: String,
1386 pub queries: Vec<Vec<QueryRow>>,
1387 pub coverage: CoverageSnapshot,
1388 pub units: Vec<UnitCatchup>,
1389 pub deliveries: Vec<CommitDelivery>,
1390}
1391
1392#[derive(Debug, Clone, Deserialize)]
1393#[serde(rename_all = "camelCase")]
1394pub struct ResolveCommitOutcomeInput {
1395 pub client_commit_id: String,
1396 pub resolution: CommitOutcomeResolution,
1397 pub replacement_client_commit_id: Option<String>,
1398}
1399
1400#[derive(Debug, Clone, Serialize)]
1401#[serde(rename_all = "camelCase")]
1402pub struct RowState {
1403 pub row_id: String,
1404 pub version: i64,
1407 pub values: Map<String, Value>,
1408 #[serde(skip_serializing_if = "Option::is_none")]
1410 pub sealed_key: Option<String>,
1411}
1412
1413#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1417#[serde(untagged, deny_unknown_fields)]
1418pub enum LocalDataPurgeTarget {
1419 Table {
1420 table: String,
1421 selectors: BTreeMap<String, Vec<String>>,
1422 },
1423 Projection {
1424 projection: String,
1425 },
1426}
1427
1428#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1431#[serde(rename_all = "camelCase", deny_unknown_fields)]
1432pub struct LocalDataPurgeInput {
1433 pub purge_id: String,
1434 pub targets: Vec<LocalDataPurgeTarget>,
1435}
1436
1437#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1439#[serde(rename_all = "camelCase")]
1440pub struct LocalDataPurgeResult {
1441 pub already_applied: bool,
1442 pub purged_rows: usize,
1443 pub dropped_commits: usize,
1444}
1445
1446#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1448#[serde(rename_all = "camelCase", deny_unknown_fields)]
1449pub struct LocalDataRebootstrapInput {
1450 pub rebootstrap_id: String,
1451}
1452
1453#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1455#[serde(rename_all = "camelCase")]
1456pub struct LocalDataRebootstrapResult {
1457 pub already_applied: bool,
1458 pub retained_commits: usize,
1459 pub reset_subscriptions: usize,
1460}
1461
1462#[derive(Debug, Clone, Default)]
1464pub struct ClientLimits {
1465 pub limit_commits: Option<i32>,
1466 pub limit_snapshot_rows: Option<i32>,
1467 pub max_snapshot_pages: Option<i32>,
1468 pub accept: Option<u8>,
1471 pub blob_cache_max_bytes: Option<i64>,
1476 pub outcome_retention_max_entries: Option<usize>,
1479 pub max_push_commits_per_request: Option<usize>,
1481 pub max_push_operations_per_request: Option<usize>,
1486 pub max_push_request_bytes: Option<usize>,
1492 pub previous_version_context: Option<PreviousVersionContextConfig>,
1496 pub authority_reads: Vec<AuthorityReadDeclaration>,
1498}
1499
1500#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq)]
1502#[serde(rename_all = "camelCase", deny_unknown_fields)]
1503pub struct AuthorityReadDeclaration {
1504 pub table: String,
1505 pub columns: Vec<String>,
1506 pub scopes: std::collections::BTreeMap<String, Vec<String>>,
1507}