1use crate::{ProgressObserver, ProgressPhase, ProgressState};
11use ssp2::encode_message;
12use std::borrow::Cow;
13#[cfg(test)]
14use std::cell::Cell;
15use std::cell::RefCell;
16use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet, VecDeque};
17use std::sync::Arc;
18
19use rusqlite::types::{ToSqlOutput, Value as SqlValue, ValueRef};
20use rusqlite::{Connection, OpenFlags, OptionalExtension};
21use serde::{Deserialize, Serialize};
22use serde_json::{json, Map, Value};
23use sha2::{Digest, Sha256};
24use ssp2::decode::WIRE_VERSION;
25use ssp2::model::{
26 FencedRecord, Frame, LiveStatus, MediaType, Message, MsgKind, Op, OpResult, PushStatus,
27 SubStatus,
28};
29use ssp2::primitives::RawJson;
30use ssp2::registration::canonical_scope_json;
31use ssp2::segment::{decode_rows_segment, Column, ColumnType, ColumnValue, Row, RowsSegment};
32use ssp2::{decode_message, encode_presence_publish, parse_control, ControlMessage, PresenceKind};
33
34use crate::api::{
35 AppliedServerCommit, AppliedServerCommitSource, ClientChangeBatch, ClientDiagnosticsHost,
36 ClientDiagnosticsLease, ClientDiagnosticsReplica, ClientDiagnosticsSchema,
37 ClientDiagnosticsSnapshot, ClientDiagnosticsStorage, ClientError, ClientLimits, CommandEffects,
38 CommitDelivery, CommitOperation, CommitOperationOutcome, CommitOutcome, CommitOutcomeQuery,
39 CommitOutcomeResolution, CommitOutcomeStatus, ConflictRecord, CoverageSnapshot,
40 CurrentBaseProof, CurrentBaseProofReason, DiagnosticLastChange, DiagnosticLastRound,
41 DiagnosticQueryFailure, DiagnosticRoundCounters, DiagnosticUnits, EchoRecord, FetchedBlob,
42 LeaseState, LocalDataPurgeInput, LocalDataPurgeResult, LocalDataPurgeTarget,
43 LocalDataRebootstrapInput, LocalDataRebootstrapResult, Mutation, PendingCommit, PresencePeer,
44 PreviousVersionStatus, QueryOwner, QueryReadFailure, QueryRow, QuerySnapshot, QueryValue,
45 RejectionDetails, RejectionRecord, ResolveCommitOutcomeInput, RetainedCommitRow,
46 RetainedUniqueConflict, RowState, SchemaFloor, SnapshotRead, SyncIntent, SyncOutcome,
47 SyncReport, SyncStatusSnapshot, TableChange, UnitCatchup, UnitRecord, UnitRestriction,
48 UnitScopes, UnitStatus, WindowBase, WindowChange, WindowCoverage, WindowState, WindowUnitRef,
49 CLIENT_DIAGNOSTICS_VERSION, MAX_DIAGNOSTIC_QUERY_FAILURES,
50};
51use crate::api::{RealtimePolicy, RealtimeState, REALTIME_UNAVAILABLE_CODE};
52#[cfg(feature = "bench-internals")]
53use crate::bench::{Phase, Recorder};
54use crate::previous_version::{
55 capture_previous_version_from_replica, first_incompatibility,
56 reconcile_previous_version_at_boot, set_local_schema_descriptor,
57 sweep_previous_version_container, PendingCommitAudit, PreviousVersionContextConfig,
58 PreviousVersionLifecycle, PreviousVersionReadSpec, PreviousVersionSnapshot,
59};
60use crate::schema::{parse_schema_json, ClientSchema, FtsIndexSchema, TableSchema};
61use crate::transport::{BlobDownload, SegmentRequest, Transport, TransportError};
62use crate::values::{
63 bytes_to_hex, column_value_to_json, decode_row_bytes, encode_sparse_row_json, full_row_values,
64 is_canonical_bytes_envelope, json_to_column_value, json_to_scope_map, normalize_values_casing,
65 render_row_id_json, scope_map_to_json, SealedRow,
66};
67
68const DEFAULT_ACCEPT: u8 = 0b0111;
72const ACCEPT_INLINE_ROWS: u8 = 1 << 0;
73const ACCEPT_EXTERNAL_ROWS: u8 = 1 << 1;
74const ACCEPT_SQLITE: u8 = 1 << 2;
75const ACCEPT_SIGNED_URLS: u8 = 1 << 3;
76const MAX_DIAGNOSTIC_DOMAINS: usize = 256;
77
78fn recommended_action_of(details: &Option<Value>) -> Option<String> {
80 details
81 .as_ref()?
82 .get("recommendedAction")?
83 .as_str()
84 .map(str::to_owned)
85}
86
87pub(crate) const LOCAL_SCHEMA_VERSION_KEY: &str = "localSchemaVersion";
89const LOCAL_REVISION_KEY: &str = "localRevision";
90const REPLICA_CURSOR_KEY: &str = "replicaCursor";
92const ECHO_DIGEST_KEY: &str = "echoDigest";
94const REGISTERED_DIGEST_KEY: &str = "registrationDigest";
96const TABLE_GENERATIONS_KEY: &str = "localTableGenerations";
98const OUTBOX_ID_KEY: &str = "outboxId";
100const CLIENT_ID_KEY: &str = "clientId";
101const LEASE_STATE_KEY: &str = "leaseState";
102const SCHEMA_FLOOR_KEY: &str = "schemaFloor";
103pub(crate) const LOG_EPOCH_KEY: &str = "logEpoch";
104const SECURITY_PREFLIGHT_PENDING_KEY: &str = "securityPreflightPending";
109const LOCAL_REBOOTSTRAP_RECEIPT_VERSION: u8 = 2;
110const MAX_JS_SAFE_INTEGER: u64 = 9_007_199_254_740_991;
111const OUTBOX_INCOMPATIBLE_CODE: &str = "sync.outbox_incompatible";
114const ENCRYPT_FAILED_CODE: &str = "client.encrypt_failed";
117const INVALID_REQUEST_CODE: &str = "sync.invalid_request:";
118const LEGACY_VALUE_REFUSAL_MESSAGE: &str =
120 "the persisted commit carries values the current codec refuses";
121const INVALID_STORED_VALUES_REASON: &str = "invalid_stored_values";
123const REPLACEMENT_PENDING: &str =
125 "client.replacement_pending: the outcome has a pending replacement";
126const REPLACEMENT_REFUSED_CODE: &str = "sync.replacement_refused";
128
129#[derive(Debug, Serialize, Deserialize)]
130#[serde(rename_all = "camelCase", deny_unknown_fields)]
131struct PersistedLocalDataRebootstrapReceipt {
132 version: u8,
133 retained_commits: u64,
134 reset_subscriptions: u64,
135}
136
137fn invalid_local_rebootstrap_receipt() -> String {
138 "sync.local_corrupt: persisted local rebootstrap receipt is invalid".to_owned()
139}
140
141fn encode_local_rebootstrap_receipt(
142 retained_commits: usize,
143 reset_subscriptions: usize,
144) -> Result<String, String> {
145 let retained_commits =
146 u64::try_from(retained_commits).map_err(|_| invalid_local_rebootstrap_receipt())?;
147 let reset_subscriptions =
148 u64::try_from(reset_subscriptions).map_err(|_| invalid_local_rebootstrap_receipt())?;
149 if retained_commits > MAX_JS_SAFE_INTEGER || reset_subscriptions > MAX_JS_SAFE_INTEGER {
150 return Err(invalid_local_rebootstrap_receipt());
151 }
152 serde_json::to_string(&PersistedLocalDataRebootstrapReceipt {
153 version: LOCAL_REBOOTSTRAP_RECEIPT_VERSION,
154 retained_commits,
155 reset_subscriptions,
156 })
157 .map_err(|_| invalid_local_rebootstrap_receipt())
158}
159
160fn decode_local_rebootstrap_receipt(value: &str) -> Result<(usize, usize), String> {
161 if value == "v1" {
163 return Ok((0, 0));
164 }
165 let receipt: PersistedLocalDataRebootstrapReceipt =
166 serde_json::from_str(value).map_err(|_| invalid_local_rebootstrap_receipt())?;
167 if receipt.version != LOCAL_REBOOTSTRAP_RECEIPT_VERSION
168 || receipt.retained_commits > MAX_JS_SAFE_INTEGER
169 || receipt.reset_subscriptions > MAX_JS_SAFE_INTEGER
170 {
171 return Err(invalid_local_rebootstrap_receipt());
172 }
173 Ok((
174 usize::try_from(receipt.retained_commits)
175 .map_err(|_| invalid_local_rebootstrap_receipt())?,
176 usize::try_from(receipt.reset_subscriptions)
177 .map_err(|_| invalid_local_rebootstrap_receipt())?,
178 ))
179}
180
181#[cfg(test)]
182mod observation_tests;
183
184#[doc(hidden)]
186#[derive(Clone)]
187pub struct CurrentBasePreparation {
188 client_commit_id: String,
189 sequence: i64,
190 replacement: Option<String>,
193 units: Vec<UnitRecord>,
194 transport_epoch: u64,
195 registration_epoch: u64,
196 security_epoch: u64,
197}
198
199#[cfg(test)]
200mod units_tests;
201
202#[cfg(test)]
203mod replace_outcome_tests;
204
205#[derive(Debug, Clone)]
206struct OutboxOp {
207 upsert: bool,
208 table: String,
209 row_id: String,
210 base_version: Option<i64>,
211 values: Option<Map<String, Value>>,
215 insert: bool,
219}
220
221impl OutboxOp {
222 fn presented_values(&self, table: &TableSchema) -> Option<Cow<'_, Map<String, Value>>> {
227 let values = self.values.as_ref()?;
228 if !self.insert || table.columns.iter().all(|c| values.contains_key(&c.name)) {
229 return Some(Cow::Borrowed(values));
230 }
231 full_row_values(table, values.clone()).ok().map(Cow::Owned)
232 }
233}
234
235impl From<CommitOperation> for OutboxOp {
236 fn from(operation: CommitOperation) -> Self {
237 Self {
238 upsert: operation.op == "upsert",
239 table: operation.table,
240 row_id: operation.row_id,
241 base_version: operation.base_version,
242 values: operation.values,
243 insert: operation.insert,
244 }
245 }
246}
247
248fn invalid_authoring(message: &str, details: Value) -> ClientError {
250 ClientError {
251 code: "sync.invalid_request".to_owned(),
252 message: message.to_owned(),
253 details: Some(details),
254 retryable: false,
255 }
256}
257
258fn chains_on(earlier: &OutboxOp, later: &OutboxOp) -> bool {
261 earlier.row_id == later.row_id
263 && earlier.table == later.table
264 && later.base_version.is_some_and(|base| base > 0)
265 && earlier.base_version == later.base_version
266 && later.values.as_ref().is_some_and(|values| {
267 values.keys().all(|column| {
268 earlier
269 .values
270 .as_ref()
271 .is_some_and(|earlier| earlier.contains_key(column))
272 })
273 })
274}
275
276impl From<&OutboxOp> for CommitOperation {
277 fn from(operation: &OutboxOp) -> Self {
278 Self {
279 table: operation.table.clone(),
280 row_id: operation.row_id.clone(),
281 op: if operation.upsert { "upsert" } else { "delete" }.to_owned(),
282 base_version: operation.base_version,
283 values: operation.values.clone(),
284 insert: operation.insert,
285 }
286 }
287}
288
289#[derive(Debug, Clone)]
290struct OutboxCommit {
291 client_commit_id: String,
292 ops: Vec<OutboxOp>,
293}
294
295fn commit_audit_operations(commit: &OutboxCommit) -> Vec<(&str, Vec<&str>, bool)> {
299 commit
300 .ops
301 .iter()
302 .filter(|operation| operation.upsert)
303 .map(|operation| {
304 (
305 operation.table.as_str(),
306 operation
307 .values
308 .as_ref()
309 .map(|values| values.keys().map(String::as_str).collect())
310 .unwrap_or_default(),
311 operation.insert,
312 )
313 })
314 .collect()
315}
316
317type FailedCommit = (OutboxCommit, Map<String, Value>);
318
319#[derive(Debug, Clone)]
320struct CompiledLocalDataPurgeTarget {
321 table: String,
322 selectors: Vec<(String, Vec<String>)>,
323}
324
325struct StoredCommitOutcomeRow {
326 sequence: i64,
327 client_commit_id: String,
328 status: String,
329 recorded_at_ms: i64,
330 results_json: String,
331 operations_json: Option<String>,
332 resolution: String,
333 resolved_at_ms: Option<i64>,
334 replacement_client_commit_id: Option<String>,
335}
336
337impl StoredCommitOutcomeRow {
338 fn from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<Self> {
339 Ok(Self {
340 sequence: row.get(0)?,
341 client_commit_id: row.get(1)?,
342 status: row.get(2)?,
343 recorded_at_ms: row.get(3)?,
344 results_json: row.get(4)?,
345 operations_json: row.get(5)?,
346 resolution: row.get(6)?,
347 resolved_at_ms: row.get(7)?,
348 replacement_client_commit_id: row.get(8)?,
349 })
350 }
351}
352
353struct SectionStart {
357 id: String,
358 status: SubStatus,
359 reason_code: String,
360 bootstrap: bool,
361 fenced: Vec<FencedRecord>,
362}
363
364enum SectionError {
365 FailClosed,
366 Refused,
368 Deferred,
371 Abort(String, String),
372 Transport(TransportError),
373}
374
375#[derive(Debug)]
376pub(crate) struct RequestMeta {
377 pushed_ids: Vec<String>,
378 registration_digest: String,
381 pub(crate) accept: u8,
382 deferred_commits: usize,
386 pub(crate) applied: BTreeMap<String, BTreeMap<String, i64>>,
389 pub(crate) deferred: BTreeSet<(String, String)>,
393}
394
395#[derive(Default)]
396struct ChangeAccumulator {
397 tables: BTreeMap<String, Option<BTreeSet<String>>>,
399 windows: BTreeMap<String, BTreeSet<String>>,
400 status: bool,
401 conflicts: bool,
402 rejections: bool,
403 outcomes: bool,
404}
405
406impl ChangeAccumulator {
407 fn table(&mut self, table: &str) {
408 self.tables.insert(table.to_owned(), None);
409 }
410
411 fn scope(&mut self, table: &str, key: String) {
412 match self.tables.get_mut(table) {
413 Some(None) => {}
414 Some(Some(keys)) => {
415 keys.insert(key);
416 }
417 None => {
418 self.tables
419 .insert(table.to_owned(), Some(BTreeSet::from([key])));
420 }
421 }
422 }
423
424 fn window(&mut self, base_key: &str, value: &str) {
425 self.windows
426 .entry(base_key.to_owned())
427 .or_default()
428 .insert(value.to_owned());
429 }
430
431 fn touched(&self) -> bool {
432 !self.tables.is_empty()
433 || !self.windows.is_empty()
434 || self.status
435 || self.conflicts
436 || self.rejections
437 || self.outcomes
438 }
439}
440
441const PUSH_OPS_PER_REQUEST: usize = 500;
447const MAX_LOCAL_PURGE_TARGETS: usize = 64;
448const MAX_LOCAL_PURGE_SELECTORS: usize = 8;
449const MAX_LOCAL_PURGE_VALUES: usize = 128;
450const MAX_LOCAL_PURGE_VALUE_LENGTH: usize = 256;
451pub const SECURITY_PREFLIGHT_REQUIRED_CODE: &str = "client.security_preflight_required";
452
453struct OverlayDirty(RefCell<Option<BTreeSet<String>>>);
455
456impl OverlayDirty {
457 fn clean() -> Self {
458 Self(RefCell::new(Some(BTreeSet::new())))
459 }
460 fn get(&self) -> bool {
461 self.0
462 .borrow()
463 .as_ref()
464 .is_none_or(|tables| !tables.is_empty())
465 }
466 fn set(&self, dirty: bool) {
467 *self.0.borrow_mut() = if dirty { None } else { Some(BTreeSet::new()) };
468 }
469 fn table(&self, table: &str) {
470 if let Some(tables) = self.0.borrow_mut().as_mut() {
471 tables.insert(table.to_owned());
472 }
473 }
474 fn snapshot(&self) -> Option<BTreeSet<String>> {
475 self.0.borrow().clone()
476 }
477 fn restore(&self, tables: Option<BTreeSet<String>>) {
478 *self.0.borrow_mut() = tables;
479 }
480}
481
482#[derive(Debug, Clone, Default)]
485struct Shared<T>(Arc<T>);
486
487impl<T> std::ops::Deref for Shared<T> {
488 type Target = T;
489 fn deref(&self) -> &T {
490 &self.0
491 }
492}
493
494impl<T: Clone> std::ops::DerefMut for Shared<T> {
495 fn deref_mut(&mut self) -> &mut T {
496 Arc::make_mut(&mut self.0)
497 }
498}
499
500impl<T> From<T> for Shared<T> {
501 fn from(value: T) -> Self {
502 Self(Arc::new(value))
503 }
504}
505
506#[derive(Debug, Clone)]
510struct Rollback {
511 outbox: Shared<Vec<Arc<OutboxCommit>>>,
512 failed_commits: Shared<Vec<FailedCommit>>,
513 conflicts: Shared<Vec<ConflictRecord>>,
514 rejections: Shared<Vec<RejectionRecord>>,
515 schema_floor: Option<SchemaFloor>,
516 lease_state: Option<LeaseState>,
517 stopped: bool,
518 upgrading: bool,
519 sync_needed: bool,
520 active_round: Option<(uuid::Uuid, i64, u64)>,
521 overlay_dirty: Option<BTreeSet<String>>,
522 change_queue: usize,
523 sync_intent_queue: usize,
524 last_change: Option<DiagnosticLastChange>,
525}
526
527pub struct SyncClient {
528 #[cfg(feature = "bench-internals")]
529 benchmark_phases: Recorder,
530 conn: Connection,
531 schema: ClientSchema,
532 client_id: String,
533 limits: ClientLimits,
534 outbox: Shared<Vec<Arc<OutboxCommit>>>,
535 failed_commits: Shared<Vec<FailedCommit>>,
536 retain_failed_commits: bool,
537 conflicts: Shared<Vec<ConflictRecord>>,
538 rejections: Shared<Vec<RejectionRecord>>,
539 schema_floor: Option<SchemaFloor>,
540 lease_state: Option<LeaseState>,
542 stopped: bool,
544 upgrading: bool,
546 sync_needed: bool,
548 realtime_policy: RealtimePolicy,
551 realtime_state: RealtimeState,
552 realtime_reason_code: Option<String>,
553 realtime_retry_delay_ms: Option<u64>,
554 presence: HashMap<String, HashMap<String, PresencePeer>>,
556 now_ms: Option<std::sync::Arc<std::sync::atomic::AtomicI64>>,
560 encryption: crate::values::EncryptionConfig,
564 security_preflight: bool,
567 security_epoch: u64,
568 transport_enabled: bool,
569 transport_epoch: u64,
570 registration_epoch: u64,
573 previous_version: Option<PreviousVersionContextConfig>,
577 insert_sql: RefCell<HashMap<String, String>>,
583 overlay_dirty: OverlayDirty,
586 storage_failure: RefCell<Option<QueryReadFailure>>,
588 #[cfg(test)]
591 overlay_rebuild_count: Cell<usize>,
592 #[cfg(test)]
593 acknowledged_replay_count: Cell<usize>,
594 #[cfg(test)]
597 outcome_prune_count: Cell<usize>,
598 #[cfg(test)]
600 image_chunk_ms: Cell<Option<f64>>,
601 progress: ProgressObserver,
603 epoch: String,
605 change_queue: VecDeque<ClientChangeBatch>,
606 sync_intent_queue: VecDeque<SyncIntent>,
607 scopes_changed: usize,
609 retry_delay_ms: u64,
611 round_retry_delay_ms: Option<u64>,
613 image_chunk_rows: HashMap<String, u32>,
616 round_failure: Option<String>,
621 active_round: Option<(uuid::Uuid, i64, u64)>,
623 last_round: Option<DiagnosticLastRound>,
624 last_change: Option<DiagnosticLastChange>,
625 query_failures: Vec<DiagnosticQueryFailure>,
627 coalesced: Option<CoalescedApply>,
629 coalesced_failure: Option<String>,
632}
633
634struct CoalescedApply {
638 rows: usize,
639 rollback: Rollback,
640}
641
642const COALESCED_APPLY_ROWS: usize = 1024;
643
644pub(crate) fn quote_ident(name: &str) -> String {
645 format!("\"{}\"", name.replace('"', "\"\""))
646}
647pub(crate) fn meta_get(conn: &Connection, key: &str) -> rusqlite::Result<Option<String>> {
651 conn.query_row(
652 "SELECT value FROM _syncular_meta WHERE key = ?1",
653 rusqlite::params![key],
654 |row| row.get::<_, String>(0),
655 )
656 .optional()
657}
658
659pub(crate) fn meta_set(conn: &Connection, key: &str, value: &str) -> rusqlite::Result<()> {
660 conn.execute(
661 "INSERT OR REPLACE INTO _syncular_meta (key, value) VALUES (?1, ?2)",
662 rusqlite::params![key, value],
663 )
664 .map(|_| ())
665}
666
667pub(crate) fn meta_delete(conn: &Connection, key: &str) -> rusqlite::Result<()> {
668 conn.execute(
669 "DELETE FROM _syncular_meta WHERE key = ?1",
670 rusqlite::params![key],
671 )
672 .map(|_| ())
673}
674
675fn row_id_predicate(table: &TableSchema) -> String {
677 let key = quote_ident(&table.primary_key);
678 let text_match = format!("CAST({key} AS TEXT) = ?1");
679 match table.columns[table.pk_index].ty {
680 ColumnType::String | ColumnType::Json => {
681 format!("{key} = ?1 AND {text_match}")
682 }
683 ColumnType::Integer | ColumnType::Boolean => {
687 format!("{key} = +CAST(?1 AS INTEGER) AND {text_match}")
688 }
689 _ => text_match,
692 }
693}
694
695fn local_scope_predicate(
702 table: &TableSchema,
703 effective: &[(String, Vec<String>)],
704 owners: &[Vec<(String, Vec<String>)>],
705) -> Result<Option<(String, Vec<SqlValue>)>, ()> {
706 if effective.is_empty() || effective.iter().any(|(_, values)| values.is_empty()) {
707 return Ok(None);
708 }
709 let column = |variable: &str| {
710 let name = table.scope_column(variable).ok_or(())?;
711 let column = table
712 .columns
713 .iter()
714 .find(|column| column.name == name)
715 .ok_or(())?;
716 Ok((quote_ident(name), column.ty == ColumnType::Integer))
717 };
718 let mut clauses = Vec::new();
719 let mut params = Vec::new();
720 for (variable, values) in effective {
721 let (key, integer) = column(variable)?;
722 let holes = vec!["?"; values.len()].join(", ");
723 clauses.push(if integer {
724 params.extend(values.iter().cloned().map(SqlValue::Text));
725 let seek = vec!["+CAST(? AS INTEGER)"; values.len()].join(", ");
726 format!("{key} IN ({seek}) AND CAST({key} AS TEXT) IN ({holes})")
727 } else {
728 format!("{key} IN ({holes})")
729 });
730 params.extend(values.iter().cloned().map(SqlValue::Text));
731 }
732 let mut groups: BTreeMap<Vec<&str>, Vec<Vec<&[String]>>> = BTreeMap::new();
738 for owner in owners {
739 if owner.is_empty()
740 || owner.iter().any(|(variable, values)| {
741 values.is_empty()
742 || effective.iter().any(|(name, wanted)| {
743 name == variable && wanted.iter().all(|value| !values.contains(value))
744 })
745 })
746 {
747 continue;
748 }
749 let mut owner: Vec<_> = owner.iter().collect();
750 owner.sort_by(|a, b| a.0.cmp(&b.0));
751 groups
752 .entry(
753 owner
754 .iter()
755 .map(|(variable, _)| variable.as_str())
756 .collect(),
757 )
758 .or_default()
759 .push(owner.iter().map(|(_, values)| values.as_slice()).collect());
760 }
761 let within = |variable: &str, list: &str| {
762 let (key, integer) = column(variable)?;
763 let key = if integer {
764 format!("CAST({key} AS TEXT)")
765 } else {
766 key
767 };
768 Ok(format!("{key} IN (SELECT value FROM json_each({list}))"))
769 };
770 for (variables, tuples) in groups {
771 if let [variable] = variables[..] {
772 let values: BTreeSet<&String> = tuples.iter().flatten().copied().flatten().collect();
773 params.push(SqlValue::Text(
774 Value::from_iter(values.into_iter().cloned()).to_string(),
775 ));
776 clauses.push(format!("NOT {}", within(variable, "?")?));
777 } else {
778 params.push(SqlValue::Text(
779 serde_json::to_string(&tuples).expect("owner tuples serialize"),
780 ));
781 let matches = variables
782 .iter()
783 .enumerate()
784 .map(|(index, variable)| within(variable, &format!("o.value,'$[{index}]'")))
785 .collect::<Result<Vec<_>, ()>>()?;
786 clauses.push(format!(
787 "NOT EXISTS (SELECT 1 FROM json_each(?) o WHERE {})",
788 matches.join(" AND ")
789 ));
790 }
791 }
792 Ok(Some((clauses.join(" AND "), params)))
793}
794
795fn owns_local_row(
797 table: &TableSchema,
798 effective: &[(String, Vec<String>)],
799 owners: &[Vec<(String, Vec<String>)>],
800 values: &Map<String, Value>,
801) -> bool {
802 let matches = |scopes: &[(String, Vec<String>)]| {
803 !scopes.is_empty()
804 && scopes.iter().all(|(variable, allowed)| {
805 table
806 .scope_column(variable)
807 .and_then(|column| values.get(column))
808 .filter(|value| !value.is_null())
809 .is_some_and(|value| {
810 allowed.contains(
811 &value
812 .as_str()
813 .map_or_else(|| value.to_string(), str::to_owned),
814 )
815 })
816 })
817 };
818 matches(effective) && !owners.iter().any(|owner| matches(owner))
819}
820
821fn is_local_operation_code_like(value: &str) -> bool {
822 let bytes = value.as_bytes();
823 bytes.first().is_some_and(u8::is_ascii_alphanumeric)
824 && bytes
825 .iter()
826 .all(|byte| byte.is_ascii_alphanumeric() || matches!(*byte, b'.' | b'_' | b':' | b'-'))
827}
828
829fn base_table(name: &str) -> String {
830 quote_ident(&format!("_syncular_base_{name}"))
831}
832
833type PendingEvict = (String, String, Vec<(String, Vec<String>)>);
835
836fn window_base_key(base: &WindowBase) -> String {
838 format!(
839 "{}\0{}",
840 base.variable,
841 ssp2::registration::canonical_unit_json(&scope_pairs(&base.fixed_scopes))
842 )
843}
844
845fn window_unit_scopes(base: &WindowBase, value: &str) -> UnitScopes {
847 let mut scopes = base.fixed_scopes.clone();
848 scopes.insert(base.variable.clone(), value.to_owned());
849 scopes
850}
851
852fn scope_pairs(scopes: &UnitScopes) -> Vec<(String, String)> {
854 let mut pairs: Vec<(String, String)> = scopes
855 .iter()
856 .map(|(variable, value)| (variable.clone(), value.clone()))
857 .collect();
858 pairs.sort_by(|a, b| a.0.encode_utf16().cmp(b.0.encode_utf16()));
859 pairs
860}
861
862fn covers(table: &TableSchema, scopes: &UnitScopes) -> bool {
864 scopes
865 .keys()
866 .all(|variable| table.scope_column(variable).is_some())
867}
868
869fn pair_scopes(
873 scopes: &UnitScopes,
874 table: &str,
875 echo: Option<&[EchoRecord]>,
876) -> Option<Vec<(String, Vec<String>)>> {
877 let fenced = echo.and_then(|echo| echo.iter().find(|record| record.table == table));
878 if fenced.is_some_and(|record| record.status == "revoked") {
879 return None;
880 }
881 let mut effective: BTreeMap<String, Vec<String>> = fenced
882 .map(|record| record.scopes.clone())
883 .unwrap_or_default();
884 for (variable, value) in scopes {
885 effective.insert(variable.clone(), vec![value.clone()]);
886 }
887 Some(effective.into_iter().collect())
888}
889
890fn unit_owners(
895 units: &[UnitRecord],
896 table: &TableSchema,
897 except_id: &str,
898) -> Vec<Vec<(String, Vec<String>)>> {
899 units
900 .iter()
901 .filter(|unit| {
902 unit.id != except_id
903 && unit.status == UnitStatus::Active
904 && unit.echo.is_some()
905 && (!unit.bootstrapping()
906 || unit.seeded.contains(&table.name)
907 || unit
908 .restriction
909 .as_ref()
910 .is_some_and(|restriction| !restriction.tables.contains(&table.name)))
911 && covers(table, &unit.scopes)
912 })
913 .filter_map(|unit| pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()))
914 .collect()
915}
916
917fn unit_scope_lists(scopes: &UnitScopes) -> Vec<(String, Vec<String>)> {
919 scopes
920 .iter()
921 .map(|(variable, value)| (variable.clone(), vec![value.clone()]))
922 .collect()
923}
924
925const ACKED_ROWS_BY_ROW: &str = "SELECT a.op_json,a.intent_json FROM json_each(?1) k JOIN _syncular_acked_rows a ON a.tbl=json_extract(k.value,'$[0]') AND a.id=json_extract(k.value,'$[1]') WHERE ?2 IS NULL OR a.tbl IN(SELECT value FROM json_each(?2)) ORDER BY a.commit_seq,a.idx";
929
930const UNIT_COLUMNS: &str =
931 "id, scopes, explicit, status, reason_code, cursor, bootstrap_state, seeded, echo, restriction";
932
933fn unit_from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<UnitRecord> {
936 fn json<T: serde::de::DeserializeOwned>(index: usize, raw: &str) -> rusqlite::Result<T> {
937 serde_json::from_str(raw).map_err(|error| {
938 rusqlite::Error::FromSqlConversionFailure(
939 index,
940 rusqlite::types::Type::Text,
941 Box::new(error),
942 )
943 })
944 }
945 Ok(UnitRecord {
946 id: row.get(0)?,
947 scopes: json(1, &row.get::<_, String>(1)?)?,
948 explicit: row.get::<_, i64>(2)? == 1,
949 status: json(
950 3,
951 &serde_json::to_string(&row.get::<_, String>(3)?).expect("text"),
952 )?,
953 reason_code: row.get(4)?,
954 cursor: row.get(5)?,
955 bootstrap_state: row.get(6)?,
956 seeded: json(7, &row.get::<_, String>(7)?)?,
957 echo: row
958 .get::<_, Option<String>>(8)?
959 .map(|echo| json::<Vec<EchoRecord>>(8, &echo))
960 .transpose()?
961 .map(|echo| {
962 if echo
963 .iter()
964 .all(|record| record.status == "active" || record.status == "revoked")
965 {
966 Ok(echo)
967 } else {
968 Err(rusqlite::Error::FromSqlConversionFailure(
969 8,
970 rusqlite::types::Type::Text,
971 "echo status is neither active nor revoked".into(),
972 ))
973 }
974 })
975 .transpose()?,
976 restriction: row
977 .get::<_, Option<String>>(9)?
978 .map(|raw| json::<UnitRestriction>(9, &raw))
979 .transpose()?,
980 })
981}
982
983fn load_units(conn: &Connection) -> rusqlite::Result<Vec<UnitRecord>> {
985 conn.prepare_cached(&format!(
986 "SELECT {UNIT_COLUMNS} FROM _syncular_units ORDER BY rowid"
987 ))?
988 .query_map([], unit_from_row)?
989 .collect()
990}
991
992fn get_unit(conn: &Connection, id: &str) -> rusqlite::Result<Option<UnitRecord>> {
993 conn.query_row(
994 &format!("SELECT {UNIT_COLUMNS} FROM _syncular_units WHERE id = ?1"),
995 [id],
996 unit_from_row,
997 )
998 .optional()
999}
1000
1001fn save_unit(conn: &Connection, unit: &UnitRecord) -> rusqlite::Result<()> {
1004 conn.prepare_cached(&format!(
1005 "INSERT INTO _syncular_units({UNIT_COLUMNS}) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9,?10)
1006 ON CONFLICT(id) DO UPDATE SET explicit=excluded.explicit, status=excluded.status,
1007 reason_code=excluded.reason_code, cursor=excluded.cursor,
1008 bootstrap_state=excluded.bootstrap_state, seeded=excluded.seeded, echo=excluded.echo,
1009 restriction=excluded.restriction,
1010 applied=CASE WHEN cursor IS excluded.cursor
1011 AND bootstrap_state IS excluded.bootstrap_state THEN applied END"
1012 ))?
1013 .execute(rusqlite::params![
1014 unit.id,
1015 serde_json::to_string(&unit.scopes).expect("scope map serializes"),
1016 i64::from(unit.explicit),
1017 unit.status.name(),
1018 unit.reason_code,
1019 unit.cursor,
1020 unit.bootstrap_state,
1021 serde_json::to_string(&unit.seeded).expect("table list serializes"),
1022 unit.echo
1023 .as_ref()
1024 .map(|echo| serde_json::to_string(echo).expect("echo serializes")),
1025 unit.restriction
1026 .as_ref()
1027 .map(|restriction| serde_json::to_string(restriction).expect("restriction serializes")),
1028 ])
1029 .map(|_| ())
1030}
1031
1032fn applied_rows(conn: &Connection, id: &str) -> rusqlite::Result<BTreeMap<String, i64>> {
1035 conn.query_row(
1036 "SELECT applied FROM _syncular_units WHERE id = ?1",
1037 [id],
1038 |row| row.get::<_, Option<String>>(0),
1039 )
1040 .optional()?
1041 .flatten()
1042 .map_or(Ok(BTreeMap::new()), |raw| {
1043 serde_json::from_str(&raw).map_err(|error| {
1044 rusqlite::Error::FromSqlConversionFailure(
1045 0,
1046 rusqlite::types::Type::Text,
1047 Box::new(error),
1048 )
1049 })
1050 })
1051}
1052
1053fn record_applied_rows(
1056 conn: &Connection,
1057 id: &str,
1058 segment_id: &str,
1059 rows: i64,
1060) -> rusqlite::Result<()> {
1061 conn.prepare_cached(
1062 "UPDATE _syncular_units SET applied=json_patch(coalesce(applied,'{}'),?1) WHERE id=?2",
1063 )?
1064 .execute(rusqlite::params![
1065 serde_json::json!({ segment_id: rows }).to_string(),
1066 id
1067 ])
1068 .map(|_| ())
1069}
1070
1071fn window_refs(conn: &Connection, unit_id: &str) -> rusqlite::Result<Vec<(String, String)>> {
1073 conn.prepare_cached("SELECT base, unit FROM _syncular_windows WHERE sub_id = ?1")?
1074 .query_map([unit_id], |row| Ok((row.get(0)?, row.get(1)?)))?
1075 .collect()
1076}
1077
1078fn reset_units(
1086 conn: &Connection,
1087 keep: &BTreeSet<String>,
1088 restrictions: Option<&BTreeMap<String, UnitRestriction>>,
1089) -> rusqlite::Result<()> {
1090 conn.execute(
1091 "UPDATE _syncular_units SET status='active', reason_code=NULL, cursor=-1,
1092 bootstrap_state=NULL, seeded='[]', applied=NULL,
1093 echo=CASE WHEN ?2 IS NULL THEN NULL ELSE echo END,
1094 restriction=(SELECT value FROM json_each(?2) WHERE key=_syncular_units.id)
1095 WHERE id NOT IN (SELECT value FROM json_each(?1))",
1096 rusqlite::params![
1097 serde_json::to_string(keep).expect("unit ids serialize"),
1098 restrictions.map(|map| serde_json::to_string(map).expect("restrictions serialize")),
1099 ],
1100 )?;
1101 conn.execute_batch(
1102 "DELETE FROM _syncular_meta WHERE key IN ('echoDigest','registrationDigest');
1103 DELETE FROM _syncular_meta WHERE key='replicaCursor'
1104 AND NOT EXISTS (SELECT 1 FROM _syncular_units WHERE cursor IS NULL);",
1105 )
1106}
1107
1108fn replica_cursor(conn: &Connection) -> rusqlite::Result<i64> {
1110 meta_get(conn, REPLICA_CURSOR_KEY)?.map_or(Ok(-1), |raw| {
1111 raw.parse().map_err(|error| {
1112 rusqlite::Error::FromSqlConversionFailure(
1113 0,
1114 rusqlite::types::Type::Text,
1115 Box::new(error),
1116 )
1117 })
1118 })
1119}
1120
1121fn visible_table(name: &str) -> String {
1122 quote_ident(name)
1123}
1124
1125const FTS_SOURCE_ID_COLUMN: &str = "_syncular_source_id";
1126
1127fn is_synced_table_name(name: &str) -> bool {
1130 if name.starts_with("sqlite_") {
1131 return false;
1132 }
1133 if name.starts_with("_syncular_base_") {
1134 return true; }
1136 !name.starts_with("_syncular_")
1138}
1139
1140fn blob_id_for(bytes: &[u8]) -> String {
1142 let digest = Sha256::digest(bytes);
1143 format!("sha256:{}", bytes_to_hex(&digest))
1144}
1145
1146enum RowParam<'a> {
1150 Cell(&'a Option<ColumnValue>),
1151 Version(i64),
1152 Text(Option<&'a str>),
1153}
1154
1155impl rusqlite::ToSql for RowParam<'_> {
1156 fn to_sql(&self) -> rusqlite::Result<ToSqlOutput<'_>> {
1157 Ok(match self {
1158 RowParam::Version(v) => ToSqlOutput::Owned(SqlValue::Integer(*v)),
1159 RowParam::Text(text) => match text {
1160 Some(text) => ToSqlOutput::Borrowed(ValueRef::Text(text.as_bytes())),
1161 None => ToSqlOutput::Owned(SqlValue::Null),
1162 },
1163 RowParam::Cell(cell) => match cell {
1164 None => ToSqlOutput::Owned(SqlValue::Null),
1165 Some(ColumnValue::String(s)) => ToSqlOutput::Borrowed(ValueRef::Text(s.as_bytes())),
1166 Some(ColumnValue::Integer(i)) => ToSqlOutput::Owned(SqlValue::Integer(*i)),
1167 Some(ColumnValue::Float(f)) => ToSqlOutput::Owned(SqlValue::Real(*f)),
1168 Some(ColumnValue::Boolean(b)) => {
1169 ToSqlOutput::Owned(SqlValue::Integer(i64::from(*b)))
1170 }
1171 Some(ColumnValue::Json(raw)) | Some(ColumnValue::BlobRef(raw)) => {
1172 ToSqlOutput::Borrowed(ValueRef::Text(raw.0.as_bytes()))
1173 }
1174 Some(ColumnValue::Bytes(b)) | Some(ColumnValue::Crdt(b)) => {
1176 ToSqlOutput::Borrowed(ValueRef::Blob(b))
1177 }
1178 },
1179 })
1180 }
1181}
1182
1183fn owned_sql_value(param: impl rusqlite::ToSql) -> Result<SqlValue, String> {
1185 match param.to_sql().map_err(|error| error.to_string())? {
1186 ToSqlOutput::Owned(value) => Ok(value),
1187 ToSqlOutput::Borrowed(value) => {
1188 SqlValue::try_from(value).map_err(|error| error.to_string())
1189 }
1190 _ => Err("sync.invalid_request: unsupported SQLite key parameter".into()),
1191 }
1192}
1193
1194fn image_cell_param<'a>(column: &Column, value: ValueRef<'a>) -> Result<ToSqlOutput<'a>, String> {
1202 use ssp2::segment::ColumnType;
1203 let mismatch = || {
1204 Err(format!(
1205 "image column {:?} holds a value of the wrong type",
1206 column.name
1207 ))
1208 };
1209 match value {
1210 ValueRef::Null => {
1211 if !column.nullable {
1212 return Err(format!(
1213 "image column {:?} is NULL but not nullable",
1214 column.name
1215 ));
1216 }
1217 Ok(ToSqlOutput::Owned(SqlValue::Null))
1218 }
1219 ValueRef::Integer(i) => match column.ty {
1220 ColumnType::Integer => Ok(ToSqlOutput::Borrowed(value)),
1221 ColumnType::Boolean => Ok(ToSqlOutput::Owned(SqlValue::Integer(i64::from(i != 0)))),
1222 ColumnType::Float => Ok(ToSqlOutput::Owned(SqlValue::Real(i as f64))),
1223 _ => mismatch(),
1224 },
1225 ValueRef::Real(_) => match column.ty {
1226 ColumnType::Float => Ok(ToSqlOutput::Borrowed(value)),
1227 _ => mismatch(),
1228 },
1229 ValueRef::Text(t) => {
1230 std::str::from_utf8(t)
1231 .map_err(|_| format!("image column {:?} is not UTF-8", column.name))?;
1232 match column.ty {
1233 ColumnType::String | ColumnType::Json | ColumnType::BlobRef => {
1234 Ok(ToSqlOutput::Borrowed(value))
1235 }
1236 _ => mismatch(),
1237 }
1238 }
1239 ValueRef::Blob(_) => match column.ty {
1240 ColumnType::Bytes | ColumnType::Crdt => Ok(ToSqlOutput::Borrowed(value)),
1242 _ => mismatch(),
1243 },
1244 }
1245}
1246
1247pub(crate) fn sql_ref_to_json(column: &Column, value: rusqlite::types::ValueRef<'_>) -> Value {
1248 use rusqlite::types::ValueRef;
1249 match value {
1250 ValueRef::Null => Value::Null,
1251 ValueRef::Integer(i) => match column.ty {
1252 ssp2::segment::ColumnType::Boolean => Value::Bool(i != 0),
1253 ssp2::segment::ColumnType::Float => {
1254 serde_json::Number::from_f64(i as f64).map_or(Value::Null, Value::Number)
1255 }
1256 _ => Value::from(i),
1257 },
1258 ValueRef::Real(f) => serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number),
1259 ValueRef::Text(t) => Value::from(String::from_utf8_lossy(t).into_owned()),
1260 ValueRef::Blob(b) => {
1261 let mut map = Map::new();
1262 map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(b)));
1263 Value::Object(map)
1264 }
1265 }
1266}
1267
1268fn json_param_to_sql(value: &Value) -> Result<SqlValue, String> {
1272 Ok(match value {
1273 Value::Null => SqlValue::Null,
1274 Value::Bool(b) => SqlValue::Integer(i64::from(*b)),
1275 Value::Number(n) => {
1276 if let Some(i) = n.as_i64() {
1277 SqlValue::Integer(i)
1278 } else if let Some(f) = n.as_f64() {
1279 SqlValue::Real(f)
1280 } else {
1281 return Err(format!("query param number {n} is out of range"));
1282 }
1283 }
1284 Value::String(s) => SqlValue::Text(s.clone()),
1285 Value::Object(_) => {
1286 if let Some(hex) = value.get("$bytes").and_then(Value::as_str) {
1287 SqlValue::Blob(crate::values::hex_to_bytes(hex)?)
1288 } else if let Some(decimal) = value.get("$bigint").and_then(Value::as_str) {
1289 SqlValue::Integer(decimal.parse::<i64>().map_err(|_| {
1290 format!("query bigint param {decimal:?} is outside SQLite's i64 range")
1291 })?)
1292 } else {
1293 return Err(
1294 "query object param must be a {$bytes: hex} or {$bigint: decimal} value"
1295 .to_owned(),
1296 );
1297 }
1298 }
1299 Value::Array(_) => return Err("query array params are not supported".to_owned()),
1300 })
1301}
1302
1303fn sql_ref_to_json_dynamic(value: rusqlite::types::ValueRef<'_>) -> Value {
1308 use rusqlite::types::ValueRef;
1309 match value {
1310 ValueRef::Null => Value::Null,
1311 ValueRef::Integer(i) => {
1312 const MAX_SAFE_INTEGER: i64 = 9_007_199_254_740_991;
1316 if (-MAX_SAFE_INTEGER..=MAX_SAFE_INTEGER).contains(&i) {
1317 Value::from(i)
1318 } else {
1319 let mut map = Map::new();
1320 map.insert("$bigint".to_owned(), Value::from(i.to_string()));
1321 Value::Object(map)
1322 }
1323 }
1324 ValueRef::Real(f) => serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number),
1325 ValueRef::Text(t) => Value::from(String::from_utf8_lossy(t).into_owned()),
1326 ValueRef::Blob(b) => {
1327 let mut map = Map::new();
1328 map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(b)));
1329 Value::Object(map)
1330 }
1331 }
1332}
1333
1334fn query_connection(
1336 conn: &Connection,
1337 sql: &str,
1338 params: &[QueryValue],
1339) -> Result<Vec<QueryRow>, QueryReadFailure> {
1340 let lowered_sql = crate::query_guard::lower_public_query_sql(sql);
1341 let mut stmt = crate::query_guard::prepare_read_only(conn, &lowered_sql)?;
1342 let bound: Vec<SqlValue> = params
1343 .iter()
1344 .map(json_param_to_sql)
1345 .collect::<Result<_, _>>()?;
1346 let columns: Vec<(usize, String)> = stmt
1351 .column_names()
1352 .enumerate()
1353 .filter(|(_, name)| {
1354 !matches!(
1355 *name,
1356 "_syncular_version" | "_sync_sealed_key" | "_sync_sealed"
1357 )
1358 })
1359 .map(|(i, name)| (i, name.to_owned()))
1360 .collect();
1361 let bound_refs: Vec<&dyn rusqlite::ToSql> =
1362 bound.iter().map(|v| v as &dyn rusqlite::ToSql).collect();
1363 let mut sql_rows = stmt.query(bound_refs.as_slice())?;
1364 let mut out = Vec::new();
1365 while let Some(row) = sql_rows.next()? {
1366 let mut record = Map::new();
1367 for (i, name) in &columns {
1368 let value = row.get_ref(*i)?;
1369 record.insert(name.clone(), sql_ref_to_json_dynamic(value));
1370 }
1371 out.push(record);
1372 }
1373 Ok(out)
1374}
1375
1376fn persisted_window_state(
1377 conn: &Connection,
1378 base: &WindowBase,
1379) -> Result<WindowState, QueryReadFailure> {
1380 let mut stmt = conn.prepare(
1381 "SELECT windows.unit, units.status, units.cursor, units.bootstrap_state
1382 FROM _syncular_windows AS windows
1383 LEFT JOIN _syncular_units AS units ON units.id = windows.sub_id
1384 WHERE windows.base = ?1
1385 ORDER BY windows.unit ASC",
1386 )?;
1387 let rows = stmt.query_map(rusqlite::params![window_base_key(base)], |row| {
1388 Ok((
1389 row.get::<_, String>(0)?,
1390 row.get::<_, Option<String>>(1)?,
1391 row.get::<_, Option<i64>>(2)?,
1392 row.get::<_, Option<String>>(3)?,
1393 ))
1394 })?;
1395 let mut units = Vec::new();
1396 let mut pending = Vec::new();
1397 for row in rows {
1398 let (unit, status, cursor, bootstrap_state) = row?;
1399 if status.as_deref() != Some("active")
1401 || cursor.is_some_and(|cursor| cursor < 0 || bootstrap_state.is_some())
1402 {
1403 pending.push(unit.clone());
1404 }
1405 units.push(unit);
1406 }
1407 Ok(WindowState { units, pending })
1408}
1409
1410#[derive(Debug, Clone, Copy)]
1412pub struct SnapshotStatement<'a> {
1413 pub sql: &'a str,
1414 pub params: &'a [Value],
1415}
1416
1417#[derive(Debug, Clone, Default)]
1421pub struct SnapshotReadRequest<'a> {
1422 pub statements: Vec<SnapshotStatement<'a>>,
1423 pub coverage: &'a [WindowCoverage],
1424 pub units: Vec<String>,
1425 pub commit_ids: Vec<String>,
1426}
1427
1428#[cfg(test)]
1429thread_local! {
1430 static SNAPSHOT_READ_HOOK: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
1434 std::cell::RefCell::new(None);
1435}
1436
1437#[cfg(test)]
1438fn run_snapshot_read_hook() {
1439 SNAPSHOT_READ_HOOK.with(|slot| {
1440 if let Some(hook) = slot.borrow_mut().take() {
1441 hook();
1442 }
1443 });
1444}
1445
1446fn snapshot_read_connection(
1451 conn: &Connection,
1452 request: &SnapshotReadRequest<'_>,
1453) -> Result<SnapshotRead, QueryReadFailure> {
1454 conn.execute_batch("SAVEPOINT syncular_snapshot_read")?;
1455 let corrupt = |message: &str| QueryReadFailure {
1456 code: Some("sync.local_corrupt"),
1457 sqlite_code: None,
1458 sqlite_message: None,
1459 rollback_failure: None,
1460 message: message.to_owned(),
1461 };
1462 let stored_failure = |error: rusqlite::Error, message: &str| match error {
1463 rusqlite::Error::Utf8Error(..)
1464 | rusqlite::Error::InvalidColumnType(..)
1465 | rusqlite::Error::FromSqlConversionFailure(..)
1466 | rusqlite::Error::IntegralValueOutOfRange(..) => corrupt(message),
1467 _ => QueryReadFailure::from(error),
1468 };
1469 let result: Result<SnapshotRead, QueryReadFailure> = (|| {
1470 let revision: Option<String> = conn
1473 .query_row(
1474 "SELECT value FROM _syncular_meta WHERE key = ?1",
1475 rusqlite::params![LOCAL_REVISION_KEY],
1476 |row| row.get(0),
1477 )
1478 .optional()
1479 .map_err(|error| stored_failure(error, "persisted local revision is invalid"))?;
1480 let revision = match revision {
1481 None => "0".to_owned(),
1482 Some(value)
1483 if value == "0"
1484 || (matches!(value.as_bytes().first(), Some(b'1'..=b'9'))
1485 && value.bytes().all(|b| b.is_ascii_digit())
1486 && value.parse::<u64>().is_ok()) =>
1487 {
1488 value
1489 }
1490 Some(_) => return Err(corrupt("persisted local revision is invalid")),
1491 };
1492 let mut queries = Vec::with_capacity(request.statements.len());
1493 for statement in &request.statements {
1494 queries.push(query_connection(conn, statement.sql, statement.params)?);
1495 #[cfg(test)]
1496 run_snapshot_read_hook();
1497 }
1498 let mut pending = Vec::new();
1499 let mut missing = Vec::new();
1500 for requested in request.coverage {
1501 let base_key = window_base_key(&requested.base);
1502 let state = persisted_window_state(conn, &requested.base)?;
1503 for unit in BTreeSet::from_iter(requested.units.iter().cloned()) {
1504 let reference = WindowUnitRef {
1505 base_key: base_key.clone(),
1506 unit: unit.clone(),
1507 };
1508 if !state.units.iter().any(|held| held == &unit) {
1509 missing.push(reference);
1510 } else if state.pending.iter().any(|held| held == &unit) {
1511 pending.push(reference);
1512 }
1513 }
1514 }
1515 let mut units = Vec::with_capacity(request.units.len());
1516 for id in &request.units {
1517 let exists: bool = conn.query_row(
1518 "SELECT EXISTS(SELECT 1 FROM _syncular_units WHERE id = ?1)",
1519 [id],
1520 |row| row.get(0),
1521 )?;
1522 if !exists {
1523 units.push(UnitCatchup::Unknown { id: id.clone() });
1524 continue;
1525 }
1526 let unit = get_unit(conn, id)
1529 .map_err(|error| stored_failure(error, "persisted unit state is invalid"))?
1530 .ok_or_else(|| corrupt("persisted unit state is invalid"))?;
1531 let cursor = match unit.cursor {
1532 Some(cursor) => cursor,
1533 None => replica_cursor(conn)
1534 .map_err(|error| stored_failure(error, "persisted unit state is invalid"))?,
1535 };
1536 if cursor.unsigned_abs() > MAX_JS_SAFE_INTEGER {
1537 return Err(corrupt("persisted unit state is invalid"));
1538 }
1539 let active = unit.status == UnitStatus::Active;
1540 let pending = unit.bootstrapping();
1541 units.push(UnitCatchup::Known {
1542 id: id.clone(),
1543 status: unit.status,
1544 live: unit.cursor.is_none(),
1545 cursor,
1546 has_resume_token: unit.bootstrap_state.is_some(),
1547 bootstrap_complete: active && !pending,
1548 known_pending_pages: active && pending,
1549 reason_code: unit.reason_code,
1550 });
1551 }
1552 let mut deliveries = Vec::with_capacity(request.commit_ids.len());
1553 for id in &request.commit_ids {
1554 let pending: bool = conn.query_row(
1555 "SELECT EXISTS(SELECT 1 FROM _syncular_outbox WHERE commit_id = ?1)",
1556 rusqlite::params![id],
1557 |row| row.get(0),
1558 )?;
1559 if pending {
1560 deliveries.push(CommitDelivery::Pending {
1561 client_commit_id: id.clone(),
1562 });
1563 continue;
1564 }
1565 let row = conn
1566 .query_row(
1567 "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
1568 resolution, resolved_at_ms, replacement_client_commit_id
1569 FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
1570 rusqlite::params![id],
1571 StoredCommitOutcomeRow::from_row,
1572 )
1573 .optional()
1574 .map_err(|error| stored_failure(error, "persisted commit outcome is invalid"))?;
1575 deliveries.push(match row {
1576 Some(row) => CommitDelivery::Known {
1577 client_commit_id: id.clone(),
1578 outcome: SyncClient::outcome_from_row(row)
1579 .map_err(|_| corrupt("persisted commit outcome is invalid"))?,
1580 },
1581 None => CommitDelivery::Unknown {
1582 client_commit_id: id.clone(),
1583 },
1584 });
1585 }
1586 Ok(SnapshotRead {
1587 revision,
1588 queries,
1589 coverage: CoverageSnapshot {
1590 complete: pending.is_empty() && missing.is_empty(),
1591 pending,
1592 missing,
1593 },
1594 units,
1595 deliveries,
1596 })
1597 })();
1598 match result {
1599 Ok(read) => {
1600 conn.execute_batch("RELEASE syncular_snapshot_read")?;
1601 Ok(read)
1602 }
1603 Err(mut error) => {
1604 if let Err(rollback) = conn
1605 .execute_batch("ROLLBACK TO syncular_snapshot_read; RELEASE syncular_snapshot_read")
1606 {
1607 error.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
1608 }
1609 Err(error)
1610 }
1611 }
1612}
1613
1614fn snapshot_connection(
1615 conn: &Connection,
1616 sql: &str,
1617 params: &[Value],
1618 coverage: &[WindowCoverage],
1619) -> Result<QuerySnapshot, QueryReadFailure> {
1620 let read = snapshot_read_connection(
1621 conn,
1622 &SnapshotReadRequest {
1623 statements: vec![SnapshotStatement { sql, params }],
1624 coverage,
1625 units: Vec::new(),
1626 commit_ids: Vec::new(),
1627 },
1628 )?;
1629 Ok(QuerySnapshot {
1630 revision: read.revision,
1631 rows: read
1632 .queries
1633 .into_iter()
1634 .next()
1635 .expect("single-query snapshot returns one result"),
1636 coverage: read.coverage,
1637 })
1638}
1639
1640pub struct FileQuerySnapshotReader {
1645 path: String,
1646 conn: Option<Connection>,
1647}
1648
1649impl FileQuerySnapshotReader {
1650 #[must_use]
1651 pub fn new(path: impl Into<String>) -> Self {
1652 Self {
1653 path: path.into(),
1654 conn: None,
1655 }
1656 }
1657
1658 fn connection(&mut self) -> Result<&Connection, QueryReadFailure> {
1659 if self.conn.is_none() {
1660 let conn = Connection::open_with_flags(
1661 &self.path,
1662 OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
1663 )
1664 .map_err(QueryReadFailure::from)?;
1665 conn.busy_timeout(std::time::Duration::from_millis(250))
1666 .map_err(QueryReadFailure::from)?;
1667 self.conn = Some(conn);
1668 }
1669 self.conn
1670 .as_ref()
1671 .ok_or_else(|| QueryReadFailure::from("read sidecar connection missing".to_owned()))
1672 }
1673
1674 pub fn snapshot_read(
1677 &mut self,
1678 request: &SnapshotReadRequest<'_>,
1679 ) -> Result<SnapshotRead, QueryReadFailure> {
1680 snapshot_read_connection(self.connection()?, request)
1681 }
1682
1683 pub fn local_revision(&mut self) -> Result<String, QueryReadFailure> {
1686 Ok(self
1687 .snapshot_read(&SnapshotReadRequest::default())?
1688 .revision)
1689 }
1690
1691 pub fn unit_catchup(&mut self, id: &str) -> Result<UnitCatchup, QueryReadFailure> {
1693 let read = self.snapshot_read(&SnapshotReadRequest {
1694 units: vec![id.to_owned()],
1695 ..Default::default()
1696 })?;
1697 Ok(read
1698 .units
1699 .into_iter()
1700 .next()
1701 .expect("one requested catch-up"))
1702 }
1703
1704 pub fn commit_delivery(&mut self, id: &str) -> Result<CommitDelivery, QueryReadFailure> {
1707 let read = self.snapshot_read(&SnapshotReadRequest {
1708 commit_ids: vec![id.to_owned()],
1709 ..Default::default()
1710 })?;
1711 Ok(read
1712 .deliveries
1713 .into_iter()
1714 .next()
1715 .expect("one requested delivery"))
1716 }
1717
1718 pub fn query_snapshot(
1721 &mut self,
1722 sql: &str,
1723 params: &[Value],
1724 coverage: &[WindowCoverage],
1725 ) -> Result<QuerySnapshot, QueryReadFailure> {
1726 snapshot_connection(self.connection()?, sql, params, coverage)
1727 }
1728}
1729
1730fn validate_authority_reads(
1731 schema: &ClientSchema,
1732 declarations: &[crate::api::AuthorityReadDeclaration],
1733) -> Result<(), String> {
1734 let mut seen = BTreeSet::new();
1735 for read in declarations {
1736 let table = schema
1737 .table(&read.table)
1738 .ok_or("client.authority_read_forbidden: authority table is not declared")?;
1739 let plain = |name: &str| {
1740 table.columns.iter().enumerate().any(|(i, c)| {
1741 c.name == name
1742 && name != "authority_version"
1743 && !name.starts_with("_sync")
1744 && !table.encrypted_columns.iter().any(|e| e.index == i)
1745 && matches!(
1746 c.ty,
1747 ssp2::segment::ColumnType::String
1748 | ssp2::segment::ColumnType::Integer
1749 | ssp2::segment::ColumnType::Float
1750 | ssp2::segment::ColumnType::Boolean
1751 | ssp2::segment::ColumnType::Json
1752 )
1753 })
1754 };
1755 if !seen.insert(&read.table)
1756 || read.columns.is_empty()
1757 || read.columns.iter().collect::<BTreeSet<_>>().len() != read.columns.len()
1758 || !read.columns.contains(&table.primary_key)
1759 || !read.columns.iter().all(|c| plain(c))
1760 || read.scopes.is_empty()
1761 || !read.scopes.iter().all(|(v, values)| {
1762 table
1763 .scope_column(v)
1764 .is_some_and(|c| read.columns.iter().any(|column| column == c) && plain(c))
1765 && !values.is_empty()
1766 && values.iter().all(|v| !v.is_empty() && v != "*")
1767 })
1768 {
1769 return Err("client.authority_read_forbidden: authority reads require plain columns, a primary key and nonempty plain scope selectors".into());
1770 }
1771 }
1772 Ok(())
1773}
1774
1775fn schema_marker_read_failure(error: rusqlite::Error) -> String {
1780 let failure = QueryReadFailure::from(error);
1781 if failure.code.is_some() {
1782 failure.to_string()
1783 } else {
1784 "sync.local_corrupt: persisted local schema marker is unreadable or invalid".to_owned()
1785 }
1786}
1787
1788fn validate_client_limits(limits: &crate::api::ClientLimits) -> Result<(), String> {
1792 if limits.outcome_retention_max_entries == Some(0) {
1793 return Err("sync.invalid_request: outcomeRetentionMaxEntries must be positive".to_owned());
1794 }
1795 if [
1796 limits.max_push_commits_per_request,
1797 limits.max_push_operations_per_request,
1798 limits.max_push_request_bytes,
1799 ]
1800 .into_iter()
1801 .flatten()
1802 .any(|value| value == 0 || value > u32::MAX as usize)
1803 {
1804 return Err(
1805 "sync.invalid_request: push limit must be an integer in 1..=4294967295".to_owned(),
1806 );
1807 }
1808 Ok(())
1809}
1810
1811fn read_local_schema_version(conn: &Connection, requested: i32) -> Result<Option<i32>, String> {
1812 let corrupt =
1813 || "sync.local_corrupt: persisted local schema marker is unreadable or invalid".to_owned();
1814 let table_type: Option<String> = conn
1815 .query_row(
1816 "SELECT type FROM sqlite_master WHERE name = '_syncular_meta'",
1817 [],
1818 |row| row.get(0),
1819 )
1820 .optional()
1821 .map_err(schema_marker_read_failure)?;
1822 let Some(table_type) = table_type else {
1823 return Ok(None);
1824 };
1825 if table_type != "table" {
1826 return Err(corrupt());
1827 }
1828 let mut statement = conn
1832 .prepare("SELECT value FROM _syncular_meta WHERE key = ?1")
1833 .map_err(schema_marker_read_failure)?;
1834 let mut rows = statement
1835 .query([LOCAL_SCHEMA_VERSION_KEY])
1836 .map_err(schema_marker_read_failure)?;
1837 let value: Option<String> = rows
1838 .next()
1839 .map_err(schema_marker_read_failure)?
1840 .map(|row| row.get(0))
1841 .transpose()
1842 .map_err(schema_marker_read_failure)?;
1843 if rows.next().map_err(schema_marker_read_failure)?.is_some() {
1844 return Err(corrupt());
1845 }
1846 let Some(value) = value else {
1847 let has_descriptor = conn
1848 .query_row(
1849 "SELECT 1 FROM _syncular_meta WHERE key = ?1 LIMIT 1",
1850 [crate::previous_version::LOCAL_SCHEMA_DESCRIPTOR_KEY],
1851 |_| Ok(()),
1852 )
1853 .optional()
1854 .map_err(schema_marker_read_failure)?
1855 .is_some();
1856 if has_descriptor {
1857 return Err(corrupt());
1858 }
1859 return Ok(None);
1860 };
1861 if !matches!(value.as_bytes().first(), Some(b'1'..=b'9'))
1862 || !value.bytes().all(|b| b.is_ascii_digit())
1863 {
1864 return Err(corrupt());
1865 }
1866 let version = value.parse::<i32>().map_err(|_| corrupt())?;
1867 if version > requested {
1868 return Err(
1869 "client.schema_downgrade: persisted local schema is newer than the requested schema"
1870 .to_owned(),
1871 );
1872 }
1873 Ok(Some(version))
1874}
1875
1876fn open_replica(path: &str) -> Result<Connection, String> {
1884 let browser = cfg!(all(target_arch = "wasm32", target_os = "unknown"))
1885 && !path.is_empty()
1886 && path != ":memory:";
1887 #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
1888 if browser {
1889 crate::wasm_vfs::disable_foreign_lock_check()?;
1890 }
1891 let conn = Connection::open(path).map_err(|e| format!("open db {path:?}: {e}"))?;
1892 if browser {
1893 conn.execute_batch("PRAGMA page_size = 65536; PRAGMA cache_size = -65536")
1894 .map_err(|e| format!("open db {path:?}: {e}"))?;
1895 }
1896 Ok(conn)
1897}
1898
1899impl SyncClient {
1900 pub fn new_with_identity(
1901 client_id: Option<String>,
1902 schema_json: &Value,
1903 limits: ClientLimits,
1904 ) -> Result<Self, String> {
1905 let resolved = client_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
1906 let conn = Connection::open_in_memory().map_err(|e| e.to_string())?;
1907 Self::with_connection(resolved, schema_json, limits, conn)
1908 }
1909
1910 pub fn new(
1911 client_id: String,
1912 schema_json: &Value,
1913 limits: ClientLimits,
1914 ) -> Result<Self, String> {
1915 let conn = Connection::open_in_memory().map_err(|e| e.to_string())?;
1916 Self::with_connection(client_id, schema_json, limits, conn)
1917 }
1918
1919 pub fn open_path(
1925 client_id: String,
1926 schema_json: &Value,
1927 limits: ClientLimits,
1928 path: &str,
1929 ) -> Result<Self, String> {
1930 validate_client_limits(&limits)?;
1931 parse_schema_json(schema_json)?;
1932 let conn = open_replica(path)?;
1933 Self::with_connection(client_id, schema_json, limits, conn)
1934 }
1935
1936 pub fn open_path_with_identity(
1940 client_id: Option<String>,
1941 schema_json: &Value,
1942 limits: ClientLimits,
1943 path: &str,
1944 ) -> Result<Self, String> {
1945 Self::open_path_with_identity_journal(
1946 client_id,
1947 schema_json,
1948 limits,
1949 path,
1950 !cfg!(all(target_arch = "wasm32", target_os = "unknown")),
1951 )
1952 }
1953
1954 fn open_path_with_identity_journal(
1955 client_id: Option<String>,
1956 schema_json: &Value,
1957 limits: ClientLimits,
1958 path: &str,
1959 require_wal: bool,
1960 ) -> Result<Self, String> {
1961 validate_client_limits(&limits)?;
1962 parse_schema_json(schema_json)?;
1965 let conn = open_replica(path)?;
1966 conn.busy_timeout(std::time::Duration::from_millis(250))
1974 .map_err(|error| format!("configure db {path:?} busy timeout: {error}"))?;
1975 conn.pragma_update(None, "synchronous", "FULL")
1980 .map_err(|error| format!("configure db {path:?} synchronous: {error}"))?;
1981 let client = Self::with_connection_identity(client_id, schema_json, limits, conn)?;
1982 if require_wal {
1986 let journal_mode: String = client
1987 .conn
1988 .pragma_update_and_check(None, "journal_mode", "WAL", |row| row.get(0))
1989 .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
1990 if journal_mode != "wal" {
1991 return Err(
1992 "sync.invalid_request: file-backed client requires WAL journal mode".to_owned(),
1993 );
1994 }
1995 }
1996 Ok(client)
1997 }
1998
1999 pub fn reset_replica(path: &str) -> Result<(), String> {
2013 if path.is_empty() || path == ":memory:" {
2014 return Err("sync.invalid_request: a memory replica has nothing to reset".to_owned());
2015 }
2016 let vfs = unsafe { rusqlite::ffi::sqlite3_vfs_find(std::ptr::null()) };
2020 if vfs.is_null() {
2021 return Err("client.storage_io: no SQLite VFS is registered".to_owned());
2022 }
2023 let delete = unsafe { (*vfs).xDelete }
2024 .ok_or_else(|| "client.storage_io: the SQLite VFS cannot delete files".to_owned())?;
2025 for suffix in ["-wal", "-shm", "-journal", ""] {
2026 let file_name = format!("{path}{suffix}");
2027 let c_name = std::ffi::CString::new(file_name.as_str()).map_err(|_| {
2028 format!("sync.invalid_request: replica path {file_name:?} contains a NUL byte")
2029 })?;
2030 let code = unsafe { delete(vfs, c_name.as_ptr(), 1) };
2033 if code != rusqlite::ffi::SQLITE_OK && code != rusqlite::ffi::SQLITE_IOERR_DELETE_NOENT
2036 {
2037 return Err(format!(
2038 "client.storage_io: deleting replica file {file_name:?} failed with SQLite code {code}"
2039 ));
2040 }
2041 }
2042 Ok(())
2043 }
2044
2045 #[must_use]
2046 pub fn client_id(&self) -> &str {
2047 &self.client_id
2048 }
2049
2050 pub fn reset_client_id(&mut self, transport: &mut dyn Transport) -> Result<String, String> {
2057 self.disconnect_realtime(transport);
2058 let client_id = uuid::Uuid::new_v4().to_string();
2059 self.set_meta(CLIENT_ID_KEY, &client_id)?;
2060 self.client_id.clone_from(&client_id);
2061 self.round_failure = None;
2062 Ok(client_id)
2063 }
2064
2065 pub fn with_connection(
2072 client_id: String,
2073 schema_json: &Value,
2074 limits: ClientLimits,
2075 conn: Connection,
2076 ) -> Result<Self, String> {
2077 Self::with_connection_identity(Some(client_id), schema_json, limits, conn)
2078 }
2079
2080 fn with_connection_identity(
2083 client_id: Option<String>,
2084 schema_json: &Value,
2085 limits: ClientLimits,
2086 conn: Connection,
2087 ) -> Result<Self, String> {
2088 validate_client_limits(&limits)?;
2089 let schema = parse_schema_json(schema_json)?;
2090 validate_authority_reads(&schema, &limits.authority_reads)?;
2091 let previous_version = match limits.previous_version_context {
2094 Some(config) => {
2095 config.validate()?;
2096 Some(config)
2097 }
2098 None => None,
2099 };
2100 let mut client = SyncClient {
2101 #[cfg(feature = "bench-internals")]
2102 benchmark_phases: Recorder::default(),
2103 conn,
2104 schema,
2105 client_id: client_id
2106 .clone()
2107 .unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
2108 limits,
2109 outbox: Shared::default(),
2110 failed_commits: Shared::default(),
2111 retain_failed_commits: false,
2112 conflicts: Shared::default(),
2113 rejections: Shared::default(),
2114 schema_floor: None,
2115 lease_state: None,
2116 stopped: false,
2117 upgrading: false,
2118 sync_needed: false,
2119 realtime_policy: RealtimePolicy::Optional,
2120 realtime_state: RealtimeState::Disconnected,
2121 realtime_reason_code: None,
2122 realtime_retry_delay_ms: None,
2123 presence: HashMap::new(),
2124 now_ms: None,
2125 encryption: crate::values::EncryptionConfig::default(),
2126 security_preflight: false,
2127 security_epoch: 0,
2128 transport_enabled: true,
2129 transport_epoch: 0,
2130 registration_epoch: 0,
2131 previous_version,
2132 insert_sql: RefCell::new(HashMap::new()),
2133 overlay_dirty: OverlayDirty::clean(),
2134 storage_failure: RefCell::new(None),
2135 #[cfg(test)]
2136 overlay_rebuild_count: Cell::new(0),
2137 #[cfg(test)]
2138 acknowledged_replay_count: Cell::new(0),
2139 #[cfg(test)]
2140 outcome_prune_count: Cell::new(0),
2141 #[cfg(test)]
2142 image_chunk_ms: Cell::new(None),
2143 progress: ProgressObserver::default(),
2144 epoch: uuid::Uuid::new_v4().to_string(),
2145 change_queue: VecDeque::new(),
2146 sync_intent_queue: VecDeque::new(),
2147 scopes_changed: 0,
2148 retry_delay_ms: 250,
2149 round_retry_delay_ms: None,
2150 image_chunk_rows: HashMap::new(),
2151 round_failure: None,
2152 active_round: None,
2153 last_round: None,
2154 last_change: None,
2155 query_failures: Vec::new(),
2156 coalesced: None,
2157 coalesced_failure: None,
2158 };
2159 client
2163 .conn
2164 .set_prepared_statement_cache_capacity(64.max(client.schema.tables.len() * 4));
2165 client
2171 .conn
2172 .execute_batch("BEGIN IMMEDIATE")
2173 .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
2174 let startup = (|| -> Result<(), String> {
2175 let marker = read_local_schema_version(&client.conn, client.schema.version)?;
2178 client.create_bookkeeping_tables()?;
2181 match client.get_meta(CLIENT_ID_KEY)? {
2182 Some(existing) => match client_id {
2183 Some(requested) if existing != requested => {
2184 return Err(format!(
2185 "client.identity_mismatch: this database belongs to {existing:?}; refusing to rebind it to {requested:?}"
2186 ))
2187 }
2188 _ => client.client_id = existing,
2189 },
2190 None => client.set_meta(CLIENT_ID_KEY, &client.client_id)?,
2191 }
2192 client.restore_persisted_state()?;
2193 client.failed_commits = client.load_failed_commits()?.into();
2194 match marker {
2195 None => {
2196 client.create_synced_tables()?;
2197 client.persist_schema_version()?;
2198 client.save_unit_scope_schema()?;
2199 }
2200 Some(version) if version == client.schema.version => {
2201 client.create_synced_tables()?;
2202 set_local_schema_descriptor(&client.conn, &client.schema)
2206 .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
2207 client.save_unit_scope_schema()?;
2208 }
2209 Some(_) => client.run_schema_reset()?,
2210 }
2211 client.reconcile_previous_version_at_boot()?;
2217 client.clear_satisfied_persisted_schema_floor()?;
2218 client.prune_unknown_units(false)?;
2219 client.drop_unencodable_outbox(false, None)?;
2228 if marker == Some(client.schema.version)
2229 && (!client.outbox.is_empty()
2230 || !client.failed_commits.is_empty()
2231 || client.has_acknowledged_rows()?)
2232 {
2233 client.overlay_dirty.set(true);
2237 client.rebuild_overlay()?;
2238 }
2239 client.enqueue_startup_sync_if_needed()?;
2246 Ok(())
2247 })();
2248 match startup {
2249 Ok(()) => match client.conn.execute_batch("COMMIT") {
2250 Ok(()) => {
2254 if !client.security_preflight {
2255 client.drain_pending_evictions()?;
2256 }
2257 Ok(client)
2258 }
2259 Err(error) => {
2260 let failure = Self::sqlite_failure(&client.storage_failure, error);
2261 if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2262 let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2264 }
2265 Err(failure)
2266 }
2267 },
2268 Err(error) => {
2269 if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2270 let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2272 }
2273 Err(error)
2274 }
2275 }
2276 }
2277
2278 pub fn set_now_ms(&mut self, now_ms: i64) {
2281 self.now_ms = Some(std::sync::Arc::new(now_ms.into()));
2282 }
2283
2284 pub fn pinned_clock(&self) -> Option<std::sync::Arc<std::sync::atomic::AtomicI64>> {
2287 self.now_ms.clone()
2288 }
2289
2290 pub fn set_encryption(&mut self, encryption: crate::values::EncryptionConfig) {
2294 self.encryption = encryption;
2295 }
2296
2297 #[must_use]
2298 pub fn security_lifecycle(&self) -> &'static str {
2299 if self.security_preflight {
2300 "preflight"
2301 } else {
2302 "active"
2303 }
2304 }
2305
2306 #[must_use]
2307 pub fn security_preflight(&self) -> bool {
2308 self.security_preflight
2309 }
2310
2311 pub fn set_transport_enabled(&mut self, transport: &mut dyn Transport, enabled: bool) {
2313 if self.transport_enabled != enabled {
2314 self.transport_enabled = enabled;
2315 self.transport_epoch = self.transport_epoch.wrapping_add(1);
2316 self.sync_intent_queue.clear();
2317 self.sync_intent_queue
2318 .push_back(if enabled && !self.security_preflight {
2319 SyncIntent::Interactive
2320 } else {
2321 SyncIntent::None
2322 });
2323 }
2324 if !enabled && self.active_round.is_none() {
2326 self.disconnect_realtime(transport);
2327 }
2328 }
2329
2330 pub fn transport_enabled(&self) -> bool {
2331 self.transport_enabled
2332 }
2333
2334 pub fn begin_security_preflight(&mut self) -> Result<(), String> {
2341 let entering = !self.security_preflight;
2342 self.seal_security_on_teardown();
2343 self.set_meta(SECURITY_PREFLIGHT_PENDING_KEY, "1")?;
2346 if entering {
2347 self.emit_status_batch()?;
2348 }
2349 Ok(())
2350 }
2351
2352 fn emit_status_batch(&mut self) -> Result<(), String> {
2354 self.begin_observation("syncular_status")?;
2355 let batch = ChangeAccumulator {
2356 status: true,
2357 ..ChangeAccumulator::default()
2358 };
2359 self.finish_observation("syncular_status", batch)
2360 .inspect_err(|_| self.rollback_observation("syncular_status"))
2361 }
2362
2363 pub fn seal_security_on_teardown(&mut self) {
2373 self.cancel_sync_round();
2374 self.security_preflight = true;
2375 self.security_epoch = self.security_epoch.wrapping_add(1);
2376 self.encryption = crate::values::EncryptionConfig::default();
2377 self.sync_intent_queue.clear();
2378 }
2379
2380 pub fn activate_security(
2382 &mut self,
2383 encryption: crate::values::EncryptionConfig,
2384 ) -> Result<(), String> {
2385 if !self.security_preflight {
2386 return Err(
2387 "sync.invalid_request: activateSecurity requires security preflight".to_owned(),
2388 );
2389 }
2390 self.drain_pending_evictions()?;
2392 self.enqueue_startup_sync_if_needed()?;
2393 self.delete_meta(SECURITY_PREFLIGHT_PENDING_KEY)?;
2394 self.encryption = encryption;
2395 self.security_preflight = false;
2396 self.reveal_sealed_rows()
2398 .map_err(|error| format!("{}: {}", error.code, error.message))?;
2399 self.emit_status_batch()
2400 }
2401
2402 fn clock_now_ms(&self) -> i64 {
2403 self.now_ms
2404 .as_ref()
2405 .map_or_else(crate::wall_clock_ms, |clock| {
2406 clock.load(std::sync::atomic::Ordering::Relaxed)
2407 })
2408 }
2409
2410 fn create_bookkeeping_tables(&self) -> Result<(), String> {
2411 let exists = |name: &str| {
2412 self.conn
2413 .query_row(
2414 "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?1)",
2415 [name],
2416 |row| row.get::<_, bool>(0),
2417 )
2418 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2419 };
2420 let outbox_existed = exists("_syncular_outbox")?;
2421 self.conn
2423 .execute_batch(
2424 "CREATE TABLE IF NOT EXISTS _syncular_outbox (
2425 seq INTEGER PRIMARY KEY AUTOINCREMENT,
2426 commit_id TEXT NOT NULL UNIQUE, ops_json TEXT NOT NULL,
2427 created_at_ms INTEGER NOT NULL DEFAULT 0);
2428 CREATE TABLE IF NOT EXISTS _syncular_row_deliveries (
2429 tbl TEXT NOT NULL, id TEXT NOT NULL, commit_seq INTEGER NOT NULL, PRIMARY KEY(tbl,id));
2430 CREATE TABLE IF NOT EXISTS _syncular_acked_rows (
2431 commit_id TEXT NOT NULL, idx INTEGER NOT NULL, tbl TEXT NOT NULL, id TEXT NOT NULL,
2432 commit_seq INTEGER NOT NULL, op_json TEXT NOT NULL, intent_json TEXT,
2433 PRIMARY KEY(commit_id, idx));
2434 CREATE INDEX IF NOT EXISTS _syncular_acked_rows_row
2435 ON _syncular_acked_rows(tbl, id);
2436 CREATE TABLE IF NOT EXISTS _syncular_failed_commits (
2437 seq INTEGER PRIMARY KEY AUTOINCREMENT, client_commit_id TEXT NOT NULL UNIQUE,
2438 operations_json TEXT NOT NULL, initial_json TEXT NOT NULL);
2439 CREATE TABLE IF NOT EXISTS _syncular_commit_outcomes (
2440 seq INTEGER PRIMARY KEY AUTOINCREMENT,
2441 client_commit_id TEXT NOT NULL UNIQUE,
2442 status TEXT NOT NULL CHECK(status IN ('applied', 'cached', 'conflict', 'rejected')),
2443 recorded_at_ms INTEGER NOT NULL,
2444 results_json TEXT NOT NULL,
2445 operations_json TEXT,
2446 resolution TEXT NOT NULL DEFAULT 'active'
2447 CHECK(resolution IN ('active', 'resolved_keep_server', 'superseded', 'dismissed')),
2448 resolved_at_ms INTEGER,
2449 replacement_client_commit_id TEXT);
2450 CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq
2451 ON _syncular_commit_outcomes(resolution, seq);
2452 CREATE TABLE IF NOT EXISTS _syncular_units (
2453 id TEXT PRIMARY KEY, scopes TEXT NOT NULL,
2454 explicit INTEGER NOT NULL DEFAULT 0,
2455 status TEXT NOT NULL DEFAULT 'active', reason_code TEXT,
2456 cursor INTEGER DEFAULT -1, bootstrap_state TEXT,
2457 seeded TEXT NOT NULL DEFAULT '[]', echo TEXT, applied TEXT, restriction TEXT);
2458 CREATE TABLE IF NOT EXISTS _syncular_meta (
2459 key TEXT PRIMARY KEY, value TEXT NOT NULL);
2460 CREATE TABLE IF NOT EXISTS _syncular_windows (
2461 base TEXT NOT NULL, unit TEXT NOT NULL, sub_id TEXT NOT NULL,
2462 PRIMARY KEY (base, unit));
2463 CREATE INDEX IF NOT EXISTS _syncular_windows_unit ON _syncular_windows(sub_id);
2464 CREATE TABLE IF NOT EXISTS _syncular_pending_evictions (
2465 unit_id TEXT NOT NULL, tbl TEXT NOT NULL,
2466 effective_scopes TEXT NOT NULL, PRIMARY KEY (unit_id, tbl));
2467 CREATE TABLE IF NOT EXISTS _syncular_blob_commit_refs(
2468 commit_id TEXT NOT NULL, blob_id TEXT NOT NULL,
2469 PRIMARY KEY(commit_id, blob_id));
2470 CREATE INDEX IF NOT EXISTS _syncular_blob_commit_refs_body
2471 ON _syncular_blob_commit_refs(blob_id);",
2472 )
2473 .map_err(|e| e.to_string())?;
2474 for column in ["applied", "restriction"] {
2477 if !self
2478 .conn
2479 .prepare("SELECT 1 FROM pragma_table_info('_syncular_units') WHERE name = ?1")
2480 .and_then(|mut stmt| stmt.exists([column]))
2481 .map_err(|e| e.to_string())?
2482 {
2483 self.conn
2484 .execute_batch(&format!(
2485 "ALTER TABLE _syncular_units ADD COLUMN {column} TEXT"
2486 ))
2487 .map_err(|e| e.to_string())?;
2488 }
2489 }
2490 let _ = self.conn.execute_batch(
2492 "ALTER TABLE _syncular_outbox ADD COLUMN created_at_ms INTEGER NOT NULL DEFAULT 0",
2493 );
2494 let _ = self
2497 .conn
2498 .execute_batch("ALTER TABLE _syncular_commit_outcomes ADD COLUMN operations_json TEXT");
2499 if self.get_meta(LOCAL_REVISION_KEY)?.is_none() {
2500 self.set_meta(LOCAL_REVISION_KEY, "0")?;
2501 }
2502 if !outbox_existed || self.get_meta(OUTBOX_ID_KEY)?.is_none() {
2505 self.set_meta(OUTBOX_ID_KEY, &uuid::Uuid::new_v4().to_string())?;
2506 }
2507 if exists("_syncular_window_pending_evict")? {
2512 let invalid: bool = self
2513 .conn
2514 .query_row(
2515 "SELECT EXISTS(SELECT 1 FROM _syncular_window_pending_evict
2516 WHERE NOT json_valid(effective_scopes)
2517 OR json_type(effective_scopes) <> 'object'
2518 OR EXISTS(SELECT 1 FROM json_each(effective_scopes)
2519 WHERE type <> 'array'
2520 OR EXISTS(SELECT 1 FROM json_each(value) AS v
2521 WHERE v.type <> 'text')))",
2522 [],
2523 |row| row.get(0),
2524 )
2525 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2526 if invalid {
2527 return Err(
2528 "sync.local_corrupt: a version 3 pending eviction cannot be upgraded"
2529 .to_owned(),
2530 );
2531 }
2532 self.conn
2533 .execute_batch(
2534 "INSERT OR REPLACE INTO _syncular_pending_evictions
2535 SELECT sub_id, tbl, effective_scopes FROM _syncular_window_pending_evict;
2536 DROP TABLE _syncular_window_pending_evict;
2537 DROP TABLE IF EXISTS _syncular_subscriptions;
2538 DELETE FROM _syncular_windows;",
2539 )
2540 .and_then(|()| reset_units(&self.conn, &BTreeSet::new(), None))
2541 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2542 }
2543 if self.schema_has_blobs() {
2546 if exists("_syncular_blobs")? {
2547 let mut statement = self
2548 .conn
2549 .prepare("PRAGMA table_info(_syncular_blobs)")
2550 .map_err(|e| e.to_string())?;
2551 let mut columns = statement
2552 .query_map([], |row| row.get::<_, String>(1))
2553 .map_err(|e| e.to_string())?
2554 .collect::<Result<Vec<_>, _>>()
2555 .map_err(|e| e.to_string())?;
2556 columns.sort();
2557 let mut expected = vec![
2558 "blob_id",
2559 "byte_length",
2560 "bytes",
2561 "created_at_ms",
2562 "media_type",
2563 ];
2564 expected.sort_unstable();
2565 if columns != expected {
2566 return Err(
2567 "sync.schema_mismatch: Local blob schema is incompatible".to_owned()
2568 );
2569 }
2570 } else {
2571 self.conn
2572 .execute_batch(
2573 "CREATE TABLE _syncular_blobs(
2574 blob_id TEXT PRIMARY KEY,
2575 bytes BLOB NOT NULL,
2576 byte_length INTEGER NOT NULL,
2577 media_type TEXT,
2578 created_at_ms INTEGER NOT NULL);",
2579 )
2580 .map_err(|e| e.to_string())?;
2581 }
2582 self.conn
2583 .execute_batch(
2584 "CREATE TABLE IF NOT EXISTS _syncular_blob_uploads(
2585 blob_id TEXT PRIMARY KEY,
2586 media_type TEXT,
2587 created_at_ms INTEGER NOT NULL);",
2588 )
2589 .map_err(|e| e.to_string())?;
2590 }
2591 Ok(())
2592 }
2593
2594 fn schema_has_blobs(&self) -> bool {
2596 self.schema
2597 .tables
2598 .iter()
2599 .any(|t| t.columns.iter().any(|c| c.ty == ColumnType::BlobRef))
2600 }
2601
2602 fn get_meta(&self, key: &str) -> Result<Option<String>, String> {
2605 meta_get(&self.conn, key)
2606 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2607 }
2608
2609 fn persist_schema_version(&self) -> Result<(), String> {
2612 self.conn
2613 .execute(
2614 "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
2615 rusqlite::params![LOCAL_SCHEMA_VERSION_KEY, self.schema.version.to_string()],
2616 )
2617 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2618 set_local_schema_descriptor(&self.conn, &self.schema)
2619 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2620 }
2621
2622 pub(crate) fn set_meta(&self, key: &str, value: &str) -> Result<(), String> {
2623 meta_set(&self.conn, key, value)
2624 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2625 }
2626
2627 fn delete_meta(&self, key: &str) -> Result<(), String> {
2628 meta_delete(&self.conn, key)
2629 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2630 }
2631
2632 fn load_outbox(&self) -> Result<Vec<Arc<OutboxCommit>>, String> {
2634 let mut stmt = self
2635 .conn
2636 .prepare("SELECT commit_id, ops_json FROM _syncular_outbox ORDER BY seq ASC")
2637 .map_err(|error| error.to_string())?;
2638 let rows = stmt
2639 .query_map([], |row| {
2640 Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
2641 })
2642 .map_err(|error| error.to_string())?;
2643 let mut commits = Vec::new();
2644 for row in rows {
2645 let (client_commit_id, raw) = row.map_err(|error| error.to_string())?;
2646 let entries: Vec<Value> = serde_json::from_str(&raw).map_err(|error| {
2647 format!("invalid persisted outbox {client_commit_id:?}: {error}")
2648 })?;
2649 let mut ops = Vec::with_capacity(entries.len());
2650 for entry in entries {
2651 let op = entry.get("op").and_then(Value::as_str).unwrap_or("delete");
2652 ops.push(OutboxOp {
2653 upsert: op == "upsert",
2654 table: entry
2655 .get("table")
2656 .and_then(Value::as_str)
2657 .ok_or_else(|| "persisted outbox operation missing table".to_owned())?
2658 .to_owned(),
2659 row_id: entry
2660 .get("rowId")
2661 .and_then(Value::as_str)
2662 .ok_or_else(|| "persisted outbox operation missing rowId".to_owned())?
2663 .to_owned(),
2664 base_version: entry.get("baseVersion").and_then(Value::as_i64),
2665 values: entry.get("values").and_then(Value::as_object).cloned(),
2668 insert: entry.get("insert") == Some(&Value::Bool(true)),
2669 });
2670 }
2671 commits.push(Arc::new(OutboxCommit {
2672 client_commit_id,
2673 ops,
2674 }));
2675 }
2676 Ok(commits)
2677 }
2678
2679 fn restore_persisted_state(&mut self) -> Result<(), String> {
2680 self.outbox = self.load_outbox()?.into();
2681
2682 self.prune_commit_outcomes()?;
2683 let active = self.commit_outcomes(CommitOutcomeQuery {
2684 active_only: true,
2685 ..CommitOutcomeQuery::default()
2686 })?;
2687 self.conflicts = active
2688 .iter()
2689 .flat_map(|outcome| outcome.results.iter())
2690 .filter_map(|result| match result {
2691 CommitOperationOutcome::Conflict { conflict } => Some(conflict.clone()),
2692 _ => None,
2693 })
2694 .collect::<Vec<_>>()
2695 .into();
2696 self.rejections = active
2697 .iter()
2698 .flat_map(|outcome| outcome.results.iter())
2699 .filter_map(|result| match result {
2700 CommitOperationOutcome::Error { rejection } => Some(rejection.clone()),
2701 _ => None,
2702 })
2703 .collect::<Vec<_>>()
2704 .into();
2705
2706 self.lease_state = self
2707 .get_meta(LEASE_STATE_KEY)?
2708 .map(|raw| serde_json::from_str(&raw))
2709 .transpose()
2710 .map_err(|error| format!("invalid persisted lease state: {error}"))?;
2711 self.schema_floor = self
2712 .get_meta(SCHEMA_FLOOR_KEY)?
2713 .map(|raw| serde_json::from_str(&raw))
2714 .transpose()
2715 .map_err(|error| format!("invalid persisted schema floor: {error}"))?;
2716 self.stopped = self.schema_floor.is_some();
2717 if self.get_meta(SECURITY_PREFLIGHT_PENDING_KEY)?.as_deref() == Some("1") {
2720 self.security_preflight = true;
2721 }
2722 Ok(())
2723 }
2724
2725 fn save_unit_scope_schema(&self) -> Result<(), String> {
2726 let declarations: BTreeMap<_, BTreeMap<_, _>> = self
2727 .schema
2728 .tables
2729 .iter()
2730 .map(|table| {
2731 (
2732 table.name.clone(),
2733 table
2734 .scope_variables
2735 .iter()
2736 .map(|scope| {
2737 (
2738 scope.variable.clone(),
2739 [scope.prefix.clone(), scope.column.clone()],
2740 )
2741 })
2742 .collect(),
2743 )
2744 })
2745 .collect();
2746 self.set_meta(
2747 "subscriptionScopeSchema",
2748 &serde_json::to_string(&declarations).expect("scope schema serialization"),
2749 )?;
2750 let generations: BTreeMap<_, _> = self
2751 .schema
2752 .tables
2753 .iter()
2754 .filter_map(|table| Some((&table.name, table.generation.as_ref()?)))
2755 .collect();
2756 self.set_meta(
2757 TABLE_GENERATIONS_KEY,
2758 &serde_json::to_string(&generations).expect("generations serialize"),
2759 )
2760 }
2761
2762 fn prune_unknown_units(&mut self, bump: bool) -> Result<(), String> {
2767 let previous: Option<BTreeMap<String, BTreeMap<String, [String; 2]>>> = if bump {
2768 self.get_meta("subscriptionScopeSchema")?
2769 .map(|raw| serde_json::from_str(&raw))
2770 .transpose()
2771 .map_err(|_| "sync.local_corrupt: invalid persisted scope schema".to_owned())?
2772 } else {
2773 None
2774 };
2775 let unchanged = |name: &str, variables: &[&String]| {
2780 let (Some(old), Some(table)) = (
2781 previous.as_ref().and_then(|previous| previous.get(name)),
2782 self.schema.table(name),
2783 ) else {
2784 return false;
2785 };
2786 variables.iter().all(|variable| {
2787 table
2788 .scope_variables
2789 .iter()
2790 .find(|scope| &scope.variable == *variable)
2791 .is_some_and(|scope| {
2792 old.get(*variable) == Some(&[scope.prefix.clone(), scope.column.clone()])
2793 })
2794 })
2795 };
2796 let compatible = |scopes: &UnitScopes| {
2797 if !self.schema.tables.iter().any(|table| covers(table, scopes)) {
2798 return false;
2799 }
2800 if !bump {
2801 return true;
2802 }
2803 let Some(previous) = &previous else {
2804 return false;
2805 };
2806 previous.iter().all(|(name, old)| {
2807 !scopes.keys().all(|variable| old.contains_key(variable))
2808 || unchanged(name, &scopes.keys().collect::<Vec<_>>())
2809 })
2810 };
2811 let mut stale: BTreeSet<String> = self
2812 .stored(load_units(&self.conn))?
2813 .into_iter()
2814 .filter(|unit| !compatible(&unit.scopes))
2815 .map(|unit| unit.id)
2816 .collect();
2817 for (id, table, effective) in self.load_pending_evictions()? {
2822 if self.schema.table(&table).is_none()
2823 || (bump
2824 && !unchanged(
2825 &table,
2826 &effective
2827 .iter()
2828 .map(|(variable, _)| variable)
2829 .collect::<Vec<_>>(),
2830 ))
2831 {
2832 stale.insert(id);
2833 }
2834 }
2835 for id in &stale {
2836 for sql in [
2837 "DELETE FROM _syncular_windows WHERE sub_id = ?1",
2838 "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
2839 "DELETE FROM _syncular_units WHERE id = ?1",
2840 ] {
2841 self.conn
2842 .execute(sql, rusqlite::params![id])
2843 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2844 }
2845 }
2846 Ok(())
2847 }
2848
2849 pub fn local_revision(&self) -> Result<u64, String> {
2850 Ok(self
2851 .get_meta(LOCAL_REVISION_KEY)?
2852 .and_then(|value| value.parse().ok())
2853 .unwrap_or(0))
2854 }
2855
2856 pub fn snapshot_read(
2862 &mut self,
2863 request: &SnapshotReadRequest<'_>,
2864 owner: Option<QueryOwner<'_>>,
2865 ) -> Result<SnapshotRead, QueryReadFailure> {
2866 let result = snapshot_read_connection(&self.conn, request);
2867 if let Some(owner) = owner {
2868 self.record_query_read(owner, result.as_ref().err());
2869 }
2870 result
2871 }
2872
2873 #[must_use]
2874 pub fn status_snapshot(&self) -> SyncStatusSnapshot {
2875 SyncStatusSnapshot {
2876 current_schema_version: self.schema.version,
2877 outbox: self.outbox.len(),
2878 upgrading: self.upgrading,
2879 lease_state: self.lease_state.clone(),
2880 schema_floor: self.schema_floor.clone(),
2881 sync_needed: self.sync_needed,
2882 previous_version_context: self.previous_version_status(),
2883 security_lifecycle: self.security_lifecycle(),
2884 }
2885 }
2886
2887 fn previous_version_status(&self) -> PreviousVersionStatus {
2890 let Some(replica_path) = self.previous_version_replica_path() else {
2891 return PreviousVersionStatus {
2892 present: false,
2893 created_at_ms: None,
2894 };
2895 };
2896 match crate::previous_version::read_previous_version_record(&replica_path) {
2897 Ok(Some(record)) => PreviousVersionStatus {
2898 present: true,
2899 created_at_ms: Some(record.created_at_ms),
2900 },
2901 _ => PreviousVersionStatus {
2902 present: std::path::Path::new(
2903 &crate::previous_version::previous_version_container_path(&replica_path),
2904 )
2905 .exists(),
2906 created_at_ms: None,
2907 },
2908 }
2909 }
2910
2911 pub fn previous_version_snapshot(
2917 &self,
2918 spec: &PreviousVersionReadSpec,
2919 ) -> Result<PreviousVersionSnapshot, String> {
2920 let now_ms = self.clock_now_ms();
2921 crate::previous_version::previous_version_snapshot(
2922 &self.conn,
2923 self.previous_version_replica_path().as_deref(),
2924 self.previous_version.as_ref(),
2925 PreviousVersionLifecycle {
2926 lease_inactive: self.previous_version_lease_inactive(now_ms),
2927 scope_revoked: self
2928 .stored(load_units(&self.conn))?
2929 .iter()
2930 .any(|unit| unit.status == UnitStatus::Revoked),
2931 coverage_complete: self.previous_version_coverage_complete()?,
2932 },
2933 now_ms,
2934 self.schema.version,
2935 spec,
2936 )
2937 }
2938
2939 pub fn previous_version_audit(
2941 &self,
2942 ) -> Result<Option<crate::previous_version::PreviousVersionAudit>, String> {
2943 crate::previous_version::stored_previous_version_audit(&self.conn)
2944 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2945 }
2946
2947 pub fn previous_version_discard(
2951 &self,
2952 ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2953 self.drop_previous_version()
2954 }
2955
2956 fn drop_previous_version(
2957 &self,
2958 ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2959 let Some(replica_path) = self.previous_version_replica_path() else {
2960 return Ok(crate::previous_version::PreviousVersionDiscardOutcome {
2961 present: false,
2962 discarded: false,
2963 });
2964 };
2965 crate::previous_version::discard_previous_version(&self.conn, &replica_path)
2966 }
2967
2968 fn previous_version_lease_inactive(&self, now_ms: i64) -> bool {
2970 let Some(lease) = &self.lease_state else {
2971 return false;
2972 };
2973 if lease.error_code.is_some() {
2974 return true;
2975 }
2976 lease.expires_at_ms.is_some_and(|expires| expires <= now_ms)
2977 }
2978
2979 fn previous_version_coverage_complete(&self) -> Result<bool, String> {
2983 let units = self.stored(load_units(&self.conn))?;
2984 let mut active = units
2985 .iter()
2986 .filter(|unit| unit.status == UnitStatus::Active)
2987 .peekable();
2988 Ok(active.peek().is_some() && !active.any(UnitRecord::bootstrapping))
2989 }
2990
2991 fn previous_version_lifetime_check(&self) {
2995 let Some(config) = self.previous_version.filter(|config| config.enabled) else {
2996 return;
2997 };
2998 let now_ms = self.clock_now_ms();
2999 if self.previous_version_lease_inactive(now_ms) {
3000 let _ = self.drop_previous_version();
3001 return;
3002 }
3003 let Some(replica_path) = self.previous_version_replica_path() else {
3004 return;
3005 };
3006 let Ok(Some(record)) = crate::previous_version::read_previous_version_record(&replica_path)
3007 else {
3008 return;
3009 };
3010 let Ok(units) = load_units(&self.conn) else {
3011 return;
3012 };
3013 if units.iter().any(|unit| unit.status == UnitStatus::Revoked) {
3014 let _ = self.drop_previous_version();
3015 return;
3016 }
3017 if now_ms - record.created_at_ms > config.max_age_ms {
3018 let _ = self.drop_previous_version();
3019 return;
3020 }
3021 if self.previous_version_coverage_complete() == Ok(true) {
3022 let _ = self.drop_previous_version();
3023 }
3024 }
3025
3026 pub fn diagnostics_snapshot(&self) -> Result<ClientDiagnosticsSnapshot, String> {
3027 let registered = self.stored(load_units(&self.conn))?;
3028 let (local_revision, replica_cursor): (Option<String>, Option<String>) = self.stored(
3031 self.conn
3032 .prepare_cached(
3033 "SELECT (SELECT value FROM _syncular_meta WHERE key = ?1),
3034 (SELECT value FROM _syncular_meta WHERE key = ?2)",
3035 )
3036 .and_then(|mut statement| {
3037 statement.query_row([LOCAL_REVISION_KEY, REPLICA_CURSOR_KEY], |row| {
3038 Ok((row.get(0)?, row.get(1)?))
3039 })
3040 }),
3041 )?;
3042 let mut units = DiagnosticUnits::default();
3043 for unit in ®istered {
3044 *match unit.status {
3045 UnitStatus::Revoked => &mut units.revoked,
3046 UnitStatus::Failed => &mut units.failed,
3047 UnitStatus::Active if !unit.bootstrapping() => &mut units.complete,
3048 UnitStatus::Active
3049 if unit.reason_code.as_deref() == Some("sync.cursor_expired") =>
3050 {
3051 &mut units.reset
3052 }
3053 UnitStatus::Active => &mut units.bootstrapping,
3054 } += 1;
3055 }
3056 units.reason_codes = registered
3057 .iter()
3058 .filter_map(|unit| unit.reason_code.as_deref().map(Self::diagnostic_code))
3059 .collect::<BTreeSet<_>>()
3060 .into_iter()
3061 .collect();
3062 let captured_at_ms = self.clock_now_ms();
3063 let lease = if let Some(error_code) = self
3064 .lease_state
3065 .as_ref()
3066 .and_then(|state| state.error_code.clone())
3067 {
3068 ClientDiagnosticsLease {
3069 state: "stopped".to_owned(),
3070 expires_at_ms: self
3071 .lease_state
3072 .as_ref()
3073 .and_then(|state| state.expires_at_ms),
3074 error_code: Some(Self::diagnostic_code(&error_code)),
3075 }
3076 } else if let Some(expires_at_ms) = self
3077 .lease_state
3078 .as_ref()
3079 .and_then(|state| state.expires_at_ms)
3080 {
3081 ClientDiagnosticsLease {
3082 state: if expires_at_ms <= captured_at_ms {
3083 "expired".to_owned()
3084 } else {
3085 "active".to_owned()
3086 },
3087 expires_at_ms: Some(expires_at_ms),
3088 error_code: None,
3089 }
3090 } else {
3091 ClientDiagnosticsLease {
3092 state: "none".to_owned(),
3093 expires_at_ms: None,
3094 error_code: None,
3095 }
3096 };
3097 let connectivity = match self.last_round.as_ref() {
3098 _ if !self.transport_enabled && self.active_round.is_none() => "offline",
3099 Some(round) if round.status == "succeeded" => "online",
3100 Some(round)
3101 if round.status == "failed"
3102 && matches!(
3103 round.cause_kind,
3104 Some(
3105 crate::TransportCauseKind::Network | crate::TransportCauseKind::Connect
3106 )
3107 ) =>
3108 {
3109 "offline"
3110 }
3111 Some(round) if round.status == "failed" && round.http_status.is_some() => "online",
3112 _ => "unknown",
3113 };
3114 Ok(ClientDiagnosticsSnapshot {
3115 version: CLIENT_DIAGNOSTICS_VERSION,
3116 captured_at_ms,
3117 host: ClientDiagnosticsHost {
3118 kind: "direct".to_owned(),
3119 role: "single".to_owned(),
3120 connectivity: connectivity.to_owned(),
3121 realtime: self.realtime_state,
3122 realtime_policy: self.realtime_policy,
3123 realtime_reason_code: self.realtime_reason_code.clone(),
3124 realtime_retry_delay_ms: self.realtime_retry_delay_ms,
3125 },
3126 security_lifecycle: self.security_lifecycle().to_owned(),
3127 schema: ClientDiagnosticsSchema {
3128 current_version: self.schema.version,
3129 upgrading: self.upgrading,
3130 required_version: self
3131 .schema_floor
3132 .as_ref()
3133 .and_then(|floor| floor.required_schema_version),
3134 latest_version: self
3135 .schema_floor
3136 .as_ref()
3137 .and_then(|floor| floor.latest_schema_version),
3138 },
3139 replica: ClientDiagnosticsReplica {
3140 local_revision: local_revision
3141 .and_then(|value| value.parse::<u64>().ok())
3142 .unwrap_or(0)
3143 .to_string(),
3144 sync_needed: self.sync_needed,
3145 pending_outbox: self.outbox.len(),
3146 },
3147 lease,
3148 active_units: registered
3149 .iter()
3150 .filter(|unit| unit.status == UnitStatus::Active)
3151 .count(),
3152 units,
3153 replica_cursor: replica_cursor.map_or(Ok(-1), |raw| {
3154 raw.parse()
3155 .map_err(|_| "sync.local_corrupt: persisted unit state is invalid".to_owned())
3156 })?,
3157 last_round: self.last_round.clone(),
3158 last_change: self.last_change.clone(),
3159 storage: self.diagnostics_storage(),
3160 query_failures: self.query_failures.clone(),
3161 })
3162 }
3163
3164 fn diagnostics_storage(&self) -> ClientDiagnosticsStorage {
3165 let read = || -> Result<ClientDiagnosticsStorage, rusqlite::Error> {
3166 let page_count: i64 = self
3167 .conn
3168 .query_row("PRAGMA page_count", [], |row| row.get(0))?;
3169 let page_size: i64 = self
3170 .conn
3171 .query_row("PRAGMA page_size", [], |row| row.get(0))?;
3172 let (outbox_bytes, outcome_entries, outcome_bytes): (i64, i64, i64) = self
3175 .conn
3176 .prepare_cached(
3177 "SELECT (SELECT COALESCE(SUM(LENGTH(ops_json)), 0) FROM _syncular_outbox),
3178 COUNT(*), COALESCE(SUM(LENGTH(results_json) + COALESCE(LENGTH(operations_json), 0)), 0)
3179 FROM _syncular_commit_outcomes",
3180 )?
3181 .query_row([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?;
3182 let blob_bytes = if self.schema_has_blobs() {
3183 self.conn
3184 .prepare_cached("SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs")?
3185 .query_row([], |row| row.get(0))?
3186 } else {
3187 0
3188 };
3189 let pressure = self
3190 .limits
3191 .blob_cache_max_bytes
3192 .is_some_and(|limit| blob_bytes > limit);
3193 Ok(ClientDiagnosticsStorage {
3194 status: if pressure { "pressure" } else { "healthy" }.to_owned(),
3195 database_bytes_approx: Some(page_count.saturating_mul(page_size).max(0)),
3196 pending_outbox_bytes_approx: Some(outbox_bytes.max(0)),
3197 retained_outcome_bytes_approx: Some(outcome_bytes.max(0)),
3198 retained_outcome_entries: Some(outcome_entries.max(0)),
3199 blob_cache_bytes_approx: Some(blob_bytes.max(0)),
3200 pressure_reason_code: pressure.then(|| "client.blob_cache_over_limit".to_owned()),
3201 })
3202 };
3203 read().unwrap_or_else(|_| ClientDiagnosticsStorage {
3204 status: "unreadable".to_owned(),
3205 database_bytes_approx: None,
3206 pending_outbox_bytes_approx: None,
3207 retained_outcome_bytes_approx: None,
3208 retained_outcome_entries: None,
3209 blob_cache_bytes_approx: None,
3210 pressure_reason_code: None,
3211 })
3212 }
3213
3214 pub fn drain_change_batches(&mut self) -> Vec<ClientChangeBatch> {
3215 self.change_queue.drain(..).collect()
3216 }
3217
3218 pub fn drain_sync_intents(&mut self) -> Vec<SyncIntent> {
3219 let intents = self.sync_intent_queue.drain(..).collect();
3220 if self.transport_enabled {
3221 intents
3222 } else {
3223 vec![SyncIntent::None]
3224 }
3225 }
3226
3227 pub fn drain_scopes_changed(&mut self) -> usize {
3231 std::mem::take(&mut self.scopes_changed)
3232 }
3233
3234 fn schedule_background_retry(&mut self) -> u64 {
3235 let delay_ms = self.retry_delay_ms;
3236 self.sync_intent_queue
3237 .push_back(SyncIntent::Background { delay_ms });
3238 self.retry_delay_ms = (self.retry_delay_ms * 2).min(30_000);
3239 self.round_retry_delay_ms = Some(delay_ms);
3240 delay_ms
3241 }
3242
3243 fn reset_background_retry(&mut self) {
3244 self.retry_delay_ms = 250;
3245 }
3246
3247 fn retryable_transport_code(code: &str) -> bool {
3248 code == "transport.failed"
3249 || code == "transport.timeout"
3250 || code == "transport.unavailable"
3251 || code == "sync.transport_failed"
3252 }
3253
3254 fn unreachable_transport(details: &Option<serde_json::Value>) -> bool {
3259 matches!(
3260 details
3261 .as_ref()
3262 .and_then(|details| details.get("causeKind"))
3263 .and_then(serde_json::Value::as_str),
3264 Some("connect" | "network")
3265 )
3266 }
3267
3268 fn segment_fetch_failed(&mut self, error: TransportError) -> SectionError {
3273 if ssp2::model::valid_round_failure_code(&error.code) {
3274 self.round_failure = Some(error.code.clone());
3275 }
3276 SectionError::Transport(error)
3277 }
3278
3279 fn retryable_failure_code(code: &str) -> bool {
3284 Self::retryable_transport_code(code)
3285 || matches!(
3286 code,
3287 "sync.auth_required"
3288 | "sync.auth_lease_required"
3289 | "sync.auth_lease_revoked"
3290 | "sync.internal_error"
3291 | "sync.idempotency_cache_miss"
3292 | "sync.schema_not_ready"
3293 | "sync.segment_expired"
3294 | "sync.rate_limited"
3295 | "sync.websocket_connection_limit"
3296 | "sync.idle_timeout"
3297 )
3298 }
3299
3300 fn diagnostic_code(code: &str) -> String {
3301 let valid = !code.is_empty()
3302 && code.len() <= 96
3303 && code.contains('.')
3304 && code
3305 .bytes()
3306 .next()
3307 .is_some_and(|byte| byte.is_ascii_lowercase())
3308 && code.bytes().all(|byte| {
3309 byte.is_ascii_lowercase()
3310 || byte.is_ascii_digit()
3311 || matches!(byte, b'.' | b'_' | b'-')
3312 });
3313 if valid {
3314 code.to_owned()
3315 } else {
3316 "client.unknown_failure".to_owned()
3317 }
3318 }
3319
3320 fn set_sync_needed(&mut self, value: bool, interactive: bool) {
3321 if self.sync_needed != value {
3322 if self.begin_observation("syncular_status").is_ok() {
3323 self.sync_needed = value;
3324 let batch = ChangeAccumulator {
3325 status: true,
3326 ..ChangeAccumulator::default()
3327 };
3328 if self.finish_observation("syncular_status", batch).is_err() {
3329 self.rollback_observation("syncular_status");
3330 }
3331 } else {
3332 self.sync_needed = value;
3333 }
3334 }
3335 if value && interactive {
3336 self.sync_intent_queue.push_back(SyncIntent::Interactive);
3337 }
3338 }
3339
3340 fn stored<T>(&self, result: rusqlite::Result<T>) -> Result<T, String> {
3343 result.map_err(|error| match error {
3344 rusqlite::Error::FromSqlConversionFailure(..) => {
3345 "sync.local_corrupt: persisted unit state is invalid".to_owned()
3346 }
3347 error => Self::sqlite_failure(&self.storage_failure, error),
3348 })
3349 }
3350
3351 fn sqlite_failure(
3352 storage_failure: &RefCell<Option<QueryReadFailure>>,
3353 error: rusqlite::Error,
3354 ) -> String {
3355 let message = error.to_string();
3356 let failure = QueryReadFailure::from(error);
3357 let code = failure.code;
3358 if code.is_some() && storage_failure.borrow().is_none() {
3359 *storage_failure.borrow_mut() = Some(failure);
3360 }
3361 match code {
3362 Some(code) => format!("{code}: {message}"),
3363 None => message,
3364 }
3365 }
3366
3367 fn begin_observation(&self, name: &str) -> Result<(), String> {
3368 if let Some(failure) = &self.coalesced_failure {
3369 return Err(failure.clone());
3370 }
3371 if self.coalesced.is_some() && self.conn.is_autocommit() {
3374 return Err("the coalesced apply transaction was rolled back".to_owned());
3375 }
3376 self.conn
3377 .execute_batch(&format!("SAVEPOINT {name}"))
3378 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3379 }
3380
3381 fn begin_coalesced_apply(&mut self) -> Result<(), String> {
3384 if self.coalesced.is_some() || !self.conn.is_autocommit() {
3385 return Ok(());
3386 }
3387 self.conn
3388 .execute_batch("BEGIN")
3389 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3390 self.coalesced = Some(CoalescedApply {
3391 rows: 0,
3392 rollback: self.capture(),
3393 });
3394 Ok(())
3395 }
3396
3397 fn capture(&self) -> Rollback {
3398 Rollback {
3399 outbox: self.outbox.clone(),
3400 failed_commits: self.failed_commits.clone(),
3401 conflicts: self.conflicts.clone(),
3402 rejections: self.rejections.clone(),
3403 schema_floor: self.schema_floor.clone(),
3404 lease_state: self.lease_state.clone(),
3405 stopped: self.stopped,
3406 upgrading: self.upgrading,
3407 sync_needed: self.sync_needed,
3408 active_round: self.active_round,
3409 overlay_dirty: self.overlay_dirty.snapshot(),
3410 change_queue: self.change_queue.len(),
3411 sync_intent_queue: self.sync_intent_queue.len(),
3412 last_change: self.last_change.clone(),
3413 }
3414 }
3415
3416 fn restore(&mut self, rollback: Rollback) {
3417 self.outbox = rollback.outbox;
3418 self.failed_commits = rollback.failed_commits;
3419 self.conflicts = rollback.conflicts;
3420 self.rejections = rollback.rejections;
3421 self.schema_floor = rollback.schema_floor;
3422 self.lease_state = rollback.lease_state;
3423 self.stopped = rollback.stopped;
3424 self.upgrading = rollback.upgrading;
3425 self.sync_needed = rollback.sync_needed;
3426 self.active_round = rollback.active_round;
3427 self.overlay_dirty.restore(rollback.overlay_dirty);
3428 self.change_queue.truncate(rollback.change_queue);
3429 self.sync_intent_queue.truncate(rollback.sync_intent_queue);
3430 self.last_change = rollback.last_change;
3431 }
3432
3433 fn coalesce_unit(&mut self, rows: usize) -> Result<(), String> {
3436 let Some(open) = &self.coalesced else {
3437 return Ok(());
3438 };
3439 if open.rows > 0 && open.rows + rows > COALESCED_APPLY_ROWS {
3440 self.commit_coalesced_apply()?;
3441 self.begin_coalesced_apply()?;
3442 }
3443 if let Some(open) = &mut self.coalesced {
3444 open.rows += rows;
3445 }
3446 Ok(())
3447 }
3448
3449 fn commit_coalesced_apply(&mut self) -> Result<(), String> {
3454 let Some(open) = self.coalesced.take() else {
3455 return Ok(());
3456 };
3457 let committed = if self.conn.is_autocommit() {
3458 Err("the coalesced apply transaction was rolled back".to_owned())
3459 } else {
3460 self.conn
3461 .execute_batch("COMMIT")
3462 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3463 };
3464 let Err(error) = committed else {
3465 return Ok(());
3466 };
3467 if !self.conn.is_autocommit() {
3468 if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3469 let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3470 }
3471 }
3472 self.restore(open.rollback);
3473 self.coalesced_failure = Some(error.clone());
3474 Err(error)
3475 }
3476
3477 fn finish_coalesced_apply(&mut self) -> Result<(), String> {
3479 let committed = self.commit_coalesced_apply();
3480 match self.coalesced_failure.take() {
3481 Some(failure) => Err(failure),
3482 None => committed,
3483 }
3484 }
3485
3486 fn rollback_observation(&self, name: &str) {
3487 if let Err(error) = self
3488 .conn
3489 .execute_batch(&format!("ROLLBACK TO {name}; RELEASE {name}"))
3490 {
3491 if let Some(failure) = self.storage_failure.borrow_mut().as_mut() {
3492 if failure.rollback_failure.is_none() {
3493 failure.rollback_failure = Some(Box::new(QueryReadFailure::from(error)));
3494 }
3495 }
3496 }
3497 }
3498
3499 fn finish_observation(
3500 &mut self,
3501 name: &str,
3502 mut batch: ChangeAccumulator,
3503 ) -> Result<(), String> {
3504 #[cfg(feature = "bench-internals")]
3505 let _phase = self.benchmark_phases.start(Phase::ObservationCommit);
3506 if self.failed_commits.iter().any(|(commit, _)| {
3507 commit
3508 .ops
3509 .iter()
3510 .any(|operation| batch.tables.contains_key(&operation.table))
3511 }) {
3512 batch.outcomes = true;
3513 }
3514 if !batch.touched() {
3515 self.conn
3516 .execute_batch(&format!("RELEASE {name}"))
3517 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3518 return Ok(());
3519 }
3520 let revision = self
3521 .local_revision()?
3522 .checked_add(1)
3523 .ok_or_else(|| "local revision exhausted u64".to_owned())?;
3524 self.conn
3525 .execute(
3526 "INSERT OR REPLACE INTO _syncular_meta(key, value) VALUES (?1, ?2)",
3527 rusqlite::params![LOCAL_REVISION_KEY, revision.to_string()],
3528 )
3529 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3530 let status = batch.status.then(|| self.status_snapshot());
3531 let event = ClientChangeBatch {
3532 revision: revision.to_string(),
3533 tables: batch
3534 .tables
3535 .into_iter()
3536 .map(|(table, scope_keys)| TableChange {
3537 table,
3538 scope_keys: scope_keys.map(|keys| keys.into_iter().collect()),
3539 })
3540 .collect(),
3541 windows: batch
3542 .windows
3543 .into_iter()
3544 .map(|(base_key, units)| WindowChange {
3545 base_key,
3546 units: units.into_iter().collect(),
3547 })
3548 .collect(),
3549 status,
3550 conflicts_changed: batch.conflicts,
3551 rejections_changed: batch.rejections,
3552 outcomes_changed: batch.outcomes,
3553 applied_commits: Vec::new(),
3554 };
3555 self.conn
3556 .execute_batch(&format!("RELEASE {name}"))
3557 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3558 let mut diagnostic_tables = event
3559 .tables
3560 .iter()
3561 .map(|entry| entry.table.clone())
3562 .collect::<BTreeSet<_>>()
3563 .into_iter()
3564 .collect::<Vec<_>>();
3565 let mut diagnostic_windows = event
3567 .windows
3568 .iter()
3569 .map(|entry| {
3570 entry
3571 .base_key
3572 .split('\0')
3573 .next()
3574 .unwrap_or_default()
3575 .to_owned()
3576 })
3577 .collect::<BTreeSet<_>>()
3578 .into_iter()
3579 .collect::<Vec<_>>();
3580 let domains_truncated = diagnostic_tables.len() > MAX_DIAGNOSTIC_DOMAINS
3581 || diagnostic_windows.len() > MAX_DIAGNOSTIC_DOMAINS;
3582 diagnostic_tables.truncate(MAX_DIAGNOSTIC_DOMAINS);
3583 diagnostic_windows.truncate(MAX_DIAGNOSTIC_DOMAINS);
3584 self.last_change = Some(DiagnosticLastChange {
3585 revision: event.revision.clone(),
3586 recorded_at_ms: self.clock_now_ms(),
3587 tables: diagnostic_tables,
3588 windows: diagnostic_windows,
3589 domains_truncated,
3590 status_changed: event.status.is_some(),
3591 conflicts_changed: event.conflicts_changed,
3592 rejections_changed: event.rejections_changed,
3593 outcomes_changed: event.outcomes_changed,
3594 });
3595 self.change_queue.push_back(event);
3596 Ok(())
3597 }
3598
3599 fn record_scope_map(
3600 &self,
3601 batch: &mut ChangeAccumulator,
3602 table_name: &str,
3603 scopes: &[(String, Vec<String>)],
3604 ) {
3605 let Some(table) = self.schema.table(table_name) else {
3606 return;
3607 };
3608 if table.scope_variables.iter().any(|scope| {
3611 !scopes
3612 .iter()
3613 .any(|(variable, _)| *variable == scope.variable)
3614 }) {
3615 batch.table(table_name);
3616 return;
3617 }
3618 for (variable, values) in scopes {
3619 let Some(scope) = table
3620 .scope_variables
3621 .iter()
3622 .find(|scope| &scope.variable == variable)
3623 else {
3624 continue;
3625 };
3626 for value in values {
3627 batch.scope(table_name, format!("{}:{value}", scope.prefix));
3628 }
3629 }
3630 }
3631
3632 fn record_row_scopes(
3634 &self,
3635 batch: &mut ChangeAccumulator,
3636 table_name: &str,
3637 row_id: &str,
3638 base: bool,
3639 ) -> bool {
3640 let Some(table) = self.schema.table(table_name) else {
3641 return false;
3642 };
3643 if table.scope_variables.is_empty() {
3644 return false;
3645 }
3646 let columns = table
3647 .scope_variables
3648 .iter()
3649 .map(|scope| quote_ident(&scope.column))
3650 .collect::<Vec<_>>()
3651 .join(", ");
3652 let full_table = if base {
3653 base_table(table_name)
3654 } else {
3655 visible_table(table_name)
3656 };
3657 let sql = format!(
3658 "SELECT {columns} FROM {full_table} WHERE {} LIMIT 1",
3659 row_id_predicate(table)
3660 );
3661 let Ok(mut stmt) = self.conn.prepare_cached(&sql) else {
3662 return false;
3663 };
3664 let values = stmt.query_row(rusqlite::params![row_id], |row| {
3665 let mut values = Vec::with_capacity(table.scope_variables.len());
3666 for index in 0..table.scope_variables.len() {
3667 values.push(row.get::<_, Option<String>>(index)?);
3668 }
3669 Ok(values)
3670 });
3671 let Ok(values) = values else {
3672 return false;
3673 };
3674 let mut recorded = false;
3675 for (scope, value) in table.scope_variables.iter().zip(values) {
3676 if let Some(value) = value {
3677 batch.scope(table_name, format!("{}:{value}", scope.prefix));
3678 recorded = true;
3679 }
3680 }
3681 recorded
3682 }
3683
3684 fn record_commit_changes(
3685 &self,
3686 batch: &mut ChangeAccumulator,
3687 tables: &[String],
3688 changes: &[ssp2::model::Change],
3689 ) {
3690 #[cfg(feature = "bench-internals")]
3691 let _phase = self.benchmark_phases.start(Phase::ObservationPrepare);
3692 for change in changes {
3693 let Some(table_name) = tables.get(change.table_index as usize) else {
3694 continue;
3695 };
3696 let mut precise = self.record_row_scopes(batch, table_name, &change.row_id, true);
3697 if let Some(table) = self.schema.table(table_name) {
3698 for (variable, value) in &change.scopes {
3699 if let Some(scope) = table
3700 .scope_variables
3701 .iter()
3702 .find(|scope| &scope.variable == variable)
3703 {
3704 batch.scope(table_name, format!("{}:{value}", scope.prefix));
3705 precise = true;
3706 }
3707 }
3708 }
3709 if !precise {
3710 batch.table(table_name);
3711 }
3712 }
3713 }
3714
3715 fn scoped_rows_exist(
3718 &self,
3719 table_name: &str,
3720 effective: &[(String, Vec<String>)],
3721 owners: &[Vec<(String, Vec<String>)>],
3722 ) -> Result<bool, String> {
3723 let Some(table) = self.schema.table(table_name) else {
3724 return Ok(false);
3725 };
3726 let Ok(Some((predicate, params))) = local_scope_predicate(table, effective, owners) else {
3727 return Ok(false);
3728 };
3729 for source in [base_table(table_name), visible_table(table_name)] {
3730 if self
3731 .conn
3732 .query_row(
3733 &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
3734 rusqlite::params_from_iter(¶ms),
3735 |row| row.get::<_, bool>(0),
3736 )
3737 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
3738 {
3739 return Ok(true);
3740 }
3741 }
3742 Ok(false)
3743 }
3744
3745 fn clear_scope(
3750 &mut self,
3751 table: &TableSchema,
3752 effective: &[(String, Vec<String>)],
3753 unit_id: &str,
3754 ) -> Result<bool, SectionError> {
3755 let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
3756 let matched = self
3757 .scoped_rows_exist(&table.name, effective, &[])
3758 .map_err(storage)?;
3759 let owners = if matched {
3760 unit_owners(
3761 &self.stored(load_units(&self.conn)).map_err(storage)?,
3762 table,
3763 unit_id,
3764 )
3765 } else {
3766 Vec::new()
3767 };
3768 let changed = matched
3769 && (owners.is_empty()
3770 || self
3771 .scoped_rows_exist(&table.name, effective, &owners)
3772 .map_err(storage)?);
3773 if !self
3774 .purge_scope_rows(&table.name, effective, &owners)
3775 .map_err(storage)?
3776 {
3777 return Err(SectionError::FailClosed);
3778 }
3779 Ok(changed)
3780 }
3781
3782 pub fn upgrading(&self) -> bool {
3784 self.upgrading
3785 }
3786
3787 pub fn recreate_with_schema(&mut self, schema_json: &Value) -> Result<(), String> {
3795 let new_schema = parse_schema_json(schema_json)?;
3796 validate_authority_reads(&new_schema, &self.limits.authority_reads)?;
3797 self.conn
3798 .execute_batch("BEGIN IMMEDIATE")
3799 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3800 let prior_schema = std::mem::replace(&mut self.schema, new_schema);
3801 let rollback = self.capture();
3807 let guarded = (|| -> Result<(), String> {
3808 let marker = read_local_schema_version(&self.conn, self.schema.version)?;
3813 self.create_bookkeeping_tables()?;
3814 match marker {
3815 Some(version) if version < self.schema.version => self.run_schema_reset()?,
3816 None => {
3817 self.create_synced_tables()?;
3818 self.persist_schema_version()?;
3819 }
3820 _ => {}
3821 }
3822 self.outbox = self.load_outbox()?.into();
3827 self.drop_unencodable_outbox(false, None)?;
3832 if marker == Some(self.schema.version)
3833 && (!self.outbox.is_empty()
3834 || !self.failed_commits.is_empty()
3835 || self.has_acknowledged_rows()?)
3836 {
3837 self.overlay_dirty.set(true);
3838 self.rebuild_overlay()?;
3839 }
3840 self.prune_unknown_units(false)?;
3841 self.save_unit_scope_schema()?;
3842 self.enqueue_startup_sync_if_needed()?;
3846 Ok(())
3847 })();
3848 let outcome = match guarded {
3849 Ok(()) => self
3850 .conn
3851 .execute_batch("COMMIT")
3852 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error)),
3853 Err(error) => Err(error),
3854 };
3855 if let Err(error) = outcome {
3856 if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3857 let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3859 }
3860 self.schema = prior_schema;
3861 self.restore(rollback);
3862 self.insert_sql.borrow_mut().clear();
3864 return Err(error);
3865 }
3866 if !self.security_preflight {
3867 self.drain_pending_evictions()?;
3868 }
3869 Ok(())
3870 }
3871
3872 fn enqueue_startup_sync_if_needed(&mut self) -> Result<(), String> {
3873 let startup_work = !self.stopped
3874 && (!self.outbox.is_empty()
3875 || self.has_acknowledged_rows()?
3876 || !self.load_pending_evictions()?.is_empty()
3877 || self
3878 .stored(load_units(&self.conn))?
3879 .iter()
3880 .any(|unit| unit.status == UnitStatus::Active));
3881 if startup_work {
3882 self.sync_needed = true;
3883 self.sync_intent_queue.push_back(SyncIntent::Interactive);
3884 }
3885 Ok(())
3886 }
3887
3888 fn clear_satisfied_persisted_schema_floor(&mut self) -> Result<(), String> {
3895 let satisfied = self
3896 .schema_floor
3897 .as_ref()
3898 .and_then(|floor| floor.required_schema_version)
3899 .is_some_and(|required| self.schema.version >= required);
3900 if !satisfied {
3901 return Ok(());
3902 }
3903 self.delete_meta(SCHEMA_FLOOR_KEY)?;
3904 self.schema_floor = None;
3905 self.stopped = false;
3906 Ok(())
3907 }
3908
3909 fn reconcile_previous_version_at_boot(&self) -> Result<(), String> {
3914 let Some(replica_path) = self.previous_version_replica_path() else {
3915 return Ok(());
3916 };
3917 let max_age_ms = self
3918 .previous_version
3919 .filter(|config| config.enabled)
3920 .map(|config| config.max_age_ms);
3921 reconcile_previous_version_at_boot(
3922 &self.conn,
3923 &replica_path,
3924 self.schema.version,
3925 max_age_ms,
3926 self.clock_now_ms(),
3927 )
3928 }
3929
3930 fn previous_version_replica_path(&self) -> Option<String> {
3934 let path = self.conn.path()?;
3935 if path.is_empty() || path.starts_with("file:") {
3936 return None;
3937 }
3938 Some(path.to_owned())
3939 }
3940
3941 fn run_schema_reset(&mut self) -> Result<(), String> {
3947 self.begin_observation("syncular_schema_reset")?;
3948 let rollback = self.capture();
3949 let mut batch = ChangeAccumulator::default();
3950 let result = self
3951 .run_schema_reset_observed(&mut batch, true)
3952 .and_then(|()| self.finish_observation("syncular_schema_reset", batch));
3953 if let Err(error) = result {
3954 self.rollback_observation("syncular_schema_reset");
3955 self.restore(rollback);
3956 return Err(error);
3957 }
3958 self.cancel_sync_round();
3960 Ok(())
3961 }
3962
3963 fn run_log_epoch_reset(&mut self, log_epoch: &str) -> Result<Vec<String>, String> {
3964 if self.get_meta(LOG_EPOCH_KEY)?.is_none() {
3965 self.begin_observation("syncular_epoch_acquisition")?;
3966 let rollback = self.capture();
3967 if let Err(error) = self.conn.execute(
3968 "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
3969 rusqlite::params![LOG_EPOCH_KEY, log_epoch],
3970 ) {
3971 self.rollback_observation("syncular_epoch_acquisition");
3972 return Err(Self::sqlite_failure(&self.storage_failure, error));
3973 }
3974 self.sync_needed = true;
3975 let batch = ChangeAccumulator {
3976 status: true,
3977 ..ChangeAccumulator::default()
3978 };
3979 if let Err(error) = self.finish_observation("syncular_epoch_acquisition", batch) {
3980 self.rollback_observation("syncular_epoch_acquisition");
3981 self.restore(rollback);
3982 return Err(error);
3983 }
3984 self.sync_intent_queue.push_back(SyncIntent::Interactive);
3985 return Ok(Vec::new());
3986 }
3987 let resets = self
3988 .stored(load_units(&self.conn))?
3989 .into_iter()
3990 .map(|unit| unit.id)
3991 .collect();
3992 self.begin_observation("syncular_log_epoch_reset")?;
3993 let rollback = self.capture();
3994 let mut batch = ChangeAccumulator::default();
3995 let result = self
3996 .run_schema_reset_observed(&mut batch, false)
3997 .and_then(|()| {
3998 self.conn
3999 .execute(
4000 "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
4001 rusqlite::params![LOG_EPOCH_KEY, log_epoch],
4002 )
4003 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4004 self.sync_needed = true;
4005 batch.status = true;
4006 self.finish_observation("syncular_log_epoch_reset", batch)
4007 });
4008 if let Err(error) = result {
4009 self.rollback_observation("syncular_log_epoch_reset");
4010 self.restore(rollback);
4011 return Err(error);
4012 }
4013 self.cancel_sync_round();
4014 self.sync_intent_queue.push_back(SyncIntent::Interactive);
4015 Ok(resets)
4016 }
4017
4018 fn run_schema_reset_observed(
4019 &mut self,
4020 batch: &mut ChangeAccumulator,
4021 capture: bool,
4022 ) -> Result<(), String> {
4023 read_local_schema_version(&self.conn, self.schema.version)?;
4029 let mut kept = BTreeSet::new();
4033 let mut previous_declarations: Option<BTreeMap<String, BTreeMap<String, Value>>> = None;
4034 if capture {
4035 let persisted: BTreeMap<String, String> = self
4036 .get_meta(TABLE_GENERATIONS_KEY)?
4037 .map(|raw| serde_json::from_str(&raw))
4038 .transpose()
4039 .map_err(|_| "sync.local_corrupt: invalid persisted table generations".to_owned())?
4040 .unwrap_or_default();
4041 kept = self
4042 .schema
4043 .tables
4044 .iter()
4045 .filter(|table| {
4046 table.generation.is_some()
4047 && table.generation.as_ref() == persisted.get(&table.name)
4048 })
4049 .map(|table| table.name.clone())
4050 .collect();
4051 previous_declarations = self
4052 .get_meta("subscriptionScopeSchema")?
4053 .map(|raw| serde_json::from_str(&raw))
4054 .transpose()
4055 .map_err(|_| "sync.local_corrupt: invalid persisted scope schema".to_owned())?;
4056 }
4057 let mut kept_objects = BTreeSet::new();
4060 for table in self
4061 .schema
4062 .tables
4063 .iter()
4064 .filter(|table| kept.contains(&table.name))
4065 {
4066 kept_objects.insert(table.name.clone());
4067 kept_objects.insert(format!("_syncular_base_{}", table.name));
4068 for index in &table.fts_indexes {
4069 kept_objects.insert(index.name.clone());
4070 for shadow in ["data", "idx", "content", "docsize", "config"] {
4071 kept_objects.insert(format!("{}_{shadow}", index.name));
4072 }
4073 }
4074 }
4075 let kept_json = serde_json::to_string(&kept).expect("table names serialize");
4076 for sql in [
4077 "DELETE FROM _syncular_acked_rows WHERE tbl NOT IN (SELECT value FROM json_each(?1))",
4078 "DELETE FROM _syncular_row_deliveries WHERE tbl NOT IN (SELECT value FROM json_each(?1))",
4079 ] {
4080 self.conn
4081 .execute(sql, [&kept_json])
4082 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4083 }
4084 self.upgrading = true;
4085 batch.status = true;
4086 if self.previous_version.is_some_and(|config| config.enabled) {
4094 let previous_version = self
4095 .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
4096 .and_then(|value| value.parse::<i32>().ok())
4097 .unwrap_or(self.schema.version);
4098 let pending = self
4099 .outbox
4100 .iter()
4101 .map(|commit| PendingCommitAudit {
4102 commit_id: &commit.client_commit_id,
4103 operations: commit_audit_operations(commit),
4104 })
4105 .collect::<Vec<_>>();
4106 crate::previous_version::write_previous_version_audit(
4107 &self.conn,
4108 &crate::previous_version::build_previous_version_audit(
4109 &self.schema,
4110 &pending,
4111 previous_version,
4112 self.schema.version,
4113 self.clock_now_ms(),
4114 ),
4115 )?;
4116 }
4117 if let Some(replica_path) = self.previous_version_replica_path() {
4122 sweep_previous_version_container(&self.conn, &replica_path)?;
4123 if capture {
4124 if let Some(config) = self.previous_version.filter(|config| config.enabled) {
4125 let previous_version = self
4126 .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
4127 .and_then(|value| value.parse::<i32>().ok())
4128 .unwrap_or(self.schema.version);
4129 capture_previous_version_from_replica(
4130 &self.conn,
4131 &replica_path,
4132 previous_version,
4133 self.schema.version,
4134 &config,
4135 self.clock_now_ms(),
4136 )?;
4137 }
4138 }
4139 }
4140 for table in self
4141 .schema
4142 .tables
4143 .iter()
4144 .filter(|table| !kept.contains(&table.name))
4145 {
4146 batch.table(&table.name);
4147 }
4148 for (base_key, value) in self.load_window_registry()? {
4149 batch.window(&base_key, &value);
4150 }
4151 if capture {
4152 self.prune_unknown_units(true)?;
4153 }
4154 self.insert_sql.borrow_mut().clear();
4156 self.overlay_dirty.set(true);
4157 let virtual_tables: Vec<String> = {
4165 let mut stmt = self
4166 .conn
4167 .prepare(
4168 "SELECT name FROM sqlite_master WHERE type = 'table' AND sql LIKE 'CREATE VIRTUAL TABLE%'",
4169 )
4170 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4171 let rows = stmt
4172 .query_map([], |row| row.get::<_, String>(0))
4173 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4174 rows.filter_map(Result::ok)
4175 .filter(|name| is_synced_table_name(name) && !kept_objects.contains(name))
4176 .collect()
4177 };
4178 for name in virtual_tables {
4179 self.conn
4180 .execute_batch(&format!(
4181 "DROP TABLE IF EXISTS {}",
4182 quote_ident(&format!("_syncular_fts_{name}"))
4183 ))
4184 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4185 self.conn
4186 .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
4187 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4188 }
4189 let existing: Vec<String> = {
4190 let mut stmt = self
4191 .conn
4192 .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
4193 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4194 let rows = stmt
4195 .query_map([], |row| row.get::<_, String>(0))
4196 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4197 rows.filter_map(Result::ok)
4198 .filter(|name| is_synced_table_name(name) && !kept_objects.contains(name))
4199 .collect()
4200 };
4201 for name in &existing {
4202 if let Some(table) = name.strip_prefix("_syncular_base_") {
4203 batch.table(table);
4204 } else if !name.starts_with("_syncular_") {
4205 batch.table(name);
4206 }
4207 }
4208 for name in existing {
4209 self.conn
4210 .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
4211 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4212 }
4213 self.create_synced_tables()?;
4215 let keep_units = match &previous_declarations {
4219 Some(previous) if !kept.is_empty() => self
4220 .stored(load_units(&self.conn))?
4221 .into_iter()
4222 .filter(|unit| {
4223 previous.iter().all(|(name, old)| {
4224 kept.contains(name) || !unit.scopes.keys().all(|v| old.contains_key(v))
4225 }) && self
4226 .schema
4227 .tables
4228 .iter()
4229 .all(|table| kept.contains(&table.name) || !covers(table, &unit.scopes))
4230 })
4231 .map(|unit| unit.id)
4232 .collect(),
4233 _ => BTreeSet::new(),
4234 };
4235 let restrictions = if capture {
4240 let replica = self.stored(replica_cursor(&self.conn))?;
4241 let mut restrictions = BTreeMap::new();
4242 for unit in self.stored(load_units(&self.conn))? {
4243 if keep_units.contains(&unit.id) || unit.status != UnitStatus::Active {
4244 continue;
4245 }
4246 let cursor = match (&unit.restriction, unit.cursor) {
4247 (Some(restriction), _) => restriction.cursor,
4248 (None, Some(cursor)) if cursor >= 0 && unit.bootstrap_state.is_none() => cursor,
4249 (None, None) if replica >= 0 => replica,
4250 _ => continue,
4251 };
4252 let covered: Vec<&String> = self
4253 .schema
4254 .tables
4255 .iter()
4256 .filter(|table| covers(table, &unit.scopes))
4257 .map(|table| &table.name)
4258 .collect();
4259 let mut tables: Vec<String> = covered
4260 .iter()
4261 .filter(|name| {
4262 !kept.contains(**name)
4263 || unit
4264 .restriction
4265 .as_ref()
4266 .is_some_and(|restriction| restriction.tables.contains(name))
4267 })
4268 .map(|name| (*name).clone())
4269 .collect();
4270 if tables.is_empty() || tables.len() == covered.len() {
4271 continue;
4272 }
4273 tables.sort_by(|a, b| a.encode_utf16().cmp(b.encode_utf16()));
4274 restrictions.insert(unit.id, UnitRestriction { cursor, tables });
4275 }
4276 Some(restrictions)
4277 } else {
4278 None
4279 };
4280 reset_units(&self.conn, &keep_units, restrictions.as_ref())
4281 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4282 self.stopped = false;
4284 self.schema_floor = None;
4285 self.delete_meta(SCHEMA_FLOOR_KEY)?;
4286 self.persist_schema_version()?;
4288 self.save_unit_scope_schema()?;
4289 self.drop_unencodable_outbox(false, Some(batch))?;
4300 self.rebuild_overlay()?;
4302 Ok(())
4303 }
4304
4305 fn drop_incompatible_outbox(&mut self) -> Result<bool, String> {
4314 let incompatible = self
4315 .outbox
4316 .iter()
4317 .filter(|commit| {
4318 first_incompatibility(&self.schema, &commit_audit_operations(commit)).is_some()
4319 })
4320 .cloned()
4321 .collect::<Vec<_>>();
4322 if incompatible.is_empty() {
4323 return Ok(false);
4324 }
4325 self.drop_outbox_commits(
4326 &incompatible,
4327 OUTBOX_INCOMPATIBLE_CODE,
4328 "the persisted commit cannot encode under the current schema",
4329 )?;
4330 Ok(true)
4331 }
4332
4333 fn drop_outbox_commits(
4337 &mut self,
4338 incompatible: &[Arc<OutboxCommit>],
4339 code: &str,
4340 message: &str,
4341 ) -> Result<(), String> {
4342 let rollback = self.capture();
4348 let owns_transaction = self.conn.is_autocommit();
4349 self.begin_observation("syncular_outbox_drop")?;
4350 let mut batch = ChangeAccumulator::default();
4351 let dropped = (|| -> Result<(), String> {
4352 let mut rejections = Vec::new();
4353 for commit in incompatible {
4354 let results = commit
4355 .ops
4356 .iter()
4357 .enumerate()
4358 .map(|(op_index, operation)| {
4359 let rejection = RejectionRecord {
4360 client_commit_id: commit.client_commit_id.clone(),
4361 op_index: op_index as i32,
4362 code: code.to_owned(),
4363 message: message.to_owned(),
4364 retryable: false,
4365 details: None,
4366 operation: Some(CommitOperation::from(operation)),
4367 };
4368 rejections.push(rejection.clone());
4369 CommitOperationOutcome::Error { rejection }
4370 })
4371 .collect::<Vec<_>>();
4372 self.persist_commit_outcome(
4373 &commit.client_commit_id,
4374 CommitOutcomeStatus::Rejected,
4375 &results,
4376 Some(&commit.ops),
4377 )?;
4378 self.delete_outbox_persisted(&commit.client_commit_id)?;
4379 for operation in &commit.ops {
4382 if self.schema.table(&operation.table).is_some() {
4383 batch.table(&operation.table);
4384 }
4385 }
4386 }
4387 self.prune_commit_outcomes()?;
4388 let incompatible_ids = incompatible
4389 .iter()
4390 .map(|commit| commit.client_commit_id.as_str())
4391 .collect::<BTreeSet<_>>();
4392 self.outbox
4393 .retain(|commit| !incompatible_ids.contains(commit.client_commit_id.as_str()));
4394 self.rejections.extend(rejections);
4395 self.overlay_dirty.set(true);
4398 self.rebuild_overlay()?;
4399 batch.status = true;
4400 batch.rejections = true;
4401 batch.outcomes = true;
4402 Ok(())
4403 })();
4404 let result = dropped.and_then(|()| self.finish_observation("syncular_outbox_drop", batch));
4405 if let Err(error) = result {
4406 if owns_transaction {
4410 if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
4411 let mut failure = self.storage_failure.borrow_mut();
4412 let failure =
4413 failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
4414 failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
4415 }
4416 } else {
4417 self.rollback_observation("syncular_outbox_drop");
4418 }
4419 self.restore(rollback);
4420 return Err(error);
4421 }
4422 Ok(())
4423 }
4424
4425 fn create_synced_tables(&self) -> Result<(), String> {
4428 for table in &self.schema.tables {
4429 for (full, index_prefix) in [
4433 (base_table(&table.name), "_syncular_base_"),
4434 (visible_table(&table.name), ""),
4435 ] {
4436 let mut cols: Vec<String> =
4437 table.columns.iter().map(|c| quote_ident(&c.name)).collect();
4438 cols.push("\"_syncular_version\" INTEGER NOT NULL".to_owned());
4439 cols.extend(
4440 table
4441 .sealed_columns()
4442 .iter()
4443 .map(|name| format!("{} TEXT", quote_ident(name))),
4444 );
4445 let sql = format!(
4446 "CREATE TABLE IF NOT EXISTS {full} ({} , PRIMARY KEY ({}))",
4447 cols.join(", "),
4448 quote_ident(&table.primary_key)
4449 );
4450 self.conn
4451 .execute(&sql, [])
4452 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4453 for name in table.sealed_columns() {
4457 let present: bool = self
4458 .conn
4459 .query_row(
4460 "SELECT EXISTS(SELECT 1 FROM pragma_table_info(?1) WHERE name = ?2)",
4461 rusqlite::params![format!("{index_prefix}{}", table.name), name],
4462 |row| row.get(0),
4463 )
4464 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4465 if !present {
4466 self.conn
4467 .execute(
4468 &format!(
4469 "ALTER TABLE {full} ADD COLUMN {} TEXT",
4470 quote_ident(name)
4471 ),
4472 [],
4473 )
4474 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4475 }
4476 }
4477 if table.has_encrypted_columns() && !index_prefix.is_empty() {
4480 self.conn
4481 .execute(
4482 &format!(
4483 "CREATE INDEX IF NOT EXISTS {} ON {full} (\"_sync_sealed_key\") WHERE \"_sync_sealed_key\" IS NOT NULL",
4484 quote_ident(&format!("_syncular_sealed_{}", table.name))
4485 ),
4486 [],
4487 )
4488 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4489 }
4490 for index in &table.indexes {
4494 let unique = if index.unique { "UNIQUE " } else { "" };
4495 let index_name = quote_ident(&format!("{index_prefix}{}", index.name));
4496 let cols_sql = index
4497 .columns
4498 .iter()
4499 .map(|c| quote_ident(c))
4500 .collect::<Vec<_>>()
4501 .join(", ");
4502 let index_sql = format!(
4503 "CREATE {unique}INDEX IF NOT EXISTS {index_name} ON {full} ({cols_sql})"
4504 );
4505 self.conn
4506 .execute(&index_sql, [])
4507 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4508 }
4509 }
4510 }
4511 for table in &self.schema.tables {
4514 for index in &table.fts_indexes {
4515 self.create_fts_projection(table, index)?;
4516 }
4517 }
4518 Ok(())
4519 }
4520
4521 fn fts_projection_exists(&self, index: &FtsIndexSchema) -> Result<bool, String> {
4522 let count: i64 = self
4523 .conn
4524 .query_row(
4525 "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?1",
4526 rusqlite::params![index.name],
4527 |row| row.get(0),
4528 )
4529 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4530 Ok(count > 0)
4531 }
4532
4533 fn drop_fts_triggers(&self, index: &FtsIndexSchema) -> Result<(), String> {
4534 for suffix in ["ai", "ad", "au"] {
4535 self.conn
4536 .execute(
4537 &format!(
4538 "DROP TRIGGER IF EXISTS {}",
4539 quote_ident(&format!("{}_{suffix}", index.name))
4540 ),
4541 [],
4542 )
4543 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4544 }
4545 Ok(())
4546 }
4547
4548 fn create_fts_triggers(
4549 &self,
4550 table: &TableSchema,
4551 index: &FtsIndexSchema,
4552 ) -> Result<(), String> {
4553 let fts = quote_ident(&index.name);
4554 let source = visible_table(&table.name);
4555 let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4556 let pk = quote_ident(&table.primary_key);
4557 let projection_columns = std::iter::once(source_id.clone())
4558 .chain(index.columns.iter().map(|column| quote_ident(column)))
4559 .collect::<Vec<_>>()
4560 .join(", ");
4561 let new_values = std::iter::once(format!("CAST(new.{pk} AS TEXT)"))
4562 .chain(
4563 index
4564 .columns
4565 .iter()
4566 .map(|column| format!("new.{}", quote_ident(column))),
4567 )
4568 .collect::<Vec<_>>()
4569 .join(", ");
4570 let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4571 let delete_new = format!("DELETE FROM {fts} WHERE rowid = (SELECT id FROM {mapping} WHERE source_id = CAST(new.{pk} AS TEXT)); DELETE FROM {mapping} WHERE source_id = CAST(new.{pk} AS TEXT)");
4572 let delete_old = format!("DELETE FROM {fts} WHERE rowid = (SELECT id FROM {mapping} WHERE source_id = CAST(old.{pk} AS TEXT)); DELETE FROM {mapping} WHERE source_id = CAST(old.{pk} AS TEXT)");
4573 let insert_new = format!("INSERT INTO {mapping}(source_id) VALUES (CAST(new.{pk} AS TEXT)); INSERT INTO {fts} (rowid, {projection_columns}) VALUES ((SELECT id FROM {mapping} WHERE source_id = CAST(new.{pk} AS TEXT)), {new_values})");
4574 let bi = quote_ident(&format!("{}_bi", index.name));
4575 let ai = quote_ident(&format!("{}_ai", index.name));
4576 let ad = quote_ident(&format!("{}_ad", index.name));
4577 let au = quote_ident(&format!("{}_au", index.name));
4578 let replacement_exists = format!("EXISTS (SELECT 1 FROM {source} WHERE {pk} = new.{pk})");
4579 let sql = format!(
4580 "DROP TRIGGER IF EXISTS {bi};
4581 DROP TRIGGER IF EXISTS {ai};
4582 DROP TRIGGER IF EXISTS {ad};
4583 DROP TRIGGER IF EXISTS {au};
4584 CREATE TRIGGER {bi} BEFORE INSERT ON {source} WHEN {replacement_exists} BEGIN {delete_new}; END;
4585 CREATE TRIGGER {ai} AFTER INSERT ON {source} BEGIN {insert_new}; END;
4586 CREATE TRIGGER {ad} AFTER DELETE ON {source} BEGIN {delete_old}; END;
4587 CREATE TRIGGER {au} AFTER UPDATE ON {source} BEGIN {delete_old}; {delete_new}; {insert_new}; END;",
4588 );
4589 self.conn
4590 .execute_batch(&sql)
4591 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4592 }
4593
4594 fn rebuild_fts_projection(
4595 &self,
4596 table: &TableSchema,
4597 index: &FtsIndexSchema,
4598 ) -> Result<(), String> {
4599 let fts = quote_ident(&index.name);
4600 let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4601 let pk = quote_ident(&table.primary_key);
4602 let indexed_columns = index
4603 .columns
4604 .iter()
4605 .map(|column| quote_ident(column))
4606 .collect::<Vec<_>>();
4607 let projection_columns = std::iter::once(source_id.clone())
4608 .chain(indexed_columns.iter().cloned())
4609 .collect::<Vec<_>>()
4610 .join(", ");
4611 let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4612 let sql = format!(
4613 "DELETE FROM {fts}; DELETE FROM {mapping}; INSERT INTO {fts} ({projection_columns}) SELECT CAST({pk} AS TEXT), {columns} FROM {source}; INSERT INTO {mapping}(id, source_id) SELECT rowid, {source_id} FROM {fts};",
4614 columns = indexed_columns.join(", "),
4615 source = visible_table(&table.name),
4616 );
4617 self.conn
4618 .execute_batch(&sql)
4619 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4620 }
4621
4622 fn create_fts_projection(
4623 &self,
4624 table: &TableSchema,
4625 index: &FtsIndexSchema,
4626 ) -> Result<(), String> {
4627 self.begin_observation("syncular_fts_schema")?;
4628 let result = (|| {
4629 let existed = self.fts_projection_exists(index)?;
4630 let tokenizer = index.tokenize.replace('\'', "''");
4631 let columns = index
4632 .columns
4633 .iter()
4634 .map(|column| quote_ident(column))
4635 .collect::<Vec<_>>()
4636 .join(", ");
4637 let sql = format!(
4638 "CREATE VIRTUAL TABLE IF NOT EXISTS {fts} USING fts5({source_id} UNINDEXED, {columns}, tokenize='{tokenizer}')",
4639 fts = quote_ident(&index.name),
4640 source_id = quote_ident(FTS_SOURCE_ID_COLUMN),
4641 );
4642 self.conn.execute(&sql, []).map_err(|error| {
4643 format!(
4644 "cannot create local FTS5 projection {:?}: {error}",
4645 index.name
4646 )
4647 })?;
4648 let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4649 let mapped: bool = self
4650 .conn
4651 .query_row(
4652 "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type='table' AND name=?1)",
4653 [format!("_syncular_fts_{}", index.name)],
4654 |row| row.get(0),
4655 )
4656 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4657 self.conn.execute_batch(&format!("CREATE TABLE IF NOT EXISTS {mapping}(id INTEGER PRIMARY KEY, source_id TEXT NOT NULL UNIQUE)")).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4658 if !mapped && existed {
4659 self.conn
4660 .execute_batch(&format!(
4661 "INSERT INTO {mapping}(id, source_id) SELECT rowid, {} FROM {}",
4662 quote_ident(FTS_SOURCE_ID_COLUMN),
4663 quote_ident(&index.name)
4664 ))
4665 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4666 }
4667 self.create_fts_triggers(table, index)?;
4668 let stale: bool = !existed
4672 || self
4673 .conn
4674 .query_row(
4675 &format!(
4676 "SELECT (SELECT count(*) FROM {mapping}) != (SELECT count(*) FROM {})",
4677 visible_table(&table.name)
4678 ),
4679 [],
4680 |row| row.get(0),
4681 )
4682 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4683 if stale {
4684 self.rebuild_fts_projection(table, index)?;
4685 }
4686 Ok(())
4687 })();
4688 if let Err(error) = result {
4689 self.rollback_observation("syncular_fts_schema");
4690 return Err(error);
4691 }
4692 if let Err(error) = self.conn.execute_batch("RELEASE syncular_fts_schema") {
4693 self.rollback_observation("syncular_fts_schema");
4694 return Err(error.to_string());
4695 }
4696 Ok(())
4697 }
4698
4699 fn persist_outbox_insert(&self, commit: &OutboxCommit) -> Result<(), String> {
4702 let ops: Vec<Value> = commit
4703 .ops
4704 .iter()
4705 .map(|op| {
4706 let mut entry = serde_json::json!({
4707 "op": if op.upsert { "upsert" } else { "delete" },
4708 "table": op.table,
4709 "rowId": op.row_id,
4710 "baseVersion": op.base_version,
4711 "values": op.values.clone().map(Value::Object),
4712 });
4713 if op.insert {
4714 entry["insert"] = Value::Bool(true);
4715 }
4716 entry
4717 })
4718 .collect();
4719 self.conn
4720 .execute(
4721 "INSERT OR REPLACE INTO _syncular_outbox (commit_id, ops_json, created_at_ms) VALUES (?1, ?2, ?3)",
4722 rusqlite::params![
4723 commit.client_commit_id,
4724 Value::Array(ops).to_string(),
4725 self.clock_now_ms()
4726 ],
4727 )
4728 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4729 for operation in &commit.ops {
4730 let Some(values) = &operation.values else {
4731 continue;
4732 };
4733 let Some(table) = self.schema.table(&operation.table) else {
4734 continue;
4735 };
4736 for column in table
4737 .columns
4738 .iter()
4739 .filter(|column| column.ty == ColumnType::BlobRef)
4740 {
4741 let Some(Value::String(raw)) = values.get(&column.name) else {
4742 continue;
4743 };
4744 let Ok(blob_ref) = serde_json::from_str::<Value>(raw) else {
4745 continue;
4746 };
4747 let Some(blob_id) = blob_ref.get("blobId").and_then(Value::as_str) else {
4748 continue;
4749 };
4750 self.conn
4751 .execute(
4752 "INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id, blob_id)
4753 SELECT ?1, ?2 WHERE EXISTS (SELECT 1 FROM _syncular_blobs WHERE blob_id = ?2)",
4754 rusqlite::params![commit.client_commit_id, blob_id],
4755 )
4756 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4757 }
4758 }
4759 Ok(())
4760 }
4761
4762 fn delete_outbox_persisted(&self, client_commit_id: &str) -> Result<(), String> {
4763 self.conn
4764 .execute(
4765 "DELETE FROM _syncular_blob_commit_refs WHERE commit_id = ?1",
4766 rusqlite::params![client_commit_id],
4767 )
4768 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4769 self.conn
4770 .execute(
4771 "DELETE FROM _syncular_outbox WHERE commit_id = ?1",
4772 rusqlite::params![client_commit_id],
4773 )
4774 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4775 self.conn.execute("DELETE FROM _syncular_row_deliveries WHERE NOT EXISTS(SELECT 1 FROM _syncular_outbox,json_each(ops_json) WHERE json_extract(json_each.value,'$.table')=tbl AND json_extract(json_each.value,'$.rowId')=id)", [])
4776 .map(|_| ())
4777 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4778 }
4779
4780 fn outcome_status_name(status: CommitOutcomeStatus) -> &'static str {
4781 match status {
4782 CommitOutcomeStatus::Applied => "applied",
4783 CommitOutcomeStatus::Cached => "cached",
4784 CommitOutcomeStatus::Conflict => "conflict",
4785 CommitOutcomeStatus::Rejected => "rejected",
4786 }
4787 }
4788
4789 fn outcome_resolution_name(resolution: CommitOutcomeResolution) -> &'static str {
4790 match resolution {
4791 CommitOutcomeResolution::Active => "active",
4792 CommitOutcomeResolution::ResolvedKeepServer => "resolved_keep_server",
4793 CommitOutcomeResolution::Superseded => "superseded",
4794 CommitOutcomeResolution::Dismissed => "dismissed",
4795 }
4796 }
4797
4798 fn parse_outcome_status(value: &str) -> Result<CommitOutcomeStatus, String> {
4799 match value {
4800 "applied" => Ok(CommitOutcomeStatus::Applied),
4801 "cached" => Ok(CommitOutcomeStatus::Cached),
4802 "conflict" => Ok(CommitOutcomeStatus::Conflict),
4803 "rejected" => Ok(CommitOutcomeStatus::Rejected),
4804 _ => Err(format!("invalid persisted commit outcome status {value:?}")),
4805 }
4806 }
4807
4808 fn parse_outcome_resolution(value: &str) -> Result<CommitOutcomeResolution, String> {
4809 match value {
4810 "active" => Ok(CommitOutcomeResolution::Active),
4811 "resolved_keep_server" => Ok(CommitOutcomeResolution::ResolvedKeepServer),
4812 "superseded" => Ok(CommitOutcomeResolution::Superseded),
4813 "dismissed" => Ok(CommitOutcomeResolution::Dismissed),
4814 _ => Err(format!(
4815 "invalid persisted commit outcome resolution {value:?}"
4816 )),
4817 }
4818 }
4819
4820 fn persist_commit_outcome(
4821 &self,
4822 client_commit_id: &str,
4823 status: CommitOutcomeStatus,
4824 results: &[CommitOperationOutcome],
4825 operations: Option<&[OutboxOp]>,
4826 ) -> Result<(), String> {
4827 let results_json = serde_json::to_string(results).map_err(|error| error.to_string())?;
4828 let operations_json = operations
4829 .map(|items| {
4830 serde_json::to_string(&items.iter().map(CommitOperation::from).collect::<Vec<_>>())
4831 })
4832 .transpose()
4833 .map_err(|error| error.to_string())?;
4834 self.conn
4835 .execute(
4836 "INSERT INTO _syncular_commit_outcomes (
4837 client_commit_id, status, recorded_at_ms, results_json,
4838 operations_json, resolution
4839 ) VALUES (?1, ?2, ?3, ?4, ?5, 'active')",
4840 rusqlite::params![
4841 client_commit_id,
4842 Self::outcome_status_name(status),
4843 self.clock_now_ms(),
4844 results_json,
4845 operations_json
4846 ],
4847 )
4848 .map(|_| ())
4849 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4850 }
4851
4852 fn stored_cell_is_representable(cell: &Value) -> bool {
4855 cell.is_null()
4856 || cell.is_string()
4857 || cell.is_boolean()
4858 || cell.is_number()
4859 || is_canonical_bytes_envelope(cell)
4860 }
4861
4862 fn stored_row_is_representable(value: &Value) -> bool {
4863 value
4864 .as_object()
4865 .is_some_and(|row| row.values().all(Self::stored_cell_is_representable))
4866 }
4867
4868 fn stored_operation_is_representable(value: &Value) -> bool {
4869 value.get("table").is_some_and(Value::is_string)
4870 && value.get("rowId").is_some_and(Value::is_string)
4871 && value.get("baseVersion").is_none_or(|v| {
4872 v.as_i64()
4873 .is_some_and(|n| n.unsigned_abs() <= MAX_JS_SAFE_INTEGER)
4874 })
4875 && match value.get("op").and_then(Value::as_str) {
4876 Some("upsert") => {
4877 value
4878 .get("values")
4879 .is_some_and(Self::stored_row_is_representable)
4880 && value
4881 .get("insert")
4882 .is_none_or(|insert| *insert == Value::Bool(true))
4883 }
4884 Some("delete") => value.get("values").is_none() && value.get("insert").is_none(),
4885 _ => false,
4886 }
4887 }
4888
4889 fn outbox_op_is_journalable(operation: &OutboxOp) -> bool {
4893 serde_json::to_value(CommitOperation::from(operation))
4894 .is_ok_and(|value| Self::stored_operation_is_representable(&value))
4895 }
4896
4897 fn outcome_from_row(row: StoredCommitOutcomeRow) -> Result<CommitOutcome, String> {
4898 let StoredCommitOutcomeRow {
4899 sequence,
4900 client_commit_id,
4901 status,
4902 recorded_at_ms,
4903 results_json,
4904 operations_json,
4905 resolution,
4906 resolved_at_ms,
4907 replacement_client_commit_id,
4908 } = row;
4909 if sequence.unsigned_abs() > MAX_JS_SAFE_INTEGER
4910 || recorded_at_ms.unsigned_abs() > MAX_JS_SAFE_INTEGER
4911 || resolved_at_ms.is_some_and(|value| value.unsigned_abs() > MAX_JS_SAFE_INTEGER)
4912 {
4913 return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned());
4914 }
4915 let invalid = || "sync.local_corrupt: persisted commit outcome is invalid".to_owned();
4916 let stored: Vec<Value> = serde_json::from_str(&results_json).map_err(|_| invalid())?;
4917 for result in &stored {
4918 let nested = match result.get("status").and_then(Value::as_str) {
4919 Some("conflict") => result.get("conflict"),
4920 Some("error") => result.get("rejection"),
4921 _ => None,
4922 };
4923 if nested
4924 .and_then(|record| record.get("operation"))
4925 .is_some_and(|op| !Self::stored_operation_is_representable(op))
4926 || (result.get("status").and_then(Value::as_str) == Some("conflict")
4927 && nested
4928 .and_then(|record| record.get("serverRow"))
4929 .is_some_and(|row| !Self::stored_row_is_representable(row)))
4930 {
4931 return Err(invalid());
4932 }
4933 }
4934 let results: Vec<CommitOperationOutcome> =
4935 serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())?;
4936 let has_conflict = results
4937 .iter()
4938 .any(|result| matches!(result, CommitOperationOutcome::Conflict { .. }));
4939 let has_error = results
4940 .iter()
4941 .any(|result| matches!(result, CommitOperationOutcome::Error { .. }));
4942 let status = Self::parse_outcome_status(&status).map_err(|_| invalid())?;
4943 let redacted = results.is_empty() && operations_json.is_none();
4944 if match status {
4945 CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => has_conflict || has_error,
4946 CommitOutcomeStatus::Conflict => !(has_conflict || redacted),
4947 CommitOutcomeStatus::Rejected => has_conflict || !(has_error || redacted),
4948 } {
4949 return Err(invalid());
4950 }
4951 let operations: Option<Vec<CommitOperation>> = operations_json
4952 .map(|raw| {
4953 let stored: Vec<Value> = serde_json::from_str(&raw).map_err(|_| invalid())?;
4954 if !stored.iter().all(Self::stored_operation_is_representable) {
4955 return Err(invalid());
4956 }
4957 serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())
4958 })
4959 .transpose()?;
4960 for result in &results {
4961 match result {
4962 CommitOperationOutcome::Conflict { conflict }
4963 if conflict.server_version.unsigned_abs() > MAX_JS_SAFE_INTEGER =>
4964 {
4965 return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned())
4966 }
4967 CommitOperationOutcome::Error { rejection } => {
4968 if let Some(details) = &rejection.details {
4969 let encoded = serde_json::to_string(details).map_err(|_| {
4970 "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4971 })?;
4972 RejectionDetails::parse(&encoded).map_err(|_| {
4973 "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4974 })?;
4975 }
4976 }
4977 _ => {}
4978 }
4979 }
4980 Ok(CommitOutcome {
4981 sequence,
4982 client_commit_id,
4983 status,
4984 recorded_at_ms,
4985 results,
4986 operations,
4987 retained_rows: None,
4988 resolution: Self::parse_outcome_resolution(&resolution)?,
4989 resolved_at_ms,
4990 replacement_client_commit_id,
4991 })
4992 }
4993
4994 fn unique_conflicts(
4996 &self,
4997 table: &TableSchema,
4998 values: &Map<String, Value>,
4999 base: bool,
5000 ) -> Result<Vec<RetainedUniqueConflict>, String> {
5001 let source = if base {
5002 base_table(&table.name)
5003 } else {
5004 visible_table(&table.name)
5005 };
5006 let mut conflicts = Vec::new();
5007 for index in table.indexes.iter().filter(|index| index.unique) {
5008 let mut params = vec![json_param_to_sql(
5009 values.get(&table.primary_key).ok_or("sync.local_corrupt")?,
5010 )?];
5011 for name in &index.columns {
5012 let column = table
5013 .columns
5014 .iter()
5015 .find(|column| column.name == *name)
5016 .ok_or("sync.local_corrupt")?;
5017 let cell = json_to_column_value(column, values.get(name))?;
5018 params.push(owned_sql_value(RowParam::Cell(&cell))?);
5019 }
5020 let sql = format!(
5021 "SELECT * FROM {source} WHERE {} != ? AND {}",
5022 quote_ident(&table.primary_key),
5023 index
5024 .columns
5025 .iter()
5026 .map(|column| format!("{} = ?", quote_ident(column)))
5027 .collect::<Vec<_>>()
5028 .join(" AND ")
5029 );
5030 let mut statement = self
5031 .conn
5032 .prepare_cached(&sql)
5033 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5034 let records = statement
5035 .query_map(rusqlite::params_from_iter(params), |record| {
5036 let values = table
5037 .columns
5038 .iter()
5039 .enumerate()
5040 .map(|(index, column)| {
5041 let value = sql_ref_to_json(column, record.get_ref(index)?);
5042 json_to_column_value(column, Some(&value)).map_err(|message| {
5043 rusqlite::Error::ToSqlConversionFailure(message.into())
5044 })
5045 })
5046 .collect::<Result<Row, _>>()?;
5047 Ok((values, record.get::<_, i64>(table.columns.len())?))
5048 })
5049 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5050 for record in records {
5051 let (row, version) =
5052 record.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5053 let row_id = render_row_id_json(Some(&column_value_to_json(&row[table.pk_index])))?;
5054 conflicts.push(RetainedUniqueConflict {
5055 index: index.name.clone(),
5056 columns: index.columns.clone(),
5057 row_id,
5058 server_row: table
5059 .columns
5060 .iter()
5061 .zip(&row)
5062 .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
5063 .collect(),
5064 server_version: version,
5065 });
5066 }
5067 }
5068 Ok(conflicts)
5069 }
5070
5071 fn attach_retained_rows(&self, mut outcome: CommitOutcome) -> Result<CommitOutcome, String> {
5072 if let Some((commit, initial)) = self
5073 .failed_commits
5074 .iter()
5075 .find(|(commit, _)| commit.client_commit_id == outcome.client_commit_id)
5076 {
5077 let mut rows = Vec::new();
5078 for operation in &commit.ops {
5079 let Some(table) = self.schema.table(&operation.table) else {
5081 continue;
5082 };
5083 let key =
5084 serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
5085 .map_err(|_| "sync.local_corrupt".to_owned())?;
5086 let base = self.stored_row(table, &operation.row_id, true)?;
5087 rows.push(RetainedCommitRow {
5088 table: operation.table.clone(),
5089 row_id: operation.row_id.clone(),
5090 unique_conflicts: if operation.upsert {
5091 self.unique_conflicts(
5092 table,
5093 initial
5094 .get(&key)
5095 .and_then(Value::as_object)
5096 .or(operation.values.as_ref())
5097 .ok_or("sync.local_corrupt")?,
5098 true,
5099 )?
5100 } else {
5101 Vec::new()
5102 },
5103 local_row: if operation.upsert {
5104 initial
5105 .get(&key)
5106 .and_then(Value::as_object)
5107 .cloned()
5108 .or_else(|| operation.values.clone())
5109 } else {
5110 None
5111 },
5112 server_row: base.as_ref().map(|(values, _)| {
5113 table
5114 .columns
5115 .iter()
5116 .zip(values)
5117 .map(|(column, value)| {
5118 (column.name.clone(), column_value_to_json(value))
5119 })
5120 .collect()
5121 }),
5122 server_version: base.map(|(_, version)| version),
5123 });
5124 }
5125 outcome.retained_rows = Some(rows);
5126 }
5127 Ok(outcome)
5128 }
5129
5130 pub fn commit_outcome(&self, client_commit_id: &str) -> Result<Option<CommitOutcome>, String> {
5131 let row = self
5132 .conn
5133 .query_row(
5134 "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
5135 resolution, resolved_at_ms, replacement_client_commit_id
5136 FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
5137 rusqlite::params![client_commit_id],
5138 |row| {
5139 Ok(StoredCommitOutcomeRow {
5140 sequence: row.get(0)?,
5141 client_commit_id: row.get(1)?,
5142 status: row.get(2)?,
5143 recorded_at_ms: row.get(3)?,
5144 results_json: row.get(4)?,
5145 operations_json: row.get(5)?,
5146 resolution: row.get(6)?,
5147 resolved_at_ms: row.get(7)?,
5148 replacement_client_commit_id: row.get(8)?,
5149 })
5150 },
5151 )
5152 .optional()
5153 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5154 row.map(|row| self.attach_retained_rows(Self::outcome_from_row(row)?))
5155 .transpose()
5156 }
5157
5158 #[doc(hidden)]
5160 pub fn prepare_current_base(
5161 &self,
5162 client_commit_id: &str,
5163 sequence: i64,
5164 ) -> Result<CurrentBasePreparation, CurrentBaseProof> {
5165 let outcome = self
5166 .commit_outcome(client_commit_id)
5167 .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?;
5168 let valid = outcome.as_ref().is_some_and(|outcome| {
5169 outcome.sequence == sequence
5170 && outcome.resolution == CommitOutcomeResolution::Active
5171 && matches!(
5172 outcome.status,
5173 CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
5174 )
5175 && outcome
5176 .operations
5177 .as_ref()
5178 .zip(outcome.retained_rows.as_ref())
5179 .is_some_and(|(operations, rows)| {
5180 !rows.is_empty() && operations.len() == rows.len()
5181 })
5182 });
5183 if !valid {
5184 return Err(CurrentBaseProof::failure(
5185 CurrentBaseProofReason::OutcomeUnavailable,
5186 ));
5187 }
5188 if !self.transport_enabled {
5189 return Err(CurrentBaseProof::failure(CurrentBaseProofReason::Offline));
5190 }
5191 Ok(CurrentBasePreparation {
5192 client_commit_id: client_commit_id.to_owned(),
5193 sequence,
5194 replacement: None,
5195 units: load_units(&self.conn)
5196 .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?,
5197 transport_epoch: self.transport_epoch,
5198 registration_epoch: self.registration_epoch,
5199 security_epoch: self.security_epoch,
5200 })
5201 }
5202
5203 #[doc(hidden)]
5205 pub fn finish_current_base(
5206 &mut self,
5207 prepared: CurrentBasePreparation,
5208 drive: SyncOutcome,
5209 ) -> CurrentBaseProof {
5210 if !self.transport_enabled || self.transport_epoch != prepared.transport_epoch {
5211 return CurrentBaseProof::failure(CurrentBaseProofReason::Offline);
5212 }
5213 if self.registration_epoch != prepared.registration_epoch {
5214 return CurrentBaseProof::failure(CurrentBaseProofReason::MissingCoverage);
5215 }
5216 if self.security_preflight || self.security_epoch != prepared.security_epoch {
5217 return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed);
5218 }
5219 let report = match drive {
5220 SyncOutcome::Ok(report) => report,
5221 SyncOutcome::BudgetExhausted(_) => {
5222 return CurrentBaseProof::failure(CurrentBaseProofReason::BudgetExhausted)
5223 }
5224 _ => return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed),
5225 };
5226 if report.schema_floor.is_some() {
5227 return CurrentBaseProof::failure(CurrentBaseProofReason::SchemaFloor);
5228 }
5229 if self
5230 .conn
5231 .execute_batch("SAVEPOINT syncular_base_proof")
5232 .is_err()
5233 {
5234 return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
5235 }
5236 let proof = (|| {
5237 let snapshot = snapshot_read_connection(
5238 &self.conn,
5239 &SnapshotReadRequest {
5240 units: prepared.units.iter().map(|unit| unit.id.clone()).collect(),
5241 commit_ids: vec![prepared.client_commit_id.clone()],
5242 ..Default::default()
5243 },
5244 )
5245 .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
5246 let current = self
5247 .commit_outcome(&prepared.client_commit_id)
5248 .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
5249 let unavailable = if report.revoked.is_empty() {
5250 CurrentBaseProofReason::OutcomeUnavailable
5251 } else {
5252 CurrentBaseProofReason::Revoked
5253 };
5254 let Some(outcome) = current else {
5255 return Err(unavailable);
5256 };
5257 if !matches!(
5258 snapshot.deliveries.first(),
5259 Some(CommitDelivery::Known { .. })
5260 ) || outcome.sequence != prepared.sequence
5261 || outcome.resolution != CommitOutcomeResolution::Active
5262 || !matches!(
5263 outcome.status,
5264 CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
5265 )
5266 {
5267 return Err(unavailable);
5268 }
5269 let (Some(operations), Some(rows)) = (outcome.operations, outcome.retained_rows) else {
5270 return Err(unavailable);
5271 };
5272 if rows.is_empty() || operations.len() != rows.len() {
5273 return Err(unavailable);
5274 }
5275 let after =
5276 load_units(&self.conn).map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
5277 let complete: HashSet<&str> = snapshot
5278 .units
5279 .iter()
5280 .filter_map(|unit| match unit {
5281 UnitCatchup::Known {
5282 id,
5283 bootstrap_complete: true,
5284 ..
5285 } => Some(id.as_str()),
5286 _ => None,
5287 })
5288 .collect();
5289 let candidates: Vec<&UnitRecord> = after
5292 .iter()
5293 .filter(|unit| {
5294 complete.contains(unit.id.as_str())
5295 && prepared.units.iter().any(|before| before.id == unit.id)
5296 })
5297 .collect();
5298 let covered = |table_name: &str, row: &Map<String, Value>| {
5299 let Some(table) = self.schema.table(table_name) else {
5300 return false;
5301 };
5302 candidates.iter().any(|unit| {
5303 covers(table, &unit.scopes)
5304 && pair_scopes(&unit.scopes, table_name, unit.echo.as_deref()).is_some_and(
5305 |scopes| {
5306 scopes.iter().all(|(variable, allowed)| {
5307 table
5308 .scope_column(variable)
5309 .and_then(|column| match row.get(column) {
5310 Some(Value::String(value)) => Some(value.clone()),
5311 Some(Value::Bool(value)) => Some(value.to_string()),
5312 Some(Value::Number(value)) => {
5313 value.as_f64().map(|number| {
5314 ryu_js::Buffer::new()
5315 .format_finite(number)
5316 .to_owned()
5317 })
5318 }
5319 _ => None,
5320 })
5321 .is_some_and(|value| {
5322 !value.is_empty() && allowed.contains(&value)
5323 })
5324 })
5325 },
5326 )
5327 })
5328 };
5329 for row in &rows {
5330 let Some(base) = row.server_row.as_ref().or(row.local_row.as_ref()) else {
5331 return Err(if report.revoked.is_empty() {
5332 CurrentBaseProofReason::MissingCoverage
5333 } else {
5334 CurrentBaseProofReason::Revoked
5335 });
5336 };
5337 if !covered(&row.table, base)
5338 || row
5339 .unique_conflicts
5340 .iter()
5341 .any(|conflict| !covered(&row.table, &conflict.server_row))
5342 {
5343 return Err(if report.revoked.is_empty() {
5344 CurrentBaseProofReason::MissingCoverage
5345 } else {
5346 CurrentBaseProofReason::Revoked
5347 });
5348 }
5349 }
5350 Ok(rows)
5351 })();
5352 if self
5353 .conn
5354 .execute_batch("RELEASE syncular_base_proof")
5355 .is_err()
5356 {
5357 return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
5358 }
5359 match proof {
5360 Ok(rows) => CurrentBaseProof {
5361 proven: true,
5362 rows: Some(rows),
5363 reason: None,
5364 },
5365 Err(reason) => CurrentBaseProof::failure(reason),
5366 }
5367 }
5368
5369 pub fn prove_current_base(
5370 &mut self,
5371 transport: &mut dyn Transport,
5372 client_commit_id: &str,
5373 sequence: i64,
5374 max_rounds: Option<u32>,
5375 ) -> CurrentBaseProof {
5376 let prepared = match self.prepare_current_base(client_commit_id, sequence) {
5377 Ok(prepared) => prepared,
5378 Err(proof) => return proof,
5379 };
5380 let drive = self.sync_until_idle(transport, max_rounds);
5381 self.finish_current_base(prepared, drive)
5382 }
5383
5384 pub fn commit_outcomes(&self, query: CommitOutcomeQuery) -> Result<Vec<CommitOutcome>, String> {
5385 if query.limit == Some(0) {
5386 return Err("sync.invalid_request: commit outcome limit must be positive".to_owned());
5387 }
5388 let mut sql = String::from(
5389 "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
5390 resolution, resolved_at_ms, replacement_client_commit_id
5391 FROM _syncular_commit_outcomes",
5392 );
5393 if query.active_only {
5394 sql.push_str(" WHERE resolution = 'active' AND status IN ('conflict', 'rejected')");
5395 }
5396 sql.push_str(" ORDER BY seq DESC");
5397 if let Some(limit) = query.limit {
5398 sql.push_str(&format!(" LIMIT {limit}"));
5399 }
5400 let mut stmt = self
5401 .conn
5402 .prepare(&sql)
5403 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5404 let rows = stmt
5405 .query_map([], |row| {
5406 Ok(StoredCommitOutcomeRow {
5407 sequence: row.get(0)?,
5408 client_commit_id: row.get(1)?,
5409 status: row.get(2)?,
5410 recorded_at_ms: row.get(3)?,
5411 results_json: row.get(4)?,
5412 operations_json: row.get(5)?,
5413 resolution: row.get(6)?,
5414 resolved_at_ms: row.get(7)?,
5415 replacement_client_commit_id: row.get(8)?,
5416 })
5417 })
5418 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5419 let mut outcomes = Vec::new();
5420 for row in rows {
5421 outcomes.push(self.attach_retained_rows(Self::outcome_from_row(
5422 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
5423 )?)?);
5424 }
5425 Ok(outcomes)
5426 }
5427
5428 fn prune_commit_outcomes(&self) -> Result<(), String> {
5429 #[cfg(test)]
5430 self.outcome_prune_count
5431 .set(self.outcome_prune_count.get() + 1);
5432 let max_entries = self.limits.outcome_retention_max_entries.unwrap_or(1_000);
5433 let count = self
5434 .conn
5435 .query_row(
5436 "SELECT COUNT(*) FROM _syncular_commit_outcomes",
5437 [],
5438 |row| row.get::<_, i64>(0),
5439 )
5440 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5441 as usize;
5442 let excess = count.saturating_sub(max_entries);
5443 if excess == 0 {
5444 return Ok(());
5445 }
5446 let mut stmt = self
5447 .conn
5448 .prepare(
5449 "SELECT seq FROM _syncular_commit_outcomes
5450 WHERE status IN ('applied', 'cached') OR resolution != 'active'
5451 ORDER BY seq ASC LIMIT ?1",
5452 )
5453 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5454 let rows = stmt
5455 .query_map(rusqlite::params![excess as i64], |row| row.get::<_, i64>(0))
5456 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5457 let sequences = rows
5458 .collect::<Result<Vec<_>, _>>()
5459 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5460 drop(stmt);
5461 for sequence in sequences {
5462 self.conn
5463 .execute(
5464 "DELETE FROM _syncular_commit_outcomes WHERE seq = ?1",
5465 rusqlite::params![sequence],
5466 )
5467 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5468 }
5469 Ok(())
5470 }
5471
5472 pub fn units(&self) -> Result<Vec<UnitRecord>, String> {
5476 self.stored(load_units(&self.conn))
5477 }
5478
5479 pub fn unit(&self, id: &str) -> Result<Option<UnitRecord>, String> {
5480 self.stored(get_unit(&self.conn, id))
5481 }
5482
5483 pub fn subscribe(&mut self, scopes: UnitScopes) -> Result<String, String> {
5485 Ok(self.subscribe_many(vec![scopes])?.remove(0))
5486 }
5487
5488 pub fn subscribe_many(&mut self, units: Vec<UnitScopes>) -> Result<Vec<String>, String> {
5495 self.begin_observation("syncular_subscribe")?;
5496 let mut changed = false;
5497 let registered = (|| {
5498 let mut ids = Vec::with_capacity(units.len());
5499 for scopes in units {
5500 let (id, held) = self.hold_unit(scopes, true)?;
5501 changed |= held;
5502 ids.push(id);
5503 }
5504 self.conn
5505 .execute_batch("RELEASE syncular_subscribe")
5506 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5507 Ok(ids)
5508 })();
5509 let ids = match registered {
5510 Ok(ids) => ids,
5511 Err(error) => {
5512 self.rollback_observation("syncular_subscribe");
5513 return Err(error);
5514 }
5515 };
5516 if changed {
5517 self.registration_epoch = self.registration_epoch.wrapping_add(1);
5518 self.set_sync_needed(true, true);
5519 }
5520 Ok(ids)
5521 }
5522
5523 pub fn unsubscribe(&mut self, id: &str) -> Result<(), String> {
5526 let Some(unit) = self.stored(get_unit(&self.conn, id))? else {
5527 return Ok(());
5528 };
5529 if !unit.explicit {
5530 return Ok(());
5531 }
5532 if !self.stored(window_refs(&self.conn, id))?.is_empty() {
5533 return self.stored(save_unit(
5534 &self.conn,
5535 &UnitRecord {
5536 explicit: false,
5537 ..unit
5538 },
5539 ));
5540 }
5541 self.conn
5542 .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5543 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5544 self.registration_epoch = self.registration_epoch.wrapping_add(1);
5545 if unit.status == UnitStatus::Active {
5546 self.set_sync_needed(true, true);
5547 }
5548 Ok(())
5549 }
5550
5551 fn hold_unit(&mut self, scopes: UnitScopes, explicit: bool) -> Result<(String, bool), String> {
5555 if scopes.is_empty()
5556 || scopes.values().any(|value| value == "*")
5557 || !self
5558 .schema
5559 .tables
5560 .iter()
5561 .any(|table| covers(table, &scopes))
5562 {
5563 return Err("sync.invalid_subscription: a unit names one non-wildcard value per variable and covers a table".to_owned());
5564 }
5565 let id = ssp2::registration::unit_id(&scope_pairs(&scopes));
5566 let existing = self.stored(get_unit(&self.conn, &id))?;
5567 if let Some(existing) = existing
5568 .as_ref()
5569 .filter(|unit| unit.status != UnitStatus::Revoked)
5570 {
5571 if explicit && !existing.explicit {
5572 self.stored(save_unit(
5573 &self.conn,
5574 &UnitRecord {
5575 explicit,
5576 ..existing.clone()
5577 },
5578 ))?;
5579 }
5580 return Ok((id, false));
5581 }
5582 self.delete_pending_evict(&id)?;
5583 self.stored(save_unit(
5584 &self.conn,
5585 &UnitRecord {
5586 id: id.clone(),
5587 scopes,
5588 explicit: explicit || existing.is_some_and(|unit| unit.explicit),
5589 status: UnitStatus::Active,
5590 reason_code: None,
5591 cursor: Some(-1),
5592 bootstrap_state: None,
5593 seeded: Vec::new(),
5594 echo: None,
5595 restriction: None,
5596 },
5597 ))?;
5598 Ok((id, true))
5599 }
5600
5601 pub fn set_window(
5609 &mut self,
5610 base: &WindowBase,
5611 units: &[String],
5612 ) -> Result<CommandEffects, String> {
5613 let base_key = window_base_key(base);
5614 let live = self.load_window_units(&base_key)?;
5615 let mut changed = false;
5616 let added: Vec<&String> = units
5618 .iter()
5619 .filter(|value| !live.iter().any(|(held, _)| held == *value))
5620 .collect();
5621 if !added.is_empty() {
5622 let rollback = self.capture();
5623 self.begin_observation("syncular_window")?;
5624 let widened = (|| {
5625 let mut batch = ChangeAccumulator::default();
5626 for value in &added {
5627 let (id, registered) =
5628 self.hold_unit(window_unit_scopes(base, value), false)?;
5629 self.sync_needed |= registered;
5630 self.conn
5631 .execute(
5632 "INSERT OR REPLACE INTO _syncular_windows(base, unit, sub_id) VALUES (?1, ?2, ?3)",
5633 rusqlite::params![base_key, value, id],
5634 )
5635 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5636 batch.window(&base_key, value);
5637 }
5638 batch.status = true;
5639 self.finish_observation("syncular_window", batch)
5640 })();
5641 if let Err(error) = widened {
5642 self.rollback_observation("syncular_window");
5643 self.restore(rollback);
5644 return Err(error);
5645 }
5646 changed = true;
5647 self.registration_epoch = self.registration_epoch.wrapping_add(1);
5648 }
5649 for (value, id) in live {
5650 if units.contains(&value) {
5651 continue;
5652 }
5653 self.rebuild_overlay_if_dirty()?;
5654 let rollback = self.capture();
5655 self.begin_observation("syncular_window")?;
5656 let remaining = self.release_window_unit(&base_key, &value, &id);
5657 let remaining = match remaining {
5658 Ok(remaining) => remaining,
5659 Err(error) => {
5660 self.rollback_observation("syncular_window");
5661 self.restore(rollback);
5662 return Err(error);
5663 }
5664 };
5665 changed = true;
5666 self.registration_epoch = self.registration_epoch.wrapping_add(1);
5667 if remaining {
5668 self.drain_pending_evictions()?;
5669 }
5670 }
5671 Ok(if changed && self.transport_enabled {
5672 CommandEffects::interactive()
5673 } else {
5674 CommandEffects::none()
5675 })
5676 }
5677
5678 pub fn window_state(&self, base: &WindowBase) -> Result<WindowState, String> {
5682 persisted_window_state(&self.conn, base).map_err(|failure| failure.message)
5683 }
5684
5685 fn load_window_units(&self, base_key: &str) -> Result<Vec<(String, String)>, String> {
5687 let mut statement = self
5688 .conn
5689 .prepare_cached(
5690 "SELECT unit, sub_id FROM _syncular_windows WHERE base = ?1 ORDER BY unit ASC",
5691 )
5692 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5693 let rows = statement
5694 .query_map([base_key], |row| Ok((row.get(0)?, row.get(1)?)))
5695 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5696 rows.collect::<Result<_, _>>()
5697 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5698 }
5699
5700 fn load_window_registry(&self) -> Result<Vec<(String, String)>, String> {
5702 let mut statement = self
5703 .conn
5704 .prepare_cached("SELECT base, unit FROM _syncular_windows ORDER BY base, unit")
5705 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5706 let rows = statement
5707 .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))
5708 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5709 rows.collect::<Result<_, _>>()
5710 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5711 }
5712
5713 fn release_window_unit(
5721 &mut self,
5722 base_key: &str,
5723 value: &str,
5724 id: &str,
5725 ) -> Result<bool, String> {
5726 self.conn
5727 .execute(
5728 "DELETE FROM _syncular_windows WHERE base = ?1 AND unit = ?2",
5729 rusqlite::params![base_key, value],
5730 )
5731 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5732 let mut batch = ChangeAccumulator::default();
5733 batch.window(base_key, value);
5734 batch.status = true;
5735 let unit = self.stored(get_unit(&self.conn, id))?;
5736 let mut remaining = false;
5737 if let Some(unit) = unit.filter(|unit| !unit.explicit) {
5738 if self.stored(window_refs(&self.conn, id))?.is_empty() {
5739 let units = self.stored(load_units(&self.conn))?;
5740 self.conn
5741 .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5742 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5743 self.sync_needed = true;
5744 for table in self.schema.tables.clone() {
5745 let Some(effective) = unit
5746 .echo
5747 .as_deref()
5748 .filter(|_| covers(&table, &unit.scopes))
5749 .and_then(|echo| pair_scopes(&unit.scopes, &table.name, Some(echo)))
5750 else {
5751 continue;
5752 };
5753 let pinned = self.pinned_row_ids(&table.name);
5754 let owners = unit_owners(&units, &table, id);
5755 let (more, deferred) =
5756 self.evict_scope_rows(&table.name, &effective, &owners, &pinned)?;
5757 remaining |= more;
5758 if deferred {
5759 self.save_pending_evict(id, &table.name, &effective)?;
5760 }
5761 self.record_scope_map(&mut batch, &table.name, &effective);
5762 }
5763 }
5764 }
5765 self.finish_observation("syncular_window", batch)?;
5766 Ok(remaining)
5767 }
5768
5769 fn evict_scope_rows(
5774 &self,
5775 table_name: &str,
5776 effective: &[(String, Vec<String>)],
5777 owners: &[Vec<(String, Vec<String>)>],
5778 pinned: &std::collections::HashSet<String>,
5779 ) -> Result<(bool, bool), String> {
5780 let table = self.schema.table(table_name).ok_or("sync.unknown_table")?;
5781 let Some((scope, mut params)) = local_scope_predicate(table, effective, owners)
5782 .map_err(|()| "sync.scope_revoked".to_owned())?
5783 else {
5784 return Ok((false, false));
5785 };
5786 let scope_params = params.len();
5787 let pk = quote_ident(&table.primary_key);
5788 let predicate = if pinned.is_empty() {
5790 scope.clone()
5791 } else {
5792 params.extend(pinned.iter().cloned().map(SqlValue::Text));
5793 let holes = vec!["?"; pinned.len()].join(", ");
5794 format!("{scope} AND CAST({pk} AS TEXT) NOT IN ({holes})")
5795 };
5796 let base = base_table(table_name);
5797 let visible = visible_table(table_name);
5798 let mut ids: Vec<SqlValue> = Vec::new();
5799 for source in [&base, &visible] {
5800 let mut stmt = self
5801 .conn
5802 .prepare_cached(&format!(
5803 "SELECT {pk} FROM {source} WHERE {predicate} LIMIT 1024"
5804 ))
5805 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5806 ids = stmt
5807 .query_map(rusqlite::params_from_iter(¶ms), |row| row.get(0))
5808 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5809 .collect::<Result<_, _>>()
5810 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5811 if !ids.is_empty() {
5812 break;
5813 }
5814 }
5815 if !ids.is_empty() {
5816 for id in &ids {
5817 self.conn
5818 .execute(
5819 "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2",
5820 rusqlite::params![table_name, id],
5821 )
5822 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5823 }
5824 let holes = vec!["?"; ids.len()].join(", ");
5825 for source in [&base, &visible] {
5826 self.conn
5827 .execute(
5828 &format!("DELETE FROM {source} WHERE {pk} IN ({holes})"),
5829 rusqlite::params_from_iter(&ids),
5830 )
5831 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5832 }
5833 }
5834 let mut remaining = false;
5835 let mut deferred = false;
5836 for source in [&base, &visible] {
5837 remaining |= self
5838 .conn
5839 .query_row(
5840 &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
5841 rusqlite::params_from_iter(¶ms),
5842 |row| row.get::<_, bool>(0),
5843 )
5844 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5845 deferred |= self
5846 .conn
5847 .query_row(
5848 &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {scope})"),
5849 rusqlite::params_from_iter(¶ms[..scope_params]),
5850 |row| row.get::<_, bool>(0),
5851 )
5852 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5853 }
5854 Ok((remaining, deferred))
5855 }
5856
5857 fn drain_pending_evictions(&mut self) -> Result<(), String> {
5861 let pending = self.load_pending_evictions()?;
5862 if pending.is_empty() {
5863 return Ok(());
5864 }
5865 self.rebuild_overlay_if_dirty()?;
5866 for (unit_id, table_name, effective) in pending {
5867 let Some(table) = self.schema.table(&table_name).cloned() else {
5868 self.delete_pending_evict_table(&unit_id, &table_name)?;
5869 continue;
5870 };
5871 loop {
5872 std::thread::yield_now();
5873 self.begin_observation("syncular_evict")?;
5874 let chunk = (|| {
5875 let pinned = self.pinned_row_ids(&table_name);
5876 let owners =
5877 unit_owners(&self.stored(load_units(&self.conn))?, &table, &unit_id);
5878 let (remaining, deferred) =
5879 self.evict_scope_rows(&table_name, &effective, &owners, &pinned)?;
5880 if !deferred {
5881 self.delete_pending_evict_table(&unit_id, &table_name)?;
5882 }
5883 let mut batch = ChangeAccumulator::default();
5884 self.record_scope_map(&mut batch, &table_name, &effective);
5885 self.finish_observation("syncular_evict", batch)?;
5886 Ok(remaining)
5887 })();
5888 match chunk {
5889 Ok(true) => {}
5890 Ok(false) => break,
5891 Err(error) => {
5892 self.rollback_observation("syncular_evict");
5893 return Err(error);
5894 }
5895 }
5896 }
5897 }
5898 Ok(())
5899 }
5900
5901 fn pinned_row_ids(&self, table: &str) -> std::collections::HashSet<String> {
5904 let mut pinned = std::collections::HashSet::new();
5905 for commit in self
5906 .outbox
5907 .iter()
5908 .map(|commit| &**commit)
5909 .chain(self.failed_commits.iter().map(|(commit, _)| commit))
5910 {
5911 for op in &commit.ops {
5912 if op.table == table {
5913 pinned.insert(op.row_id.clone());
5914 }
5915 }
5916 }
5917 pinned
5918 }
5919
5920 fn save_pending_evict(
5921 &self,
5922 unit_id: &str,
5923 table: &str,
5924 effective: &[(String, Vec<String>)],
5925 ) -> Result<(), String> {
5926 self.conn.execute(
5927 "INSERT OR REPLACE INTO _syncular_pending_evictions(unit_id, tbl, effective_scopes) VALUES (?1, ?2, ?3)",
5928 rusqlite::params![unit_id, table, scope_map_to_json(effective).to_string()],
5929 ).map(|_| ()).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5930 }
5931
5932 fn delete_pending_evict(&self, unit_id: &str) -> Result<(), String> {
5934 self.conn
5935 .execute(
5936 "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
5937 [unit_id],
5938 )
5939 .map(|_| ())
5940 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5941 }
5942
5943 fn delete_pending_evict_table(&self, unit_id: &str, table: &str) -> Result<(), String> {
5944 self.conn
5945 .execute(
5946 "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1 AND tbl = ?2",
5947 [unit_id, table],
5948 )
5949 .map(|_| ())
5950 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5951 }
5952
5953 fn load_pending_evictions(&self) -> Result<Vec<PendingEvict>, String> {
5954 let mut stmt = self
5955 .conn
5956 .prepare("SELECT unit_id, tbl, effective_scopes FROM _syncular_pending_evictions")
5957 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5958 let rows = stmt
5959 .query_map([], |row| {
5960 Ok((
5961 row.get::<_, String>(0)?,
5962 row.get::<_, String>(1)?,
5963 row.get::<_, String>(2)?,
5964 ))
5965 })
5966 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5967 rows.map(|row| {
5968 let (unit_id, table, json) =
5969 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5970 let value: Value = serde_json::from_str(&json)
5971 .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5972 let effective = json_to_scope_map(&value)
5973 .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5974 Ok((unit_id, table, effective))
5975 })
5976 .collect()
5977 }
5978
5979 pub fn set_retain_failed_commits(&mut self, enabled: bool) -> Result<(), String> {
5981 self.retain_failed_commits = enabled;
5982 for (commit, _) in self.failed_commits.iter() {
5983 for operation in &commit.ops {
5984 self.overlay_dirty.table(&operation.table);
5985 }
5986 }
5987 self.failed_commits = self.load_failed_commits()?.into();
5988 for (commit, _) in self.failed_commits.iter() {
5989 for operation in &commit.ops {
5990 self.overlay_dirty.table(&operation.table);
5991 }
5992 }
5993 Ok(())
5994 }
5995
5996 fn load_failed_commits(&self) -> Result<Vec<FailedCommit>, String> {
5997 let mut statement = self.conn.prepare("SELECT client_commit_id, operations_json, initial_json FROM _syncular_failed_commits ORDER BY seq")
5998 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5999 let rows = statement
6000 .query_map([], |row| {
6001 Ok((
6002 row.get::<_, String>(0)?,
6003 row.get::<_, String>(1)?,
6004 row.get::<_, String>(2)?,
6005 ))
6006 })
6007 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6008 rows.map(|row| {
6009 let (id, operations, initial) =
6010 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6011 let operations: Vec<CommitOperation> =
6012 serde_json::from_str(&operations).map_err(|_| "sync.local_corrupt".to_owned())?;
6013 let initial =
6014 serde_json::from_str(&initial).map_err(|_| "sync.local_corrupt".to_owned())?;
6015 Ok((
6016 OutboxCommit {
6017 client_commit_id: id,
6018 ops: operations
6019 .into_iter()
6020 .map(|op| OutboxOp {
6021 upsert: op.op == "upsert",
6022 table: op.table,
6023 row_id: op.row_id,
6024 base_version: op.base_version,
6025 values: op.values,
6026 insert: op.insert,
6027 })
6028 .collect(),
6029 },
6030 initial,
6031 ))
6032 })
6033 .collect()
6034 }
6035
6036 fn retain_failed_commit(&mut self, id: &str, operations: &[OutboxOp]) -> Result<(), String> {
6037 let mut initial = Map::new();
6038 for operation in operations {
6039 let Some(table) = self.schema.table(&operation.table) else {
6041 continue;
6042 };
6043 let initial_row = match self.stored_row(table, &operation.row_id, true)? {
6044 Some(row) => Some(row),
6045 None => self.visible_row(table, &operation.row_id)?,
6046 };
6047 if let Some((values, _)) = initial_row {
6048 let mut intended: Map<String, Value> = table
6049 .columns
6050 .iter()
6051 .zip(values.iter())
6052 .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
6053 .collect();
6054 if let Some(patch) = &operation.values {
6055 intended.extend(patch.clone());
6056 }
6057 initial.insert(
6058 serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
6059 .map_err(|_| "sync.local_corrupt".to_owned())?,
6060 Value::Object(intended),
6061 );
6062 }
6063 }
6064 self.conn.execute("INSERT INTO _syncular_failed_commits(client_commit_id, operations_json, initial_json) VALUES (?1, ?2, ?3)", rusqlite::params![id,
6065 serde_json::to_string(&operations.iter().map(CommitOperation::from).collect::<Vec<_>>()).map_err(|_| "sync.local_corrupt".to_owned())?,
6066 serde_json::to_string(&initial).map_err(|_| "sync.local_corrupt".to_owned())?])
6067 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6068 self.failed_commits.push((
6069 OutboxCommit {
6070 client_commit_id: id.to_owned(),
6071 ops: operations.to_vec(),
6072 },
6073 initial,
6074 ));
6075 Ok(())
6076 }
6077
6078 fn drop_failed_commits(
6079 &mut self,
6080 matches: impl Fn(&str, &Map<String, Value>) -> bool,
6081 ) -> Result<Vec<OutboxCommit>, String> {
6082 let mut doomed = self.drop_acknowledged_rows(&matches)?;
6083 for (commit, initial) in self.failed_commits.iter() {
6084 for operation in &commit.ops {
6085 let key =
6086 serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
6087 .map_err(|_| "sync.local_corrupt".to_owned())?;
6088 if initial
6089 .get(&key)
6090 .and_then(Value::as_object)
6091 .is_some_and(|values| matches(&operation.table, values))
6092 {
6093 doomed.push(commit.clone());
6094 break;
6095 }
6096 }
6097 }
6098 for commit in &doomed {
6099 self.conn
6100 .execute(
6101 "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
6102 rusqlite::params![commit.client_commit_id],
6103 )
6104 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6105 }
6106 for commit in &doomed {
6107 self.conn.execute("UPDATE _syncular_commit_outcomes SET operations_json = NULL, results_json = '[]' WHERE client_commit_id = ?1", rusqlite::params![commit.client_commit_id]).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6108 }
6109 self.conflicts.retain(|record| {
6110 !doomed
6111 .iter()
6112 .any(|commit| commit.client_commit_id == record.client_commit_id)
6113 });
6114 self.rejections.retain(|record| {
6115 !doomed
6116 .iter()
6117 .any(|commit| commit.client_commit_id == record.client_commit_id)
6118 });
6119 self.failed_commits.retain(|(commit, _)| {
6120 !doomed
6121 .iter()
6122 .any(|dropped| dropped.client_commit_id == commit.client_commit_id)
6123 });
6124 for commit in &doomed {
6125 for operation in &commit.ops {
6126 self.overlay_dirty.table(&operation.table);
6127 }
6128 }
6129 Ok(doomed)
6130 }
6131
6132 pub fn mutate(&mut self, mutations: Vec<Mutation>) -> Result<String, ClientError> {
6136 self.mutate_with_commit_id(mutations, None)
6137 }
6138
6139 pub fn mutate_with_commit_id(
6143 &mut self,
6144 mutations: Vec<Mutation>,
6145 client_commit_id: Option<String>,
6146 ) -> Result<String, ClientError> {
6147 let prior = self.storage_failure.borrow_mut().take();
6148 if let Some(id) = &client_commit_id {
6149 let held = if id.is_empty() {
6150 Err("sync.invalid_request: clientCommitId is empty".to_owned())
6151 } else {
6152 self.conn
6153 .query_row(
6154 "SELECT EXISTS(SELECT 1 FROM _syncular_outbox WHERE commit_id=?1 UNION ALL SELECT 1 FROM _syncular_commit_outcomes WHERE client_commit_id=?1)",
6155 [id],
6156 |row| row.get(0),
6157 )
6158 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
6159 };
6160 match held {
6161 Ok(false) => {}
6162 Ok(true) => {
6163 return self.finish_authoring(
6164 prior,
6165 Err(ClientError {
6166 code: "client.commit_id_reused".to_owned(),
6167 message: "clientCommitId is held".to_owned(),
6168 details: Some(json!({ "clientCommitId": id })),
6169 retryable: false,
6170 }),
6171 )
6172 }
6173 Err(message) => return self.finish_authoring(prior, Err(message.into())),
6174 }
6175 }
6176 let outcome = self
6177 .prepare_mutations(mutations)
6178 .and_then(|ops| Ok(self.record_outbox_commit(ops, client_commit_id, None)?));
6179 self.finish_authoring(prior, outcome)
6180 }
6181
6182 fn prepare_mutations(&self, mutations: Vec<Mutation>) -> Result<Vec<OutboxOp>, ClientError> {
6184 {
6185 if mutations.is_empty() {
6186 return Err(
6187 "sync.invalid_request: a commit must contain at least one operation (§6.1)"
6188 .to_owned()
6189 .into(),
6190 );
6191 }
6192 let mut ops = Vec::with_capacity(mutations.len());
6193 let mut staged: HashMap<(String, String), Option<Map<String, Value>>> = HashMap::new();
6198 for mutation in mutations {
6199 match mutation {
6200 Mutation::Patch {
6201 table,
6202 values,
6203 base_version,
6204 } => {
6205 let schema_table = self
6206 .schema
6207 .table(&table)
6208 .ok_or_else(|| "sync.unknown_table".to_owned())?;
6209 let values = normalize_values_casing(schema_table, values)?;
6210 let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
6211 let base = staged.get(&(table.clone(), row_id.clone()));
6212 ops.push(self.prepare_patch(
6213 &table,
6214 &row_id,
6215 values,
6216 base_version,
6217 base,
6218 )?);
6219 }
6220 Mutation::Upsert {
6221 table,
6222 values,
6223 base_version,
6224 } => {
6225 let schema_table = self.schema.table(&table).ok_or_else(|| {
6226 format!("sync.unknown_table: unknown table {table:?}")
6227 })?;
6228 let values = normalize_values_casing(schema_table, values)?;
6232 let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
6233 let values = full_row_values(schema_table, values)?;
6236 self.refuse_sealed_row(schema_table, &row_id)?;
6237 self.validate_author_encode(schema_table, &row_id, &values)?;
6243 let insert = !self.visible_row_exists(schema_table, &row_id)?;
6247 staged.insert((table.clone(), row_id.clone()), Some(values.clone()));
6248 ops.push(OutboxOp {
6249 upsert: true,
6250 table,
6251 row_id,
6252 base_version,
6253 values: Some(values),
6254 insert,
6255 });
6256 }
6257 Mutation::Delete {
6258 table,
6259 row_id,
6260 base_version,
6261 } => {
6262 let schema_table = self.schema.table(&table).ok_or_else(|| {
6263 format!("sync.unknown_table: unknown table {table:?}")
6264 })?;
6265 self.refuse_sealed_row(schema_table, &row_id)?;
6266 if row_id.contains('\0') {
6268 return Err("sync.invalid_request: rowId holds U+0000 (§2.4)"
6269 .to_owned()
6270 .into());
6271 }
6272 staged.insert((table.clone(), row_id.clone()), None);
6273 ops.push(OutboxOp {
6274 upsert: false,
6275 table,
6276 row_id,
6277 base_version,
6278 values: None,
6279 insert: false,
6280 });
6281 }
6282 }
6283 }
6284 Ok(ops)
6285 }
6286 }
6287
6288 fn finish_authoring(
6294 &self,
6295 prior: Option<QueryReadFailure>,
6296 outcome: Result<String, ClientError>,
6297 ) -> Result<String, ClientError> {
6298 let fresh = self.storage_failure.borrow_mut().take();
6299 *self.storage_failure.borrow_mut() = fresh.clone().or(prior);
6300 outcome.map_err(|error| fresh.map(ClientError::from).unwrap_or(error))
6301 }
6302
6303 fn record_outbox_commit(
6306 &mut self,
6307 ops: Vec<OutboxOp>,
6308 client_commit_id: Option<String>,
6309 decides: Option<&str>,
6310 ) -> Result<String, String> {
6311 let commit = OutboxCommit {
6312 client_commit_id: client_commit_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
6313 ops,
6314 };
6315 self.begin_observation("syncular_mutation")?;
6316 let mut batch = ChangeAccumulator::default();
6317 for op in &commit.ops {
6318 let mut precise = self.record_row_scopes(&mut batch, &op.table, &op.row_id, false);
6319 if let Some(values) = &op.values {
6320 if let Some(table) = self.schema.table(&op.table) {
6321 for scope in &table.scope_variables {
6322 if let Some(Value::String(value)) = values.get(&scope.column) {
6323 batch.scope(&op.table, format!("{}:{value}", scope.prefix));
6324 precise = true;
6325 }
6326 }
6327 }
6328 }
6329 if !precise {
6330 batch.table(&op.table);
6331 }
6332 }
6333 let persisted = self.persist_outbox_insert(&commit).and_then(|()| {
6334 let Some(outcome) = decides else {
6335 return Ok(());
6336 };
6337 batch.outcomes = true;
6338 let updated = self
6339 .conn
6340 .execute(
6341 "UPDATE _syncular_commit_outcomes SET replacement_client_commit_id = ?1
6342 WHERE client_commit_id = ?2 AND resolution = 'active'
6343 AND replacement_client_commit_id IS NULL",
6344 rusqlite::params![commit.client_commit_id, outcome],
6345 )
6346 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6347 if updated == 1 {
6348 Ok(())
6349 } else {
6350 Err(REPLACEMENT_PENDING.to_owned())
6351 }
6352 });
6353 if let Err(error) = persisted {
6354 self.rollback_observation("syncular_mutation");
6355 return Err(error);
6356 }
6357 let was_dirty = self.overlay_dirty.snapshot();
6363 let id = commit.client_commit_id.clone();
6364 let appended = self.rebuild_overlay_if_dirty().and_then(|()| {
6365 commit
6366 .ops
6367 .iter()
6368 .try_for_each(|op| self.apply_outbox_op(op))?;
6369 self.outbox.push(Arc::new(commit));
6370 batch.status = true;
6371 self.finish_observation("syncular_mutation", batch)
6372 .inspect_err(|_| drop(self.outbox.pop()))
6373 });
6374 if let Err(error) = appended {
6375 self.rollback_observation("syncular_mutation");
6376 self.overlay_dirty.restore(was_dirty);
6377 return Err(error);
6378 }
6379 Ok(id)
6380 }
6381
6382 pub fn patch(
6388 &mut self,
6389 table: &str,
6390 row_id: &str,
6391 partial: Map<String, Value>,
6392 base_version: Option<i64>,
6393 ) -> Result<String, ClientError> {
6394 let prior = self.storage_failure.borrow_mut().take();
6395 let outcome = self.perform_patch(table, row_id, partial, base_version);
6396 self.finish_authoring(prior, outcome)
6397 }
6398
6399 fn perform_patch(
6402 &mut self,
6403 table: &str,
6404 row_id: &str,
6405 partial: Map<String, Value>,
6406 base_version: Option<i64>,
6407 ) -> Result<String, ClientError> {
6408 let operation = self.prepare_patch(table, row_id, partial, base_version, None)?;
6409 Ok(self.record_outbox_commit(vec![operation], None, None)?)
6410 }
6411
6412 fn prepare_patch(
6415 &self,
6416 table: &str,
6417 row_id: &str,
6418 partial: Map<String, Value>,
6419 base_version: Option<i64>,
6420 staged: Option<&Option<Map<String, Value>>>,
6421 ) -> Result<OutboxOp, ClientError> {
6422 let schema_table = self
6423 .schema
6424 .table(table)
6425 .ok_or_else(|| format!("sync.unknown_table: unknown table {table:?}"))?;
6426 let partial = normalize_values_casing(schema_table, partial)?;
6427 if let Some(pk) = partial.get(&schema_table.primary_key) {
6428 if render_row_id_json(Some(pk)).ok().as_deref() != Some(row_id) {
6429 return Err(invalid_authoring(
6430 "patch cannot change the primary key",
6431 json!({ "table": table }),
6432 ));
6433 }
6434 }
6435 let exists = match staged {
6436 Some(row) => row.is_some(),
6437 None => self.visible_row_exists(schema_table, row_id)?,
6438 };
6439 if !exists {
6440 return Err("sync.row_missing: a sparse patch requires a local row"
6441 .to_owned()
6442 .into());
6443 }
6444 self.refuse_sealed_row(schema_table, row_id)?;
6445 for scope in &schema_table.scope_variables {
6455 if !partial.contains_key(&scope.column) || scope.column == schema_table.primary_key {
6456 continue;
6457 }
6458 let Some(column) = schema_table
6459 .columns
6460 .iter()
6461 .find(|column| column.name == scope.column)
6462 else {
6463 continue;
6464 };
6465 let stored = match staged {
6466 Some(row) => row.as_ref().and_then(|row| {
6467 json_to_column_value(column, row.get(&scope.column))
6468 .ok()
6469 .map(|value| column_value_to_json(&value))
6470 }),
6471 None => self
6472 .conn
6473 .query_row(
6474 &format!(
6475 "SELECT {} FROM {} WHERE {}",
6476 quote_ident(&scope.column),
6477 visible_table(&schema_table.name),
6478 row_id_predicate(schema_table)
6479 ),
6480 rusqlite::params![row_id],
6481 |row| Ok(sql_ref_to_json(column, row.get_ref(0)?)),
6482 )
6483 .optional()
6484 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
6485 };
6486 let incoming = json_to_column_value(column, partial.get(&scope.column))
6491 .ok()
6492 .map(|value| column_value_to_json(&value));
6493 let equal = stored.as_ref().is_some_and(|stored| {
6497 stored.get("$bytes").is_none() && incoming.as_ref() == Some(stored)
6498 });
6499 if !equal {
6500 return Err(invalid_authoring(
6501 "patch cannot write a scope column (§3.4)",
6502 json!({ "table": table, "column": scope.column }),
6503 ));
6504 }
6505 }
6506 let mut values = partial;
6507 for scope in &schema_table.scope_variables {
6510 values.remove(&scope.column);
6511 }
6512 let pk_value = match schema_table.columns[schema_table.pk_index].ty {
6513 ColumnType::Integer => match row_id.parse::<i64>() {
6515 Ok(v)
6516 if v.to_string() == row_id
6517 && (-ssp2::primitives::I64_SAFE_MAX..=ssp2::primitives::I64_SAFE_MAX)
6518 .contains(&v) =>
6519 {
6520 Value::from(v)
6521 }
6522 _ => {
6523 return Err(format!(
6524 "sync.invalid_request: table {table:?}: invalid integer primary key {row_id:?}"
6525 )
6526 .into())
6527 }
6528 },
6529 ColumnType::Boolean => match row_id {
6530 "true" => Value::Bool(true),
6531 "false" => Value::Bool(false),
6532 _ => {
6533 return Err(format!(
6534 "sync.invalid_request: table {table:?}: invalid boolean primary key {row_id:?}"
6535 )
6536 .into())
6537 }
6538 },
6539 _ => Value::from(row_id.to_owned()),
6540 };
6541 values.insert(schema_table.primary_key.clone(), pk_value);
6542 if let Some(column) = schema_table
6544 .columns
6545 .iter()
6546 .find(|column| !column.nullable && values.get(&column.name) == Some(&Value::Null))
6547 {
6548 return Err(invalid_authoring(
6549 "a non-nullable column is null (§6.1)",
6550 json!({ "table": table, "column": column.name }),
6551 ));
6552 }
6553 self.validate_author_encode(schema_table, row_id, &values)?;
6559 Ok(OutboxOp {
6560 upsert: true,
6561 table: table.to_owned(),
6562 row_id: row_id.to_owned(),
6563 base_version,
6564 values: Some(values),
6565 insert: false,
6566 })
6567 }
6568
6569 fn stored_key_fallback(
6574 &self,
6575 table: &TableSchema,
6576 row_id: &str,
6577 ) -> Result<Option<Row>, String> {
6578 let Some(selector) = self.encryption.key_id_columns.get(&table.name) else {
6579 return Ok(None);
6580 };
6581 let Some(index) = table
6582 .columns
6583 .iter()
6584 .position(|column| &column.name == selector)
6585 else {
6586 return Ok(None);
6587 };
6588 let sql = format!(
6589 "SELECT {} FROM {} WHERE {}",
6590 quote_ident(selector),
6591 visible_table(&table.name),
6592 row_id_predicate(table)
6593 );
6594 let key = self
6595 .conn
6596 .query_row(&sql, rusqlite::params![row_id], |row| {
6597 row.get::<_, Option<String>>(0)
6598 })
6599 .optional()
6600 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6601 .flatten()
6602 .filter(|key| !key.is_empty());
6603 let Some(key) = key else {
6604 return Ok(None);
6605 };
6606 let mut fallback: Row = vec![None; table.columns.len()];
6607 fallback[index] = Some(ColumnValue::String(key));
6608 Ok(Some(fallback))
6609 }
6610
6611 fn validate_author_encode(
6616 &self,
6617 table: &TableSchema,
6618 row_id: &str,
6619 values: &Map<String, Value>,
6620 ) -> Result<(), String> {
6621 match encode_sparse_row_json(table, row_id, values, &self.encryption, None) {
6622 Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => Ok(()),
6623 result => result.map(|_| ()),
6624 }
6625 }
6626
6627 fn drop_unencodable_outbox(
6641 &mut self,
6642 with_encryption: bool,
6643 batch: Option<&mut ChangeAccumulator>,
6644 ) -> Result<bool, String> {
6645 let mut failures = Vec::new();
6646 for commit in self.outbox.iter() {
6647 for op in &commit.ops {
6648 let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6649 continue;
6650 };
6651 let Some(values) = op.presented_values(table) else {
6654 continue;
6655 };
6656 let fallback = self.stored_key_fallback(table, &op.row_id)?;
6657 let failure = match encode_sparse_row_json(
6658 table,
6659 &op.row_id,
6660 &values,
6661 &self.encryption,
6662 fallback.as_ref(),
6663 ) {
6664 Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => {
6665 with_encryption.then_some((error, ENCRYPT_FAILED_CODE))
6666 }
6667 Err(error) if error.starts_with(INVALID_REQUEST_CODE) => Some((
6672 LEGACY_VALUE_REFUSAL_MESSAGE.to_owned(),
6673 OUTBOX_INCOMPATIBLE_CODE,
6674 )),
6675 _ => None,
6676 };
6677 if let Some((error, code)) = failure {
6678 failures.push((commit.clone(), error, code));
6679 break;
6680 }
6681 }
6682 }
6683 if failures.is_empty() {
6684 return Ok(false);
6685 }
6686 self.reject_outbox_commits(
6687 failures
6688 .into_iter()
6689 .map(|(commit, message, code)| {
6690 let details = (code == OUTBOX_INCOMPATIBLE_CODE).then(|| RejectionDetails {
6691 field_paths: None,
6692 reason: Some(INVALID_STORED_VALUES_REASON.to_owned()),
6693 required_action: None,
6694 references: None,
6695 });
6696 (commit, message, code, details)
6697 })
6698 .collect(),
6699 batch,
6700 )?;
6701 Ok(true)
6702 }
6703
6704 #[allow(clippy::type_complexity)]
6708 fn reject_outbox_commits(
6709 &mut self,
6710 failures: Vec<(
6711 Arc<OutboxCommit>,
6712 String,
6713 &'static str,
6714 Option<RejectionDetails>,
6715 )>,
6716 batch: Option<&mut ChangeAccumulator>,
6717 ) -> Result<(), String> {
6718 let rollback = self.capture();
6724 let owns_observation = batch.is_none();
6725 let owns_transaction = self.conn.is_autocommit();
6726 let mut domains = ChangeAccumulator::default();
6727 if owns_observation {
6728 self.begin_observation("syncular_value_recovery")?;
6729 }
6730 let dropped = (|| -> Result<(), String> {
6731 for (commit, message, code, details) in failures {
6732 if self.retain_failed_commits && code != OUTBOX_INCOMPATIBLE_CODE {
6733 self.retain_failed_commit(&commit.client_commit_id, &commit.ops)?;
6734 }
6735 let representable = commit.ops.iter().all(Self::outbox_op_is_journalable);
6736 let rejection = RejectionRecord {
6737 client_commit_id: commit.client_commit_id.clone(),
6738 op_index: 0,
6739 code: code.to_owned(),
6740 message,
6741 retryable: false,
6742 details,
6743 operation: representable
6744 .then(|| commit.ops.first())
6745 .flatten()
6746 .map(CommitOperation::from),
6747 };
6748 self.persist_commit_outcome(
6749 &commit.client_commit_id,
6750 CommitOutcomeStatus::Rejected,
6751 &[CommitOperationOutcome::Error {
6752 rejection: rejection.clone(),
6753 }],
6754 representable.then_some(commit.ops.as_slice()),
6755 )?;
6756 self.delete_outbox_persisted(&commit.client_commit_id)?;
6757 self.outbox
6758 .retain(|candidate| candidate.client_commit_id != commit.client_commit_id);
6759 self.rejections.push(rejection);
6760 for operation in &commit.ops {
6761 domains.table(operation.table.as_str());
6762 }
6763 }
6764 domains.status = true;
6765 domains.rejections = true;
6766 domains.outcomes = true;
6767 self.prune_commit_outcomes()?;
6768 self.overlay_dirty.set(true);
6770 self.rebuild_overlay()?;
6771 Ok(())
6772 })();
6773 let result = match batch {
6774 Some(batch) => {
6775 if dropped.is_ok() {
6776 for table in domains.tables.keys() {
6777 batch.table(table.as_str());
6778 }
6779 batch.status |= domains.status;
6780 batch.rejections |= domains.rejections;
6781 batch.outcomes |= domains.outcomes;
6782 }
6783 dropped
6784 }
6785 None => {
6786 dropped.and_then(|()| self.finish_observation("syncular_value_recovery", domains))
6787 }
6788 };
6789 if let Err(error) = result {
6790 if owns_observation {
6791 if owns_transaction {
6792 if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
6793 let mut failure = self.storage_failure.borrow_mut();
6794 let failure =
6795 failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
6796 failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
6797 }
6798 } else {
6799 self.rollback_observation("syncular_value_recovery");
6800 }
6801 }
6802 self.restore(rollback);
6803 return Err(error);
6804 }
6805 Ok(())
6806 }
6807
6808 pub fn pending_commit_ids(&self) -> Vec<String> {
6809 self.outbox
6810 .iter()
6811 .map(|c| c.client_commit_id.clone())
6812 .collect()
6813 }
6814
6815 pub fn pending_commits(&self) -> Result<Vec<PendingCommit>, String> {
6818 let mut stmt = self
6819 .conn
6820 .prepare_cached(
6821 "SELECT seq, commit_id, created_at_ms, ops_json FROM _syncular_outbox ORDER BY seq",
6822 )
6823 .map_err(|error| error.to_string())?;
6824 let rows = stmt
6825 .query_map([], |row| {
6826 Ok((
6827 row.get(0)?,
6828 row.get(1)?,
6829 row.get(2)?,
6830 row.get::<_, String>(3)?,
6831 ))
6832 })
6833 .map_err(|error| error.to_string())?;
6834 rows.map(|row| {
6835 let (seq, client_commit_id, created_at_ms, raw) =
6836 row.map_err(|error| error.to_string())?;
6837 let operations = serde_json::from_str(&raw).map_err(|error| {
6838 format!("invalid persisted outbox {client_commit_id:?}: {error}")
6839 })?;
6840 Ok(PendingCommit {
6841 seq,
6842 client_commit_id,
6843 created_at_ms,
6844 operations,
6845 })
6846 })
6847 .collect()
6848 }
6849
6850 pub fn pending_payloads(&self) -> Result<Vec<Vec<u8>>, String> {
6854 let mut payloads = Vec::new();
6855 for commit in self.outbox.iter() {
6856 for op in &commit.ops {
6857 let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6858 continue;
6859 };
6860 let Some(values) = op.presented_values(table) else {
6861 continue;
6862 };
6863 let fallback = self.stored_key_fallback(table, &op.row_id)?;
6864 if let Ok(payload) = encode_sparse_row_json(
6865 table,
6866 &op.row_id,
6867 &values,
6868 &self.encryption,
6869 fallback.as_ref(),
6870 ) {
6871 payloads.push(payload);
6872 }
6873 }
6874 }
6875 Ok(payloads)
6876 }
6877
6878 pub fn conflicts(&self) -> &[ConflictRecord] {
6879 &self.conflicts
6880 }
6881
6882 pub fn rejections(&self) -> &[RejectionRecord] {
6883 &self.rejections
6884 }
6885
6886 pub fn resolve_commit_outcome(
6887 &mut self,
6888 input: ResolveCommitOutcomeInput,
6889 ) -> Result<CommitOutcome, String> {
6890 let current = self
6891 .commit_outcome(&input.client_commit_id)?
6892 .ok_or_else(|| {
6893 format!(
6894 "sync.outcome_not_found: no durable outcome exists for {:?}",
6895 input.client_commit_id
6896 )
6897 })?;
6898 if current.resolution != CommitOutcomeResolution::Active {
6899 return Ok(current);
6900 }
6901 if current.replacement_client_commit_id.is_some() {
6902 return Err(REPLACEMENT_PENDING.to_owned());
6903 }
6904 if input.resolution == CommitOutcomeResolution::Active {
6905 return Err("sync.invalid_request: resolution must leave active state".to_owned());
6906 }
6907 match input.resolution {
6908 CommitOutcomeResolution::Superseded => {
6909 let replacement = input
6910 .replacement_client_commit_id
6911 .as_deref()
6912 .filter(|value| !value.is_empty() && *value != input.client_commit_id)
6913 .ok_or_else(|| {
6914 "sync.invalid_request: superseded outcomes require a distinct replacementClientCommitId"
6915 .to_owned()
6916 })?;
6917 let _ = replacement;
6918 }
6919 _ if input.replacement_client_commit_id.is_some() => {
6920 return Err(
6921 "sync.invalid_request: replacementClientCommitId is valid only for superseded outcomes"
6922 .to_owned(),
6923 );
6924 }
6925 _ => {}
6926 }
6927 let allowed = match current.status {
6928 CommitOutcomeStatus::Conflict => matches!(
6929 input.resolution,
6930 CommitOutcomeResolution::ResolvedKeepServer | CommitOutcomeResolution::Superseded
6931 ),
6932 CommitOutcomeStatus::Rejected => {
6933 matches!(
6934 input.resolution,
6935 CommitOutcomeResolution::Superseded
6936 | CommitOutcomeResolution::ResolvedKeepServer
6937 )
6938 }
6939 CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => {
6940 input.resolution == CommitOutcomeResolution::Dismissed
6941 }
6942 };
6943 if !allowed {
6944 return Err(format!(
6945 "sync.invalid_request: resolution {:?} is invalid for {:?} outcome",
6946 input.resolution, current.status
6947 ));
6948 }
6949
6950 let rollback = self.capture();
6951 self.begin_observation("syncular_outcome_resolution")?;
6952 let mut batch = ChangeAccumulator::default();
6953 let result = self
6954 .release_outcome(
6955 ¤t,
6956 input.resolution,
6957 input.replacement_client_commit_id.as_deref(),
6958 &mut batch,
6959 )
6960 .and_then(|()| self.rebuild_overlay_if_dirty())
6961 .and_then(|()| self.finish_observation("syncular_outcome_resolution", batch));
6962 if let Err(error) = result {
6963 self.rollback_observation("syncular_outcome_resolution");
6964 self.restore(rollback);
6965 return Err(error);
6966 }
6967 self.commit_outcome(¤t.client_commit_id)?
6968 .ok_or_else(|| "sync.outcome_not_found: outcome disappeared".to_owned())
6969 }
6970
6971 pub fn replace_commit_outcome(
6976 &mut self,
6977 client_commit_id: &str,
6978 sequence: i64,
6979 replacement: Option<Vec<Mutation>>,
6980 ) -> Result<String, ClientError> {
6981 let prior = self.storage_failure.borrow_mut().take();
6982 let outcome = (|| -> Result<String, ClientError> {
6983 let Some(current) = self.commit_outcome(client_commit_id)? else {
6984 return Err(ClientError {
6985 code: "sync.outcome_not_found".to_owned(),
6986 message: "no durable outcome exists for the commit".to_owned(),
6987 details: Some(json!({ "clientCommitId": client_commit_id })),
6988 retryable: false,
6989 });
6990 };
6991 if current.resolution == CommitOutcomeResolution::Active
6992 && current.replacement_client_commit_id.is_some()
6993 {
6994 return Err(ClientError {
6995 code: "client.replacement_pending".to_owned(),
6996 message: "the outcome has a pending replacement".to_owned(),
6997 details: Some(json!({ "clientCommitId": client_commit_id })),
6998 retryable: false,
6999 });
7000 }
7001 let (Some(envelope), Some(rows)) = (current.operations, current.retained_rows) else {
7002 return Err(invalid_authoring(
7003 "the outcome cannot be replaced",
7004 json!({ "clientCommitId": client_commit_id }),
7005 ));
7006 };
7007 if current.sequence != sequence
7008 || current.resolution != CommitOutcomeResolution::Active
7009 || !matches!(
7010 current.status,
7011 CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
7012 )
7013 || rows.is_empty()
7014 || envelope.len() != rows.len()
7015 {
7016 return Err(invalid_authoring(
7017 "the outcome cannot be replaced",
7018 json!({ "clientCommitId": client_commit_id }),
7019 ));
7020 }
7021 let ops = match replacement {
7022 None => envelope
7023 .into_iter()
7024 .zip(&rows)
7025 .map(|(operation, row)| OutboxOp {
7026 base_version: Some(row.server_version.unwrap_or(0)),
7027 ..OutboxOp::from(operation)
7028 })
7029 .collect(),
7030 Some(mutations) => {
7031 let mut ops = self.prepare_mutations(mutations)?;
7032 for op in &mut ops {
7033 let Some(row) = rows
7034 .iter()
7035 .find(|row| row.table == op.table && row.row_id == op.row_id)
7036 else {
7037 continue;
7038 };
7039 if op.base_version.is_some() {
7040 return Err(invalid_authoring(
7041 "an operation on a retained row takes its base version",
7042 json!({ "table": op.table }),
7043 ));
7044 }
7045 op.base_version = Some(row.server_version.unwrap_or(0));
7046 }
7047 ops
7048 }
7049 };
7050 Ok(self.record_outbox_commit(ops, None, Some(client_commit_id))?)
7051 })();
7052 self.finish_authoring(prior, outcome)
7053 }
7054
7055 #[doc(hidden)]
7058 pub fn prepare_replacements(&self) -> Result<Vec<CurrentBasePreparation>, String> {
7059 let mut stmt = self
7060 .conn
7061 .prepare_cached(
7062 "SELECT client_commit_id, seq, replacement_client_commit_id
7063 FROM _syncular_commit_outcomes
7064 WHERE resolution = 'active' AND replacement_client_commit_id IS NOT NULL
7065 ORDER BY seq ASC",
7066 )
7067 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7068 let decisions = stmt
7069 .query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))
7070 .and_then(|rows| rows.collect::<Result<Vec<(String, i64, String)>, _>>())
7071 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7072 if decisions.is_empty() {
7073 return Ok(Vec::new());
7074 }
7075 let units = self.stored(load_units(&self.conn))?;
7076 Ok(decisions
7077 .into_iter()
7078 .map(
7079 |(client_commit_id, sequence, replacement)| CurrentBasePreparation {
7080 client_commit_id,
7081 sequence,
7082 replacement: Some(replacement),
7083 units: units.clone(),
7084 transport_epoch: self.transport_epoch,
7085 registration_epoch: self.registration_epoch,
7086 security_epoch: self.security_epoch,
7087 },
7088 )
7089 .collect())
7090 }
7091
7092 #[doc(hidden)]
7096 pub fn settle_replacements(
7097 &mut self,
7098 decisions: &[CurrentBasePreparation],
7099 drive: &SyncOutcome,
7100 ) -> Result<bool, String> {
7101 if !self.transport_enabled {
7102 return Ok(false);
7103 }
7104 let mut written = false;
7105 for decision in decisions {
7106 if decision.registration_epoch != self.registration_epoch {
7109 continue;
7110 }
7111 let Some(replacement) = decision.replacement.as_deref() else {
7112 continue;
7113 };
7114 let Some(current) =
7115 self.commit_outcome(&decision.client_commit_id)?
7116 .filter(|current| {
7117 current.resolution == CommitOutcomeResolution::Active
7118 && current.replacement_client_commit_id.as_deref() == Some(replacement)
7119 })
7120 else {
7121 continue;
7122 };
7123 let held = self
7124 .outbox
7125 .iter()
7126 .find(|commit| commit.client_commit_id == replacement)
7127 .cloned();
7128 let refused = match &held {
7129 None => None,
7132 Some(commit) => match self.finish_current_base(decision.clone(), drive.clone()) {
7133 CurrentBaseProof {
7134 rows: Some(rows), ..
7135 } => {
7136 let proven = commit.ops.iter().all(|op| {
7137 rows.iter()
7138 .find(|row| row.table == op.table && row.row_id == op.row_id)
7139 .is_none_or(|row| {
7140 op.base_version == Some(row.server_version.unwrap_or(0))
7141 })
7142 });
7143 written |= proven;
7144 (!proven).then(|| "base_moved".to_owned())
7145 }
7146 CurrentBaseProof {
7147 reason:
7148 Some(
7149 reason @ (CurrentBaseProofReason::SchemaFloor
7150 | CurrentBaseProofReason::MissingCoverage
7151 | CurrentBaseProofReason::Revoked
7152 | CurrentBaseProofReason::OutcomeUnavailable),
7153 ),
7154 ..
7155 } => Some(
7156 serde_json::to_value(reason)
7157 .ok()
7158 .and_then(|reason| reason.as_str().map(str::to_owned))
7159 .ok_or("sync.local_corrupt")?,
7160 ),
7161 _ => continue,
7162 },
7163 };
7164 let rollback = self.capture();
7168 self.begin_observation("syncular_replacement")?;
7169 let mut batch = ChangeAccumulator::default();
7170 let result = self
7171 .release_outcome(
7172 ¤t,
7173 CommitOutcomeResolution::Superseded,
7174 Some(replacement),
7175 &mut batch,
7176 )
7177 .and_then(|()| self.rebuild_overlay_if_dirty())
7178 .and_then(|()| match (refused, held) {
7179 (Some(reason), Some(commit)) => self.reject_outbox_commits(
7180 vec![(
7181 commit,
7182 "the replacement could not be written on a proven base".to_owned(),
7183 REPLACEMENT_REFUSED_CODE,
7184 Some(RejectionDetails {
7185 field_paths: None,
7186 reason: Some(reason),
7187 required_action: None,
7188 references: None,
7189 }),
7190 )],
7191 Some(&mut batch),
7192 ),
7193 _ => Ok(()),
7194 })
7195 .and_then(|()| self.finish_observation("syncular_replacement", batch));
7196 if let Err(error) = result {
7197 self.rollback_observation("syncular_replacement");
7198 self.restore(rollback);
7199 return Err(error);
7200 }
7201 }
7202 if written {
7203 self.set_sync_needed(true, true);
7204 }
7205 Ok(written)
7206 }
7207
7208 fn release_outcome(
7213 &mut self,
7214 current: &CommitOutcome,
7215 resolution: CommitOutcomeResolution,
7216 replacement: Option<&str>,
7217 batch: &mut ChangeAccumulator,
7218 ) -> Result<(), String> {
7219 self.conn
7220 .execute(
7221 "UPDATE _syncular_commit_outcomes
7222 SET resolution = ?1, resolved_at_ms = ?2,
7223 replacement_client_commit_id = ?3
7224 WHERE client_commit_id = ?4 AND resolution = 'active'",
7225 rusqlite::params![
7226 Self::outcome_resolution_name(resolution),
7227 self.clock_now_ms(),
7228 replacement,
7229 current.client_commit_id
7230 ],
7231 )
7232 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7233 self.conn
7234 .execute(
7235 "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
7236 rusqlite::params![current.client_commit_id],
7237 )
7238 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7239 for (commit, _) in self.failed_commits.iter() {
7240 if commit.client_commit_id == current.client_commit_id {
7241 for operation in &commit.ops {
7242 self.overlay_dirty.table(&operation.table);
7243 }
7244 }
7245 }
7246 self.failed_commits
7247 .retain(|(commit, _)| commit.client_commit_id != current.client_commit_id);
7248 self.prune_commit_outcomes()?;
7249 self.conflicts
7250 .retain(|record| record.client_commit_id != current.client_commit_id);
7251 self.rejections
7252 .retain(|record| record.client_commit_id != current.client_commit_id);
7253 batch.conflicts |= current.status == CommitOutcomeStatus::Conflict;
7254 batch.rejections |= current.status == CommitOutcomeStatus::Rejected;
7255 batch.outcomes = true;
7256 for operation in current.operations.iter().flatten() {
7257 batch.table(&operation.table);
7258 }
7259 Ok(())
7260 }
7261
7262 pub fn schema_floor(&self) -> Option<&SchemaFloor> {
7263 self.schema_floor.as_ref()
7264 }
7265
7266 pub fn lease_state(&self) -> Option<&LeaseState> {
7268 self.lease_state.as_ref()
7269 }
7270
7271 fn record_lease_error(&mut self, code: &str) -> Result<(), String> {
7274 if code != "sync.auth_lease_required" && code != "sync.auth_lease_revoked" {
7275 return Ok(());
7276 }
7277 let mut next = self.lease_state.clone().unwrap_or_default();
7278 next.error_code = Some(code.to_owned());
7279 self.set_lease_state(Some(next))
7280 }
7281
7282 fn set_lease_state(&mut self, next: Option<LeaseState>) -> Result<(), String> {
7283 if self.lease_state == next {
7284 return Ok(());
7285 }
7286 self.begin_observation("syncular_lease")?;
7287 let rollback = self.capture();
7288 self.lease_state = next;
7289 let persisted = match &self.lease_state {
7290 Some(lease) => serde_json::to_string(lease)
7291 .map_err(|error| error.to_string())
7292 .and_then(|json| self.set_meta(LEASE_STATE_KEY, &json)),
7293 None => self.delete_meta(LEASE_STATE_KEY),
7294 };
7295 let batch = ChangeAccumulator {
7296 status: true,
7297 ..ChangeAccumulator::default()
7298 };
7299 if let Err(error) =
7300 persisted.and_then(|()| self.finish_observation("syncular_lease", batch))
7301 {
7302 self.rollback_observation("syncular_lease");
7303 self.restore(rollback);
7304 return Err(error);
7305 }
7306 Ok(())
7307 }
7308
7309 fn set_schema_floor(&mut self, next: Option<SchemaFloor>) -> Result<(), String> {
7310 if self.schema_floor == next {
7311 return Ok(());
7312 }
7313 self.begin_observation("syncular_schema_floor")?;
7314 let rollback = self.capture();
7315 self.stopped = next.is_some();
7316 self.schema_floor = next;
7317 let persisted = match &self.schema_floor {
7318 Some(floor) => serde_json::to_string(floor)
7319 .map_err(|error| error.to_string())
7320 .and_then(|json| self.set_meta(SCHEMA_FLOOR_KEY, &json)),
7321 None => self.delete_meta(SCHEMA_FLOOR_KEY),
7322 };
7323 let batch = ChangeAccumulator {
7324 status: true,
7325 ..ChangeAccumulator::default()
7326 };
7327 if let Err(error) =
7328 persisted.and_then(|()| self.finish_observation("syncular_schema_floor", batch))
7329 {
7330 self.rollback_observation("syncular_schema_floor");
7331 self.restore(rollback);
7332 return Err(error);
7333 }
7334 Ok(())
7335 }
7336
7337 fn set_upgrading(&mut self, value: bool) {
7338 if self.upgrading == value {
7339 return;
7340 }
7341 if self.begin_observation("syncular_upgrading").is_err() {
7342 return;
7343 }
7344 self.upgrading = value;
7345 let batch = ChangeAccumulator {
7346 status: true,
7347 ..ChangeAccumulator::default()
7348 };
7349 if self
7350 .finish_observation("syncular_upgrading", batch)
7351 .is_err()
7352 {
7353 self.rollback_observation("syncular_upgrading");
7354 }
7355 }
7356
7357 pub fn sync_needed(&self) -> bool {
7358 self.sync_needed
7359 }
7360
7361 pub fn read_rows(&self, table: &str) -> Result<Vec<RowState>, String> {
7362 let schema_table = self
7363 .schema
7364 .table(table)
7365 .ok_or_else(|| format!("unknown table {table:?}"))?;
7366 let sql = format!(
7367 "SELECT * FROM {} ORDER BY {} ASC",
7368 visible_table(table),
7369 quote_ident(&schema_table.primary_key)
7370 );
7371 let mut stmt = self
7372 .conn
7373 .prepare(&sql)
7374 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7375 let mut rows = stmt
7376 .query([])
7377 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7378 let mut out = Vec::new();
7379 while let Some(row) = rows
7380 .next()
7381 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
7382 {
7383 let mut values = Map::new();
7384 for (i, column) in schema_table.columns.iter().enumerate() {
7385 let value = row
7386 .get_ref(i)
7387 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7388 values.insert(column.name.clone(), sql_ref_to_json(column, value));
7389 }
7390 let version: i64 = row
7391 .get(schema_table.columns.len())
7392 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7393 let row_id = match values.get(&schema_table.primary_key) {
7394 Some(Value::String(s)) => s.clone(),
7395 Some(Value::Number(n)) => n.to_string(),
7396 Some(Value::Bool(b)) => b.to_string(),
7397 other => format!("{}", other.cloned().unwrap_or(Value::Null)),
7398 };
7399 let sealed_key = if schema_table.has_encrypted_columns() {
7400 row.get(schema_table.columns.len() + 1)
7401 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
7402 } else {
7403 None
7404 };
7405 out.push(RowState {
7406 row_id,
7407 version,
7408 values,
7409 sealed_key,
7410 });
7411 }
7412 Ok(out)
7413 }
7414
7415 #[cfg(feature = "crdt-yjs")]
7431 fn crdt_column_bytes(
7432 &self,
7433 table: &str,
7434 row_id: &str,
7435 column: &str,
7436 ) -> Result<Option<Vec<u8>>, String> {
7437 let schema_table = self
7438 .schema
7439 .table(table)
7440 .ok_or_else(|| format!("unknown table {table:?}"))?;
7441 let col = schema_table
7442 .columns
7443 .iter()
7444 .find(|c| c.name == column)
7445 .ok_or_else(|| format!("table {table:?} has no column {column:?}"))?;
7446 if col.ty != ColumnType::Crdt {
7447 return Err(format!("column {column:?} is not a crdt column (§5.10.1)"));
7448 }
7449 let sql = format!(
7450 "SELECT {} FROM {} WHERE {}",
7451 quote_ident(column),
7452 visible_table(table),
7453 row_id_predicate(schema_table)
7454 );
7455 let bytes: Option<Vec<u8>> = self
7456 .conn
7457 .prepare_cached(&sql)
7458 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
7459 .query_row(rusqlite::params![row_id], |row| {
7460 row.get::<_, Option<Vec<u8>>>(0)
7461 })
7462 .map_err(|e| match e {
7463 rusqlite::Error::QueryReturnedNoRows => "no such row".to_owned(),
7464 other => Self::sqlite_failure(&self.storage_failure, other),
7465 })?;
7466 Ok(bytes)
7467 }
7468
7469 #[cfg(feature = "crdt-yjs")]
7473 pub fn crdt_text(
7474 &self,
7475 table: &str,
7476 row_id: &str,
7477 column: &str,
7478 name: &str,
7479 ) -> Result<String, String> {
7480 let bytes = self
7481 .crdt_column_bytes(table, row_id, column)?
7482 .unwrap_or_default();
7483 crate::crdt::text(&bytes, name)
7484 }
7485
7486 #[cfg(feature = "crdt-yjs")]
7490 pub fn crdt_insert_text(
7491 &mut self,
7492 table: &str,
7493 row_id: &str,
7494 column: &str,
7495 name: &str,
7496 index: u32,
7497 value: &str,
7498 ) -> Result<String, ClientError> {
7499 let prior = self.storage_failure.borrow_mut().take();
7500 let outcome = (|| -> Result<String, ClientError> {
7501 let current = self
7502 .crdt_column_bytes(table, row_id, column)?
7503 .unwrap_or_default();
7504 let update = crate::crdt::insert_text(¤t, name, index, value)?;
7505 self.perform_crdt_push_update(table, row_id, column, &update)
7506 })();
7507 self.finish_authoring(prior, outcome)
7508 }
7509
7510 #[cfg(feature = "crdt-yjs")]
7514 pub fn crdt_delete_text(
7515 &mut self,
7516 table: &str,
7517 row_id: &str,
7518 column: &str,
7519 name: &str,
7520 index: u32,
7521 len: u32,
7522 ) -> Result<String, ClientError> {
7523 let prior = self.storage_failure.borrow_mut().take();
7524 let outcome = (|| -> Result<String, ClientError> {
7525 let current = self
7526 .crdt_column_bytes(table, row_id, column)?
7527 .unwrap_or_default();
7528 let update = crate::crdt::delete_text(¤t, name, index, len)?;
7529 self.perform_crdt_push_update(table, row_id, column, &update)
7530 })();
7531 self.finish_authoring(prior, outcome)
7532 }
7533
7534 #[cfg(feature = "crdt-yjs")]
7539 pub fn crdt_apply_update(
7540 &mut self,
7541 table: &str,
7542 row_id: &str,
7543 column: &str,
7544 update: &[u8],
7545 ) -> Result<String, ClientError> {
7546 let prior = self.storage_failure.borrow_mut().take();
7547 let outcome = (|| -> Result<String, ClientError> {
7548 let current = self
7549 .crdt_column_bytes(table, row_id, column)?
7550 .unwrap_or_default();
7551 let next = crate::crdt::apply_update(¤t, update)?;
7552 self.perform_crdt_push_update(table, row_id, column, &next)
7553 })();
7554 self.finish_authoring(prior, outcome)
7555 }
7556
7557 #[cfg(feature = "crdt-yjs")]
7564 fn perform_crdt_push_update(
7565 &mut self,
7566 table: &str,
7567 row_id: &str,
7568 column: &str,
7569 crdt_bytes: &[u8],
7570 ) -> Result<String, ClientError> {
7571 let mut bytes_obj = Map::new();
7572 bytes_obj.insert("$bytes".to_owned(), Value::from(bytes_to_hex(crdt_bytes)));
7573 let mut partial = Map::new();
7574 partial.insert(column.to_owned(), Value::Object(bytes_obj));
7575 self.perform_patch(table, row_id, partial, None)
7576 }
7577
7578 pub fn query(&self, sql: &str, params: &[QueryValue]) -> Result<Vec<QueryRow>, String> {
7593 query_connection(&self.conn, sql, params).map_err(|failure| failure.to_string())
7594 }
7595
7596 #[cfg(feature = "bench-internals")]
7598 #[doc(hidden)]
7599 pub fn benchmark_connection(&mut self) -> &mut Connection {
7600 &mut self.conn
7601 }
7602
7603 #[cfg(feature = "bench-internals")]
7605 #[doc(hidden)]
7606 pub fn benchmark_phases(
7607 &self,
7608 enabled: Option<bool>,
7609 reset: bool,
7610 ) -> Result<Option<Value>, String> {
7611 self.benchmark_phases.configure(enabled, reset)?;
7612 Ok(self.benchmark_phases.snapshot())
7613 }
7614
7615 pub fn authority_snapshot(&self) -> Result<Value, String> {
7617 validate_authority_reads(&self.schema, &self.limits.authority_reads)?;
7618 if self.limits.authority_reads.is_empty() {
7619 return Err("client.authority_read_forbidden: no authority reads were declared at client creation".into());
7620 }
7621 self.conn
7622 .execute_batch("SAVEPOINT authority_snapshot")
7623 .map_err(|e| e.to_string())?;
7624 let result = (|| {
7625 let revision = self
7626 .get_meta(LOCAL_REVISION_KEY)?
7627 .ok_or("sync.local_corrupt: authority revision is missing")?;
7628 let parsed_revision = revision
7629 .parse::<u64>()
7630 .map_err(|_| "sync.local_corrupt: authority revision is invalid")?;
7631 if parsed_revision.to_string() != revision {
7632 return Err("sync.local_corrupt: authority revision is invalid".into());
7633 }
7634 let mut tables = Vec::new();
7635 for read in &self.limits.authority_reads {
7636 let table = self
7637 .schema
7638 .table(&read.table)
7639 .ok_or("client.authority_read_forbidden: authority table is not declared")?;
7640 let scalar = |column: &str, value: &Value| -> Result<String, String> {
7641 let ty = table
7642 .columns
7643 .iter()
7644 .find(|c| c.name == column)
7645 .expect("validated authority column")
7646 .ty;
7647 if ty == ColumnType::Boolean {
7648 if let Some(value) = value.as_bool() {
7649 return Ok(value.to_string());
7650 }
7651 return match value.as_i64() {
7652 Some(0) => Ok("false".into()),
7653 Some(1) => Ok("true".into()),
7654 _ => Err("sync.local_corrupt: authority boolean is invalid".into()),
7655 };
7656 }
7657 match value {
7658 Value::String(s) => Ok(s.clone()),
7659 Value::Number(n) => Ok(n.to_string()),
7660 Value::Object(o) if ty == ColumnType::Integer && o.len() == 1 => o
7661 .get("$bigint")
7662 .and_then(Value::as_str)
7663 .map(str::to_owned)
7664 .ok_or("sync.local_corrupt: authority integer is invalid".into()),
7665 _ => {
7666 Err("sync.local_corrupt: authority scalar is missing or invalid".into())
7667 }
7668 }
7669 };
7670 let matches = |row: &QueryRow| -> Result<bool, String> {
7671 for (variable, values) in &read.scopes {
7672 let column = table
7673 .scope_column(variable)
7674 .expect("validated authority scope");
7675 let value = row
7676 .get(column)
7677 .ok_or("sync.local_corrupt: authority scope column is missing")?;
7678 if value.is_null() || !values.contains(&scalar(column, value)?) {
7679 return Ok(false);
7680 }
7681 }
7682 Ok(true)
7683 };
7684 let selected = read
7685 .columns
7686 .iter()
7687 .map(|c| quote_ident(c))
7688 .collect::<Vec<_>>()
7689 .join(",");
7690 let mut intent = BTreeSet::new();
7691 let mut relevant = BTreeSet::new();
7692 for row in query_connection(&self.conn,
7693 "SELECT id,values_json FROM (SELECT json_extract(value,'$.table') AS tbl,json_extract(value,'$.rowId') AS id,json_extract(value,'$.values') AS values_json FROM _syncular_outbox,json_each(ops_json) UNION ALL SELECT json_extract(value,'$.table'),json_extract(value,'$.rowId'),json_extract(value,'$.values') FROM _syncular_failed_commits,json_each(operations_json) UNION ALL SELECT tbl,id,intent_json FROM _syncular_acked_rows) WHERE tbl=?",
7694 &[Value::String(read.table.clone())]).map_err(|e| e.to_string())? {
7695 let id = row.get("id").and_then(Value::as_str).ok_or("sync.local_corrupt: authority intent id is invalid")?.to_owned();
7696 intent.insert(id.clone());
7697 if let Some(raw) = row.get("values_json").and_then(Value::as_str) {
7698 let values: QueryRow = serde_json::from_str(raw).map_err(|_| "sync.local_corrupt: authority intent values are invalid")?;
7699 if read.scopes.keys().all(|v| values.contains_key(table.scope_column(v).expect("validated scope"))) && matches(&values)? {relevant.insert(id);}
7700 }
7701 }
7702 let mut rows = BTreeMap::new();
7703 for full in [base_table(&read.table), visible_table(&read.table)] {
7704 for mut values in query_connection(
7705 &self.conn,
7706 &format!(
7707 "SELECT {selected},_syncular_version AS authority_version FROM {full}"
7708 ),
7709 &[],
7710 )
7711 .map_err(|e| e.to_string())?
7712 {
7713 if !matches(&values)? {
7714 continue;
7715 }
7716 let id = scalar(
7717 &table.primary_key,
7718 values
7719 .get(&table.primary_key)
7720 .expect("selected primary key"),
7721 )?;
7722 relevant.insert(id.clone());
7723 if full == base_table(&read.table) {
7724 let version = values
7725 .remove("authority_version")
7726 .expect("selected version");
7727 let version = version
7728 .as_i64()
7729 .ok_or("sync.local_corrupt: authority server version is invalid")?;
7730 if version >= 0 {
7731 rows.insert(id.clone(), json!({"values": values, "version": version, "hasLocalIntent": intent.contains(&id)}));
7732 }
7733 }
7734 }
7735 }
7736 intent.retain(|id| relevant.contains(id));
7737 let rows = rows.into_values().collect::<Vec<_>>();
7738 let replica = self.stored(replica_cursor(&self.conn))?;
7740 let persisted = self
7741 .stored(load_units(&self.conn))?
7742 .into_iter()
7743 .filter(|unit| covers(table, &unit.scopes))
7744 .map(|unit| {
7745 let effective = unit.echo.as_deref().and_then(|echo| {
7746 pair_scopes(&unit.scopes, &read.table, Some(echo))
7747 });
7748 let requested = read
7749 .scopes
7750 .keys()
7751 .map(|v| (v.clone(), json!(unit.scopes.get(v).into_iter().collect::<Vec<_>>())))
7752 .collect::<Map<_, _>>();
7753 let complete = effective
7754 .as_ref()
7755 .is_some_and(|scopes| scopes.len() == read.scopes.len())
7756 && unit.status == UnitStatus::Active
7757 && !unit.bootstrapping();
7758 let exposed = effective.map(|scopes| {
7759 read.scopes
7760 .keys()
7761 .map(|v| {
7762 let held = scopes.iter().find(|(variable, _)| variable == v);
7763 (v.clone(), json!(held.map_or(&Vec::new(), |(_, values)| values)))
7764 })
7765 .collect::<Map<_, _>>()
7766 });
7767 json!({"requestedScopes": requested, "status": unit.status, "cursor": unit.cursor.unwrap_or(replica), "effectiveScopes": exposed, "complete": complete})
7768 })
7769 .collect::<Vec<_>>();
7770 fn covered(selectors: &[(&String, &Vec<String>)], candidates: &[&Value]) -> bool {
7771 match selectors.split_first() {
7772 None => !candidates.is_empty(),
7773 Some(((variable, values), rest)) => values.iter().all(|value| {
7774 covered(
7775 rest,
7776 &candidates
7777 .iter()
7778 .copied()
7779 .filter(|p| {
7780 p["effectiveScopes"][variable.as_str()]
7781 .as_array()
7782 .is_some_and(|held| {
7783 held.contains(&Value::String(value.clone()))
7784 || held.contains(&Value::String("*".into()))
7785 })
7786 })
7787 .collect::<Vec<_>>(),
7788 )
7789 }),
7790 }
7791 }
7792 let coverage = if covered(
7793 &read.scopes.iter().collect::<Vec<_>>(),
7794 &persisted
7795 .iter()
7796 .filter(|p| p["complete"] == true)
7797 .collect::<Vec<_>>(),
7798 ) {
7799 "complete"
7800 } else if persisted.iter().any(|p| {
7801 p["status"] == "active"
7802 && read.scopes.iter().all(|(v, values)| {
7803 values.iter().any(|value| {
7804 p["requestedScopes"][v].as_array().is_some_and(|held| {
7805 held.contains(&Value::String(value.clone()))
7806 })
7807 })
7808 })
7809 }) {
7810 "pending"
7811 } else {
7812 "missing"
7813 };
7814 tables.push(json!({"table": read.table, "rows": rows, "localIntentRowIds": intent, "scopes": read.scopes, "coverage": coverage, "persisted": persisted}));
7815 }
7816 Ok(
7817 json!({"revision": revision, "complete": tables.iter().all(|t| t["coverage"] == "complete"), "tables": tables}),
7818 )
7819 })();
7820 match result {
7821 Ok(snapshot) => {
7822 self.conn
7823 .execute_batch("RELEASE authority_snapshot")
7824 .map_err(|e| e.to_string())?;
7825 Ok(snapshot)
7826 }
7827 Err(error) => {
7828 self.conn
7829 .execute_batch("ROLLBACK TO authority_snapshot; RELEASE authority_snapshot")
7830 .map_err(|e| format!("{error}; rollback failed: {e}"))?;
7831 Err(error)
7832 }
7833 }
7834 }
7835
7836 pub fn query_snapshot(
7840 &mut self,
7841 sql: &str,
7842 params: &[QueryValue],
7843 coverage: &[WindowCoverage],
7844 owner: Option<QueryOwner<'_>>,
7845 ) -> Result<QuerySnapshot, String> {
7846 let result = snapshot_connection(&self.conn, sql, params, coverage);
7847 if let Some(owner) = owner {
7848 self.record_query_read(owner, result.as_ref().err());
7849 }
7850 result.map_err(|failure| failure.to_string())
7851 }
7852
7853 pub fn record_query_read(&mut self, owner: QueryOwner<'_>, failure: Option<&QueryReadFailure>) {
7857 let position = self
7858 .query_failures
7859 .iter()
7860 .position(|entry| entry.id == owner.id);
7861 let Some(failure) = failure else {
7862 if let Some(index) = position {
7863 self.query_failures.remove(index);
7864 }
7865 return;
7866 };
7867 let tables: Vec<String> = BTreeSet::from_iter(owner.tables.iter().copied())
7868 .into_iter()
7869 .map(str::to_owned)
7870 .collect();
7871 let code = failure.code.unwrap_or("client.query_failed").to_owned();
7872 if position.is_some_and(|index| {
7873 let entry = &self.query_failures[index];
7874 entry.tables == tables && entry.code == code && entry.sqlite_code == failure.sqlite_code
7875 }) {
7876 return;
7877 }
7878 if let Some(index) = position {
7879 self.query_failures.remove(index);
7880 }
7881 self.query_failures.push(DiagnosticQueryFailure {
7882 id: owner.id.to_owned(),
7883 tables,
7884 code,
7885 sqlite_code: failure.sqlite_code,
7886 at_ms: self.clock_now_ms(),
7887 });
7888 if self.query_failures.len() > MAX_DIAGNOSTIC_QUERY_FAILURES {
7889 self.query_failures.remove(0);
7890 }
7891 }
7892
7893 fn build_request(&self, url_capable: bool) -> Result<(Message, RequestMeta), Box<SyncOutcome>> {
7896 #[cfg(feature = "bench-internals")]
7897 let _phase = self.benchmark_phases.start(Phase::RequestPrepare);
7898 let log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7899 Box::new(SyncOutcome::Failed {
7900 error_code: "storage.failed".into(),
7901 message,
7902 details: None,
7903 recommended_action: None,
7904 })
7905 })?;
7906 let max_commits = self.limits.max_push_commits_per_request;
7907 let max_ops = self
7908 .limits
7909 .max_push_operations_per_request
7910 .unwrap_or(PUSH_OPS_PER_REQUEST);
7911 let byte_cap = self.limits.max_push_request_bytes;
7912 let accept = self.limits.accept.unwrap_or(if url_capable {
7915 DEFAULT_ACCEPT | ACCEPT_SIGNED_URLS
7916 } else {
7917 DEFAULT_ACCEPT
7918 });
7919 let storage_failed = |message: String| {
7920 Box::new(SyncOutcome::Failed {
7921 error_code: "storage.failed".into(),
7922 message,
7923 details: None,
7924 recommended_action: None,
7925 })
7926 };
7927 let header = Frame::ReqHeader {
7928 client_id: self.client_id.clone(),
7929 schema_version: self.schema.version,
7930 log_epoch: log_epoch.clone(),
7931 outbox_id: self.get_meta(OUTBOX_ID_KEY).map_err(storage_failed)?,
7932 };
7933 let mut lead = vec![header];
7937 lead.extend(
7938 self.round_failure
7939 .iter()
7940 .map(|code| Frame::RoundFailure { code: code.clone() }),
7941 );
7942 if log_epoch.is_none() {
7944 lead.push(Frame::AdoptEpoch);
7945 }
7946 let registered: Vec<UnitRecord> = self
7947 .stored(load_units(&self.conn))
7948 .map_err(storage_failed)?
7949 .into_iter()
7950 .filter(|unit| unit.status == UnitStatus::Active)
7951 .collect();
7952 let registration_digest = ssp2::registration::registration_digest(
7953 registered
7954 .iter()
7955 .map(|unit| scope_pairs(&unit.scopes))
7956 .collect::<Vec<_>>()
7957 .iter()
7958 .map(Vec::as_slice),
7959 );
7960 let echo_digest = self
7961 .get_meta(ECHO_DIGEST_KEY)
7962 .map_err(storage_failed)?
7963 .filter(|hex| !hex.is_empty())
7964 .map(|hex| {
7965 crate::values::hex_to_bytes(&hex)
7966 .ok()
7967 .and_then(|bytes| <[u8; 32]>::try_from(bytes).ok())
7968 .ok_or_else(|| {
7969 "sync.local_corrupt: persisted echo digest is invalid".to_owned()
7970 })
7971 })
7972 .transpose()
7973 .map_err(storage_failed)?;
7974 let pull = Frame::PullHeader {
7975 limit_commits: self.limits.limit_commits.unwrap_or(0),
7976 limit_snapshot_rows: self.limits.limit_snapshot_rows.unwrap_or(0),
7977 max_snapshot_pages: self.limits.max_snapshot_pages.unwrap_or(0),
7978 accept,
7979 cursor: self
7980 .stored(replica_cursor(&self.conn))
7981 .map_err(storage_failed)?,
7982 registration_digest,
7983 echo_digest,
7984 };
7985 let registration_digest = bytes_to_hex(®istration_digest);
7986 let travels = self
7989 .get_meta(REGISTERED_DIGEST_KEY)
7990 .map_err(storage_failed)?
7991 .as_deref()
7992 != Some(registration_digest.as_str());
7993 let mut sub_frames: Vec<Frame> = Vec::new();
7994 if travels {
7995 sub_frames.extend(registered.iter().map(|unit| Frame::Unit {
7996 scopes: scope_pairs(&unit.scopes),
7997 }));
7998 }
7999 for unit in ®istered {
8002 let Some(cursor) = unit.cursor else {
8003 continue;
8004 };
8005 sub_frames.push(Frame::Progress {
8006 id: unit.id.clone(),
8007 cursor,
8008 bootstrap_state: unit.bootstrap_state.clone().map(RawJson),
8009 });
8010 sub_frames.extend(
8011 unit.restriction
8012 .as_ref()
8013 .map(|restriction| Frame::Restrict {
8014 cursor: restriction.cursor,
8015 tables: restriction.tables.clone(),
8016 }),
8017 );
8018 }
8019 let fixed_bytes = match byte_cap {
8022 Some(_) => {
8023 let mut frames = lead.clone();
8024 frames.push(pull.clone());
8025 frames.extend(sub_frames.iter().cloned());
8026 encode_message(&Message {
8027 wire_version: WIRE_VERSION,
8028 msg_kind: MsgKind::Request,
8029 frames,
8030 })
8031 .len()
8032 }
8033 None => 0,
8034 };
8035 if let Some(cap) = byte_cap {
8036 if fixed_bytes > cap {
8037 return Err(Self::push_capacity_outcome("bytes", cap, fixed_bytes, None));
8038 }
8039 }
8040 let base_bytes = match byte_cap {
8041 Some(_) => {
8042 let mut frames = lead.clone();
8043 frames.push(pull.clone());
8044 encode_message(&Message {
8045 wire_version: WIRE_VERSION,
8046 msg_kind: MsgKind::Request,
8047 frames,
8048 })
8049 .len()
8050 }
8051 None => 0,
8052 };
8053 let total_outbox = if log_epoch.is_some() {
8054 self.outbox.len()
8055 } else {
8056 0
8057 };
8058 let mut push_frames: Vec<Frame> = Vec::new();
8059 let mut pushed_ids = Vec::new();
8060 let mut ops_in_request = 0usize;
8061 let mut bytes_in_request = 0usize;
8062 let mut deferred_commits = self.outbox.len() - total_outbox;
8065 let held: HashSet<String> = self
8068 .prepare_replacements()
8069 .map_err(storage_failed)?
8070 .into_iter()
8071 .filter_map(|decision| decision.replacement)
8072 .collect();
8073 #[cfg(feature = "bench-internals")]
8074 let outbox_phase = self.benchmark_phases.start(Phase::OutboxEncode);
8075 for (index, commit) in self.outbox.iter().take(total_outbox).enumerate() {
8076 if held.contains(&commit.client_commit_id) {
8077 break;
8078 }
8079 if max_commits.is_some_and(|cap| push_frames.len() >= cap) {
8083 deferred_commits = total_outbox - index;
8084 break;
8085 }
8086 if ops_in_request + commit.ops.len() > max_ops {
8087 if push_frames.is_empty() {
8088 return Err(Self::push_capacity_outcome(
8089 "operations",
8090 max_ops,
8091 commit.ops.len(),
8092 Some(commit.client_commit_id.as_str()),
8093 ));
8094 }
8095 deferred_commits = total_outbox - index;
8096 break;
8097 }
8098 if self.outbox[..index]
8101 .iter()
8102 .flat_map(|earlier| &earlier.ops)
8103 .any(|earlier| commit.ops.iter().any(|op| chains_on(earlier, op)))
8104 {
8105 deferred_commits = total_outbox - index;
8106 break;
8107 }
8108 let operations = commit
8109 .ops
8110 .iter()
8111 .map(|op| {
8112 let payload = match self
8113 .schema
8114 .table(&op.table)
8115 .and_then(|table| Some((table, op.presented_values(table)?)))
8116 {
8117 Some((table, values)) => {
8118 let fallback =
8128 self.stored_key_fallback(table, &op.row_id)
8129 .map_err(|message| {
8130 Box::new(SyncOutcome::Failed {
8131 error_code: "storage.failed".into(),
8132 message,
8133 details: None,
8134 recommended_action: None,
8135 })
8136 })?;
8137 encode_sparse_row_json(
8138 table,
8139 &op.row_id,
8140 &values,
8141 &self.encryption,
8142 fallback.as_ref(),
8143 )
8144 .ok()
8145 }
8146 None => None,
8147 };
8148 Ok(ssp2::model::Operation {
8149 table: op.table.clone(),
8150 row_id: op.row_id.clone(),
8151 op: if op.upsert { Op::Upsert } else { Op::Delete },
8152 base_version: op.base_version,
8153 payload,
8154 })
8155 })
8156 .collect::<Result<Vec<_>, Box<SyncOutcome>>>()?;
8157 let client_seq = self
8159 .conn
8160 .prepare_cached("SELECT seq FROM _syncular_outbox WHERE commit_id = ?1")
8161 .and_then(|mut statement| {
8162 statement.query_row([&commit.client_commit_id], |row| row.get(0))
8163 })
8164 .map_err(|error| {
8165 storage_failed(Self::sqlite_failure(&self.storage_failure, error))
8166 })?;
8167 let frame = Frame::PushCommit {
8168 client_commit_id: commit.client_commit_id.clone(),
8169 client_seq,
8170 operations,
8171 };
8172 let frame_bytes = match byte_cap {
8173 Some(_) => {
8174 let mut frames = lead.clone();
8175 frames.push(frame.clone());
8176 frames.push(pull.clone());
8177 encode_message(&Message {
8178 wire_version: WIRE_VERSION,
8179 msg_kind: MsgKind::Request,
8180 frames,
8181 })
8182 .len()
8183 - base_bytes
8184 }
8185 None => 0,
8186 };
8187 if let Some(cap) = byte_cap {
8191 if !push_frames.is_empty() && fixed_bytes + bytes_in_request + frame_bytes > cap {
8192 deferred_commits = total_outbox - index;
8193 break;
8194 }
8195 }
8196 push_frames.push(frame);
8197 pushed_ids.push(commit.client_commit_id.clone());
8198 ops_in_request += commit.ops.len();
8199 bytes_in_request += frame_bytes;
8200 }
8201 #[cfg(feature = "bench-internals")]
8202 drop(outbox_phase);
8203 if let Some(cap) = byte_cap {
8204 if fixed_bytes + bytes_in_request > cap {
8205 let blocked = if push_frames.is_empty() {
8208 None
8209 } else {
8210 self.outbox.first().map(|c| c.client_commit_id.as_str())
8211 };
8212 return Err(Self::push_capacity_outcome(
8213 "bytes",
8214 cap,
8215 fixed_bytes + bytes_in_request,
8216 blocked,
8217 ));
8218 }
8219 }
8220 let mut frames = lead;
8221 frames.extend(push_frames);
8222 frames.push(pull);
8223 frames.extend(sub_frames);
8224 let message = Message {
8225 wire_version: WIRE_VERSION,
8226 msg_kind: MsgKind::Request,
8227 frames,
8228 };
8229 Ok((
8230 message,
8231 RequestMeta {
8232 pushed_ids,
8233 registration_digest,
8234 accept,
8235 deferred_commits,
8236 applied: BTreeMap::new(),
8237 deferred: BTreeSet::new(),
8238 },
8239 ))
8240 }
8241
8242 fn push_capacity_outcome(
8244 kind: &str,
8245 limit: usize,
8246 size: usize,
8247 client_commit_id: Option<&str>,
8248 ) -> Box<SyncOutcome> {
8249 let mut details = Map::new();
8250 details.insert("kind".to_owned(), Value::from(kind));
8251 details.insert("limit".to_owned(), Value::from(limit as u64));
8252 details.insert("size".to_owned(), Value::from(size as u64));
8253 if let Some(id) = client_commit_id {
8254 details.insert("clientCommitId".to_owned(), Value::from(id));
8255 }
8256 Box::new(SyncOutcome::Failed {
8257 error_code: "client.push_request_too_large".into(),
8258 message: "the push request exceeds a configured capacity limit".into(),
8259 details: Some(Value::Object(details)),
8260 recommended_action: None,
8261 })
8262 }
8263
8264 pub fn progress(&self) -> ProgressObserver {
8268 self.progress.clone()
8269 }
8270
8271 pub fn sync(&mut self, transport: &mut dyn Transport) -> SyncOutcome {
8272 self.sync_bounded(transport, None)
8273 }
8274
8275 fn sync_bounded(
8277 &mut self,
8278 transport: &mut dyn Transport,
8279 idle_bound: Option<(u64, u32)>,
8280 ) -> SyncOutcome {
8281 let mut prepared = match self.prepare_sync_round(transport.supports_url_fetch()) {
8282 Ok(prepared) => prepared,
8283 Err(outcome) => return *outcome,
8284 };
8285 prepared.idle_bound = idle_bound;
8286 let mut next = prepared;
8291 loop {
8292 match self.apply_sync_round(next.exchange(transport)) {
8293 crate::AppliedSyncRound::Continue(prepared) => next = prepared,
8294 crate::AppliedSyncRound::Complete {
8295 outcome, controls, ..
8296 } => {
8297 if self.transport_enabled {
8298 for text in controls {
8299 let _ = transport.realtime_send(&text);
8300 }
8301 } else {
8302 self.disconnect_realtime(transport);
8303 }
8304 return outcome;
8305 }
8306 }
8307 }
8308 }
8309
8310 fn finish_sync_round(
8311 &mut self,
8312 started_at_ms: i64,
8313 attempt: u64,
8314 mut outcome: SyncOutcome,
8315 ) -> SyncOutcome {
8316 if let SyncOutcome::Failed {
8317 error_code,
8318 message,
8319 details,
8320 ..
8321 } = &mut outcome
8322 {
8323 if let Some((failure, code)) = self
8324 .storage_failure
8325 .borrow()
8326 .as_ref()
8327 .and_then(|failure| failure.code.map(|code| (failure, code)))
8328 {
8329 *error_code = code.to_owned();
8330 *message = match code {
8331 "client.storage_busy" => "local SQLite storage is busy",
8332 "client.storage_full" => "local SQLite storage is full",
8333 "client.storage_io" => "local SQLite storage I/O failed",
8334 "client.storage_corrupt" => "local SQLite storage is corrupt",
8335 _ => unreachable!("unrecognized classified storage failure"),
8336 }
8337 .to_owned();
8338 *details = failure.details();
8339 }
8340 }
8341 let details = match &outcome {
8342 SyncOutcome::Failed { details, .. } => details.as_ref(),
8343 _ => None,
8344 };
8345 let cause_kind = details
8346 .and_then(|details| details.get("causeKind"))
8347 .and_then(Value::as_str)
8348 .and_then(|cause| match cause {
8349 "network" => Some(crate::TransportCauseKind::Network),
8350 "connect" => Some(crate::TransportCauseKind::Connect),
8351 "tls" => Some(crate::TransportCauseKind::Tls),
8352 "io" => Some(crate::TransportCauseKind::Io),
8353 "request" => Some(crate::TransportCauseKind::Request),
8354 "protocol" => Some(crate::TransportCauseKind::Protocol),
8355 "timeout" => Some(crate::TransportCauseKind::Timeout),
8356 "round_deadline" => Some(crate::TransportCauseKind::RoundDeadline),
8357 "aborted" => Some(crate::TransportCauseKind::Aborted),
8358 "body" => Some(crate::TransportCauseKind::Body),
8359 "status" => Some(crate::TransportCauseKind::Status),
8360 "redirect" => Some(crate::TransportCauseKind::Redirect),
8361 "unknown" => Some(crate::TransportCauseKind::Unknown),
8362 _ => None,
8363 });
8364 let http_status = if matches!(
8365 cause_kind,
8366 Some(
8367 crate::TransportCauseKind::Status
8368 | crate::TransportCauseKind::Body
8369 | crate::TransportCauseKind::Redirect
8370 )
8371 ) {
8372 details
8373 .and_then(|details| details.get("httpStatus"))
8374 .and_then(Value::as_f64)
8375 .filter(|status| status.fract() == 0.0 && (100.0..=599.0).contains(status))
8376 .map(|status| status as u16)
8377 } else {
8378 None
8379 };
8380 let retry_delay_ms = self.round_retry_delay_ms;
8381 self.progress.update(|p| match &outcome {
8382 SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report)
8383 if report.failed.is_empty() =>
8384 {
8385 p.state = ProgressState::Complete
8386 }
8387 SyncOutcome::Ok(_) | SyncOutcome::BudgetExhausted(_) => {
8388 p.state = ProgressState::Failed;
8389 p.error_code = Some("sync.scope_revoked".into());
8390 }
8391 SyncOutcome::Failed { error_code, .. } => {
8392 p.state = ProgressState::Failed;
8393 p.error_code = Some(Self::diagnostic_code(error_code));
8394 p.cause_kind = cause_kind;
8395 p.http_status = http_status;
8396 p.retry_delay_ms = retry_delay_ms;
8397 }
8398 SyncOutcome::RealtimeUnavailable { .. } => {
8399 p.state = ProgressState::Failed;
8400 p.error_code = Some(REALTIME_UNAVAILABLE_CODE.to_owned());
8401 p.retry_delay_ms = retry_delay_ms;
8402 }
8403 });
8404 let completed_at_ms = self.clock_now_ms();
8405 self.last_round = Some(match &outcome {
8406 SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report) => DiagnosticLastRound {
8407 epoch: self.epoch.clone(),
8408 attempt,
8409 status: "succeeded".to_owned(),
8410 started_at_ms,
8411 completed_at_ms,
8412 duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
8413 counters: Some(DiagnosticRoundCounters {
8414 pushed: report.pushed,
8415 applied: report.applied.len(),
8416 rejected: report.rejected.len(),
8417 retryable: report.retryable.len(),
8418 conflicts: report.conflicts,
8419 commits_applied: report.commits_applied,
8420 segment_rows_applied: report.segment_rows_applied,
8421 bootstrapping: report.bootstrapping.len(),
8422 resets: report.resets.len(),
8423 revoked: report.revoked.len(),
8424 failed: report.failed.len(),
8425 deferred_commits: report.deferred_commits,
8426 }),
8427 error_code: None,
8428 cause_kind: None,
8429 http_status: None,
8430 },
8431 SyncOutcome::Failed { error_code, .. } => DiagnosticLastRound {
8432 epoch: self.epoch.clone(),
8433 attempt,
8434 status: "failed".to_owned(),
8435 started_at_ms,
8436 completed_at_ms,
8437 duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
8438 counters: None,
8439 error_code: Some(Self::diagnostic_code(error_code)),
8440 cause_kind,
8441 http_status,
8442 },
8443 SyncOutcome::RealtimeUnavailable { .. } => DiagnosticLastRound {
8444 epoch: self.epoch.clone(),
8445 attempt,
8446 status: "failed".to_owned(),
8447 started_at_ms,
8448 completed_at_ms,
8449 duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
8450 counters: None,
8451 error_code: Some(REALTIME_UNAVAILABLE_CODE.to_owned()),
8452 cause_kind: None,
8453 http_status: None,
8454 },
8455 });
8456 outcome
8457 }
8458
8459 pub fn prepare_sync_round(
8462 &mut self,
8463 url_capable: bool,
8464 ) -> Result<crate::PreparedSyncRound, Box<SyncOutcome>> {
8465 if !self.transport_enabled {
8466 return Err(Box::new(SyncOutcome::Failed {
8467 error_code: "sync.offline".into(),
8468 message: "transport gate is closed".into(),
8469 details: None,
8470 recommended_action: None,
8471 }));
8472 }
8473 if self.active_round.is_some() {
8474 return Err(Box::new(SyncOutcome::Failed {
8475 error_code: "client.round_in_progress".into(),
8476 message: "a sync round is already in flight".into(),
8477 details: None,
8478 recommended_action: None,
8479 }));
8480 }
8481 self.storage_failure.borrow_mut().take();
8482 let attempt = self.progress.start(&self.epoch);
8483 self.round_retry_delay_ms = None;
8484 let started_at_ms = self.clock_now_ms();
8485 let prepared = (|| {
8486 if self.stopped {
8487 return Err(Box::new(SyncOutcome::Ok(SyncReport {
8488 schema_floor: self.schema_floor.clone(),
8489 ..SyncReport::default()
8490 })));
8491 }
8492 if self.security_preflight {
8493 return Err(Box::new(SyncOutcome::Failed {
8494 error_code: SECURITY_PREFLIGHT_REQUIRED_CODE.into(),
8495 message: "security preflight must complete before syncing".into(),
8496 details: None,
8497 recommended_action: None,
8498 }));
8499 }
8500 self.set_sync_needed(false, false);
8501 self.drain_pending_evictions()
8502 .and_then(|_| self.drop_incompatible_outbox())
8503 .and_then(|_| self.drop_unencodable_outbox(true, None))
8504 .map_err(|message| {
8505 Box::new(SyncOutcome::Failed {
8506 error_code: "storage.failed".into(),
8507 message,
8508 details: None,
8509 recommended_action: None,
8510 })
8511 })?;
8512 self.reveal_sealed_rows().map_err(|error| {
8514 Box::new(SyncOutcome::Failed {
8515 error_code: error.code,
8516 message: error.message,
8517 details: error.details,
8518 recommended_action: None,
8519 })
8520 })?;
8521 let has_log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
8522 Box::new(SyncOutcome::Failed {
8523 error_code: "storage.failed".into(),
8524 message,
8525 details: None,
8526 recommended_action: None,
8527 })
8528 })?;
8529 let uploads = if has_log_epoch.is_some() && self.schema_has_blobs() {
8530 self.pending_blob_uploads().map_err(|e| {
8531 Box::new(SyncOutcome::Failed {
8532 error_code: e.code,
8533 message: e.message,
8534 details: e.details,
8535 recommended_action: None,
8536 })
8537 })?
8538 } else {
8539 Vec::new()
8540 };
8541 if self.realtime_state != RealtimeState::Connected
8542 && self.realtime_policy == RealtimePolicy::Required
8543 {
8544 let retry_delay_ms = self.schedule_background_retry();
8545 self.realtime_retry_delay_ms = Some(retry_delay_ms);
8546 return Err(Box::new(SyncOutcome::RealtimeUnavailable {
8547 state: self.realtime_state,
8548 reason_code: self.realtime_reason_code.clone(),
8549 retry_delay_ms,
8550 }));
8551 }
8552 let (message, mut meta) = self.build_request(url_capable)?;
8553 let units = self.stored(load_units(&self.conn)).map_err(|message| {
8554 Box::new(SyncOutcome::Failed {
8555 error_code: "storage.failed".into(),
8556 message,
8557 details: None,
8558 recommended_action: None,
8559 })
8560 })?;
8561 for unit in &units {
8562 let applied =
8563 self.stored(applied_rows(&self.conn, &unit.id))
8564 .map_err(|message| {
8565 Box::new(SyncOutcome::Failed {
8566 error_code: "storage.failed".into(),
8567 message,
8568 details: None,
8569 recommended_action: None,
8570 })
8571 })?;
8572 if !applied.is_empty() {
8573 meta.applied.insert(unit.id.clone(), applied);
8574 }
8575 }
8576 let id = uuid::Uuid::new_v4();
8577 self.active_round = Some((id, started_at_ms, attempt));
8578 let phase = if uploads.is_empty() {
8579 crate::round::RoundPhase::Sync
8580 } else {
8581 crate::round::RoundPhase::UploadGrant
8582 };
8583 Ok(crate::PreparedSyncRound {
8584 id,
8585 started_at_ms,
8586 attempt,
8587 message,
8588 meta,
8589 uploads: uploads.into(),
8590 phase,
8591 encoded: None,
8592 continuation: None,
8593 completed: None,
8594 realtime: self.realtime_state == RealtimeState::Connected,
8595 scopes: units
8597 .into_iter()
8598 .map(|unit| {
8599 (
8600 unit.id,
8601 canonical_scope_json(&unit_scope_lists(&unit.scopes)),
8602 )
8603 })
8604 .collect(),
8605 #[cfg(feature = "bench-internals")]
8606 benchmark_phases: self.benchmark_phases.clone(),
8607 progress: self.progress.clone(),
8608 fixed_now: self
8609 .now_ms
8610 .as_ref()
8611 .map(|clock| clock.load(std::sync::atomic::Ordering::Relaxed)),
8612 round_deadline_at: None,
8613 idle_bound: None,
8614 })
8615 })();
8616 prepared
8617 .map_err(|outcome| Box::new(self.finish_sync_round(started_at_ms, attempt, *outcome)))
8618 }
8619
8620 pub fn cancel_sync_round(&mut self) {
8624 if let Some((_, started_at_ms, attempt)) = self.active_round.take() {
8625 self.storage_failure.borrow_mut().take();
8627 self.finish_sync_round(
8628 started_at_ms,
8629 attempt,
8630 SyncOutcome::Failed {
8631 error_code: "client.round_cancelled".into(),
8632 message: "sync round belongs to a released client context".into(),
8633 details: None,
8634 recommended_action: None,
8635 },
8636 );
8637 }
8638 }
8639
8640 pub fn apply_sync_round(
8643 &mut self,
8644 completed: crate::CompletedSyncRound,
8645 ) -> crate::AppliedSyncRound {
8646 let mut prepared = completed.prepared;
8647 if self.active_round.map(|(id, ..)| id) != Some(prepared.id) || self.security_preflight {
8648 return crate::AppliedSyncRound::Complete {
8649 outcome: SyncOutcome::Failed {
8650 error_code: "client.round_cancelled".into(),
8651 message: "sync round belongs to a released client context".into(),
8652 details: None,
8653 recommended_action: None,
8654 },
8655 controls: Vec::new(),
8656 more: false,
8657 bootstrap_advanced: false,
8658 };
8659 }
8660 self.storage_failure.borrow_mut().take();
8661 let (response, mut downloads, transport_failed) = match completed.exchange {
8662 crate::round::ExchangeResult::Upload { id, result } => {
8663 let result = match result {
8664 Err(error)
8669 if error
8670 .details
8671 .as_ref()
8672 .and_then(|details| details.get("retryable"))
8673 == Some(&Value::Bool(false)) =>
8674 {
8675 self.conn
8676 .prepare(
8677 "SELECT commit_id FROM _syncular_blob_commit_refs WHERE blob_id = ?",
8678 )
8679 .and_then(|mut statement| {
8680 statement
8681 .query_map(rusqlite::params![id], |row| row.get::<_, String>(0))?
8682 .collect::<Result<HashSet<_>, _>>()
8683 })
8684 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
8685 .and_then(|refused| {
8686 let commits = self
8687 .outbox
8688 .iter()
8689 .filter(|commit| refused.contains(&commit.client_commit_id))
8690 .cloned()
8691 .collect::<Vec<_>>();
8692 if !commits.is_empty() {
8693 self.drop_outbox_commits(&commits, &error.code, &error.message)?;
8694 }
8695 prepared.message.frames.retain(|frame| {
8696 !matches!(frame, Frame::PushCommit { client_commit_id, .. }
8697 if refused.contains(client_commit_id))
8698 });
8699 prepared.meta.pushed_ids.retain(|id| !refused.contains(id));
8700 prepared.continuation = Some(crate::round::RoundPhase::UploadGrant);
8701 Ok(())
8702 })
8703 .map_err(|message| TransportError::new("client.failed", message))
8704 }
8705 result => result,
8706 };
8707 let result = result.and_then(|()| {
8708 self.conn
8709 .execute(
8710 "DELETE FROM _syncular_blob_uploads WHERE blob_id = ?",
8711 rusqlite::params![id],
8712 )
8713 .map(|_| ())
8714 .map_err(|error| {
8715 TransportError::new(
8716 "client.failed",
8717 Self::sqlite_failure(&self.storage_failure, error),
8718 )
8719 })
8720 });
8721 match result {
8722 Ok(()) => return crate::AppliedSyncRound::Continue(prepared),
8723 Err(TransportError {
8724 code,
8725 message,
8726 details,
8727 }) => {
8728 self.active_round = None;
8729 if Self::unreachable_transport(&details) {
8730 self.set_sync_needed(true, false);
8733 } else if Self::retryable_failure_code(&code) {
8734 self.schedule_background_retry();
8735 }
8736 let recommended_action = recommended_action_of(&details);
8737 let outcome = self.finish_sync_round(
8738 prepared.started_at_ms,
8739 prepared.attempt,
8740 SyncOutcome::Failed {
8741 error_code: code,
8742 message,
8743 details,
8744 recommended_action,
8745 },
8746 );
8747 return crate::AppliedSyncRound::Complete {
8748 outcome,
8749 controls: Vec::new(),
8750 more: false,
8751 bootstrap_advanced: false,
8752 };
8753 }
8754 }
8755 }
8756 crate::round::ExchangeResult::Reply {
8757 response,
8758 downloads,
8759 transport_failed,
8760 } => (response, downloads, transport_failed),
8761 };
8762 self.active_round = None;
8763 let before = self.resume_tokens();
8764 let outcome = (|| {
8765 let response = match response {
8766 Ok(response) => {
8767 self.round_failure = None;
8770 response
8771 }
8772 Err(TransportError {
8773 code,
8774 message,
8775 details,
8776 }) => {
8777 if code != "sync.idle_timeout" && ssp2::model::valid_round_failure_code(&code) {
8783 self.round_failure = Some(code.clone());
8784 }
8785 if transport_failed {
8786 if prepared.realtime {
8787 self.set_realtime_state(RealtimeState::Lost, Some(&code));
8788 }
8789 if let Err(message) = self.record_lease_error(&code) {
8790 return SyncOutcome::Failed {
8791 error_code: "storage.failed".to_owned(),
8792 message,
8793 details: None,
8794 recommended_action: None,
8795 };
8796 }
8797 }
8798 if Self::retryable_failure_code(&code) && !Self::unreachable_transport(&details)
8799 {
8800 let delay = self.schedule_background_retry();
8801 if prepared.realtime && transport_failed {
8802 self.realtime_retry_delay_ms = Some(delay);
8803 }
8804 }
8805 let recommended_action = recommended_action_of(&details);
8806 return SyncOutcome::Failed {
8807 error_code: code,
8808 message,
8809 details,
8810 recommended_action,
8811 };
8812 }
8813 };
8814 let mut outcome = self.process_response(&mut downloads, response, &prepared.meta);
8815 if let SyncOutcome::Ok(report) = &mut outcome {
8816 report.deferred_commits = prepared.meta.deferred_commits;
8817 }
8818 match &outcome {
8819 SyncOutcome::Ok(_) => self.reset_background_retry(),
8820 SyncOutcome::Failed {
8821 error_code,
8822 details,
8823 ..
8824 } if Self::retryable_failure_code(error_code)
8825 && !Self::unreachable_transport(details) =>
8826 {
8827 self.schedule_background_retry();
8828 }
8829 _ => {}
8830 }
8831 if prepared.meta.deferred_commits > 0 {
8832 self.set_sync_needed(true, true);
8833 }
8834 self.previous_version_lifetime_check();
8835 outcome
8836 })();
8837 match &outcome {
8838 SyncOutcome::Ok(report) if !report.bootstrapping.is_empty() => {
8841 self.set_sync_needed(true, false)
8842 }
8843 SyncOutcome::Failed { details, .. } if Self::unreachable_transport(details) => {
8846 self.set_sync_needed(true, false)
8847 }
8848 _ => {}
8849 }
8850 let more = self.transport_enabled
8851 && matches!(&outcome, SyncOutcome::Ok(report)
8852 if report.schema_floor.is_none()
8853 && (!report.bootstrapping.is_empty()
8854 || report.commits_applied > 0
8855 || report.segment_rows_applied > 0
8856 || !report.resets.is_empty()
8857 || report.deferred_commits > 0
8858 || self.sync_needed));
8859 let bootstrap_advanced = matches!(&outcome, SyncOutcome::Ok(report) if report.segment_rows_applied > 0 && !report.bootstrapping.is_empty())
8860 && before != self.resume_tokens();
8861 crate::AppliedSyncRound::Complete {
8862 outcome: self.finish_sync_round(prepared.started_at_ms, prepared.attempt, outcome),
8863 controls: if self.transport_enabled {
8864 downloads.controls
8865 } else {
8866 Vec::new()
8867 },
8868 more,
8869 bootstrap_advanced,
8870 }
8871 }
8872
8873 #[allow(clippy::type_complexity)]
8877 fn resume_tokens(&self) -> Option<Vec<(String, Option<String>, Option<String>)>> {
8878 self.conn
8879 .prepare_cached(
8880 "SELECT id, bootstrap_state, applied FROM _syncular_units ORDER BY rowid",
8881 )
8882 .and_then(|mut stmt| {
8883 stmt.query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?
8884 .collect()
8885 })
8886 .ok()
8887 }
8888
8889 pub const SYNC_IDLE_TIMEOUT_MS: u64 = 60_000;
8891
8892 pub fn sync_until_idle(
8893 &mut self,
8894 transport: &mut dyn Transport,
8895 max_rounds: Option<u32>,
8896 ) -> SyncOutcome {
8897 self.sync_until_idle_with_deadline(transport, max_rounds, Some(Self::SYNC_IDLE_TIMEOUT_MS))
8898 }
8899
8900 pub fn sync_until_idle_with_deadline(
8907 &mut self,
8908 transport: &mut dyn Transport,
8909 max_rounds: Option<u32>,
8910 timeout_ms: Option<u64>,
8911 ) -> SyncOutcome {
8912 if max_rounds == Some(0) {
8915 return SyncOutcome::Failed {
8916 details: None,
8917 error_code: "sync.invalid_request".into(),
8918 message: "maxRounds must be a positive integer".into(),
8919 recommended_action: None,
8920 };
8921 }
8922 if timeout_ms.is_some_and(|ms| ms == 0 || i64::try_from(ms).is_err()) {
8923 return SyncOutcome::Failed {
8924 details: None,
8925 error_code: "sync.invalid_request".into(),
8926 message: "timeoutMs must be a positive integer".into(),
8927 recommended_action: None,
8928 };
8929 }
8930 let started_at_ms = self.clock_now_ms();
8931 let rounds = max_rounds.unwrap_or(20);
8932 let mut aggregate = SyncReport::default();
8933 let decisions = match self.prepare_replacements() {
8936 Ok(decisions) => decisions,
8937 Err(message) => {
8938 return SyncOutcome::Failed {
8939 details: None,
8940 error_code: "storage.failed".into(),
8941 message,
8942 recommended_action: None,
8943 }
8944 }
8945 };
8946 let mut spent = 0;
8947 let mut completed = false;
8948 while spent < rounds {
8949 if completed
8952 && timeout_ms.is_some_and(|ms| {
8953 self.clock_now_ms() >= started_at_ms.saturating_add(ms as i64)
8954 })
8955 {
8956 return SyncOutcome::BudgetExhausted(aggregate);
8957 }
8958 let idle_bound = timeout_ms.map(|ms| (ms, spent));
8959 spent += 1;
8960 let before = self.resume_tokens();
8961 match self.sync_bounded(transport, idle_bound) {
8962 SyncOutcome::Failed {
8963 error_code,
8964 message,
8965 details,
8966 recommended_action,
8967 } => {
8968 return SyncOutcome::Failed {
8969 details,
8970 error_code,
8971 message,
8972 recommended_action,
8973 };
8974 }
8975 outcome @ SyncOutcome::RealtimeUnavailable { .. } => return outcome,
8976 SyncOutcome::BudgetExhausted(_) => {
8977 unreachable!("sync() never exhausts a round budget")
8978 }
8979 SyncOutcome::Ok(report) => {
8980 completed = true;
8981 if max_rounds.is_none()
8982 && report.segment_rows_applied > 0
8983 && !report.bootstrapping.is_empty()
8984 && before != self.resume_tokens()
8985 {
8986 spent = 0;
8987 }
8988 let stop = !self.transport_enabled() || report.schema_floor.is_some();
8991 aggregate.merge(&report);
8992 let more = !stop
8998 && (!report.bootstrapping.is_empty()
8999 || report.commits_applied > 0
9000 || report.segment_rows_applied > 0
9001 || !report.resets.is_empty()
9002 || report.deferred_commits > 0
9003 || self.sync_needed);
9004 if more {
9005 continue;
9006 }
9007 match self.settle_replacements(&decisions, &SyncOutcome::Ok(aggregate.clone()))
9010 {
9011 Ok(true) if !stop => {}
9012 Ok(_) => return SyncOutcome::Ok(aggregate),
9013 Err(message) => {
9014 return SyncOutcome::Failed {
9015 details: None,
9016 error_code: "storage.failed".into(),
9017 message,
9018 recommended_action: None,
9019 }
9020 }
9021 }
9022 }
9023 }
9024 }
9025 SyncOutcome::BudgetExhausted(aggregate)
9028 }
9029
9030 fn process_response(
9031 &mut self,
9032 transport: &mut dyn Transport,
9033 response: Message,
9034 meta: &RequestMeta,
9035 ) -> SyncOutcome {
9036 #[cfg(feature = "bench-internals")]
9037 let _phase = self.benchmark_phases.start(Phase::ResponseApply);
9038 let mut report = SyncReport {
9039 pushed: meta.pushed_ids.len() as u32,
9040 ..SyncReport::default()
9041 };
9042 let mut rejection_details_by_commit: HashMap<String, BTreeMap<i32, RejectionDetails>> =
9043 HashMap::new();
9044 let pushed_ids = meta
9045 .pushed_ids
9046 .iter()
9047 .map(String::as_str)
9048 .collect::<HashSet<_>>();
9049 let mut last_final_push_result_id: Option<String> = None;
9050 for frame in &response.frames {
9051 match frame {
9052 Frame::PushResultDetails {
9053 client_commit_id,
9054 entries,
9055 } => {
9056 let details = rejection_details_by_commit
9057 .entry(client_commit_id.clone())
9058 .or_default();
9059 for entry in entries {
9060 let parsed = match RejectionDetails::parse(&entry.details.0) {
9061 Ok(value) => value,
9062 Err(message) => {
9063 return SyncOutcome::Failed {
9064 details: None,
9065 error_code: "sync.invalid_request".to_owned(),
9066 message,
9067 recommended_action: None,
9068 };
9069 }
9070 };
9071 details.insert(entry.op_index, parsed);
9072 }
9073 }
9074 Frame::PushResult {
9075 client_commit_id,
9076 status,
9077 results,
9078 ..
9079 } if pushed_ids.contains(client_commit_id.as_str())
9080 && Self::push_result_is_final(*status, results) =>
9081 {
9082 last_final_push_result_id = Some(client_commit_id.clone());
9083 }
9084 _ => {}
9085 }
9086 }
9087 let mut frames = response.frames.into_iter().peekable();
9088 match frames.next() {
9089 Some(Frame::RespHeader {
9090 required_schema_version,
9091 latest_schema_version,
9092 log_epoch,
9093 reset_required,
9094 }) => {
9095 if let Some(required) = required_schema_version {
9096 let floor = SchemaFloor {
9099 required_schema_version: Some(required),
9100 latest_schema_version,
9101 };
9102 if let Err(message) = self.set_schema_floor(Some(floor.clone())) {
9103 return SyncOutcome::Failed {
9104 details: None,
9105 error_code: "storage.failed".to_owned(),
9106 message,
9107 recommended_action: None,
9108 };
9109 }
9110 report.schema_floor = Some(floor);
9111 return SyncOutcome::Ok(report);
9112 }
9113 if reset_required {
9114 if frames.next().is_some() {
9115 return SyncOutcome::Failed {
9116 details: None,
9117 error_code: "client.invalid_host_response".to_owned(),
9118 message: "log-epoch reset response contains body frames".to_owned(),
9119 recommended_action: None,
9120 };
9121 }
9122 match self.run_log_epoch_reset(&log_epoch) {
9123 Ok(resets) => {
9124 report.resets = resets;
9125 return SyncOutcome::Ok(report);
9126 }
9127 Err(message) => {
9128 return SyncOutcome::Failed {
9129 details: None,
9130 error_code: "sync.local_corrupt".to_owned(),
9131 message,
9132 recommended_action: None,
9133 };
9134 }
9135 }
9136 }
9137 let stored_epoch = match self.get_meta(LOG_EPOCH_KEY) {
9138 Ok(stored) => stored,
9139 Err(message) => {
9140 return SyncOutcome::Failed {
9141 details: None,
9142 error_code: "storage.failed".to_owned(),
9143 message,
9144 recommended_action: None,
9145 };
9146 }
9147 };
9148 if stored_epoch.is_none() {
9150 if let Err(message) = self.set_meta(LOG_EPOCH_KEY, &log_epoch) {
9151 return SyncOutcome::Failed {
9152 details: None,
9153 error_code: "storage.failed".to_owned(),
9154 message,
9155 recommended_action: None,
9156 };
9157 }
9158 } else if stored_epoch.as_deref() != Some(log_epoch.as_str()) {
9159 return SyncOutcome::Failed {
9160 details: None,
9161 error_code: "client.invalid_host_response".to_owned(),
9162 message: "server changed logEpoch without requiring a reset".to_owned(),
9163 recommended_action: None,
9164 };
9165 }
9166 }
9167 _ => {
9168 return SyncOutcome::Failed {
9169 details: None,
9170 error_code: "sync.invalid_request".to_owned(),
9171 message: "response does not start with RESP_HEADER".to_owned(),
9172 recommended_action: None,
9173 };
9174 }
9175 }
9176
9177 if let Err(message) = self.begin_coalesced_apply() {
9178 return SyncOutcome::Failed {
9179 details: None,
9180 error_code: "storage.failed".into(),
9181 message,
9182 recommended_action: None,
9183 };
9184 }
9185 let mut failure: Option<(String, String, Option<String>, Option<Value>)> = None;
9186 let mut live: Option<(LiveStatus, String, Vec<UnitRecord>)> = None;
9189 let mut live_ended = false;
9190 while let Some(frame) = frames.next() {
9191 match frame {
9192 frame @ Frame::PushResult { .. } => {
9193 let successful = matches!(
9194 &frame,
9195 Frame::PushResult {
9196 status: PushStatus::Applied | PushStatus::Cached,
9197 ..
9198 }
9199 );
9200 let mut results = vec![frame];
9201 if successful {
9202 while matches!(
9203 frames.peek(),
9204 Some(Frame::PushResult {
9205 status: PushStatus::Applied | PushStatus::Cached,
9206 ..
9207 })
9208 ) {
9209 if let Some(next) = frames.next() {
9210 results.push(next);
9211 }
9212 }
9213 }
9214 if self
9215 .handle_push_results(
9216 &results,
9217 &pushed_ids,
9218 &rejection_details_by_commit,
9219 &mut report,
9220 last_final_push_result_id.as_deref(),
9221 )
9222 .is_err()
9223 {
9224 failure = Some((
9225 "client.outcome_persistence_failed".to_owned(),
9226 "local commit outcome could not be persisted".to_owned(),
9227 None,
9228 None,
9229 ));
9230 break;
9231 }
9232 }
9233 Frame::PushResultDetails { .. } => {}
9234 Frame::SubStart {
9235 id,
9236 status,
9237 reason_code,
9238 bootstrap,
9239 fenced,
9240 } => {
9241 let mut body = Vec::new();
9244 let mut sub_end: Option<(i64, Option<String>)> = None;
9245 let mut error: Option<Frame> = None;
9246 for inner in frames.by_ref() {
9247 match inner {
9248 Frame::SubEnd {
9249 next_cursor,
9250 bootstrap_state,
9251 } => {
9252 sub_end = Some((next_cursor, bootstrap_state.map(|r| r.0)));
9253 break;
9254 }
9255 inner @ Frame::Error { .. } => {
9256 error = Some(inner);
9257 break;
9258 }
9259 Frame::Unknown { .. } => {}
9260 other => body.push(other),
9261 }
9262 }
9263 let ended = sub_end.is_some();
9264 let section = SectionStart {
9265 id,
9266 status,
9267 reason_code,
9268 bootstrap,
9269 fenced,
9270 };
9271 let completed = match self.process_section(
9272 transport,
9273 §ion,
9274 body,
9275 sub_end,
9276 meta,
9277 &mut report,
9278 ) {
9279 Err(SectionError::Abort(code, message)) => {
9280 failure = Some((code, message, None, None));
9281 break;
9282 }
9283 Err(SectionError::Transport(error)) => {
9284 failure = Some((error.code, error.message, None, error.details));
9285 break;
9286 }
9287 Ok(completed) => completed,
9288 Err(_) => false,
9289 };
9290 if ended {
9291 self.progress.update(|p| {
9295 p.unit_id = None;
9296 p.table = None;
9297 p.segment_id = None;
9298 if completed && p.unit_rows_total.is_some() {
9299 p.unit_rows_total = p.unit_rows_processed;
9300 }
9301 });
9302 }
9303 match error {
9304 Some(Frame::Error {
9305 code,
9306 message,
9307 recommended_action,
9308 details,
9309 ..
9310 }) => {
9311 failure = Some(Self::error_frame_failure(
9312 code,
9313 message,
9314 recommended_action,
9315 details,
9316 ));
9317 break;
9318 }
9319 Some(_) => unreachable!("only an ERROR closes a section early"),
9320 None if !ended => {
9321 failure = Some((
9322 "sync.invalid_request".to_owned(),
9323 "unit section without SUB_END".to_owned(),
9324 None,
9325 None,
9326 ));
9327 break;
9328 }
9329 None => {}
9330 }
9331 }
9332 Frame::LiveStart {
9333 status,
9334 reason_code,
9335 } => {
9336 let receivers = match self.stored(load_units(&self.conn)) {
9337 Ok(units) => units
9338 .into_iter()
9339 .filter(|unit| {
9340 unit.status == UnitStatus::Active
9341 && unit.echo.is_some()
9342 && !unit.bootstrapping()
9343 })
9344 .collect(),
9345 Err(message) => {
9346 failure = Some(("storage.failed".to_owned(), message, None, None));
9347 break;
9348 }
9349 };
9350 live = Some((status, reason_code, receivers));
9351 }
9352 Frame::Commit {
9353 commit_seq,
9354 tables,
9355 changes,
9356 ..
9357 } => {
9358 let Some((LiveStatus::Active, _, receivers)) = &live else {
9359 continue;
9360 };
9361 let receivers = receivers.clone();
9362 match self.apply_live_commit(
9363 &receivers,
9364 &tables,
9365 changes,
9366 commit_seq,
9367 AppliedServerCommitSource::Pull,
9368 ) {
9369 Ok(applied) => report.commits_applied += u32::from(applied),
9370 Err(error) => {
9371 failure = Some((error.code, error.message, None, error.details));
9372 break;
9373 }
9374 }
9375 }
9376 Frame::LiveEnd {
9377 through_seq,
9378 echo_digest,
9379 } => {
9380 let Some((status, reason_code, _)) = live.take() else {
9381 continue;
9382 };
9383 live_ended = true;
9384 live = Some((status, String::new(), Vec::new()));
9385 if let Err(message) = self.finish_live_section(
9386 status,
9387 &reason_code,
9388 through_seq,
9389 echo_digest,
9390 &meta.registration_digest,
9391 &mut report,
9392 ) {
9393 failure = Some(("storage.failed".to_owned(), message, None, None));
9394 break;
9395 }
9396 }
9397 Frame::Lease {
9398 lease_id,
9399 expires_at_ms,
9400 } => {
9401 if let Err(message) = self.set_lease_state(Some(LeaseState {
9404 lease_id: Some(lease_id),
9405 expires_at_ms: Some(expires_at_ms),
9406 error_code: None,
9407 })) {
9408 failure = Some(("storage.failed".to_owned(), message, None, None));
9409 break;
9410 }
9411 }
9412 Frame::Error {
9413 code,
9414 message,
9415 recommended_action,
9416 details,
9417 ..
9418 } => {
9419 failure = Some(Self::error_frame_failure(
9422 code,
9423 message,
9424 recommended_action,
9425 details,
9426 ));
9427 break;
9428 }
9429 Frame::Unknown { .. } => {}
9430 _ => {
9431 failure = Some((
9432 "sync.invalid_request".to_owned(),
9433 "unexpected frame in response".to_owned(),
9434 None,
9435 None,
9436 ));
9437 break;
9438 }
9439 }
9440 }
9441
9442 let applied = match failure {
9443 Some(failure) => Err(failure),
9444 None => self
9449 .rebuild_overlay_if_dirty()
9450 .and_then(|()| self.drain_pending_evictions())
9451 .map_err(|message| ("storage.failed".to_owned(), message, None, None)),
9452 };
9453 if let Err(message) = self.finish_coalesced_apply() {
9456 return SyncOutcome::Failed {
9457 details: None,
9458 error_code: "storage.failed".into(),
9459 message,
9460 recommended_action: None,
9461 };
9462 }
9463 if let Err((error_code, message, recommended_action, details)) = applied {
9464 return SyncOutcome::Failed {
9465 details,
9466 error_code,
9467 message,
9468 recommended_action,
9469 };
9470 }
9471 let catching_up = match self.stored(load_units(&self.conn)) {
9472 Ok(units) => units
9473 .into_iter()
9474 .filter(|unit| unit.status == UnitStatus::Active && unit.cursor.is_some())
9475 .map(|unit| unit.id)
9476 .collect::<Vec<_>>(),
9477 Err(message) => {
9478 return SyncOutcome::Failed {
9479 details: None,
9480 error_code: "storage.failed".into(),
9481 message,
9482 recommended_action: None,
9483 }
9484 }
9485 };
9486 let status = live.map(|(status, _, _)| status);
9490 if !live_ended || status != Some(LiveStatus::Active) || !catching_up.is_empty() {
9491 self.set_sync_needed(true, status == Some(LiveStatus::Unregistered));
9492 }
9493 self.ack_after_pull(transport);
9494 if self.upgrading && catching_up.is_empty() {
9497 self.set_upgrading(false);
9498 }
9499 report.bootstrapping = catching_up;
9500 SyncOutcome::Ok(report)
9501 }
9502
9503 fn error_frame_failure(
9505 code: String,
9506 message: String,
9507 recommended_action: String,
9508 details: Option<RawJson>,
9509 ) -> (String, String, Option<String>, Option<Value>) {
9510 let recommended_action = (!recommended_action.is_empty()).then_some(recommended_action);
9511 let details = details
9512 .and_then(|details| serde_json::from_str::<Value>(&details.0).ok())
9513 .filter(Value::is_object);
9514 (code, message, recommended_action, details)
9515 }
9516
9517 fn finish_live_section(
9522 &mut self,
9523 status: LiveStatus,
9524 reason_code: &str,
9525 through_seq: i64,
9526 echo_digest: Option<[u8; 32]>,
9527 registration_digest: &str,
9528 report: &mut SyncReport,
9529 ) -> Result<(), String> {
9530 let rollback = self.capture();
9531 let resets = report.resets.len();
9532 self.begin_observation("syncular_live_end")?;
9533 let finished = (|| {
9534 let mut batch = ChangeAccumulator::default();
9535 let before = self.stored(replica_cursor(&self.conn))?;
9536 let mut cursor = if status == LiveStatus::Unregistered {
9537 before
9538 } else {
9539 -1
9540 };
9541 let joined = before.max(through_seq);
9542 for unit in self.stored(load_units(&self.conn))? {
9543 if unit.status != UnitStatus::Active || unit.bootstrapping() {
9544 continue;
9545 }
9546 match status {
9547 LiveStatus::Reset if unit.cursor.is_none() => {
9550 for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9551 batch.window(&base_key, &value);
9552 }
9553 report.resets.push(unit.id.clone());
9554 self.stored(save_unit(
9555 &self.conn,
9556 &UnitRecord {
9557 reason_code: Some(reason_code.to_owned()),
9558 cursor: Some(-1),
9559 seeded: Vec::new(),
9560 ..unit
9561 },
9562 ))?;
9563 }
9564 LiveStatus::Active => {
9566 let next = unit.cursor.unwrap_or(joined).max(through_seq);
9567 if next >= joined {
9568 cursor = joined;
9569 }
9570 if unit.cursor.is_some() {
9571 self.stored(save_unit(
9572 &self.conn,
9573 &UnitRecord {
9574 cursor: (next < joined).then_some(next),
9575 ..unit
9576 },
9577 ))?;
9578 }
9579 }
9580 _ => {}
9581 }
9582 }
9583 self.set_meta(REPLICA_CURSOR_KEY, &cursor.to_string())?;
9584 self.set_meta(
9585 ECHO_DIGEST_KEY,
9586 &echo_digest
9587 .map(|digest| bytes_to_hex(&digest))
9588 .unwrap_or_default(),
9589 )?;
9590 if status == LiveStatus::Unregistered {
9591 self.delete_meta(REGISTERED_DIGEST_KEY)?;
9592 } else {
9593 self.set_meta(REGISTERED_DIGEST_KEY, registration_digest)?;
9594 }
9595 self.finish_observation("syncular_live_end", batch)
9596 })();
9597 if finished.is_err() {
9598 self.rollback_observation("syncular_live_end");
9599 self.restore(rollback);
9600 report.resets.truncate(resets);
9601 }
9602 finished
9603 }
9604
9605 fn handle_push_results(
9608 &mut self,
9609 frames: &[Frame],
9610 pushed_ids: &HashSet<&str>,
9611 rejection_details_by_commit: &HashMap<String, BTreeMap<i32, RejectionDetails>>,
9612 report: &mut SyncReport,
9613 last_final_push_result_id: Option<&str>,
9614 ) -> Result<(), String> {
9615 self.begin_observation("syncular_push_results")?;
9616 let rollback = self.capture();
9617 let conflict_count = self.conflicts.len();
9618 let applied_count = report.applied.len();
9619 let rejected_count = report.rejected.len();
9620 let retryable_count = report.retryable.len();
9621 let mut drained = Vec::new();
9622 let mut batch = ChangeAccumulator::default();
9623 let persisted = (|| {
9624 for frame in frames {
9625 let Frame::PushResult {
9626 client_commit_id,
9627 status,
9628 results,
9629 commit_seq,
9630 } = frame
9631 else {
9632 return Err("unexpected acknowledgement frame".to_owned());
9633 };
9634 if !pushed_ids.contains(client_commit_id.as_str()) {
9635 continue;
9636 }
9637 let Some(index) = self
9638 .outbox
9639 .iter()
9640 .position(|commit| commit.client_commit_id == *client_commit_id)
9641 else {
9642 continue;
9643 };
9644 let status = *status;
9645 let rejection_details = rejection_details_by_commit.get(client_commit_id);
9646 let operations = self.outbox[index].ops.clone();
9647 match status {
9648 PushStatus::Applied | PushStatus::Cached => {
9649 let sequence =
9652 commit_seq.ok_or_else(|| "ACK lacks a commit sequence".to_owned())?;
9653 let affected: HashSet<_> = operations
9654 .iter()
9655 .map(|op| (op.table.as_str(), op.row_id.as_str()))
9656 .collect();
9657 let prior = self.acknowledged_operations(Some(&affected), None)?;
9658 for (op_index, operation) in operations.iter().enumerate() {
9659 let delivered: bool = self.conn.query_row("SELECT EXISTS(SELECT 1 FROM _syncular_row_deliveries WHERE tbl=?1 AND id=?2 AND commit_seq>=?3)", rusqlite::params![operation.table, operation.row_id, sequence], |row| row.get(0))
9660 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9661 if delivered {
9662 continue;
9663 }
9664 let table = self
9665 .schema
9666 .table(&operation.table)
9667 .ok_or_else(|| "sync.unknown_table".to_owned())?;
9668 let mut intended: Map<String, Value> = self
9669 .stored_row(table, &operation.row_id, true)?
9670 .map(|(row, _)| {
9671 table
9672 .columns
9673 .iter()
9674 .zip(&row)
9675 .map(|(column, value)| {
9676 (column.name.clone(), column_value_to_json(value))
9677 })
9678 .collect()
9679 })
9680 .unwrap_or_default();
9681 let mut scope_image = intended.clone();
9682 for op in prior
9683 .iter()
9684 .chain(
9685 self.failed_commits
9686 .iter()
9687 .flat_map(|(commit, _)| &commit.ops),
9688 )
9689 .chain(
9690 self.outbox
9691 .iter()
9692 .take(index)
9693 .flat_map(|commit| &commit.ops),
9694 )
9695 .chain(operations.iter().take(op_index + 1))
9696 {
9697 if op.table != operation.table || op.row_id != operation.row_id {
9698 continue;
9699 }
9700 if let Some(values) = &op.values {
9701 intended.extend(values.clone());
9702 } else {
9703 scope_image = intended.clone();
9704 intended.clear();
9705 }
9706 }
9707 self.conn.execute("INSERT INTO _syncular_acked_rows(commit_id,idx,tbl,id,commit_seq,op_json,intent_json) VALUES (?1,?2,?3,?4,?5,?6,?7)",
9708 rusqlite::params![client_commit_id, op_index as i64, operation.table, operation.row_id, sequence,
9709 serde_json::to_string(&CommitOperation::from(operation)).map_err(|_| "sync.local_corrupt".to_owned())?,
9710 serde_json::to_string(if operation.upsert { &intended } else { &scope_image }).map_err(|_| "sync.local_corrupt".to_owned())?])
9711 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9712 }
9713 let journal_results = results
9714 .iter()
9715 .map(|result| {
9716 let op_index = match result {
9717 OpResult::Applied { op_index }
9718 | OpResult::Conflict { op_index, .. }
9719 | OpResult::Error { op_index, .. } => *op_index,
9720 };
9721 CommitOperationOutcome::Applied { op_index }
9722 })
9723 .collect::<Vec<_>>();
9724 let outcome_status = if status == PushStatus::Applied {
9725 CommitOutcomeStatus::Applied
9726 } else {
9727 CommitOutcomeStatus::Cached
9728 };
9729 let persisted = self
9730 .persist_commit_outcome(
9731 client_commit_id,
9732 outcome_status,
9733 &journal_results,
9734 None,
9735 )
9736 .and_then(|()| self.delete_outbox_persisted(client_commit_id));
9737 persisted?;
9738 self.sync_needed = true;
9739 batch.status = true;
9740 batch.outcomes = true;
9741 }
9742 PushStatus::Rejected => {
9743 if results.iter().any(|result| {
9744 matches!(
9745 result,
9746 OpResult::Error {
9747 code,
9748 retryable: true,
9749 ..
9750 } if code == "sync.idempotency_cache_miss"
9751 )
9752 }) {
9753 report.retryable.push(client_commit_id.to_owned());
9756 continue;
9757 }
9758
9759 let mut journal_results = Vec::with_capacity(results.len());
9760 let mut conflicts = Vec::new();
9761 let mut rejections = Vec::new();
9762 for result in results {
9763 match result {
9764 OpResult::Applied { op_index } => {
9765 journal_results.push(CommitOperationOutcome::Applied {
9766 op_index: *op_index,
9767 });
9768 }
9769 OpResult::Conflict {
9770 op_index,
9771 code,
9772 message,
9773 server_version,
9774 server_row,
9775 conflict_columns: conflict_columns_bitmap,
9776 } => {
9777 let operation = operations
9778 .get(*op_index as usize)
9779 .map(CommitOperation::from);
9780 let (table, row_id) = operation
9781 .as_ref()
9782 .map(|op| (op.table.clone(), op.row_id.clone()))
9783 .unwrap_or_default();
9784 let server_row_json = self
9785 .schema
9786 .table(&table)
9787 .and_then(|t| {
9788 decode_row_bytes(t, server_row, &self.encryption)
9789 .ok()
9790 .map(|(row, _)| (t, row))
9791 })
9792 .map(|(t, row)| {
9793 let mut map = Map::new();
9794 for (i, column) in t.columns.iter().enumerate() {
9795 map.insert(
9796 column.name.clone(),
9797 column_value_to_json(
9798 row.get(i).unwrap_or(&None),
9799 ),
9800 );
9801 }
9802 map
9803 })
9804 .unwrap_or_default();
9805 let conflict_columns = self
9808 .schema
9809 .table(&table)
9810 .map(|t| {
9811 t.columns
9812 .iter()
9813 .enumerate()
9814 .filter(|(index, _)| {
9815 conflict_columns_bitmap
9816 .get(index / 8)
9817 .is_some_and(|byte| {
9818 byte & (1 << (index % 8)) != 0
9819 })
9820 })
9821 .map(|(_, column)| column.name.clone())
9822 .collect::<Vec<_>>()
9823 })
9824 .unwrap_or_default();
9825 let conflict = ConflictRecord {
9826 client_commit_id: client_commit_id.to_owned(),
9827 op_index: *op_index,
9828 table,
9829 row_id,
9830 code: code.clone(),
9831 message: message.clone(),
9832 server_version: *server_version,
9833 server_row: server_row_json,
9834 conflict_columns,
9835 operation,
9836 };
9837 journal_results.push(CommitOperationOutcome::Conflict {
9838 conflict: conflict.clone(),
9839 });
9840 conflicts.push(conflict);
9841 }
9842 OpResult::Error {
9843 op_index,
9844 code,
9845 message,
9846 retryable,
9847 } => {
9848 let rejection = RejectionRecord {
9849 client_commit_id: client_commit_id.to_owned(),
9850 op_index: *op_index,
9851 code: code.clone(),
9852 message: message.clone(),
9853 retryable: *retryable,
9854 details: rejection_details
9855 .and_then(|details| details.get(op_index))
9856 .cloned(),
9857 operation: operations
9858 .get(*op_index as usize)
9859 .map(CommitOperation::from),
9860 };
9861 journal_results.push(CommitOperationOutcome::Error {
9862 rejection: rejection.clone(),
9863 });
9864 rejections.push(rejection);
9865 }
9866 }
9867 }
9868 if self.retain_failed_commits {
9869 self.retain_failed_commit(client_commit_id, &operations)?;
9870 }
9871 let outcome_status = if conflicts.is_empty() {
9872 CommitOutcomeStatus::Rejected
9873 } else {
9874 CommitOutcomeStatus::Conflict
9875 };
9876 let persisted = self
9877 .persist_commit_outcome(
9878 client_commit_id,
9879 outcome_status,
9880 &journal_results,
9881 Some(&operations),
9882 )
9883 .and_then(|()| self.delete_outbox_persisted(client_commit_id));
9884 persisted?;
9885 batch.conflicts = !conflicts.is_empty();
9886 batch.rejections = !rejections.is_empty();
9887 batch.status = true;
9888 batch.outcomes = true;
9889 self.conflicts.extend(conflicts);
9890 self.rejections.extend(rejections);
9891 }
9892 }
9893 drained.push(self.outbox.remove(index));
9894 if batch.status {
9895 for operation in &operations {
9896 if !self.record_row_scopes(
9897 &mut batch,
9898 &operation.table,
9899 &operation.row_id,
9900 false,
9901 ) {
9902 batch.table(&operation.table);
9903 }
9904 }
9905 }
9906 match status {
9907 PushStatus::Applied | PushStatus::Cached => {
9908 report.applied.push(client_commit_id.to_owned())
9909 }
9910 PushStatus::Rejected => report.rejected.push(client_commit_id.to_owned()),
9911 }
9912 }
9913 if batch.outcomes && frames.iter().any(|frame| matches!(frame, Frame::PushResult { client_commit_id, .. } if Some(client_commit_id.as_str()) == last_final_push_result_id)) {
9914 self.prune_commit_outcomes()?;
9915 }
9916 self.reconcile_rows(&drained)?;
9917 self.rebuild_overlay_if_dirty()?;
9918 self.finish_observation("syncular_push_results", batch)
9919 })();
9920 if let Err(error) = persisted {
9921 self.rollback_observation("syncular_push_results");
9922 self.restore(rollback);
9923 report.applied.truncate(applied_count);
9924 report.rejected.truncate(rejected_count);
9925 report.retryable.truncate(retryable_count);
9926 return Err(error);
9927 }
9928 if !rollback.sync_needed && self.sync_needed {
9929 self.sync_intent_queue.push_back(SyncIntent::Interactive);
9930 }
9931 report.conflicts += (self.conflicts.len() - conflict_count) as u32;
9932 Ok(())
9933 }
9934
9935 fn push_result_is_final(status: PushStatus, results: &[OpResult]) -> bool {
9936 status != PushStatus::Rejected
9937 || !results.iter().any(|result| {
9938 matches!(
9939 result,
9940 OpResult::Error {
9941 code,
9942 retryable: true,
9943 ..
9944 } if code == "sync.idempotency_cache_miss"
9945 )
9946 })
9947 }
9948
9949 fn process_section(
9958 &mut self,
9959 transport: &mut dyn Transport,
9960 start: &SectionStart,
9961 body: Vec<Frame>,
9962 sub_end: Option<(i64, Option<String>)>,
9963 meta: &RequestMeta,
9964 report: &mut SyncReport,
9965 ) -> Result<bool, SectionError> {
9966 let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
9967 let unit = self
9968 .stored(get_unit(&self.conn, &start.id))
9969 .map_err(storage)?
9970 .filter(|unit| unit.status == UnitStatus::Active);
9971 let extent = match (&unit, body.first()) {
9974 (
9975 Some(_),
9976 Some(Frame::UnitExtent {
9977 rows_total,
9978 rows_done,
9979 }),
9980 ) => u64::try_from(*rows_total)
9981 .ok()
9982 .zip(u64::try_from(*rows_done).ok()),
9983 _ => None,
9984 };
9985 self.progress.update(|p| {
9986 p.phase = ProgressPhase::Import;
9987 p.unit_id = unit.as_ref().map(|unit| unit.id.clone());
9988 p.unit_rows_total = extent.map(|(total, _)| total);
9989 p.unit_rows_processed = extent.map(|(_, done)| done);
9990 p.table = None;
9991 p.segment_id = None;
9992 p.bytes_received = 0;
9993 p.bytes_total = None;
9994 p.rows_processed = 0;
9995 p.rows_total = None;
9996 p.import_write_ms = None;
9997 p.import_commit_ms = None;
9998 });
9999 let Some(unit) = unit else {
10000 return Ok(false);
10001 };
10002 let echo: Vec<EchoRecord> = start
10003 .fenced
10004 .iter()
10005 .map(|record| EchoRecord {
10006 table: record.table.clone(),
10007 status: record.status.name().to_owned(),
10008 scopes: record.scopes.iter().cloned().collect(),
10009 })
10010 .collect();
10011 let applied_record = self
10013 .stored(applied_rows(&self.conn, &unit.id))
10014 .map_err(storage)?;
10015 let mut seeded: BTreeSet<String> = if unit.bootstrap_state.is_none() {
10017 BTreeSet::new()
10018 } else {
10019 unit.seeded.iter().cloned().collect()
10020 };
10021 let applied = (|| {
10022 for frame in body {
10023 match frame {
10024 Frame::SegmentInline { payload } => {
10025 let segment = decode_rows_segment(&payload).map_err(|e| {
10026 SectionError::Abort(e.code.as_str().to_owned(), e.detail)
10027 })?;
10028 self.progress.update(|p| {
10029 p.phase = ProgressPhase::Import;
10030 p.unit_id = Some(unit.id.clone());
10031 p.table = Some(segment.table.clone());
10032 p.segment_id = None;
10033 p.bytes_received = payload.len() as u64;
10034 p.bytes_total = Some(payload.len() as u64);
10035 p.rows_processed = 0;
10036 p.rows_total =
10037 Some(segment.blocks.iter().map(|block| block.len() as u64).sum());
10038 p.import_write_ms = None;
10039 p.import_commit_ms = None;
10040 });
10041 let (pair, clear, effective) =
10042 self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
10043 report.segment_rows_applied +=
10044 self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
10045 seeded.insert(segment.table);
10046 }
10047 Frame::SegmentRef {
10048 segment_id,
10049 byte_length,
10050 media_type,
10051 table,
10052 row_count,
10053 as_of_commit_seq,
10054 scope_digest,
10055 row_cursor,
10056 next_row_cursor,
10057 url,
10058 url_expires_at_ms,
10059 ..
10060 } => {
10061 let advertised = match media_type {
10064 MediaType::Rows => {
10065 meta.accept & ACCEPT_EXTERNAL_ROWS != 0
10066 || meta.accept & ACCEPT_INLINE_ROWS != 0
10067 }
10068 MediaType::Sqlite => meta.accept & ACCEPT_SQLITE != 0,
10069 };
10070 if !advertised {
10071 return Err(SectionError::Abort(
10072 "sync.invalid_request".to_owned(),
10073 format!(
10074 "SEGMENT_REF mediaType {} was not advertised in accept (§4.2)",
10075 media_type.name()
10076 ),
10077 ));
10078 }
10079 let resumed = applied_record.get(&segment_id).copied();
10082 if resumed.is_some() {
10083 seeded.insert(table.clone());
10084 }
10085 if resumed == Some(row_count) {
10086 self.progress.update(|p| {
10089 p.phase = ProgressPhase::Import;
10090 p.unit_id = Some(unit.id.clone());
10091 p.table = Some(table.clone());
10092 p.segment_id = Some(segment_id.clone());
10093 p.bytes_received = 0;
10094 p.bytes_total = None;
10095 p.rows_processed = 0;
10096 p.rows_total = u64::try_from(row_count).ok();
10097 p.import_write_ms = None;
10098 p.import_commit_ms = None;
10099 });
10100 self.progress.update(|p| {
10101 p.rows_processed = u64::try_from(row_count).unwrap_or(0)
10102 });
10103 continue;
10104 }
10105 if meta
10106 .deferred
10107 .contains(&(unit.id.clone(), segment_id.clone()))
10108 {
10109 return Err(SectionError::Deferred);
10110 }
10111 self.progress.update(|p| {
10112 p.phase = ProgressPhase::Download;
10113 p.unit_id = Some(unit.id.clone());
10114 p.table = Some(table.clone());
10115 p.segment_id = Some(segment_id.clone());
10116 p.bytes_received = 0;
10117 p.bytes_total = u64::try_from(byte_length).ok();
10118 p.rows_processed = 0;
10119 p.rows_total = u64::try_from(row_count).ok();
10120 p.import_write_ms = None;
10121 p.import_commit_ms = None;
10122 });
10123 let observer = self.progress.clone();
10124 let mut on_progress = |bytes| observer.update(|p| p.bytes_received = bytes);
10125 let bytes = if let Some(url) = url {
10126 if meta.accept & ACCEPT_SIGNED_URLS == 0 {
10131 return Err(SectionError::Abort(
10132 "sync.invalid_request".to_owned(),
10133 "SEGMENT_REF carries a url but accept bit 3 was not advertised (§5.4)"
10134 .to_owned(),
10135 ));
10136 }
10137 if url_expires_at_ms.is_some_and(|exp| {
10139 exp <= transport
10140 .segment_fetch_started_at(&url)
10141 .unwrap_or_else(|| self.clock_now_ms())
10142 }) {
10143 return Err(SectionError::Abort(
10144 "sync.segment_expired".to_owned(),
10145 format!(
10146 "signed URL for segment {segment_id} expired before fetch — re-pull mints fresh descriptors (§5.4)"
10147 ),
10148 ));
10149 }
10150 transport
10151 .fetch_url(
10152 &url,
10153 u64::try_from(byte_length).unwrap_or(0),
10154 &mut on_progress,
10155 )
10156 .map_err(|e| self.segment_fetch_failed(e))?
10157 } else {
10158 let requested_scopes_json =
10160 canonical_scope_json(&unit_scope_lists(&unit.scopes));
10161 transport
10162 .download_segment(
10163 &SegmentRequest {
10164 segment_id: segment_id.clone(),
10165 table: table.clone(),
10166 requested_scopes_json,
10167 byte_length: u64::try_from(byte_length).unwrap_or(0),
10168 },
10169 &mut on_progress,
10170 )
10171 .map_err(|e| {
10172 if e.code == "sync.forbidden" {
10175 SectionError::Refused
10176 } else {
10177 self.segment_fetch_failed(e)
10178 }
10179 })?
10180 };
10181 if bytes.len() as i64 > byte_length {
10185 self.schedule_background_retry();
10186 return Err(SectionError::Abort(
10187 "sync.invalid_request".to_owned(),
10188 "segment exceeds its byteLength".to_owned(),
10189 ));
10190 }
10191 on_progress(bytes.len() as u64);
10192 let digest = Sha256::digest(&bytes);
10193 let expected = segment_id
10194 .strip_prefix("sha256:")
10195 .unwrap_or(segment_id.as_str());
10196 if bytes_to_hex(&digest) != expected {
10197 self.schedule_background_retry();
10199 return Err(SectionError::Abort(
10200 "sync.invalid_request".to_owned(),
10201 "segment bytes do not match the content address (§5.1)".to_owned(),
10202 ));
10203 }
10204 self.progress.update(|p| p.phase = ProgressPhase::Import);
10205 if media_type == MediaType::Sqlite {
10206 if row_cursor.is_some() || next_row_cursor.is_some() {
10209 return Err(SectionError::Abort(
10210 "sync.invalid_request".to_owned(),
10211 "sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)"
10212 .to_owned(),
10213 ));
10214 }
10215 let (pair, clear, effective) =
10216 self.segment_pair(&unit, &echo, &seeded, &table)?;
10217 report.segment_rows_applied += self.apply_sqlite_segment(
10218 &pair,
10219 &bytes,
10220 clear,
10221 &effective,
10222 &unit.id,
10223 &segment_id,
10224 resumed.unwrap_or(0),
10225 row_count,
10226 as_of_commit_seq,
10227 &scope_digest,
10228 )?;
10229 seeded.insert(table);
10230 } else {
10231 let segment = decode_rows_segment(&bytes).map_err(|e| {
10232 SectionError::Abort(e.code.as_str().to_owned(), e.detail)
10233 })?;
10234 let (pair, clear, effective) =
10235 self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
10236 report.segment_rows_applied +=
10237 self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
10238 seeded.insert(segment.table);
10239 self.stored(record_applied_rows(
10241 &self.conn,
10242 &unit.id,
10243 &segment_id,
10244 row_count,
10245 ))
10246 .map_err(storage)?;
10247 }
10248 }
10249 Frame::UnitExtent { .. } => {}
10250 _ => {
10251 return Err(SectionError::Abort(
10252 "sync.invalid_request".to_owned(),
10253 "unexpected frame inside a unit section".to_owned(),
10254 ));
10255 }
10256 }
10257 }
10258 Ok(())
10259 })();
10260 match applied {
10261 Ok(()) => {}
10262 Err(SectionError::Refused | SectionError::Deferred) => return Ok(false),
10264 Err(SectionError::FailClosed) => {
10265 self.begin_observation("syncular_section_failure")
10268 .map_err(storage)?;
10269 let failed = (|| {
10270 let mut batch = ChangeAccumulator::default();
10271 for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
10272 batch.window(&base_key, &value);
10273 }
10274 batch.status = true;
10275 self.stored(save_unit(
10276 &self.conn,
10277 &UnitRecord {
10278 status: UnitStatus::Failed,
10279 reason_code: Some("sync.scope_revoked".to_owned()),
10280 restriction: None,
10281 ..unit.clone()
10282 },
10283 ))?;
10284 self.finish_observation("syncular_section_failure", batch)
10285 })();
10286 if let Err(message) = failed {
10287 self.rollback_observation("syncular_section_failure");
10288 return Err(storage(message));
10289 }
10290 report.failed.push(unit.id);
10291 return Ok(false);
10292 }
10293 Err(error) => return Err(error),
10294 }
10295 let Some((next_cursor, bootstrap_state)) = sub_end else {
10296 return Ok(false);
10297 };
10298 let completes = start.bootstrap && bootstrap_state.is_none();
10299 let rollback = self.capture();
10300 let counts = (
10301 report.resets.len(),
10302 report.revoked.len(),
10303 report.failed.len(),
10304 );
10305 self.begin_observation("syncular_sub_end")
10306 .map_err(storage)?;
10307 let finished = self
10308 .finish_section(start, echo, next_cursor, bootstrap_state, seeded, report)
10309 .and_then(|batch| {
10310 self.rebuild_overlay_if_dirty()?;
10311 self.finish_observation("syncular_sub_end", batch)
10312 });
10313 if let Err(message) = finished {
10314 self.rollback_observation("syncular_sub_end");
10315 self.restore(rollback);
10316 report.resets.truncate(counts.0);
10317 report.revoked.truncate(counts.1);
10318 report.failed.truncate(counts.2);
10319 return Err(storage(message));
10320 }
10321 Ok(completes)
10322 }
10323
10324 #[allow(clippy::type_complexity)]
10327 fn segment_pair(
10328 &self,
10329 unit: &UnitRecord,
10330 echo: &[EchoRecord],
10331 seeded: &BTreeSet<String>,
10332 name: &str,
10333 ) -> Result<(TableSchema, bool, Vec<(String, Vec<String>)>), SectionError> {
10334 let table = self.schema.table(name).cloned().ok_or_else(|| {
10335 SectionError::Abort(
10336 "sync.schema_mismatch".to_owned(),
10337 format!("segment table {name:?} is not in the client schema"),
10338 )
10339 })?;
10340 let effective = covers(&table, &unit.scopes)
10341 .then(|| pair_scopes(&unit.scopes, name, Some(echo)))
10342 .flatten()
10343 .ok_or_else(|| {
10344 SectionError::Abort(
10345 "sync.invalid_request".to_owned(),
10346 "a segment names no active pair of its unit".to_owned(),
10347 )
10348 })?;
10349 let first_page = !seeded.contains(name);
10350 if first_page
10354 && unit
10355 .restriction
10356 .as_ref()
10357 .is_some_and(|restriction| !restriction.tables.iter().any(|t| t == name))
10358 {
10359 self.conn
10360 .execute(
10361 "UPDATE _syncular_units SET restriction=NULL WHERE id=?1",
10362 [&unit.id],
10363 )
10364 .map_err(|error| {
10365 SectionError::Abort(
10366 "storage.failed".to_owned(),
10367 Self::sqlite_failure(&self.storage_failure, error),
10368 )
10369 })?;
10370 }
10371 Ok((table, first_page, effective))
10372 }
10373
10374 fn finish_section(
10381 &mut self,
10382 start: &SectionStart,
10383 echo: Vec<EchoRecord>,
10384 next_cursor: i64,
10385 bootstrap_state: Option<String>,
10386 seeded: BTreeSet<String>,
10387 report: &mut SyncReport,
10388 ) -> Result<ChangeAccumulator, String> {
10389 #[cfg(feature = "bench-internals")]
10390 let _phase = self.benchmark_phases.start(Phase::CursorPersist);
10391 let mut batch = ChangeAccumulator::default();
10392 let Some(unit) = self
10394 .stored(get_unit(&self.conn, &start.id))?
10395 .filter(|unit| unit.status == UnitStatus::Active)
10396 else {
10397 return Ok(batch);
10398 };
10399 for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
10400 batch.window(&base_key, &value);
10401 }
10402 if start.status == SubStatus::Reset {
10403 report.resets.push(unit.id.clone());
10406 self.stored(save_unit(
10407 &self.conn,
10408 &UnitRecord {
10409 reason_code: Some(start.reason_code.clone()),
10410 cursor: Some(-1),
10411 bootstrap_state: None,
10412 seeded: Vec::new(),
10413 restriction: None,
10414 ..unit
10415 },
10416 ))?;
10417 return Ok(batch);
10418 }
10419 let revoked = start.status == SubStatus::Revoked;
10420 let mut units = None;
10421 let mut failed = false;
10422 let mut rearmed = false;
10423 for table in self.schema.tables.clone() {
10424 if !covers(&table, &unit.scopes) {
10425 continue;
10426 }
10427 let last = unit
10428 .echo
10429 .as_deref()
10430 .and_then(|last| pair_scopes(&unit.scopes, &table.name, Some(last)));
10431 let next = (!revoked)
10432 .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
10433 .flatten();
10434 rearmed |= unit.echo.is_some() && last.is_none() && next.is_some();
10436 if let (Some(last), None) = (&last, &next) {
10439 let units = match units {
10440 Some(ref units) => units,
10441 None => units.insert(self.stored(load_units(&self.conn))?),
10442 };
10443 let owners = unit_owners(units, &table, &unit.id);
10444 failed |= !self.purge_pair(&mut batch, &table, last, &owners)?;
10445 }
10446 }
10447 if revoked || failed {
10448 if revoked {
10449 report.revoked.push(unit.id.clone());
10450 }
10451 if failed {
10452 report.failed.push(unit.id.clone());
10453 }
10454 batch.status = true;
10455 self.stored(save_unit(
10456 &self.conn,
10457 &UnitRecord {
10458 status: if failed {
10459 UnitStatus::Failed
10460 } else {
10461 UnitStatus::Revoked
10462 },
10463 reason_code: Some(if failed {
10464 "sync.scope_revoked".to_owned()
10465 } else {
10466 start.reason_code.clone()
10467 }),
10468 cursor: Some(-1),
10469 bootstrap_state: None,
10470 seeded: Vec::new(),
10471 echo: None,
10472 restriction: None,
10473 ..unit
10474 },
10475 ))?;
10476 return Ok(batch);
10477 }
10478 let completed = start.bootstrap && !rearmed && bootstrap_state.is_none();
10479 let (cursor, bootstrap_state, seeded) = if rearmed {
10480 (Some(-1), None, Vec::new())
10481 } else if start.bootstrap {
10482 let seeded = if bootstrap_state.is_none() {
10483 Vec::new()
10484 } else {
10485 seeded.into_iter().collect()
10486 };
10487 (Some(next_cursor), bootstrap_state, seeded)
10488 } else {
10489 (
10490 unit.cursor,
10491 unit.bootstrap_state.clone(),
10492 unit.seeded.clone(),
10493 )
10494 };
10495 self.stored(save_unit(
10496 &self.conn,
10497 &UnitRecord {
10498 reason_code: None,
10499 echo: Some(echo.clone()),
10500 cursor,
10501 bootstrap_state,
10502 seeded,
10503 restriction: unit.restriction.clone().filter(|_| !rearmed && !completed),
10506 ..unit.clone()
10507 },
10508 ))?;
10509 if !completed {
10510 return Ok(batch);
10511 }
10512 for table in self.schema.tables.clone() {
10517 let Some(effective) = covers(&table, &unit.scopes)
10518 .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
10519 .flatten()
10520 else {
10521 continue;
10522 };
10523 let mut statement = self
10524 .conn
10525 .prepare("SELECT id,intent_json FROM _syncular_acked_rows WHERE tbl=?1 AND commit_seq<=?2")
10526 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10527 let rows = statement
10528 .query_map(rusqlite::params![table.name, next_cursor], |row| {
10529 Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
10530 })
10531 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10532 let mut covered = HashSet::new();
10533 for row in rows {
10534 let (id, intent) =
10535 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10536 let values: Map<String, Value> =
10537 serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
10538 let base = self.stored_row(&table, &id, true)?.map(|(row, _)| {
10539 table
10540 .columns
10541 .iter()
10542 .zip(&row)
10543 .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
10544 .collect()
10545 });
10546 if [Some(values), base]
10547 .iter()
10548 .flatten()
10549 .any(|values| owns_local_row(&table, &effective, &[], values))
10550 {
10551 covered.insert(id);
10552 }
10553 }
10554 drop(statement);
10555 for id in covered {
10556 self.conn
10557 .execute(
10558 "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3",
10559 rusqlite::params![table.name, id, next_cursor],
10560 )
10561 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10562 self.overlay_dirty.table(&table.name);
10563 batch.table(&table.name);
10564 }
10565 }
10566 Ok(batch)
10567 }
10568
10569 fn purge_pair(
10575 &mut self,
10576 batch: &mut ChangeAccumulator,
10577 table: &TableSchema,
10578 last: &[(String, Vec<String>)],
10579 owners: &[Vec<(String, Vec<String>)>],
10580 ) -> Result<bool, String> {
10581 if local_scope_predicate(table, last, owners).is_err() {
10582 return Ok(false);
10583 }
10584 for commit in self.drop_failed_commits(|name, values| {
10585 name == table.name && owns_local_row(table, last, owners, values)
10586 })? {
10587 batch.conflicts = true;
10588 batch.rejections = true;
10589 batch.outcomes = true;
10590 for operation in commit.ops {
10591 batch.table(&operation.table);
10592 }
10593 }
10594 if !self.purge_scope_rows(&table.name, last, owners)? {
10595 return Err("storage.failed: the revoked scope purge failed".to_owned());
10596 }
10597 self.record_scope_map(batch, &table.name, last);
10598 if self.drop_doomed_outbox(table, last, owners)? {
10599 batch.status = true;
10600 batch.rejections = true;
10601 batch.outcomes = true;
10602 }
10603 self.delete_unreferenced_cached_blobs()?;
10605 Ok(true)
10606 }
10607
10608 fn apply_live_commit(
10613 &mut self,
10614 receivers: &[UnitRecord],
10615 tables: &[String],
10616 changes: Vec<ssp2::model::Change>,
10617 commit_seq: i64,
10618 source: AppliedServerCommitSource,
10619 ) -> Result<bool, TransportError> {
10620 let changes: Vec<ssp2::model::Change> = changes
10621 .into_iter()
10622 .filter(|change| {
10623 let Some(table) = tables
10625 .get(change.table_index as usize)
10626 .and_then(|name| self.schema.table(name))
10627 else {
10628 return true;
10629 };
10630 receivers.iter().any(|unit| {
10631 covers(table, &unit.scopes)
10632 && pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()).is_some_and(
10633 |scopes| {
10634 scopes.iter().all(|(variable, values)| {
10635 change
10636 .scopes
10637 .iter()
10638 .find(|(key, _)| key == variable)
10639 .is_some_and(|(_, value)| values.contains(value))
10640 })
10641 },
10642 )
10643 })
10644 })
10645 .collect();
10646 if changes.is_empty() {
10647 return Ok(false);
10648 }
10649 let affected_tables = changes
10650 .iter()
10651 .filter_map(|change| tables.get(change.table_index as usize))
10652 .cloned()
10653 .collect::<BTreeSet<_>>();
10654 let previous_batches = self.change_queue.len();
10655 self.apply_commit_frame(tables, &changes, commit_seq)?;
10656 if self.change_queue.len() > previous_batches {
10657 if let Some(batch) = self.change_queue.back_mut() {
10658 batch
10659 .applied_commits
10660 .extend(
10661 affected_tables
10662 .into_iter()
10663 .map(|table| AppliedServerCommit {
10664 table,
10665 commit_seq,
10666 source,
10667 }),
10668 );
10669 }
10670 }
10671 Ok(true)
10672 }
10673
10674 fn apply_commit_frame(
10676 &mut self,
10677 tables: &[String],
10678 changes: &[ssp2::model::Change],
10679 sequence: i64,
10680 ) -> Result<(), TransportError> {
10681 #[cfg(feature = "bench-internals")]
10682 let _phase = self.benchmark_phases.start(Phase::CommitApply);
10683 let rollback = self.capture();
10684 self.coalesce_unit(changes.len())
10685 .and_then(|()| self.begin_observation("syncular_commit"))
10686 .map_err(|message| TransportError::new("storage.failed", message))?;
10687 let applied = (|| {
10688 let mut batch = ChangeAccumulator::default();
10689 self.record_commit_changes(&mut batch, tables, changes);
10690 for change in changes {
10693 let Some(table) = tables.get(change.table_index as usize) else {
10694 continue;
10695 };
10696 let acknowledged = self
10697 .conn
10698 .prepare_cached("SELECT op_json FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq=?3")
10699 .and_then(|mut statement| {
10700 statement
10701 .query_map(rusqlite::params![table, change.row_id, sequence], |row| row.get::<_, String>(0))?
10702 .collect::<Result<Vec<_>, _>>()
10703 })
10704 .map_err(|error| TransportError::new("storage.failed", Self::sqlite_failure(&self.storage_failure, error)))?
10705 .iter()
10706 .map(|op| serde_json::from_str::<CommitOperation>(op).map(OutboxOp::from))
10707 .collect::<Result<Vec<_>, _>>()
10708 .map_err(|_| TransportError::new("storage.failed", "sync.local_corrupt: invalid acknowledged operation".to_owned()))?;
10709 for index in 0..self.outbox.len() {
10710 if !self.outbox[index]
10711 .ops
10712 .iter()
10713 .any(|op| acknowledged.iter().any(|earlier| chains_on(earlier, op)))
10714 {
10715 continue;
10716 }
10717 let commit = Arc::make_mut(&mut self.outbox[index]);
10718 for op in &mut commit.ops {
10719 if acknowledged.iter().any(|earlier| chains_on(earlier, op)) {
10720 op.base_version = Some(change.row_version);
10721 }
10722 }
10723 let ops = serde_json::to_string(
10724 &commit
10725 .ops
10726 .iter()
10727 .map(CommitOperation::from)
10728 .collect::<Vec<_>>(),
10729 )
10730 .map_err(|_| {
10731 TransportError::new(
10732 "storage.failed",
10733 "sync.local_corrupt: unencodable outbox".to_owned(),
10734 )
10735 })?;
10736 let id = commit.client_commit_id.clone();
10737 self.conn
10738 .execute(
10739 "UPDATE _syncular_outbox SET ops_json=?1 WHERE commit_id=?2",
10740 rusqlite::params![ops, id],
10741 )
10742 .map_err(|error| {
10743 TransportError::new(
10744 "storage.failed",
10745 Self::sqlite_failure(&self.storage_failure, error),
10746 )
10747 })?;
10748 }
10749 }
10750 {
10751 let storage_failed = |error| {
10752 TransportError::new(
10753 "storage.failed",
10754 Self::sqlite_failure(&self.storage_failure, error),
10755 )
10756 };
10757 let pinned: HashSet<(&str, &str)> = self
10758 .outbox
10759 .iter()
10760 .flat_map(|commit| &commit.ops)
10761 .map(|op| (op.table.as_str(), op.row_id.as_str()))
10762 .collect();
10763 for change in changes {
10764 let table = tables.get(change.table_index as usize).ok_or_else(|| {
10765 TransportError::new(
10766 "sync.invalid_request",
10767 "change tableIndex out of range".to_owned(),
10768 )
10769 })?;
10770 if pinned.contains(&(table.as_str(), change.row_id.as_str())) {
10771 self.conn.prepare_cached("INSERT INTO _syncular_row_deliveries(tbl,id,commit_seq) VALUES (?1,?2,?3) ON CONFLICT(tbl,id) DO UPDATE SET commit_seq=MAX(commit_seq,excluded.commit_seq)")
10772 .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
10773 .map_err(storage_failed)?;
10774 }
10775 self.conn.prepare_cached("DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3")
10776 .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
10777 .map_err(storage_failed)?;
10778 }
10779 }
10780 self.apply_commit_changes(tables, changes)?;
10781 self.rebuild_overlay_if_dirty()
10782 .map_err(|message| TransportError::new("storage.failed", message))?;
10783 self.finish_observation("syncular_commit", batch)
10784 .map_err(|message| TransportError::new("storage.failed", message))
10785 })();
10786 if applied.is_err() {
10787 self.rollback_observation("syncular_commit");
10788 self.restore(rollback);
10789 }
10790 applied
10791 }
10792
10793 fn apply_commit_changes(
10794 &mut self,
10795 tables: &[String],
10796 changes: &[ssp2::model::Change],
10797 ) -> Result<(), TransportError> {
10798 let changed_tables: BTreeSet<&str> = changes
10803 .iter()
10804 .filter_map(|change| tables.get(change.table_index as usize))
10805 .map(String::as_str)
10806 .collect();
10807 let mut mirror_visible = !self.overlay_dirty.get();
10808 for name in &changed_tables {
10809 if mirror_visible
10810 && self
10811 .schema
10812 .table(name)
10813 .is_some_and(|table| table.indexes.iter().any(|index| index.unique))
10814 {
10815 let (pending, protected) = self
10816 .table_intent(name)
10817 .map_err(|message| TransportError::new("storage.failed", message))?;
10818 mirror_visible = !pending && !protected;
10819 }
10820 }
10821 for change in changes {
10822 let table_name = tables.get(change.table_index as usize).ok_or_else(|| {
10823 TransportError::new(
10824 "sync.invalid_request",
10825 "change tableIndex out of range".to_owned(),
10826 )
10827 })?;
10828 let table = self.schema.table(table_name).ok_or_else(|| {
10829 TransportError::new(
10830 "sync.schema_mismatch",
10831 format!("change targets unknown table {table_name:?}"),
10832 )
10833 })?;
10834 let landed = match change.op {
10835 Op::Upsert => {
10836 let payload = change.row.as_ref().ok_or_else(|| {
10837 TransportError::new(
10838 "sync.invalid_request",
10839 "upsert change without row payload".to_owned(),
10840 )
10841 })?;
10842 let (row, sealed) = {
10844 #[cfg(feature = "bench-internals")]
10845 let _phase = self.benchmark_phases.start(Phase::RowDecode);
10846 decode_row_bytes(table, payload, &self.encryption)?
10848 };
10849 let table_name = table.name.clone();
10850 let landed = self
10852 .write_base_row(&table_name, &row, change.row_version, sealed.as_ref())
10853 .map_err(|m| TransportError::new("sync.invalid_request", m))?;
10854 if mirror_visible && landed {
10855 self.write_row(
10856 &visible_table(&table_name),
10857 &table_name,
10858 &row,
10859 change.row_version,
10860 sealed.as_ref(),
10861 )
10862 .map_err(|m| TransportError::new("sync.invalid_request", m))?;
10863 }
10864 landed
10865 }
10866 Op::Delete => self
10869 .delete_base_row(table_name, &change.row_id, change.row_version)
10870 .map_err(|m| TransportError::new("sync.invalid_request", m))?,
10871 };
10872 self.overlay_dirty.table(table_name);
10876 if mirror_visible && !(landed && change.op == Op::Upsert) {
10877 let predicate = row_id_predicate(table);
10878 let visible = visible_table(table_name);
10879 let mut statements = vec![format!("DELETE FROM {visible} WHERE {predicate}")];
10880 if !landed {
10881 statements.push(format!(
10882 "INSERT INTO {visible} SELECT * FROM {} WHERE {predicate}",
10883 base_table(table_name)
10884 ));
10885 }
10886 for statement in &statements {
10887 self.conn
10888 .prepare_cached(statement)
10889 .and_then(|mut statement| {
10890 statement.execute(rusqlite::params![change.row_id])
10891 })
10892 .map_err(|error| {
10893 TransportError::new("sync.invalid_request", error.to_string())
10894 })?;
10895 }
10896 }
10897 }
10898 if mirror_visible {
10899 let changed_rows: HashSet<(&str, &str)> = changes
10900 .iter()
10901 .map(|change| {
10902 (
10903 tables[change.table_index as usize].as_str(),
10904 change.row_id.as_str(),
10905 )
10906 })
10907 .collect();
10908 self.replay_overlay(&changed_tables, Some(&changed_rows))
10909 .map_err(|message| TransportError::new("storage.failed", message))?;
10910 self.overlay_dirty.set(false);
10911 }
10912 Ok(())
10913 }
10914
10915 fn apply_segment(
10920 &mut self,
10921 table: &TableSchema,
10922 segment: &RowsSegment,
10923 first_page: bool,
10924 effective: &[(String, Vec<String>)],
10925 unit_id: &str,
10926 ) -> Result<u32, SectionError> {
10927 let column = if segment.columns.len() != table.wire_columns.len() {
10932 Some(Value::from("count"))
10933 } else {
10934 segment
10935 .columns
10936 .iter()
10937 .zip(table.wire_columns.iter())
10938 .position(|(a, b)| a.name != b.name || a.ty != b.ty || a.nullable != b.nullable)
10939 .map(Value::from)
10940 };
10941 if segment.table != table.name
10942 || segment.schema_version != self.schema.version
10943 || column.is_some()
10944 {
10945 let mut details = Map::new();
10946 details.insert("table".to_owned(), Value::from(table.name.as_str()));
10947 if let Some(column) = column {
10948 details.insert("column".to_owned(), column);
10949 }
10950 return Err(SectionError::Transport(TransportError {
10951 code: "sync.schema_mismatch".to_owned(),
10952 message: "rows segment columns do not match the generated schema (§5.2)".to_owned(),
10953 details: Some(Value::Object(details)),
10954 }));
10955 }
10956 let mut applied = 0u32;
10957 let (mut write, mut commit) = (std::time::Duration::ZERO, std::time::Duration::ZERO);
10958 let empty = Vec::new();
10959 let blocks = if segment.blocks.is_empty() {
10960 std::slice::from_ref(&empty)
10961 } else {
10962 &segment.blocks
10963 };
10964 for (index, block) in blocks.iter().enumerate() {
10965 let clear = first_page && index == 0;
10966 if !clear && block.is_empty() {
10967 continue;
10968 }
10969 let rollback = self.capture();
10970 let (pending, protected) = self
10971 .table_intent(&table.name)
10972 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10973 let reconcile_pending =
10974 !protected && pending && table.indexes.iter().any(|index| index.unique);
10975 let mirror_visible = !protected && !reconcile_pending;
10976 self.coalesce_unit(block.len())
10977 .and_then(|()| self.begin_observation("syncular_segment_block"))
10978 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10979 let started = std::time::Instant::now();
10980 let outcome = (|| {
10981 self.rebuild_overlay_if_dirty()
10982 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10983 let mut changed_keys = Vec::new();
10984 let mut batch = ChangeAccumulator::default();
10985 if clear && self.clear_scope(table, effective, unit_id)? || !block.is_empty() {
10986 batch.table(&table.name);
10987 }
10988 for (row_index, row) in block.iter().enumerate() {
10989 let decrypted;
10990 let mut sealed = None;
10991 let values = if table.has_encrypted_columns() {
10992 let mut values = row.values.clone();
10993 sealed = crate::values::decrypt_segment_row(
10994 table,
10995 &mut values,
10996 &self.encryption,
10997 )
10998 .map_err(SectionError::Transport)?;
10999 decrypted = values;
11000 &decrypted
11001 } else {
11002 &row.values
11003 };
11004 if !self
11005 .write_base_row(&table.name, values, row.server_version, sealed.as_ref())
11006 .map_err(|message| {
11007 SectionError::Abort("sync.invalid_request".into(), message)
11008 })?
11009 {
11010 continue;
11011 }
11012 if reconcile_pending {
11013 changed_keys.push(
11014 owned_sql_value(RowParam::Cell(&values[table.pk_index])).map_err(
11015 |message| SectionError::Abort("storage.failed".into(), message),
11016 )?,
11017 );
11018 }
11019 if mirror_visible {
11020 self.write_row(
11021 &visible_table(&table.name),
11022 &table.name,
11023 values,
11024 row.server_version,
11025 sealed.as_ref(),
11026 )
11027 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11028 }
11029 let processed = u64::from(applied) + row_index as u64 + 1;
11030 if processed.is_multiple_of(1024) {
11031 self.progress.update(|p| p.rows_processed = processed);
11032 }
11033 }
11034 self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
11035 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11036 let written = std::time::Instant::now();
11037 self.finish_observation("syncular_segment_block", batch)
11038 .map(|()| written)
11039 .map_err(|message| SectionError::Abort("storage.failed".into(), message))
11040 })();
11041 let written = match outcome {
11042 Ok(written) => written,
11043 Err(error) => {
11044 self.rollback_observation("syncular_segment_block");
11045 self.restore(rollback);
11046 return Err(error);
11047 }
11048 };
11049 write += written - started;
11051 commit += written.elapsed();
11052 applied += block.len() as u32;
11053 self.progress.update(|p| {
11054 p.rows_processed = u64::from(applied);
11055 p.import_write_ms = u64::try_from(write.as_millis()).ok();
11056 p.import_commit_ms = u64::try_from(commit.as_millis()).ok();
11057 });
11058 std::thread::yield_now();
11059 }
11060 self.progress
11061 .update(|p| p.rows_processed = u64::from(applied));
11062 Ok(applied)
11063 }
11064
11065 #[allow(clippy::too_many_arguments)]
11073 fn apply_sqlite_segment(
11074 &mut self,
11075 table: &TableSchema,
11076 bytes: &[u8],
11077 first_page: bool,
11078 effective: &[(String, Vec<String>)],
11079 unit_id: &str,
11080 segment_id: &str,
11081 resumed: i64,
11082 row_count: i64,
11083 as_of_commit_seq: i64,
11084 scope_digest: &str,
11085 ) -> Result<u32, SectionError> {
11086 let invalid = |detail: &str| {
11087 SectionError::Abort(
11088 "sync.invalid_request".to_owned(),
11089 format!("sqlite segment rejected: {detail} (§5.3)"),
11090 )
11091 };
11092 if table.has_encrypted_columns() {
11095 return Err(invalid("table has encrypted columns"));
11096 }
11097
11098 let directory = self
11102 .previous_version_replica_path()
11103 .and_then(|replica| std::path::Path::new(&replica).parent().map(Into::into))
11104 .unwrap_or_else(std::env::temp_dir);
11105 let path = directory.join(format!(".syncular-image-{}.tmp", uuid::Uuid::new_v4()));
11106 let outcome = (|| {
11107 let mut options = std::fs::OpenOptions::new();
11108 options.write(true).create_new(true);
11109 #[cfg(unix)]
11110 std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600);
11111 std::io::Write::write_all(
11112 &mut options
11113 .open(&path)
11114 .map_err(|_| invalid("image temp file write failed"))?,
11115 bytes,
11116 )
11117 .map_err(|_| invalid("image temp file write failed"))?;
11118 let img = rusqlite::Connection::open_with_flags(
11119 &path,
11120 rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY,
11121 )
11122 .map_err(|_| invalid("bytes do not open as a SQLite database"))?;
11123 self.apply_sqlite_image(
11124 &img,
11125 table,
11126 first_page,
11127 effective,
11128 unit_id,
11129 segment_id,
11130 resumed,
11131 row_count,
11132 as_of_commit_seq,
11133 scope_digest,
11134 )
11135 })();
11136 let _ = std::fs::remove_file(&path);
11137 outcome
11138 }
11139
11140 #[allow(clippy::too_many_arguments)]
11141 fn apply_sqlite_image(
11142 &mut self,
11143 img: &rusqlite::Connection,
11144 table: &crate::schema::TableSchema,
11145 first_fresh_page: bool,
11146 effective: &[(String, Vec<String>)],
11147 unit_id: &str,
11148 segment_id: &str,
11149 resumed: i64,
11150 row_count: i64,
11151 as_of_commit_seq: i64,
11152 scope_digest: &str,
11153 ) -> Result<u32, SectionError> {
11154 let invalid = |detail: String| {
11155 SectionError::Abort(
11156 "sync.invalid_request".to_owned(),
11157 format!("sqlite segment rejected: {detail} (§5.3)"),
11158 )
11159 };
11160
11161 type MetaRow = (i64, String, i64, i64, String, i64, i64);
11164 let meta: MetaRow = img
11165 .query_row(
11166 "SELECT format, \"table\", \"schemaVersion\", \"asOfCommitSeq\",
11167 \"scopeDigest\", \"rowCount\",
11168 (SELECT count(*) FROM _syncular_segment)
11169 FROM _syncular_segment",
11170 [],
11171 |row| {
11172 Ok((
11173 row.get(0)?,
11174 row.get(1)?,
11175 row.get(2)?,
11176 row.get(3)?,
11177 row.get(4)?,
11178 row.get(5)?,
11179 row.get(6)?,
11180 ))
11181 },
11182 )
11183 .map_err(|_| invalid("missing or unreadable _syncular_segment metadata".to_owned()))?;
11184 let (format, meta_table, schema_version, pin, digest, meta_rows, meta_count) = meta;
11185 if meta_count != 1 {
11186 return Err(invalid(format!(
11187 "_syncular_segment must contain exactly one row, found {meta_count}"
11188 )));
11189 }
11190 if format != 1 {
11191 return Err(invalid(format!("format {format}")));
11192 }
11193 if meta_table != table.name {
11194 return Err(invalid(format!("image table {meta_table:?}")));
11195 }
11196 if schema_version != i64::from(self.schema.version) {
11197 return Err(invalid(format!("schemaVersion {schema_version}")));
11198 }
11199 if pin != as_of_commit_seq {
11200 return Err(invalid(format!("asOfCommitSeq {pin}")));
11201 }
11202 if digest != scope_digest {
11203 return Err(invalid("scopeDigest mismatch".to_owned()));
11204 }
11205 if meta_rows != row_count {
11206 return Err(invalid(format!("rowCount {meta_rows}")));
11207 }
11208
11209 let mut names: Vec<String> = Vec::new();
11211 let mut primary_keys: Vec<String> = Vec::new();
11212 {
11213 let mut stmt = img
11214 .prepare(&format!("PRAGMA table_info({})", quote_ident(&table.name)))
11215 .map_err(|_| invalid("image data table missing".to_owned()))?;
11216 let mut rows = stmt
11217 .query([])
11218 .map_err(|_| invalid("image data table unreadable".to_owned()))?;
11219 while let Some(row) = rows
11220 .next()
11221 .map_err(|_| invalid("image data table unreadable".to_owned()))?
11222 {
11223 if row
11224 .get::<_, i64>(5)
11225 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?
11226 > 0
11227 {
11228 primary_keys.push(row.get(1).map_err(|error| {
11229 invalid(Self::sqlite_failure(&self.storage_failure, error))
11230 })?);
11231 }
11232 names.push(
11233 row.get::<_, String>(1)
11234 .map_err(|_| invalid("image data table unreadable".to_owned()))?,
11235 );
11236 }
11237 }
11238 let mut expected: Vec<&str> = table.columns.iter().map(|c| c.name.as_str()).collect();
11239 expected.push("_syncular_version");
11240 if names.len() != expected.len() || names.iter().zip(expected.iter()).any(|(a, b)| a != b) {
11241 return Err(SectionError::Transport(TransportError {
11242 code: "sync.schema_mismatch".to_owned(),
11243 message: "sqlite segment columns do not match the generated schema (§5.3)"
11244 .to_owned(),
11245 details: Some(serde_json::json!({ "table": table.name })),
11246 }));
11247 }
11248
11249 if primary_keys != vec![table.primary_key.clone()] {
11250 return Err(invalid(
11251 "image primary key does not match generated schema".into(),
11252 ));
11253 }
11254 let actual_count: i64 = img
11255 .query_row(
11256 &format!("SELECT count(*) FROM {}", quote_ident(&table.name)),
11257 [],
11258 |row| row.get(0),
11259 )
11260 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
11261 if actual_count != row_count {
11262 return Err(invalid("image row count does not match descriptor".into()));
11263 }
11264 let insert = self.insert_row_sql(&base_table(&table.name), table);
11265 let visible_insert = self.insert_row_sql(&visible_table(&table.name), table);
11266 let column_list = names
11267 .iter()
11268 .map(|n| quote_ident(n))
11269 .collect::<Vec<_>>()
11270 .join(", ");
11271 let mut stmt = img
11274 .prepare(&format!(
11275 "SELECT {column_list} FROM {} ORDER BY {} LIMIT -1 OFFSET ?1",
11276 quote_ident(&table.name),
11277 quote_ident(&table.primary_key)
11278 ))
11279 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
11280 let mut rows = stmt
11281 .query([resumed])
11282 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
11283 let resumed = u32::try_from(resumed)
11284 .ok()
11285 .filter(|rows| i64::from(*rows) <= actual_count)
11286 .ok_or_else(|| invalid("applied-segment record exceeds the image".into()))?;
11287 let mut applied = resumed;
11288 let mut limit = if first_fresh_page {
11289 1024
11290 } else {
11291 self.image_chunk_rows
11292 .get(&table.name)
11293 .copied()
11294 .unwrap_or(1024)
11295 };
11296 let (mut write, mut commit) = (std::time::Duration::ZERO, std::time::Duration::ZERO);
11297 loop {
11298 let clear = applied == 0 && first_fresh_page;
11299 let rollback = self.capture();
11300 let (pending, protected) = self
11301 .table_intent(&table.name)
11302 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11303 let reconcile_pending =
11304 !protected && pending && table.indexes.iter().any(|index| index.unique);
11305 let mirror_visible = !protected && !reconcile_pending;
11306 let chunk = if pending || protected {
11313 limit.min(1024)
11314 } else {
11315 limit
11316 };
11317 self.coalesce_unit(chunk as usize)
11318 .and_then(|()| self.begin_observation("syncular_image_chunk"))
11319 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11320 let started = std::time::Instant::now();
11321 let result = (|| {
11322 self.rebuild_overlay_if_dirty()
11323 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11324 let mut changed_keys = Vec::new();
11325 let mut batch = ChangeAccumulator::default();
11326 if clear && self.clear_scope(table, effective, unit_id)? {
11327 batch.table(&table.name);
11328 }
11329 let mut processed = 0u32;
11330 {
11331 let mut ins = self.conn.prepare_cached(&insert).map_err(|error| {
11332 invalid(Self::sqlite_failure(&self.storage_failure, error))
11333 })?;
11334 let mut mirror = if mirror_visible {
11335 Some(self.conn.prepare_cached(&visible_insert).map_err(|error| {
11336 invalid(Self::sqlite_failure(&self.storage_failure, error))
11337 })?)
11338 } else {
11339 None
11340 };
11341 for _ in 0..chunk {
11342 let Some(row) = rows.next().map_err(|error| {
11343 invalid(Self::sqlite_failure(&self.storage_failure, error))
11344 })?
11345 else {
11346 break;
11347 };
11348 for (i, column) in table.columns.iter().enumerate() {
11349 let cell = row.get_ref(i).map_err(|error| {
11350 invalid(Self::sqlite_failure(&self.storage_failure, error))
11351 })?;
11352 let param = image_cell_param(column, cell).map_err(invalid)?;
11353 ins.raw_bind_parameter(i + 1, ¶m).map_err(|error| {
11354 invalid(Self::sqlite_failure(&self.storage_failure, error))
11355 })?;
11356 if let Some(mirror) = &mut mirror {
11357 mirror.raw_bind_parameter(i + 1, ¶m).map_err(|error| {
11358 invalid(Self::sqlite_failure(&self.storage_failure, error))
11359 })?;
11360 }
11361 }
11362 let version_index = table.columns.len();
11363 let version: i64 = row.get(version_index).map_err(|error| {
11364 invalid(Self::sqlite_failure(&self.storage_failure, error))
11365 })?;
11366 if version < 1 {
11367 return Err(invalid("image row version must be positive".into()));
11368 }
11369 ins.raw_bind_parameter(version_index + 1, version)
11370 .map_err(|error| {
11371 invalid(Self::sqlite_failure(&self.storage_failure, error))
11372 })?;
11373 let landed = ins.raw_execute().map_err(|error| {
11375 invalid(Self::sqlite_failure(&self.storage_failure, error))
11376 })? > 0;
11377 processed += 1;
11378 if processed.is_multiple_of(1024) && processed < chunk {
11379 self.progress
11380 .update(|p| p.rows_processed = u64::from(applied + processed));
11381 }
11382 if !landed {
11383 continue;
11384 }
11385 if let Some(mirror) = &mut mirror {
11386 mirror
11387 .raw_bind_parameter(version_index + 1, version)
11388 .map_err(|error| {
11389 invalid(Self::sqlite_failure(&self.storage_failure, error))
11390 })?;
11391 mirror.raw_execute().map_err(|error| {
11392 invalid(Self::sqlite_failure(&self.storage_failure, error))
11393 })?;
11394 }
11395 if reconcile_pending {
11396 changed_keys.push(row.get::<_, SqlValue>(table.pk_index).map_err(
11397 |error| invalid(Self::sqlite_failure(&self.storage_failure, error)),
11398 )?);
11399 }
11400 }
11401 }
11402 if processed > 0 {
11403 batch.table(&table.name);
11404 self.overlay_dirty.table(&table.name);
11405 }
11406 self.stored(record_applied_rows(
11407 &self.conn,
11408 unit_id,
11409 segment_id,
11410 i64::from(applied + processed),
11411 ))
11412 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11413 self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
11414 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11415 let written = std::time::Instant::now();
11416 self.finish_observation("syncular_image_chunk", batch)
11417 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11418 Ok((processed, written))
11419 })();
11420 let (processed, written) = match result {
11421 Ok(done) => done,
11422 Err(error) => {
11423 self.rollback_observation("syncular_image_chunk");
11424 self.restore(rollback);
11425 return Err(error);
11426 }
11427 };
11428 let coalesced = self.coalesced.is_some();
11430 if coalesced {
11431 self.commit_coalesced_apply()
11432 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11433 }
11434 write += written - started;
11435 commit += written.elapsed();
11436 applied += processed;
11437 let last = processed < chunk || i64::from(applied) == actual_count;
11438 if last && self.conn.is_autocommit() {
11440 self.conn
11441 .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
11442 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
11443 }
11444 if coalesced {
11445 self.begin_coalesced_apply()
11446 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11447 }
11448 self.progress.update(|p| {
11449 p.rows_processed = u64::from(applied);
11450 p.import_write_ms = u64::try_from(write.as_millis()).ok();
11451 p.import_commit_ms = u64::try_from(commit.as_millis()).ok();
11452 });
11453 let duration = started.elapsed().as_secs_f64() * 1000.0;
11454 #[cfg(test)]
11455 let duration = self.image_chunk_ms.get().unwrap_or(duration);
11456 std::thread::yield_now();
11457 if last {
11458 break;
11459 }
11460 limit = (processed * 2)
11462 .min(65_536)
11463 .min((f64::from(processed) * 250.0 / duration) as u32)
11464 .max(1024);
11465 self.image_chunk_rows.insert(table.name.clone(), limit);
11466 }
11467 if i64::from(applied) != actual_count {
11468 return Err(invalid(format!(
11469 "image yielded {applied} rows, expected {actual_count}"
11470 )));
11471 }
11472 Ok(applied - resumed)
11473 }
11474
11475 fn reconcile_rows(&self, drained: &[Arc<OutboxCommit>]) -> Result<(), String> {
11480 let names: BTreeSet<&str> = drained
11481 .iter()
11482 .flat_map(|commit| &commit.ops)
11483 .map(|op| op.table.as_str())
11484 .collect();
11485 for name in names {
11486 let Some(table) = self.schema.table(name) else {
11487 continue;
11488 };
11489 let ops = drained.iter().flat_map(|commit| &commit.ops);
11490 let tables = BTreeSet::from([name]);
11491 let rows: HashSet<_> = ops
11492 .clone()
11493 .map(|op| (op.table.as_str(), op.row_id.as_str()))
11494 .collect();
11495 let unique = table.indexes.iter().any(|index| index.unique);
11496 let acknowledged = if unique {
11497 self.acknowledged_operations(None, Some(&tables))?
11498 } else {
11499 Vec::new()
11500 };
11501 let peers = acknowledged
11502 .iter()
11503 .chain(
11504 self.failed_commits
11505 .iter()
11506 .flat_map(|(commit, _)| &commit.ops),
11507 )
11508 .chain(self.outbox.iter().flat_map(|commit| &commit.ops))
11509 .filter(|_| unique);
11510 self.restore_base_rows(table, &mut Vec::new(), peers.chain(ops.clone()))?;
11511 self.replay_overlay(&tables, (!unique).then_some(&rows))?;
11512 }
11513 Ok(())
11514 }
11515
11516 fn table_intent(&self, table: &str) -> Result<(bool, bool), String> {
11519 let touches = |op: &OutboxOp| op.table == table;
11520 Ok((
11521 self.outbox
11522 .iter()
11523 .flat_map(|commit| &commit.ops)
11524 .any(touches),
11525 self.failed_commits
11526 .iter()
11527 .flat_map(|(commit, _)| &commit.ops)
11528 .any(touches)
11529 || self
11530 .conn
11531 .query_row(
11532 "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows WHERE tbl=?1)",
11533 [table],
11534 |row| row.get(0),
11535 )
11536 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
11537 ))
11538 }
11539
11540 fn reconcile_import(
11544 &mut self,
11545 table: &TableSchema,
11546 keys: &mut Vec<SqlValue>,
11547 protected: bool,
11548 restore: bool,
11549 ) -> Result<(), String> {
11550 if protected {
11551 return self.rebuild_overlay_if_dirty();
11552 }
11553 let pending = self.outbox.iter().flat_map(|commit| &commit.ops);
11554 if restore {
11555 self.restore_base_rows(table, keys, pending.clone())?;
11556 }
11557 self.apply_outbox_ops(pending.filter(|op| op.table == table.name))?;
11558 self.overlay_dirty.set(false);
11559 Ok(())
11560 }
11561
11562 fn restore_base_rows<'a>(
11566 &self,
11567 table: &TableSchema,
11568 keys: &mut Vec<SqlValue>,
11569 ops: impl IntoIterator<Item = &'a OutboxOp>,
11570 ) -> Result<(), String> {
11571 let visible = visible_table(&table.name);
11572 let base = base_table(&table.name);
11573 let pk = quote_ident(&table.primary_key);
11574 let predicate = row_id_predicate(table);
11575 let mut lookup = self.conn.prepare_cached(&format!(
11576 "SELECT {pk} FROM {base} WHERE {predicate} UNION SELECT {pk} FROM {visible} WHERE {predicate}"
11577 )).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11578 let mut deleted = HashSet::new();
11579 for op in ops.into_iter().filter(|op| op.table == table.name) {
11580 if op.upsert {
11581 if let Some(values) = &op.values {
11582 let key = json_to_column_value(
11583 &table.columns[table.pk_index],
11584 values.get(&table.primary_key),
11585 )?;
11586 keys.push(owned_sql_value(RowParam::Cell(&key))?);
11587 }
11588 } else if deleted.insert(&op.row_id) {
11589 keys.extend(
11590 lookup
11591 .query_map([&op.row_id], |row| row.get::<_, SqlValue>(0))
11592 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11593 .collect::<Result<Vec<_>, _>>()
11594 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
11595 );
11596 }
11597 }
11598 for chunk in keys.chunks(400) {
11601 let holes = vec!["?"; chunk.len()].join(",");
11602 self.conn
11603 .prepare_cached(&format!("DELETE FROM {visible} WHERE {pk} IN ({holes})"))
11604 .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
11605 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11606 }
11607 let updates = table
11608 .columns
11609 .iter()
11610 .map(|column| column.name.as_str())
11611 .chain(std::iter::once("_syncular_version"))
11612 .chain(table.sealed_columns().iter().copied())
11613 .filter(|name| *name != table.primary_key)
11614 .map(|name| {
11615 let name = quote_ident(name);
11616 format!("{name}=excluded.{name}")
11617 })
11618 .collect::<Vec<_>>()
11619 .join(",");
11620 for chunk in keys.chunks(400) {
11621 let holes = vec!["?"; chunk.len()].join(",");
11622 self.conn.prepare_cached(&format!("INSERT INTO {visible} SELECT * FROM {base} WHERE {pk} IN ({holes}) ON CONFLICT ({pk}) DO UPDATE SET {updates}"))
11623 .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
11624 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11625 }
11626 Ok(())
11627 }
11628
11629 fn compile_local_data_purge(
11632 &self,
11633 input: &LocalDataPurgeInput,
11634 ) -> Result<(Vec<CompiledLocalDataPurgeTarget>, String), String> {
11635 let invalid = |message: String| format!("sync.invalid_request: {message}");
11636 if input.purge_id.is_empty()
11637 || input.purge_id.len() > 128
11638 || !is_local_operation_code_like(&input.purge_id)
11639 {
11640 return Err(invalid(
11641 "local purge purgeId must be a 1–128 character code-like identifier".to_owned(),
11642 ));
11643 }
11644 if input.targets.is_empty() || input.targets.len() > MAX_LOCAL_PURGE_TARGETS {
11645 return Err(invalid(format!(
11646 "local purge needs between 1 and {MAX_LOCAL_PURGE_TARGETS} targets"
11647 )));
11648 }
11649
11650 let mut deduplicated: BTreeMap<
11651 String,
11652 (CompiledLocalDataPurgeTarget, LocalDataPurgeTarget),
11653 > = BTreeMap::new();
11654 for target in &input.targets {
11655 let table = self.schema.table(&target.table).ok_or_else(|| {
11656 invalid(format!(
11657 "local purge names unknown table {:?}",
11658 target.table
11659 ))
11660 })?;
11661 if target.selectors.is_empty() || target.selectors.len() > MAX_LOCAL_PURGE_SELECTORS {
11662 return Err(invalid(format!(
11663 "local purge target {:?} needs between 1 and {MAX_LOCAL_PURGE_SELECTORS} selectors",
11664 target.table
11665 )));
11666 }
11667 let mut selectors = Vec::with_capacity(target.selectors.len());
11668 let mut canonical_selectors = BTreeMap::new();
11669 for (column_name, raw_values) in &target.selectors {
11670 let Some((column_index, column)) = table
11671 .columns
11672 .iter()
11673 .enumerate()
11674 .find(|(_, column)| column.name == *column_name)
11675 else {
11676 return Err(invalid(format!(
11677 "local purge target {:?} names unknown column {:?}",
11678 target.table, column_name
11679 )));
11680 };
11681 let encrypted = table
11682 .encrypted_columns
11683 .iter()
11684 .any(|candidate| candidate.index == column_index);
11685 if column.ty != ColumnType::String || encrypted {
11686 return Err(invalid(format!(
11687 "local purge selector {:?}.{:?} must be a plaintext string column",
11688 target.table, column_name
11689 )));
11690 }
11691 if raw_values.is_empty() || raw_values.len() > MAX_LOCAL_PURGE_VALUES {
11692 return Err(invalid(format!(
11693 "local purge selector {:?}.{:?} needs between 1 and {MAX_LOCAL_PURGE_VALUES} values",
11694 target.table, column_name
11695 )));
11696 }
11697 let mut values = raw_values.clone();
11698 values.sort();
11699 values.dedup();
11700 if values.iter().any(|value| {
11701 value.is_empty()
11702 || value.len() > MAX_LOCAL_PURGE_VALUE_LENGTH
11703 || !is_local_operation_code_like(value)
11704 }) {
11705 return Err(invalid(format!(
11706 "local purge selector values must be 1–{MAX_LOCAL_PURGE_VALUE_LENGTH} character code-like identifiers"
11707 )));
11708 }
11709 selectors.push((column_name.clone(), values.clone()));
11710 canonical_selectors.insert(column_name.clone(), values);
11711 }
11712 let canonical = LocalDataPurgeTarget {
11713 table: target.table.clone(),
11714 selectors: canonical_selectors,
11715 };
11716 let key = serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
11717 deduplicated.insert(
11718 key,
11719 (
11720 CompiledLocalDataPurgeTarget {
11721 table: target.table.clone(),
11722 selectors,
11723 },
11724 canonical,
11725 ),
11726 );
11727 }
11728 let targets = deduplicated
11729 .values()
11730 .map(|(compiled, _)| compiled.clone())
11731 .collect::<Vec<_>>();
11732 let canonical = deduplicated
11733 .values()
11734 .map(|(_, target)| target.clone())
11735 .collect::<Vec<_>>();
11736 let canonical_plan =
11737 serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
11738 Ok((targets, canonical_plan))
11739 }
11740
11741 fn local_purge_base_row_ids(
11742 &self,
11743 targets: &[CompiledLocalDataPurgeTarget],
11744 ) -> Result<BTreeMap<String, BTreeSet<String>>, String> {
11745 let mut by_table: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
11746 for target in targets {
11747 let table = self
11748 .schema
11749 .table(&target.table)
11750 .ok_or_else(|| format!("sync.invalid_request: unknown table {:?}", target.table))?;
11751 let mut clauses = Vec::with_capacity(target.selectors.len());
11752 let mut params = Vec::new();
11753 for (column, values) in &target.selectors {
11754 clauses.push(format!(
11755 "{} IN ({})",
11756 quote_ident(column),
11757 values.iter().map(|_| "?").collect::<Vec<_>>().join(", ")
11758 ));
11759 params.extend(values.iter().cloned().map(SqlValue::Text));
11760 }
11761 let sql = format!(
11762 "SELECT CAST({} AS TEXT) FROM {} WHERE {}",
11763 quote_ident(&table.primary_key),
11764 base_table(&target.table),
11765 clauses.join(" AND ")
11766 );
11767 let mut statement = self
11768 .conn
11769 .prepare(&sql)
11770 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11771 let rows = statement
11772 .query_map(rusqlite::params_from_iter(params), |row| {
11773 let value = sql_ref_to_json(&table.columns[table.pk_index], row.get_ref(0)?);
11774 render_row_id_json(Some(&value))
11775 .map_err(|message| rusqlite::Error::ToSqlConversionFailure(message.into()))
11776 })
11777 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11778 let ids = by_table.entry(target.table.clone()).or_default();
11779 for row in rows {
11780 ids.insert(
11781 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
11782 );
11783 }
11784 }
11785 Ok(by_table)
11786 }
11787
11788 fn local_purge_values_match(
11789 target: &CompiledLocalDataPurgeTarget,
11790 values: &Map<String, Value>,
11791 ) -> bool {
11792 target.selectors.iter().all(|(column, allowed)| {
11793 values
11794 .get(column)
11795 .and_then(Value::as_str)
11796 .is_some_and(|value| allowed.iter().any(|candidate| candidate == value))
11797 })
11798 }
11799
11800 pub fn purge_local_data(
11804 &mut self,
11805 input: &LocalDataPurgeInput,
11806 ) -> Result<LocalDataPurgeResult, String> {
11807 let (targets, canonical_plan) = self.compile_local_data_purge(input)?;
11808 let meta_key = format!("localPurge:{}", input.purge_id);
11809 let applied_plan = self
11810 .conn
11811 .query_row(
11812 "SELECT value FROM _syncular_meta WHERE key = ?1",
11813 rusqlite::params![meta_key],
11814 |row| row.get::<_, String>(0),
11815 )
11816 .optional()
11817 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11818 if let Some(applied_plan) = applied_plan {
11819 if applied_plan != canonical_plan {
11820 return Err(format!(
11821 "sync.invalid_request: local purge id {:?} was already used with a different plan",
11822 input.purge_id
11823 ));
11824 }
11825 self.erase_purged_pages()?;
11827 return Ok(LocalDataPurgeResult {
11828 already_applied: true,
11829 purged_rows: 0,
11830 dropped_commits: 0,
11831 });
11832 }
11833
11834 let _ = self.drop_previous_version();
11838
11839 let rollback = self.capture();
11840 self.begin_observation("syncular_local_purge")?;
11841 let applied = (|| -> Result<(ChangeAccumulator, LocalDataPurgeResult), String> {
11842 let row_ids = self.local_purge_base_row_ids(&targets)?;
11843 let retained_dropped = self.drop_failed_commits(|table, values| {
11844 targets.iter().any(|target| {
11845 target.table == table && Self::local_purge_values_match(target, values)
11846 })
11847 })?;
11848 let doomed = self
11849 .outbox
11850 .iter()
11851 .filter(|commit| {
11852 commit.ops.iter().any(|operation| {
11853 let matching_targets = targets
11854 .iter()
11855 .filter(|target| target.table == operation.table)
11856 .collect::<Vec<_>>();
11857 if matching_targets.is_empty() {
11858 return false;
11859 }
11860 if row_ids
11861 .get(&operation.table)
11862 .is_some_and(|ids| ids.contains(&operation.row_id))
11863 {
11864 return true;
11865 }
11866 operation.values.as_ref().is_some_and(|values| {
11867 matching_targets
11868 .iter()
11869 .any(|target| Self::local_purge_values_match(target, values))
11870 })
11871 })
11872 })
11873 .cloned()
11874 .collect::<Vec<_>>();
11875 let doomed_ids = doomed
11876 .iter()
11877 .map(|commit| commit.client_commit_id.clone())
11878 .collect::<BTreeSet<_>>();
11879 let mut batch = ChangeAccumulator::default();
11880 for commit in &retained_dropped {
11881 batch.conflicts = true;
11882 batch.rejections = true;
11883 batch.outcomes = true;
11884 for operation in &commit.ops {
11885 batch.table(&operation.table);
11886 }
11887 }
11888 let mut rejections = Vec::new();
11889 for commit in &doomed {
11892 for operation in &commit.ops {
11893 batch.table(&operation.table);
11894 self.overlay_dirty.table(&operation.table);
11895 }
11896 let results = (0..commit.ops.len())
11897 .map(|op_index| {
11898 let rejection = RejectionRecord {
11899 client_commit_id: commit.client_commit_id.clone(),
11900 op_index: op_index as i32,
11901 code: "client.local_data_purged".to_owned(),
11902 message: "the commit was dropped by an application-authorized local data purge".to_owned(),
11903 retryable: false,
11904 details: None,
11905 operation: None,
11906 };
11907 rejections.push(rejection.clone());
11908 CommitOperationOutcome::Error { rejection }
11909 })
11910 .collect::<Vec<_>>();
11911 self.persist_commit_outcome(
11912 &commit.client_commit_id,
11913 CommitOutcomeStatus::Rejected,
11914 &results,
11915 None,
11916 )?;
11917 self.delete_outbox_persisted(&commit.client_commit_id)?;
11918 }
11919 if !doomed.is_empty() {
11920 self.outbox
11921 .retain(|commit| !doomed_ids.contains(&commit.client_commit_id));
11922 self.rejections.extend(rejections);
11923 self.prune_commit_outcomes()?;
11924 batch.status = true;
11925 batch.rejections = true;
11926 batch.outcomes = true;
11927 }
11928
11929 let mut purged_rows = 0usize;
11930 for (table, ids) in &row_ids {
11931 if ids.is_empty() {
11932 continue;
11933 }
11934 batch.table(table);
11935 self.overlay_dirty.table(table);
11936 for row_id in ids {
11937 self.delete_base_row(table, row_id, i64::MAX)?;
11938 purged_rows += 1;
11939 }
11940 }
11941 let touches = |table: &str, row_id: &str, values: Option<&Map<String, Value>>| {
11945 targets.iter().any(|target| {
11946 target.table == table
11947 && (row_ids.get(table).is_some_and(|ids| ids.contains(row_id))
11948 || values.is_some_and(|values| {
11949 Self::local_purge_values_match(target, values)
11950 }))
11951 })
11952 };
11953 let entries = self
11954 .conn
11955 .prepare("SELECT client_commit_id, results_json, operations_json FROM _syncular_commit_outcomes")
11956 .and_then(|mut statement| {
11957 statement
11958 .query_map([], |row| {
11959 Ok((
11960 row.get::<_, String>(0)?,
11961 row.get::<_, String>(1)?,
11962 row.get::<_, Option<String>>(2)?,
11963 ))
11964 })?
11965 .collect::<Result<Vec<_>, _>>()
11966 })
11967 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11968 for (client_commit_id, results_json, operations_json) in entries {
11969 let corrupt = |_| "sync.local_corrupt: persisted commit outcome is invalid".to_owned();
11970 let mut results: Vec<CommitOperationOutcome> =
11971 serde_json::from_str(&results_json).map_err(corrupt)?;
11972 let operations: Vec<CommitOperation> = operations_json
11973 .map(|json| serde_json::from_str(&json))
11974 .transpose()
11975 .map_err(corrupt)?
11976 .unwrap_or_default();
11977 let named = operations
11978 .iter()
11979 .chain(results.iter().filter_map(|result| match result {
11980 CommitOperationOutcome::Conflict { conflict } => conflict.operation.as_ref(),
11981 CommitOperationOutcome::Error { rejection } => rejection.operation.as_ref(),
11982 CommitOperationOutcome::Applied { .. } => None,
11983 }))
11984 .any(|operation| touches(&operation.table, &operation.row_id, operation.values.as_ref()))
11985 || results.iter().any(|result| {
11986 matches!(result, CommitOperationOutcome::Conflict { conflict }
11987 if touches(&conflict.table, &conflict.row_id, Some(&conflict.server_row)))
11988 });
11989 if !named {
11990 continue;
11991 }
11992 for result in &mut results {
11993 match result {
11994 CommitOperationOutcome::Conflict { conflict } => {
11995 conflict.server_row = Map::new();
11996 conflict.conflict_columns.clear();
11997 conflict.operation = None;
11998 }
11999 CommitOperationOutcome::Error { rejection } => {
12000 rejection.details = None;
12001 rejection.operation = None;
12002 }
12003 CommitOperationOutcome::Applied { .. } => {}
12004 }
12005 }
12006 let results_json = serde_json::to_string(&results).map_err(|error| error.to_string())?;
12007 self.conn
12008 .execute(
12009 "UPDATE _syncular_commit_outcomes SET results_json = ?1, operations_json = NULL WHERE client_commit_id = ?2",
12010 rusqlite::params![results_json, client_commit_id],
12011 )
12012 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12013 batch.outcomes = true;
12014 }
12015 self.rebuild_overlay_if_dirty()?;
12016 self.delete_unreferenced_cached_blobs()?;
12017 self.conn
12018 .execute(
12019 "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
12020 rusqlite::params![meta_key, canonical_plan],
12021 )
12022 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12023 Ok((
12024 batch,
12025 LocalDataPurgeResult {
12026 already_applied: false,
12027 purged_rows,
12028 dropped_commits: doomed.len(),
12029 },
12030 ))
12031 })()
12032 .and_then(|(batch, result)| {
12033 self.finish_observation("syncular_local_purge", batch)
12034 .map(|()| result)
12035 });
12036 let result = match applied {
12037 Ok(result) => result,
12038 Err(error) => {
12039 self.rollback_observation("syncular_local_purge");
12040 self.restore(rollback);
12041 return Err(error);
12042 }
12043 };
12044 self.cancel_sync_round();
12045 self.erase_purged_pages()?;
12046 Ok(result)
12047 }
12048
12049 fn erase_purged_pages(&self) -> Result<(), String> {
12054 let erased = self
12055 .conn
12056 .execute_batch("PRAGMA secure_delete = ON; VACUUM;")
12057 .and_then(|()| {
12058 self.conn
12059 .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
12060 });
12061 let reset = self.conn.execute_batch("PRAGMA secure_delete = OFF");
12062 erased
12063 .and(reset)
12064 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
12065 }
12066
12067 pub fn rebootstrap_local_data(
12073 &mut self,
12074 input: &LocalDataRebootstrapInput,
12075 ) -> Result<LocalDataRebootstrapResult, String> {
12076 if input.rebootstrap_id.is_empty()
12077 || input.rebootstrap_id.len() > 128
12078 || !is_local_operation_code_like(&input.rebootstrap_id)
12079 {
12080 return Err(
12081 "sync.invalid_request: local rebootstrap rebootstrapId must be a 1–128 character code-like identifier"
12082 .to_owned(),
12083 );
12084 }
12085 let meta_key = format!("localRebootstrap:{}", input.rebootstrap_id);
12086 if let Some(persisted) = meta_get(&self.conn, &meta_key).map_err(|_| {
12087 "sync.local_corrupt: persisted local rebootstrap receipt is unreadable".to_owned()
12088 })? {
12089 let (retained_commits, reset_subscriptions) =
12090 decode_local_rebootstrap_receipt(&persisted)?;
12091 return Ok(LocalDataRebootstrapResult {
12092 already_applied: true,
12093 retained_commits,
12094 reset_subscriptions,
12095 });
12096 }
12097 if self.stopped || self.schema_floor.is_some() {
12098 return Err(
12099 "sync.invalid_request: local rebootstrap cannot bypass an active schema-floor stop; update the application first"
12100 .to_owned(),
12101 );
12102 }
12103
12104 let retained_commits = self.outbox.len();
12105 let reset_subscriptions = self.stored(load_units(&self.conn))?.len();
12106 let receipt = encode_local_rebootstrap_receipt(retained_commits, reset_subscriptions)?;
12107 let rollback = self.capture();
12108 self.begin_observation("syncular_local_rebootstrap")?;
12109 let mut batch = ChangeAccumulator::default();
12110 let applied = (|| -> Result<(), String> {
12111 self.run_schema_reset_observed(&mut batch, false)?;
12112 self.conn
12113 .execute(
12114 "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
12115 rusqlite::params![meta_key, receipt],
12116 )
12117 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12118 self.sync_needed = true;
12119 self.sync_intent_queue.push_back(SyncIntent::Interactive);
12120 batch.status = true;
12121 Ok(())
12122 })()
12123 .and_then(|()| self.finish_observation("syncular_local_rebootstrap", batch));
12124 if let Err(error) = applied {
12125 self.rollback_observation("syncular_local_rebootstrap");
12126 self.restore(rollback);
12127 return Err(error);
12128 }
12129 self.cancel_sync_round();
12130
12131 Ok(LocalDataRebootstrapResult {
12132 already_applied: false,
12133 retained_commits,
12134 reset_subscriptions,
12135 })
12136 }
12137
12138 fn purge_scope_rows(
12144 &mut self,
12145 table_name: &str,
12146 effective: &[(String, Vec<String>)],
12147 owners: &[Vec<(String, Vec<String>)>],
12148 ) -> Result<bool, String> {
12149 let Some(table) = self.schema.table(table_name) else {
12150 return Ok(false);
12151 };
12152 let Ok(predicate) = local_scope_predicate(table, effective, owners) else {
12153 return Ok(false);
12154 };
12155 let Some((predicate, params)) = predicate else {
12156 return Ok(true);
12157 };
12158 self.overlay_dirty.table(table_name);
12159 for source in [base_table(table_name), visible_table(table_name)] {
12160 self.conn
12161 .execute(
12162 &format!("DELETE FROM {source} WHERE {predicate}"),
12163 rusqlite::params_from_iter(¶ms),
12164 )
12165 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12166 }
12167 Ok(true)
12168 }
12169
12170 fn drop_doomed_outbox(
12174 &mut self,
12175 table: &TableSchema,
12176 effective: &[(String, Vec<String>)],
12177 owners: &[Vec<(String, Vec<String>)>],
12178 ) -> Result<bool, String> {
12179 let doomed: Vec<_> =
12180 self.outbox
12181 .iter()
12182 .filter(|commit| {
12183 commit.ops.iter().any(|op| {
12184 op.upsert
12185 && op.table == table.name
12186 && op.values.as_ref().is_some_and(|values| {
12187 owns_local_row(table, effective, owners, values)
12188 })
12189 })
12190 })
12191 .cloned()
12192 .collect();
12193 if doomed.is_empty() {
12194 return Ok(false);
12195 }
12196 let mut rejections = Vec::new();
12197 for commit in &doomed {
12198 let results = commit
12199 .ops
12200 .iter()
12201 .enumerate()
12202 .map(|(op_index, operation)| {
12203 self.overlay_dirty.table(&operation.table);
12204 let rejection = RejectionRecord {
12205 client_commit_id: commit.client_commit_id.clone(),
12206 op_index: op_index as i32,
12207 code: "sync.scope_revoked".to_owned(),
12208 message: "the commit was dropped because its effective scope was revoked"
12209 .to_owned(),
12210 retryable: false,
12211 details: None,
12212 operation: Some(CommitOperation::from(operation)),
12213 };
12214 rejections.push(rejection.clone());
12215 CommitOperationOutcome::Error { rejection }
12216 })
12217 .collect::<Vec<_>>();
12218 self.persist_commit_outcome(
12219 &commit.client_commit_id,
12220 CommitOutcomeStatus::Rejected,
12221 &results,
12222 Some(&commit.ops),
12223 )?;
12224 self.delete_outbox_persisted(&commit.client_commit_id)?;
12225 }
12226 self.prune_commit_outcomes()?;
12227 let doomed_ids = doomed
12228 .iter()
12229 .map(|commit| commit.client_commit_id.as_str())
12230 .collect::<BTreeSet<_>>();
12231 self.outbox
12232 .retain(|commit| !doomed_ids.contains(commit.client_commit_id.as_str()));
12233 self.rejections.extend(rejections);
12234 Ok(true)
12235 }
12236
12237 pub fn upload_blob(
12244 &mut self,
12245 bytes: &[u8],
12246 media_type: Option<String>,
12247 name: Option<String>,
12248 ) -> Result<Value, String> {
12249 let blob_id = blob_id_for(bytes);
12250 let now = self.clock_now_ms();
12251 let tx = self
12252 .conn
12253 .transaction()
12254 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12255 tx.execute(
12256 "INSERT INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,?,?)
12257 ON CONFLICT(blob_id) DO NOTHING",
12258 rusqlite::params![blob_id, bytes, bytes.len() as i64, media_type, now],
12259 )
12260 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12261 tx.execute(
12262 "INSERT OR IGNORE INTO _syncular_blob_uploads(blob_id, media_type, created_at_ms) VALUES (?,?,?)",
12263 rusqlite::params![blob_id, media_type, now],
12264 )
12265 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12266 tx.commit()
12267 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12268 self.enforce_blob_cache_cap();
12269 let mut obj = Map::new();
12270 obj.insert("blobId".to_owned(), Value::from(blob_id));
12271 obj.insert("byteLength".to_owned(), Value::from(bytes.len() as i64));
12272 if let Some(mt) = media_type {
12273 obj.insert("mediaType".to_owned(), Value::from(mt));
12274 }
12275 if let Some(n) = name {
12276 obj.insert("name".to_owned(), Value::from(n));
12277 }
12278 Ok(Value::Object(obj))
12279 }
12280
12281 pub fn fetch_blob_bytes(
12285 &mut self,
12286 transport: &mut dyn Transport,
12287 blob_id_or_ref: &str,
12288 ) -> Result<FetchedBlob, (String, String)> {
12289 let simple = |m: String| ("client.failed".to_owned(), m);
12290 let (blob_id, byte_length) = if blob_id_or_ref.starts_with("sha256:") {
12293 (blob_id_or_ref.to_owned(), None)
12294 } else {
12295 let value: Value = serde_json::from_str(blob_id_or_ref)
12296 .map_err(|_| simple("blob ref is not JSON".to_owned()))?;
12297 (
12298 value
12299 .get("blobId")
12300 .and_then(Value::as_str)
12301 .ok_or_else(|| simple("blob ref has no blobId".to_owned()))?
12302 .to_owned(),
12303 value.get("byteLength").and_then(Value::as_u64),
12304 )
12305 };
12306 if let Some(cached) = self.get_cached_blob_bytes(&blob_id).map_err(simple)? {
12307 return Ok(cached);
12308 }
12309 if !self.transport_enabled {
12310 return Err(("sync.offline".into(), "transport gate is closed".into()));
12311 }
12312 #[cfg(feature = "bench-internals")]
12318 let download_phase = self.benchmark_phases.start(Phase::BlobDownload);
12319 let bytes = match transport
12320 .blob_download(&blob_id, byte_length)
12321 .map_err(|e| (e.code, e.message))?
12322 {
12323 BlobDownload::Bytes(bytes) => bytes,
12324 BlobDownload::Url {
12325 url,
12326 url_expires_at_ms,
12327 } => {
12328 if url_expires_at_ms.is_some_and(|exp| exp <= self.clock_now_ms()) {
12330 return Err((
12331 "sync.segment_expired".to_owned(),
12332 format!(
12333 "blob url for {blob_id} expired before fetch — re-request mints a fresh url (§5.9.5)"
12334 ),
12335 ));
12336 }
12337 transport
12338 .fetch_blob_url(&url, byte_length)
12339 .map_err(|e| (e.code, e.message))?
12340 }
12341 };
12342 #[cfg(feature = "bench-internals")]
12343 drop(download_phase);
12344 #[cfg(feature = "bench-internals")]
12345 let validate_phase = self.benchmark_phases.start(Phase::BlobValidate);
12346 if byte_length.is_some_and(|cap| bytes.len() as u64 > cap) {
12349 return Err((
12350 "sync.invalid_request".to_owned(),
12351 "blob exceeds its byteLength".to_owned(),
12352 ));
12353 }
12354 if blob_id_for(&bytes) != blob_id {
12355 return Err(simple(format!(
12356 "blob content address mismatch for {blob_id}"
12357 )));
12358 }
12359 #[cfg(feature = "bench-internals")]
12360 drop(validate_phase);
12361 #[cfg(feature = "bench-internals")]
12362 let insert_phase = self.benchmark_phases.start(Phase::BlobCacheInsert);
12363 let now = self.clock_now_ms();
12364 self.conn
12365 .execute(
12366 "INSERT OR IGNORE INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,NULL,?)",
12367 rusqlite::params![blob_id, bytes, bytes.len() as i64, now],
12368 )
12369 .map_err(|e| simple(e.to_string()))?;
12370 self.conn
12371 .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
12372 .map_err(|e| simple(e.to_string()))?;
12373 self.enforce_blob_cache_cap();
12374 #[cfg(feature = "bench-internals")]
12375 drop(insert_phase);
12376 self.get_cached_blob_bytes(&blob_id)
12377 .map_err(simple)?
12378 .ok_or_else(|| simple("blob cache write failed".to_owned()))
12379 }
12380
12381 fn get_cached_blob_bytes(&self, blob_id: &str) -> Result<Option<FetchedBlob>, String> {
12382 #[cfg(feature = "bench-internals")]
12383 let _phase = self.benchmark_phases.start(Phase::BlobCacheRead);
12384 let mut stmt = self
12385 .conn
12386 .prepare("SELECT bytes, byte_length, media_type FROM _syncular_blobs WHERE blob_id = ?")
12387 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12388 let mut rows = stmt
12389 .query(rusqlite::params![blob_id])
12390 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12391 if let Some(row) = rows
12392 .next()
12393 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
12394 {
12395 let bytes: Vec<u8> = row
12396 .get(0)
12397 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12398 let byte_length: i64 = row
12399 .get(1)
12400 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12401 let media_type: Option<String> = row
12402 .get(2)
12403 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12404 return Ok(Some(FetchedBlob {
12405 blob_id: blob_id.to_owned(),
12406 byte_length,
12407 bytes,
12408 media_type,
12409 }));
12410 }
12411 Ok(None)
12412 }
12413
12414 fn pending_blob_uploads(&self) -> Result<Vec<crate::round::PendingUpload>, TransportError> {
12416 let pending: Vec<(String, Option<String>)> = {
12417 let mut stmt = self
12418 .conn
12419 .prepare(
12420 "SELECT blob_id, media_type FROM (
12421 SELECT blob_id, media_type, created_at_ms FROM _syncular_blob_uploads
12422 UNION ALL
12423 SELECT DISTINCT r.blob_id, b.media_type, 9223372036854775807 AS created_at_ms
12424 FROM _syncular_blob_commit_refs r LEFT JOIN _syncular_blobs b ON b.blob_id = r.blob_id
12425 WHERE NOT EXISTS (SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id = r.blob_id)
12426 ) ORDER BY created_at_ms, blob_id",
12427 )
12428 .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
12429 let rows = stmt
12430 .query_map([], |row| {
12431 Ok((row.get::<_, String>(0)?, row.get::<_, Option<String>>(1)?))
12432 })
12433 .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
12434 rows.collect::<Result<_, _>>()
12435 .map_err(|error| match error {
12436 rusqlite::Error::InvalidColumnType(..)
12437 | rusqlite::Error::FromSqlConversionFailure(..) => TransportError::new(
12438 "sync.local_corrupt",
12439 "Pending blob upload metadata is invalid",
12440 ),
12441 _ => TransportError::new("client.failed", error.to_string()),
12442 })?
12443 };
12444 let mut uploads = Vec::new();
12445 for (blob_id, media_type) in pending {
12446 let bytes = (|| {
12447 let stored: Option<(SqlValue, SqlValue)> = self
12448 .conn
12449 .query_row(
12450 "SELECT bytes, byte_length FROM _syncular_blobs WHERE blob_id = ?",
12451 rusqlite::params![blob_id],
12452 |row| Ok((row.get(0)?, row.get(1)?)),
12453 )
12454 .optional()
12455 .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
12456 let Some((SqlValue::Blob(bytes), SqlValue::Integer(byte_length))) = stored else {
12457 return Err(TransportError::new(
12458 "sync.local_corrupt",
12459 "Pending blob upload body is missing or corrupt",
12460 ));
12461 };
12462 if byte_length != bytes.len() as i64 || blob_id_for(&bytes) != blob_id {
12463 return Err(TransportError::new(
12464 "sync.local_corrupt",
12465 "Pending blob upload body is missing or corrupt",
12466 ));
12467 }
12468 Ok(bytes)
12469 })();
12470 let failed = bytes.is_err();
12471 uploads.push(crate::round::PendingUpload {
12472 id: blob_id,
12473 bytes,
12474 media_type,
12475 });
12476 if failed {
12477 break;
12478 }
12479 }
12480 Ok(uploads)
12481 }
12482
12483 fn visible_blob_ids_sql(&self) -> String {
12484 let mut selects = Vec::new();
12485 for table in &self.schema.tables {
12486 for column in table
12487 .columns
12488 .iter()
12489 .filter(|column| column.ty == ColumnType::BlobRef)
12490 {
12491 let identifier = quote_ident(&column.name);
12492 selects.push(format!(
12493 "SELECT json_extract({identifier}, '$.blobId') AS blob_id FROM {} \
12494 WHERE typeof({identifier}) = 'text' AND json_valid({identifier}) \
12495 AND json_type({identifier}, '$.blobId') = 'text'",
12496 quote_ident(&table.name),
12497 ));
12498 }
12499 }
12500 if selects.is_empty() {
12501 "SELECT NULL AS blob_id WHERE 0".to_owned()
12502 } else {
12503 selects.join(" UNION ")
12504 }
12505 }
12506
12507 fn enforce_blob_cache_cap(&self) {
12510 let Some(max_bytes) = self.limits.blob_cache_max_bytes else {
12511 return;
12512 };
12513 let mut total: i64 = self
12514 .conn
12515 .query_row(
12516 "SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs",
12517 [],
12518 |row| row.get(0),
12519 )
12520 .unwrap_or(0);
12521 if total <= max_bytes {
12522 return;
12523 }
12524 let query = format!(
12525 "SELECT blob_id, byte_length FROM _syncular_blobs
12526 WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
12527 AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
12528 AND blob_id NOT IN ({})
12529 ORDER BY created_at_ms ASC, blob_id ASC",
12530 self.visible_blob_ids_sql(),
12531 );
12532 let candidates: Vec<(String, i64)> = {
12533 let Ok(mut stmt) = self.conn.prepare(&query) else {
12534 return;
12535 };
12536 let Ok(rows) = stmt.query_map([], |row| {
12537 Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
12538 }) else {
12539 return;
12540 };
12541 rows.filter_map(Result::ok).collect()
12542 };
12543 for (blob_id, byte_length) in candidates {
12544 if total <= max_bytes {
12545 break;
12546 }
12547 let _ = self.conn.execute(
12548 "DELETE FROM _syncular_blobs WHERE blob_id = ?",
12549 rusqlite::params![blob_id],
12550 );
12551 total -= byte_length;
12552 }
12553 }
12554
12555 fn delete_unreferenced_cached_blobs(&mut self) -> Result<(), String> {
12556 #[cfg(feature = "bench-internals")]
12557 let _phase = self.benchmark_phases.start(Phase::BlobRetention);
12558 if !self.schema_has_blobs() {
12559 return Ok(());
12560 }
12561 self.rebuild_overlay_if_dirty()?;
12562 self.conn
12563 .execute(
12564 &format!(
12565 "DELETE FROM _syncular_blobs
12566 WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
12567 AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
12568 AND blob_id NOT IN ({})",
12569 self.visible_blob_ids_sql(),
12570 ),
12571 [],
12572 )
12573 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12574 Ok(())
12575 }
12576
12577 fn insert_row_sql(&self, full_table: &str, table: &crate::schema::TableSchema) -> String {
12582 if let Some(sql) = self.insert_sql.borrow().get(full_table) {
12583 return sql.clone();
12584 }
12585 let mut columns: Vec<String> = table.columns.iter().map(|c| quote_ident(&c.name)).collect();
12586 columns.push(quote_ident("_syncular_version"));
12587 columns.extend(table.sealed_columns().iter().map(|name| quote_ident(name)));
12588 let placeholders: Vec<&str> = columns.iter().map(|_| "?").collect();
12589 let primary_key = quote_ident(&table.primary_key);
12590 let updates = columns
12591 .iter()
12592 .filter(|column| **column != primary_key)
12593 .map(|column| format!("{column}=excluded.{column}"))
12594 .collect::<Vec<_>>()
12595 .join(", ");
12596 let guard = if full_table == base_table(&table.name) {
12599 format!(" WHERE excluded._syncular_version > {full_table}._syncular_version")
12600 } else {
12601 String::new()
12602 };
12603 let sql = format!(
12604 "INSERT INTO {full_table} ({}) VALUES ({}) ON CONFLICT ({primary_key}) DO UPDATE SET {updates}{guard}",
12605 columns.join(", "),
12606 placeholders.join(", ")
12607 );
12608 self.insert_sql
12609 .borrow_mut()
12610 .insert(full_table.to_owned(), sql.clone());
12611 sql
12612 }
12613
12614 fn write_base_row(
12617 &self,
12618 table_name: &str,
12619 row: &Row,
12620 version: i64,
12621 sealed: Option<&SealedRow>,
12622 ) -> Result<bool, String> {
12623 let landed = self.write_row(&base_table(table_name), table_name, row, version, sealed)?;
12624 if landed {
12625 self.overlay_dirty.table(table_name);
12626 }
12627 Ok(landed)
12628 }
12629
12630 fn write_row(
12631 &self,
12632 full_table: &str,
12633 table_name: &str,
12634 row: &Row,
12635 version: i64,
12636 sealed: Option<&SealedRow>,
12637 ) -> Result<bool, String> {
12638 #[cfg(feature = "bench-internals")]
12639 let _phase = self.benchmark_phases.start(Phase::RowWrite);
12640 let table = self
12641 .schema
12642 .table(table_name)
12643 .ok_or_else(|| format!("unknown table {table_name:?}"))?;
12644 let sql = self.insert_row_sql(full_table, table);
12645 let mut stmt = self
12646 .conn
12647 .prepare_cached(&sql)
12648 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12649 let params = row
12650 .iter()
12651 .map(RowParam::Cell)
12652 .chain(std::iter::once(RowParam::Version(version)))
12653 .chain(
12654 [
12655 sealed.map(|sealed| sealed.key_id.as_str()),
12656 sealed.map(|sealed| sealed.envelopes.as_str()),
12657 ]
12658 .into_iter()
12659 .take(table.sealed_columns().len())
12660 .map(RowParam::Text),
12661 );
12662 stmt.execute(rusqlite::params_from_iter(params))
12663 .map(|changed| changed > 0)
12664 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
12665 }
12666
12667 fn delete_base_row(
12670 &self,
12671 table_name: &str,
12672 row_id: &str,
12673 version: i64,
12674 ) -> Result<bool, String> {
12675 let table = self
12676 .schema
12677 .table(table_name)
12678 .ok_or_else(|| format!("unknown table {table_name:?}"))?;
12679 let sql = format!(
12680 "DELETE FROM {} WHERE {} AND _syncular_version < ?2",
12681 base_table(table_name),
12682 row_id_predicate(table)
12683 );
12684 let mut stmt = self
12685 .conn
12686 .prepare_cached(&sql)
12687 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12688 let landed = stmt
12689 .execute(rusqlite::params![row_id, version])
12690 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
12691 > 0;
12692 if landed {
12693 self.overlay_dirty.table(table_name);
12694 }
12695 Ok(landed)
12696 }
12697
12698 fn has_acknowledged_rows(&self) -> Result<bool, String> {
12699 self.conn
12700 .query_row(
12701 "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows)",
12702 [],
12703 |row| row.get(0),
12704 )
12705 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
12706 }
12707
12708 fn acknowledged_operations(
12709 &self,
12710 rows: Option<&HashSet<(&str, &str)>>,
12711 tables: Option<&BTreeSet<&str>>,
12712 ) -> Result<Vec<OutboxOp>, String> {
12713 let keys = rows.map(|rows| serde_json::to_string(&rows).expect("row keys"));
12714 let mut statement = self
12715 .conn
12716 .prepare_cached(if keys.is_some() {
12717 ACKED_ROWS_BY_ROW
12718 } else {
12719 "SELECT op_json,intent_json FROM _syncular_acked_rows WHERE ?1 IS NULL AND (?2 IS NULL OR tbl IN(SELECT value FROM json_each(?2))) ORDER BY commit_seq,idx"
12720 })
12721 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12722 let rows = statement
12723 .query_map(
12724 rusqlite::params![
12725 keys,
12726 tables.map(|tables| serde_json::to_string(tables).expect("table keys"))
12727 ],
12728 |row| {
12729 #[cfg(test)]
12730 self.acknowledged_replay_count
12731 .set(self.acknowledged_replay_count.get() + 1);
12732 Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
12733 },
12734 )
12735 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12736 rows.map(|row| {
12737 let (op, intent) =
12738 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12739 let op: CommitOperation =
12740 serde_json::from_str(&op).map_err(|_| "sync.local_corrupt".to_owned())?;
12741 let table = self
12742 .schema
12743 .table(&op.table)
12744 .ok_or_else(|| "sync.unknown_table".to_owned())?;
12745 let values = if op.op == "upsert" && self.visible_row(table, &op.row_id)?.is_none() {
12746 Some(serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?)
12747 } else {
12748 op.values.clone()
12749 };
12750 Ok(OutboxOp {
12751 values,
12752 ..op.into()
12753 })
12754 })
12755 .collect()
12756 }
12757
12758 fn drop_acknowledged_rows(
12759 &self,
12760 matches: impl Fn(&str, &Map<String, Value>) -> bool,
12761 ) -> Result<Vec<OutboxCommit>, String> {
12762 let mut statement = self
12763 .conn
12764 .prepare("SELECT commit_id,tbl,intent_json,id FROM _syncular_acked_rows")
12765 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12766 let rows = statement
12767 .query_map([], |row| {
12768 Ok((
12769 row.get::<_, String>(0)?,
12770 row.get::<_, String>(1)?,
12771 row.get::<_, String>(2)?,
12772 row.get::<_, String>(3)?,
12773 ))
12774 })
12775 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12776 let mut doomed = HashSet::new();
12777 for row in rows {
12778 let (id, table, intent, row_id) =
12779 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12780 let values =
12781 serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
12782 let base_matches = self
12783 .schema
12784 .table(&table)
12785 .map(|schema| self.stored_row(schema, &row_id, true))
12786 .transpose()?
12787 .flatten()
12788 .is_some_and(|(base, _)| {
12789 let schema = self.schema.table(&table).expect("acknowledged table");
12790 let values = schema
12791 .columns
12792 .iter()
12793 .zip(base.iter())
12794 .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
12795 .collect();
12796 matches(&table, &values)
12797 });
12798 if matches(&table, &values) || base_matches {
12799 doomed.insert(id);
12800 }
12801 }
12802 let mut dropped = Vec::new();
12803 for id in doomed {
12804 let mut statement = self
12805 .conn
12806 .prepare("SELECT op_json FROM _syncular_acked_rows WHERE commit_id=?1 ORDER BY idx")
12807 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12808 let operations = statement
12809 .query_map([&id], |row| row.get::<_, String>(0))
12810 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12811 let mut ops = Vec::new();
12812 for operation in operations {
12813 let json = operation
12814 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12815 let op: CommitOperation =
12816 serde_json::from_str(&json).map_err(|_| "sync.local_corrupt".to_owned())?;
12817 self.overlay_dirty.table(&op.table);
12818 ops.push(OutboxOp {
12819 table: op.table,
12820 row_id: op.row_id,
12821 upsert: op.op == "upsert",
12822 base_version: op.base_version,
12823 values: op.values,
12824 insert: op.insert,
12825 });
12826 }
12827 dropped.push(OutboxCommit {
12828 client_commit_id: id.clone(),
12829 ops,
12830 });
12831 self.conn
12832 .execute("DELETE FROM _syncular_acked_rows WHERE commit_id=?1", [id])
12833 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12834 }
12835 Ok(dropped)
12836 }
12837
12838 fn rebuild_overlay_if_dirty(&mut self) -> Result<(), String> {
12841 if self.overlay_dirty.get() {
12842 self.rebuild_overlay()?;
12843 }
12844 Ok(())
12845 }
12846
12847 fn rebuild_overlay(&mut self) -> Result<(), String> {
12851 #[cfg(feature = "bench-internals")]
12852 let _phase = self.benchmark_phases.start(Phase::OverlayRebuild);
12853 #[cfg(test)]
12854 self.overlay_rebuild_count
12855 .set(self.overlay_rebuild_count.get() + 1);
12856 let dirty = self.overlay_dirty.snapshot();
12857 let tables: Vec<_> = self
12858 .schema
12859 .tables
12860 .iter()
12861 .filter(|table| {
12862 dirty
12863 .as_ref()
12864 .is_none_or(|names| names.is_empty() || names.contains(&table.name))
12865 })
12866 .cloned()
12867 .collect();
12868 let names: BTreeSet<_> = tables.iter().map(|table| table.name.as_str()).collect();
12869 self.begin_observation("syncular_overlay")?;
12870 let rebuilt = (|| {
12871 for table in &tables {
12872 for index in &table.fts_indexes {
12873 self.drop_fts_triggers(index)?;
12874 }
12875 let visible = visible_table(&table.name);
12876 let base = base_table(&table.name);
12877 self.conn
12878 .execute_batch(&format!(
12879 "DELETE FROM {visible}; INSERT INTO {visible} SELECT * FROM {base}"
12880 ))
12881 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12882 }
12883 self.replay_overlay(&names, None)?;
12884 for table in &tables {
12885 for index in &table.fts_indexes {
12886 self.rebuild_fts_projection(table, index)?;
12887 self.create_fts_triggers(table, index)?;
12888 }
12889 }
12890 self.conn
12891 .execute_batch("RELEASE syncular_overlay")
12892 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12893 Ok(())
12894 })();
12895 if rebuilt.is_err() {
12896 self.conn
12897 .execute_batch("ROLLBACK TO syncular_overlay; RELEASE syncular_overlay")
12898 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12899 } else {
12900 self.overlay_dirty.set(false);
12901 }
12902 rebuilt
12903 }
12904
12905 fn replay_overlay(
12909 &self,
12910 tables: &BTreeSet<&str>,
12911 rows: Option<&HashSet<(&str, &str)>>,
12912 ) -> Result<(), String> {
12913 let replays = |op: &&OutboxOp| {
12914 tables.contains(op.table.as_str())
12915 && rows.is_none_or(|rows| rows.contains(&(op.table.as_str(), op.row_id.as_str())))
12916 };
12917 self.apply_outbox_ops(&self.acknowledged_operations(rows, Some(tables))?)?;
12918 for (commit, initial) in self.failed_commits.iter() {
12919 for operation in commit.ops.iter().filter(replays) {
12920 let Some(table) = self.schema.table(&operation.table) else {
12921 continue;
12922 };
12923 if operation.upsert
12924 && self.visible_row(table, &operation.row_id)?.is_none()
12925 && operation.presented_values(table).is_some_and(|values| {
12926 table
12927 .columns
12928 .iter()
12929 .all(|column| values.contains_key(&column.name))
12930 })
12931 {
12932 let key = serde_json::to_string(&(&operation.table, &operation.row_id))
12933 .expect("row key serialization");
12934 if let Some(Value::Object(values)) = initial.get(&key) {
12935 self.apply_outbox_ops(&[OutboxOp {
12936 values: Some(values.clone()),
12937 ..operation.clone()
12938 }])?;
12939 }
12940 }
12941 }
12942 self.apply_outbox_ops(commit.ops.iter().filter(replays))?;
12943 }
12944 self.apply_outbox_ops(
12945 self.outbox
12946 .iter()
12947 .flat_map(|commit| &commit.ops)
12948 .filter(replays),
12949 )
12950 }
12951
12952 fn apply_outbox_ops<'a>(
12957 &self,
12958 ops: impl IntoIterator<Item = &'a OutboxOp>,
12959 ) -> Result<(), String> {
12960 #[cfg(feature = "bench-internals")]
12961 let mut phase = self.benchmark_phases.start(Phase::PendingReplay);
12962 for op in ops {
12963 #[cfg(feature = "bench-internals")]
12964 if let Some(phase) = &mut phase {
12965 phase.unit();
12966 }
12967 if op.upsert {
12968 if let Some((table, values)) = self
12969 .schema
12970 .table(&op.table)
12971 .filter(|table| table.indexes.iter().any(|index| index.unique))
12972 .and_then(|table| Some((table, op.presented_values(table)?)))
12973 {
12974 let mut intended: Map<String, Value> = self
12975 .visible_row(table, &op.row_id)?
12976 .map(|(row, _)| {
12977 table
12978 .columns
12979 .iter()
12980 .zip(&row)
12981 .map(|(column, value)| {
12982 (column.name.clone(), column_value_to_json(value))
12983 })
12984 .collect()
12985 })
12986 .unwrap_or_default();
12987 intended.extend(values.into_owned());
12988 if !self.unique_conflicts(table, &intended, false)?.is_empty() {
12989 continue;
12990 }
12991 }
12992 }
12993 self.apply_outbox_op(op)?;
12994 }
12995 Ok(())
12996 }
12997
12998 fn apply_outbox_op(&self, op: &OutboxOp) -> Result<(), String> {
12999 let Some(table) = self.schema.table(&op.table) else {
13000 return Ok(());
13001 };
13002 let visible = visible_table(&table.name);
13003 if !op.upsert {
13004 let sql = format!("DELETE FROM {visible} WHERE {}", row_id_predicate(table));
13005 self.conn
13006 .prepare_cached(&sql)
13007 .and_then(|mut statement| statement.execute(rusqlite::params![op.row_id]))
13008 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13009 return Ok(());
13010 }
13011 let Some(values) = op.presented_values(table) else {
13015 return Ok(());
13016 };
13017 let full = table
13023 .columns
13024 .iter()
13025 .all(|column| values.contains_key(&column.name));
13026 let local = self.visible_row(table, &op.row_id)?;
13027 if local.is_none() && !full {
13028 return Ok(());
13029 }
13030 let mut row: Row = Vec::with_capacity(table.columns.len());
13031 for (index, column) in table.columns.iter().enumerate() {
13032 let incoming = match values.get(&column.name) {
13033 Some(raw) => json_to_column_value(
13034 if raw.get("$bytes").is_some()
13035 && table
13036 .encrypted_columns
13037 .iter()
13038 .any(|encrypted| encrypted.index == index)
13039 {
13040 &table.wire_columns[index]
13041 } else {
13042 column
13043 },
13044 Some(raw),
13045 ),
13046 None => Ok(local
13047 .as_ref()
13048 .and_then(|(values, _)| values.get(index).cloned())
13049 .flatten()),
13050 };
13051 row.push(incoming.map_err(|_| {
13052 "sync.local_corrupt: persisted optimistic row value is invalid".to_owned()
13053 })?);
13054 }
13055 let version = local.as_ref().map_or(-1, |(_, version)| *version);
13056 self.write_row(&visible, &table.name, &row, version, None)
13057 .map(|_| ())
13058 .map_err(|error| {
13059 if error.starts_with("UNIQUE constraint failed:") {
13060 "sync.constraint_violation: local write violates a unique constraint".to_owned()
13061 } else {
13062 error
13063 }
13064 })
13065 }
13066
13067 fn visible_row_exists(&self, table: &TableSchema, row_id: &str) -> Result<bool, String> {
13071 self.conn
13072 .query_row(
13073 &format!(
13074 "SELECT EXISTS(SELECT 1 FROM {} WHERE {})",
13075 visible_table(&table.name),
13076 row_id_predicate(table)
13077 ),
13078 rusqlite::params![row_id],
13079 |row| row.get(0),
13080 )
13081 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
13082 }
13083
13084 fn refuse_sealed_row(&self, table: &TableSchema, row_id: &str) -> Result<(), ClientError> {
13087 if !table.has_encrypted_columns() {
13088 return Ok(());
13089 }
13090 let key_id: Option<String> = self
13091 .conn
13092 .query_row(
13093 &format!(
13094 "SELECT \"_sync_sealed_key\" FROM {} WHERE {}",
13095 visible_table(&table.name),
13096 row_id_predicate(table)
13097 ),
13098 rusqlite::params![row_id],
13099 |row| row.get(0),
13100 )
13101 .optional()
13102 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
13103 .flatten();
13104 match key_id {
13105 None => Ok(()),
13106 Some(key_id) => Err(ClientError {
13107 code: "client.encryption_key_missing".to_owned(),
13108 message: "the row is sealed under a key this device does not hold".to_owned(),
13109 details: Some(json!({ "table": table.name, "keyId": key_id })),
13110 retryable: false,
13111 }),
13112 }
13113 }
13114
13115 fn reveal_sealed_rows(&mut self) -> Result<(), TransportError> {
13119 let storage = |message: String| TransportError::new("storage.failed", message);
13120 let tables: Vec<TableSchema> = self
13121 .schema
13122 .tables
13123 .iter()
13124 .filter(|table| table.has_encrypted_columns())
13125 .cloned()
13126 .collect();
13127 for table in &tables {
13128 let base = base_table(&table.name);
13129 let pk = quote_ident(&table.primary_key);
13130 let sealed: Vec<(SqlValue, i64, String)> = self
13131 .conn
13132 .prepare_cached(&format!(
13133 "SELECT {pk}, \"_syncular_version\", \"_sync_sealed\" FROM {base} WHERE \"_sync_sealed_key\" IS NOT NULL"
13134 ))
13135 .and_then(|mut statement| {
13136 statement
13137 .query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?
13138 .collect()
13139 })
13140 .map_err(|error| storage(Self::sqlite_failure(&self.storage_failure, error)))?;
13141 let mut revealed = Vec::new();
13142 for (key, version, envelopes) in sealed {
13143 if let Some(row) =
13144 crate::values::reveal_sealed_row(table, &envelopes, &self.encryption)?
13145 {
13146 revealed.push((key, version, row));
13147 }
13148 }
13149 if revealed.is_empty() {
13150 continue;
13151 }
13152 self.begin_observation("syncular_reveal").map_err(storage)?;
13153 let outcome = (|| {
13154 let assignments = table
13155 .encrypted_columns
13156 .iter()
13157 .map(|enc| format!("{}=?", quote_ident(&table.columns[enc.index].name)))
13158 .collect::<Vec<_>>()
13159 .join(",");
13160 let mut statement = self
13161 .conn
13162 .prepare_cached(&format!(
13163 "UPDATE {base} SET {assignments},\"_sync_sealed_key\"=NULL,\"_sync_sealed\"=NULL WHERE {pk}=? AND \"_syncular_version\"=?"
13164 ))
13165 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13166 for (key, version, row) in &revealed {
13167 let mut params = table
13168 .encrypted_columns
13169 .iter()
13170 .map(|enc| owned_sql_value(RowParam::Cell(&row[enc.index])))
13171 .collect::<Result<Vec<_>, _>>()?;
13172 params.push(key.clone());
13173 params.push(SqlValue::Integer(*version));
13174 statement
13175 .execute(rusqlite::params_from_iter(params))
13176 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13177 }
13178 drop(statement);
13179 self.overlay_dirty.table(&table.name);
13180 self.rebuild_overlay()?;
13181 let mut batch = ChangeAccumulator::default();
13182 batch.table(&table.name);
13183 self.finish_observation("syncular_reveal", batch)
13184 })();
13185 if outcome.is_err() {
13186 self.rollback_observation("syncular_reveal");
13187 }
13188 outcome.map_err(storage)?;
13189 }
13190 Ok(())
13191 }
13192
13193 fn visible_row(&self, table: &TableSchema, row_id: &str) -> Result<Option<(Row, i64)>, String> {
13196 self.stored_row(table, row_id, false)
13197 }
13198
13199 fn stored_row(
13200 &self,
13201 table: &TableSchema,
13202 row_id: &str,
13203 base: bool,
13204 ) -> Result<Option<(Row, i64)>, String> {
13205 let sql = format!(
13206 "SELECT * FROM {} WHERE {}",
13207 if base {
13208 base_table(&table.name)
13209 } else {
13210 visible_table(&table.name)
13211 },
13212 row_id_predicate(table)
13213 );
13214 let mut stmt = self
13215 .conn
13216 .prepare_cached(&sql)
13217 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13218 let mut rows = stmt
13219 .query(rusqlite::params![row_id])
13220 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13221 let Some(row) = rows
13222 .next()
13223 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
13224 else {
13225 return Ok(None);
13226 };
13227 let mut values = Vec::with_capacity(table.columns.len());
13228 for (index, column) in table.columns.iter().enumerate() {
13229 let raw = row
13230 .get_ref(index)
13231 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13232 if let rusqlite::types::ValueRef::Blob(bytes) = raw {
13233 if table
13234 .encrypted_columns
13235 .iter()
13236 .any(|encrypted| encrypted.index == index)
13237 {
13238 values.push(Some(ColumnValue::Bytes(bytes.to_vec())));
13239 continue;
13240 }
13241 }
13242 let json = sql_ref_to_json(column, raw);
13243 values.push(json_to_column_value(column, Some(&json)).map_err(|_| {
13244 "sync.local_corrupt: persisted local row value is invalid".to_owned()
13245 })?);
13246 }
13247 let version: i64 = row
13248 .get(table.columns.len())
13249 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13250 Ok(Some((values, version)))
13251 }
13252
13253 #[must_use]
13257 pub fn realtime_policy(&self) -> RealtimePolicy {
13258 self.realtime_policy
13259 }
13260
13261 #[must_use]
13263 pub fn realtime_state(&self) -> RealtimeState {
13264 self.realtime_state
13265 }
13266
13267 pub fn set_realtime_policy(&mut self, policy: RealtimePolicy) -> Result<(), String> {
13270 if self.realtime_state == RealtimeState::Connected && policy != self.realtime_policy {
13271 return Err(
13272 "sync.invalid_request: disconnect realtime before changing the realtime policy"
13273 .to_owned(),
13274 );
13275 }
13276 self.realtime_policy = policy;
13277 match policy {
13278 RealtimePolicy::Off => self.set_realtime_state(RealtimeState::Disabled, None),
13279 RealtimePolicy::Required | RealtimePolicy::Optional
13280 if self.realtime_state == RealtimeState::Disabled =>
13281 {
13282 self.set_realtime_state(RealtimeState::Disconnected, None);
13283 }
13284 RealtimePolicy::Required | RealtimePolicy::Optional => {}
13285 }
13286 Ok(())
13287 }
13288
13289 fn set_realtime_state(&mut self, state: RealtimeState, reason_code: Option<&str>) {
13292 self.realtime_state = state;
13293 self.realtime_reason_code = reason_code.map(Self::diagnostic_code);
13294 if matches!(state, RealtimeState::Connected | RealtimeState::Disabled) {
13295 self.realtime_reason_code = None;
13296 self.realtime_retry_delay_ms = None;
13297 }
13298 }
13299
13300 #[must_use]
13301 fn realtime_connected(&self) -> bool {
13302 self.realtime_state == RealtimeState::Connected
13303 }
13304
13305 pub fn connect_realtime(&mut self, transport: &mut dyn Transport) -> Result<(), String> {
13306 if !self.transport_enabled {
13307 return Err("sync.offline: transport gate is closed".into());
13308 }
13309 if self.realtime_policy == RealtimePolicy::Off {
13310 return Err(
13311 "sync.invalid_request: realtime is off; realtime connect is refused".to_owned(),
13312 );
13313 }
13314 if self.realtime_connected() {
13315 return Ok(());
13316 }
13317 self.realtime_state = RealtimeState::Connecting;
13318 match transport.realtime_connect(&self.client_id) {
13319 Ok(()) => {
13320 self.set_realtime_state(RealtimeState::Connected, None);
13321 Ok(())
13322 }
13323 Err(error) => {
13324 self.set_realtime_state(RealtimeState::Refused, Some(&error.code));
13325 Err(format!("{}: {}", error.code, error.message))
13326 }
13327 }
13328 }
13329
13330 pub fn disconnect_realtime(&mut self, transport: &mut dyn Transport) {
13331 self.cancel_sync_round();
13332 if self.realtime_state == RealtimeState::Disconnected
13335 || self.realtime_state == RealtimeState::Disabled
13336 {
13337 return;
13338 }
13339 let _ = transport.realtime_close();
13340 self.set_realtime_state(
13341 if self.realtime_policy == RealtimePolicy::Off {
13342 RealtimeState::Disabled
13343 } else {
13344 RealtimeState::Disconnected
13345 },
13346 None,
13347 );
13348 self.presence.clear(); }
13350
13351 pub fn realtime_lost(&mut self, transport: &mut dyn Transport, error: &TransportError) {
13357 if self.realtime_state != RealtimeState::Connected {
13358 return;
13359 }
13360 self.cancel_sync_round();
13361 let _ = transport.realtime_close();
13362 self.set_realtime_state(RealtimeState::Lost, Some(&error.code));
13363 self.realtime_retry_delay_ms = Some(self.schedule_background_retry());
13364 self.presence.clear();
13365 }
13366
13367 pub fn set_presence(
13373 &mut self,
13374 transport: &mut dyn Transport,
13375 scope_key: &str,
13376 doc: Option<&Value>,
13377 ) -> Result<(), String> {
13378 if !self.transport_enabled {
13379 return Err("sync.offline: transport gate is closed".into());
13380 }
13381 if !self.realtime_connected() {
13382 return Err("setPresence requires a connected realtime socket (§8.6)".to_string());
13383 }
13384 let text = encode_presence_publish(scope_key, doc);
13385 transport
13386 .realtime_send(&text)
13387 .map_err(|e| format!("{}: {}", e.code, e.message))
13388 }
13389
13390 pub fn presence(&self, scope_key: &str) -> Vec<PresencePeer> {
13392 self.presence
13393 .get(scope_key)
13394 .map(|peers| peers.values().cloned().collect())
13395 .unwrap_or_default()
13396 }
13397
13398 fn apply_presence(
13400 &mut self,
13401 scope_key: String,
13402 kind: Option<PresenceKind>,
13403 actor_id: Option<String>,
13404 client_id: Option<String>,
13405 doc: Option<Value>,
13406 error: Option<String>,
13407 ) {
13408 if error.is_some() {
13411 return;
13412 }
13413 let (Some(kind), Some(actor_id), Some(client_id)) = (kind, actor_id, client_id) else {
13414 return;
13415 };
13416 let peer_key = format!("{actor_id} {client_id}");
13417 match kind {
13418 PresenceKind::Leave => {
13419 if let Some(peers) = self.presence.get_mut(&scope_key) {
13420 peers.remove(&peer_key);
13421 if peers.is_empty() {
13422 self.presence.remove(&scope_key);
13423 }
13424 }
13425 }
13426 _ => {
13427 let doc = match doc {
13428 Some(Value::Object(_)) => doc.unwrap(),
13429 _ => return,
13430 };
13431 self.presence.entry(scope_key).or_default().insert(
13432 peer_key,
13433 PresencePeer {
13434 actor_id,
13435 client_id,
13436 doc,
13437 },
13438 );
13439 }
13440 }
13441 }
13442
13443 pub fn on_realtime_text(&mut self, text: &str) {
13445 if self.stopped || !self.transport_enabled || self.security_preflight {
13446 return;
13447 }
13448 match parse_control(text) {
13449 Ok(ControlMessage::Hello { requires_sync, .. }) => {
13450 if requires_sync {
13451 self.set_sync_needed(true, true);
13453 }
13454 }
13455 Ok(ControlMessage::Presence {
13456 scope_key,
13457 kind,
13458 actor_id,
13459 client_id,
13460 doc,
13461 error,
13462 ..
13463 }) => {
13464 self.apply_presence(scope_key, kind, actor_id, client_id, doc, error);
13465 }
13466 Ok(ControlMessage::Wake { .. }) => {
13467 self.set_sync_needed(true, true);
13469 }
13470 Ok(ControlMessage::Scopes { .. }) => {
13471 self.scopes_changed += 1;
13473 }
13474 _ => {}
13475 }
13476 }
13477
13478 pub fn on_realtime_binary_queued(&mut self, bytes: &[u8]) -> Vec<String> {
13482 let mut transport = crate::round::DownloadResults::default();
13483 self.on_realtime_binary(&mut transport, bytes);
13484 transport.controls
13485 }
13486
13487 pub fn on_realtime_binary(&mut self, transport: &mut dyn Transport, bytes: &[u8]) {
13493 if self.stopped || !self.transport_enabled || self.security_preflight {
13494 return;
13495 }
13496 #[cfg(feature = "bench-internals")]
13497 let decode_phase = self.benchmark_phases.start(Phase::ResponseDecode);
13498 let message = match decode_message(bytes) {
13499 Ok(m) if m.msg_kind == MsgKind::Response => m,
13500 _ => {
13501 self.set_sync_needed(true, true);
13502 return;
13503 }
13504 };
13505 #[cfg(feature = "bench-internals")]
13506 drop(decode_phase);
13507 if let Some(Frame::RespHeader {
13510 required_schema_version: Some(required),
13511 latest_schema_version,
13512 ..
13513 }) = message.frames.first()
13514 {
13515 let floor = SchemaFloor {
13516 required_schema_version: Some(*required),
13517 latest_schema_version: *latest_schema_version,
13518 };
13519 if self.set_schema_floor(Some(floor)).is_err() {
13520 self.set_sync_needed(true, true);
13521 }
13522 return;
13523 }
13524 let through = message.frames.iter().find_map(|frame| match frame {
13525 Frame::LiveEnd { through_seq, .. } => Some(*through_seq),
13526 _ => None,
13527 });
13528 let epoch = self.get_meta(LOG_EPOCH_KEY).ok().flatten();
13529 let mut dropped = !matches!(message.frames.first(), Some(Frame::RespHeader {
13530 reset_required: false,
13531 log_epoch,
13532 ..
13533 }) if Some(log_epoch) == epoch.as_ref());
13534 let mut applied: Option<i64> = None;
13535 dropped |= self.begin_coalesced_apply().is_err();
13536 let mut receivers: Option<Vec<UnitRecord>> = None;
13537 for frame in message.frames {
13538 if dropped {
13539 break;
13540 }
13541 match frame {
13542 Frame::LiveStart { status, .. } => {
13543 let Ok(cursor) = self.stored(replica_cursor(&self.conn)) else {
13544 dropped = true;
13545 break;
13546 };
13547 if status != LiveStatus::Active || cursor < 0 {
13548 dropped = true;
13549 } else if !through.is_some_and(|through| through <= cursor) {
13550 receivers = self.stored(load_units(&self.conn)).ok().map(|units| {
13552 units
13553 .into_iter()
13554 .filter(|unit| {
13555 unit.status == UnitStatus::Active
13556 && unit.echo.is_some()
13557 && unit.cursor.is_none()
13558 })
13559 .collect()
13560 });
13561 dropped = receivers.is_none();
13562 }
13563 }
13564 Frame::Commit {
13565 commit_seq,
13566 tables,
13567 changes,
13568 ..
13569 } => {
13570 let Some(receivers) = receivers.clone() else {
13571 continue;
13572 };
13573 dropped = self
13574 .apply_live_commit(
13575 &receivers,
13576 &tables,
13577 changes,
13578 commit_seq,
13579 AppliedServerCommitSource::Delta,
13580 )
13581 .is_err();
13582 }
13583 Frame::LiveEnd { through_seq, .. } if receivers.is_some() => {
13584 dropped = self
13585 .set_meta(REPLICA_CURSOR_KEY, &through_seq.to_string())
13586 .is_err();
13587 applied = Some(through_seq);
13588 }
13589 Frame::Error { .. } => dropped = true,
13590 _ => {}
13591 }
13592 }
13593 if self.finish_coalesced_apply().is_err() || dropped {
13596 applied = None;
13597 dropped = true;
13598 }
13599 if let Some(cursor) = applied {
13600 let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
13602 let _ = transport.realtime_send(&ack);
13603 }
13604 if dropped {
13605 self.set_sync_needed(true, true);
13606 }
13607 }
13608
13609 fn ack_after_pull(&mut self, transport: &mut dyn Transport) {
13612 if !self.realtime_connected() {
13613 return;
13614 }
13615 if let Ok(cursor @ 0..) = self.stored(replica_cursor(&self.conn)) {
13616 let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
13617 let _ = transport.realtime_send(&ack);
13618 }
13619 }
13620}
13621
13622#[cfg(test)]
13623mod previous_version_wiring_tests;
13624
13625#[cfg(test)]
13626mod identity_tests;
13627
13628#[cfg(test)]
13629mod insert_intent_tests;
13630
13631#[cfg(test)]
13632mod robustness_tests;
13633
13634#[cfg(test)]
13635mod range_image_tests;