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 for value in units {
5617 if live.iter().any(|(held, _)| held == value) {
5618 continue;
5619 }
5620 let rollback = self.capture();
5621 self.begin_observation("syncular_window")?;
5622 let widened = (|| {
5623 let (id, registered) = self.hold_unit(window_unit_scopes(base, value), false)?;
5624 self.sync_needed |= registered;
5625 self.conn
5626 .execute(
5627 "INSERT OR REPLACE INTO _syncular_windows(base, unit, sub_id) VALUES (?1, ?2, ?3)",
5628 rusqlite::params![base_key, value, id],
5629 )
5630 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5631 let mut batch = ChangeAccumulator::default();
5632 batch.window(&base_key, value);
5633 batch.status = true;
5634 self.finish_observation("syncular_window", batch)
5635 })();
5636 if let Err(error) = widened {
5637 self.rollback_observation("syncular_window");
5638 self.restore(rollback);
5639 return Err(error);
5640 }
5641 changed = true;
5642 self.registration_epoch = self.registration_epoch.wrapping_add(1);
5643 }
5644 for (value, id) in live {
5645 if units.contains(&value) {
5646 continue;
5647 }
5648 self.rebuild_overlay_if_dirty()?;
5649 let rollback = self.capture();
5650 self.begin_observation("syncular_window")?;
5651 let remaining = self.release_window_unit(&base_key, &value, &id);
5652 let remaining = match remaining {
5653 Ok(remaining) => remaining,
5654 Err(error) => {
5655 self.rollback_observation("syncular_window");
5656 self.restore(rollback);
5657 return Err(error);
5658 }
5659 };
5660 changed = true;
5661 self.registration_epoch = self.registration_epoch.wrapping_add(1);
5662 if remaining {
5663 self.drain_pending_evictions()?;
5664 }
5665 }
5666 Ok(if changed && self.transport_enabled {
5667 CommandEffects::interactive()
5668 } else {
5669 CommandEffects::none()
5670 })
5671 }
5672
5673 pub fn window_state(&self, base: &WindowBase) -> Result<WindowState, String> {
5677 persisted_window_state(&self.conn, base).map_err(|failure| failure.message)
5678 }
5679
5680 fn load_window_units(&self, base_key: &str) -> Result<Vec<(String, String)>, String> {
5682 let mut statement = self
5683 .conn
5684 .prepare_cached(
5685 "SELECT unit, sub_id FROM _syncular_windows WHERE base = ?1 ORDER BY unit ASC",
5686 )
5687 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5688 let rows = statement
5689 .query_map([base_key], |row| Ok((row.get(0)?, row.get(1)?)))
5690 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5691 rows.collect::<Result<_, _>>()
5692 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5693 }
5694
5695 fn load_window_registry(&self) -> Result<Vec<(String, String)>, String> {
5697 let mut statement = self
5698 .conn
5699 .prepare_cached("SELECT base, unit FROM _syncular_windows ORDER BY base, unit")
5700 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5701 let rows = statement
5702 .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))
5703 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5704 rows.collect::<Result<_, _>>()
5705 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5706 }
5707
5708 fn release_window_unit(
5716 &mut self,
5717 base_key: &str,
5718 value: &str,
5719 id: &str,
5720 ) -> Result<bool, String> {
5721 self.conn
5722 .execute(
5723 "DELETE FROM _syncular_windows WHERE base = ?1 AND unit = ?2",
5724 rusqlite::params![base_key, value],
5725 )
5726 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5727 let mut batch = ChangeAccumulator::default();
5728 batch.window(base_key, value);
5729 batch.status = true;
5730 let unit = self.stored(get_unit(&self.conn, id))?;
5731 let mut remaining = false;
5732 if let Some(unit) = unit.filter(|unit| !unit.explicit) {
5733 if self.stored(window_refs(&self.conn, id))?.is_empty() {
5734 let units = self.stored(load_units(&self.conn))?;
5735 self.conn
5736 .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5737 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5738 self.sync_needed = true;
5739 for table in self.schema.tables.clone() {
5740 let Some(effective) = unit
5741 .echo
5742 .as_deref()
5743 .filter(|_| covers(&table, &unit.scopes))
5744 .and_then(|echo| pair_scopes(&unit.scopes, &table.name, Some(echo)))
5745 else {
5746 continue;
5747 };
5748 let pinned = self.pinned_row_ids(&table.name);
5749 let owners = unit_owners(&units, &table, id);
5750 let (more, deferred) =
5751 self.evict_scope_rows(&table.name, &effective, &owners, &pinned)?;
5752 remaining |= more;
5753 if deferred {
5754 self.save_pending_evict(id, &table.name, &effective)?;
5755 }
5756 self.record_scope_map(&mut batch, &table.name, &effective);
5757 }
5758 }
5759 }
5760 self.finish_observation("syncular_window", batch)?;
5761 Ok(remaining)
5762 }
5763
5764 fn evict_scope_rows(
5769 &self,
5770 table_name: &str,
5771 effective: &[(String, Vec<String>)],
5772 owners: &[Vec<(String, Vec<String>)>],
5773 pinned: &std::collections::HashSet<String>,
5774 ) -> Result<(bool, bool), String> {
5775 let table = self.schema.table(table_name).ok_or("sync.unknown_table")?;
5776 let Some((scope, mut params)) = local_scope_predicate(table, effective, owners)
5777 .map_err(|()| "sync.scope_revoked".to_owned())?
5778 else {
5779 return Ok((false, false));
5780 };
5781 let scope_params = params.len();
5782 let pk = quote_ident(&table.primary_key);
5783 let predicate = if pinned.is_empty() {
5785 scope.clone()
5786 } else {
5787 params.extend(pinned.iter().cloned().map(SqlValue::Text));
5788 let holes = vec!["?"; pinned.len()].join(", ");
5789 format!("{scope} AND CAST({pk} AS TEXT) NOT IN ({holes})")
5790 };
5791 let base = base_table(table_name);
5792 let visible = visible_table(table_name);
5793 let mut ids: Vec<SqlValue> = Vec::new();
5794 for source in [&base, &visible] {
5795 let mut stmt = self
5796 .conn
5797 .prepare_cached(&format!(
5798 "SELECT {pk} FROM {source} WHERE {predicate} LIMIT 1024"
5799 ))
5800 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5801 ids = stmt
5802 .query_map(rusqlite::params_from_iter(¶ms), |row| row.get(0))
5803 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5804 .collect::<Result<_, _>>()
5805 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5806 if !ids.is_empty() {
5807 break;
5808 }
5809 }
5810 if !ids.is_empty() {
5811 for id in &ids {
5812 self.conn
5813 .execute(
5814 "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2",
5815 rusqlite::params![table_name, id],
5816 )
5817 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5818 }
5819 let holes = vec!["?"; ids.len()].join(", ");
5820 for source in [&base, &visible] {
5821 self.conn
5822 .execute(
5823 &format!("DELETE FROM {source} WHERE {pk} IN ({holes})"),
5824 rusqlite::params_from_iter(&ids),
5825 )
5826 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5827 }
5828 }
5829 let mut remaining = false;
5830 let mut deferred = false;
5831 for source in [&base, &visible] {
5832 remaining |= self
5833 .conn
5834 .query_row(
5835 &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
5836 rusqlite::params_from_iter(¶ms),
5837 |row| row.get::<_, bool>(0),
5838 )
5839 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5840 deferred |= self
5841 .conn
5842 .query_row(
5843 &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {scope})"),
5844 rusqlite::params_from_iter(¶ms[..scope_params]),
5845 |row| row.get::<_, bool>(0),
5846 )
5847 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5848 }
5849 Ok((remaining, deferred))
5850 }
5851
5852 fn drain_pending_evictions(&mut self) -> Result<(), String> {
5856 let pending = self.load_pending_evictions()?;
5857 if pending.is_empty() {
5858 return Ok(());
5859 }
5860 self.rebuild_overlay_if_dirty()?;
5861 for (unit_id, table_name, effective) in pending {
5862 let Some(table) = self.schema.table(&table_name).cloned() else {
5863 self.delete_pending_evict_table(&unit_id, &table_name)?;
5864 continue;
5865 };
5866 loop {
5867 std::thread::yield_now();
5868 self.begin_observation("syncular_evict")?;
5869 let chunk = (|| {
5870 let pinned = self.pinned_row_ids(&table_name);
5871 let owners =
5872 unit_owners(&self.stored(load_units(&self.conn))?, &table, &unit_id);
5873 let (remaining, deferred) =
5874 self.evict_scope_rows(&table_name, &effective, &owners, &pinned)?;
5875 if !deferred {
5876 self.delete_pending_evict_table(&unit_id, &table_name)?;
5877 }
5878 let mut batch = ChangeAccumulator::default();
5879 self.record_scope_map(&mut batch, &table_name, &effective);
5880 self.finish_observation("syncular_evict", batch)?;
5881 Ok(remaining)
5882 })();
5883 match chunk {
5884 Ok(true) => {}
5885 Ok(false) => break,
5886 Err(error) => {
5887 self.rollback_observation("syncular_evict");
5888 return Err(error);
5889 }
5890 }
5891 }
5892 }
5893 Ok(())
5894 }
5895
5896 fn pinned_row_ids(&self, table: &str) -> std::collections::HashSet<String> {
5899 let mut pinned = std::collections::HashSet::new();
5900 for commit in self
5901 .outbox
5902 .iter()
5903 .map(|commit| &**commit)
5904 .chain(self.failed_commits.iter().map(|(commit, _)| commit))
5905 {
5906 for op in &commit.ops {
5907 if op.table == table {
5908 pinned.insert(op.row_id.clone());
5909 }
5910 }
5911 }
5912 pinned
5913 }
5914
5915 fn save_pending_evict(
5916 &self,
5917 unit_id: &str,
5918 table: &str,
5919 effective: &[(String, Vec<String>)],
5920 ) -> Result<(), String> {
5921 self.conn.execute(
5922 "INSERT OR REPLACE INTO _syncular_pending_evictions(unit_id, tbl, effective_scopes) VALUES (?1, ?2, ?3)",
5923 rusqlite::params![unit_id, table, scope_map_to_json(effective).to_string()],
5924 ).map(|_| ()).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5925 }
5926
5927 fn delete_pending_evict(&self, unit_id: &str) -> Result<(), String> {
5929 self.conn
5930 .execute(
5931 "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
5932 [unit_id],
5933 )
5934 .map(|_| ())
5935 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5936 }
5937
5938 fn delete_pending_evict_table(&self, unit_id: &str, table: &str) -> Result<(), String> {
5939 self.conn
5940 .execute(
5941 "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1 AND tbl = ?2",
5942 [unit_id, table],
5943 )
5944 .map(|_| ())
5945 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5946 }
5947
5948 fn load_pending_evictions(&self) -> Result<Vec<PendingEvict>, String> {
5949 let mut stmt = self
5950 .conn
5951 .prepare("SELECT unit_id, tbl, effective_scopes FROM _syncular_pending_evictions")
5952 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5953 let rows = stmt
5954 .query_map([], |row| {
5955 Ok((
5956 row.get::<_, String>(0)?,
5957 row.get::<_, String>(1)?,
5958 row.get::<_, String>(2)?,
5959 ))
5960 })
5961 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5962 rows.map(|row| {
5963 let (unit_id, table, json) =
5964 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5965 let value: Value = serde_json::from_str(&json)
5966 .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5967 let effective = json_to_scope_map(&value)
5968 .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5969 Ok((unit_id, table, effective))
5970 })
5971 .collect()
5972 }
5973
5974 pub fn set_retain_failed_commits(&mut self, enabled: bool) -> Result<(), String> {
5976 self.retain_failed_commits = enabled;
5977 for (commit, _) in self.failed_commits.iter() {
5978 for operation in &commit.ops {
5979 self.overlay_dirty.table(&operation.table);
5980 }
5981 }
5982 self.failed_commits = self.load_failed_commits()?.into();
5983 for (commit, _) in self.failed_commits.iter() {
5984 for operation in &commit.ops {
5985 self.overlay_dirty.table(&operation.table);
5986 }
5987 }
5988 Ok(())
5989 }
5990
5991 fn load_failed_commits(&self) -> Result<Vec<FailedCommit>, String> {
5992 let mut statement = self.conn.prepare("SELECT client_commit_id, operations_json, initial_json FROM _syncular_failed_commits ORDER BY seq")
5993 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5994 let rows = statement
5995 .query_map([], |row| {
5996 Ok((
5997 row.get::<_, String>(0)?,
5998 row.get::<_, String>(1)?,
5999 row.get::<_, String>(2)?,
6000 ))
6001 })
6002 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6003 rows.map(|row| {
6004 let (id, operations, initial) =
6005 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6006 let operations: Vec<CommitOperation> =
6007 serde_json::from_str(&operations).map_err(|_| "sync.local_corrupt".to_owned())?;
6008 let initial =
6009 serde_json::from_str(&initial).map_err(|_| "sync.local_corrupt".to_owned())?;
6010 Ok((
6011 OutboxCommit {
6012 client_commit_id: id,
6013 ops: operations
6014 .into_iter()
6015 .map(|op| OutboxOp {
6016 upsert: op.op == "upsert",
6017 table: op.table,
6018 row_id: op.row_id,
6019 base_version: op.base_version,
6020 values: op.values,
6021 insert: op.insert,
6022 })
6023 .collect(),
6024 },
6025 initial,
6026 ))
6027 })
6028 .collect()
6029 }
6030
6031 fn retain_failed_commit(&mut self, id: &str, operations: &[OutboxOp]) -> Result<(), String> {
6032 let mut initial = Map::new();
6033 for operation in operations {
6034 let Some(table) = self.schema.table(&operation.table) else {
6036 continue;
6037 };
6038 let initial_row = match self.stored_row(table, &operation.row_id, true)? {
6039 Some(row) => Some(row),
6040 None => self.visible_row(table, &operation.row_id)?,
6041 };
6042 if let Some((values, _)) = initial_row {
6043 let mut intended: Map<String, Value> = table
6044 .columns
6045 .iter()
6046 .zip(values.iter())
6047 .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
6048 .collect();
6049 if let Some(patch) = &operation.values {
6050 intended.extend(patch.clone());
6051 }
6052 initial.insert(
6053 serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
6054 .map_err(|_| "sync.local_corrupt".to_owned())?,
6055 Value::Object(intended),
6056 );
6057 }
6058 }
6059 self.conn.execute("INSERT INTO _syncular_failed_commits(client_commit_id, operations_json, initial_json) VALUES (?1, ?2, ?3)", rusqlite::params![id,
6060 serde_json::to_string(&operations.iter().map(CommitOperation::from).collect::<Vec<_>>()).map_err(|_| "sync.local_corrupt".to_owned())?,
6061 serde_json::to_string(&initial).map_err(|_| "sync.local_corrupt".to_owned())?])
6062 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6063 self.failed_commits.push((
6064 OutboxCommit {
6065 client_commit_id: id.to_owned(),
6066 ops: operations.to_vec(),
6067 },
6068 initial,
6069 ));
6070 Ok(())
6071 }
6072
6073 fn drop_failed_commits(
6074 &mut self,
6075 matches: impl Fn(&str, &Map<String, Value>) -> bool,
6076 ) -> Result<Vec<OutboxCommit>, String> {
6077 let mut doomed = self.drop_acknowledged_rows(&matches)?;
6078 for (commit, initial) in self.failed_commits.iter() {
6079 for operation in &commit.ops {
6080 let key =
6081 serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
6082 .map_err(|_| "sync.local_corrupt".to_owned())?;
6083 if initial
6084 .get(&key)
6085 .and_then(Value::as_object)
6086 .is_some_and(|values| matches(&operation.table, values))
6087 {
6088 doomed.push(commit.clone());
6089 break;
6090 }
6091 }
6092 }
6093 for commit in &doomed {
6094 self.conn
6095 .execute(
6096 "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
6097 rusqlite::params![commit.client_commit_id],
6098 )
6099 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6100 }
6101 for commit in &doomed {
6102 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))?;
6103 }
6104 self.conflicts.retain(|record| {
6105 !doomed
6106 .iter()
6107 .any(|commit| commit.client_commit_id == record.client_commit_id)
6108 });
6109 self.rejections.retain(|record| {
6110 !doomed
6111 .iter()
6112 .any(|commit| commit.client_commit_id == record.client_commit_id)
6113 });
6114 self.failed_commits.retain(|(commit, _)| {
6115 !doomed
6116 .iter()
6117 .any(|dropped| dropped.client_commit_id == commit.client_commit_id)
6118 });
6119 for commit in &doomed {
6120 for operation in &commit.ops {
6121 self.overlay_dirty.table(&operation.table);
6122 }
6123 }
6124 Ok(doomed)
6125 }
6126
6127 pub fn mutate(&mut self, mutations: Vec<Mutation>) -> Result<String, ClientError> {
6131 self.mutate_with_commit_id(mutations, None)
6132 }
6133
6134 pub fn mutate_with_commit_id(
6138 &mut self,
6139 mutations: Vec<Mutation>,
6140 client_commit_id: Option<String>,
6141 ) -> Result<String, ClientError> {
6142 let prior = self.storage_failure.borrow_mut().take();
6143 if let Some(id) = &client_commit_id {
6144 let held = if id.is_empty() {
6145 Err("sync.invalid_request: clientCommitId is empty".to_owned())
6146 } else {
6147 self.conn
6148 .query_row(
6149 "SELECT EXISTS(SELECT 1 FROM _syncular_outbox WHERE commit_id=?1 UNION ALL SELECT 1 FROM _syncular_commit_outcomes WHERE client_commit_id=?1)",
6150 [id],
6151 |row| row.get(0),
6152 )
6153 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
6154 };
6155 match held {
6156 Ok(false) => {}
6157 Ok(true) => {
6158 return self.finish_authoring(
6159 prior,
6160 Err(ClientError {
6161 code: "client.commit_id_reused".to_owned(),
6162 message: "clientCommitId is held".to_owned(),
6163 details: Some(json!({ "clientCommitId": id })),
6164 retryable: false,
6165 }),
6166 )
6167 }
6168 Err(message) => return self.finish_authoring(prior, Err(message.into())),
6169 }
6170 }
6171 let outcome = self
6172 .prepare_mutations(mutations)
6173 .and_then(|ops| Ok(self.record_outbox_commit(ops, client_commit_id, None)?));
6174 self.finish_authoring(prior, outcome)
6175 }
6176
6177 fn prepare_mutations(&self, mutations: Vec<Mutation>) -> Result<Vec<OutboxOp>, ClientError> {
6179 {
6180 if mutations.is_empty() {
6181 return Err(
6182 "sync.invalid_request: a commit must contain at least one operation (§6.1)"
6183 .to_owned()
6184 .into(),
6185 );
6186 }
6187 let mut ops = Vec::with_capacity(mutations.len());
6188 let mut staged: HashMap<(String, String), Option<Map<String, Value>>> = HashMap::new();
6193 for mutation in mutations {
6194 match mutation {
6195 Mutation::Patch {
6196 table,
6197 values,
6198 base_version,
6199 } => {
6200 let schema_table = self
6201 .schema
6202 .table(&table)
6203 .ok_or_else(|| "sync.unknown_table".to_owned())?;
6204 let values = normalize_values_casing(schema_table, values)?;
6205 let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
6206 let base = staged.get(&(table.clone(), row_id.clone()));
6207 ops.push(self.prepare_patch(
6208 &table,
6209 &row_id,
6210 values,
6211 base_version,
6212 base,
6213 )?);
6214 }
6215 Mutation::Upsert {
6216 table,
6217 values,
6218 base_version,
6219 } => {
6220 let schema_table = self.schema.table(&table).ok_or_else(|| {
6221 format!("sync.unknown_table: unknown table {table:?}")
6222 })?;
6223 let values = normalize_values_casing(schema_table, values)?;
6227 let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
6228 let values = full_row_values(schema_table, values)?;
6231 self.refuse_sealed_row(schema_table, &row_id)?;
6232 self.validate_author_encode(schema_table, &row_id, &values)?;
6238 let insert = !self.visible_row_exists(schema_table, &row_id)?;
6242 staged.insert((table.clone(), row_id.clone()), Some(values.clone()));
6243 ops.push(OutboxOp {
6244 upsert: true,
6245 table,
6246 row_id,
6247 base_version,
6248 values: Some(values),
6249 insert,
6250 });
6251 }
6252 Mutation::Delete {
6253 table,
6254 row_id,
6255 base_version,
6256 } => {
6257 let schema_table = self.schema.table(&table).ok_or_else(|| {
6258 format!("sync.unknown_table: unknown table {table:?}")
6259 })?;
6260 self.refuse_sealed_row(schema_table, &row_id)?;
6261 if row_id.contains('\0') {
6263 return Err("sync.invalid_request: rowId holds U+0000 (§2.4)"
6264 .to_owned()
6265 .into());
6266 }
6267 staged.insert((table.clone(), row_id.clone()), None);
6268 ops.push(OutboxOp {
6269 upsert: false,
6270 table,
6271 row_id,
6272 base_version,
6273 values: None,
6274 insert: false,
6275 });
6276 }
6277 }
6278 }
6279 Ok(ops)
6280 }
6281 }
6282
6283 fn finish_authoring(
6289 &self,
6290 prior: Option<QueryReadFailure>,
6291 outcome: Result<String, ClientError>,
6292 ) -> Result<String, ClientError> {
6293 let fresh = self.storage_failure.borrow_mut().take();
6294 *self.storage_failure.borrow_mut() = fresh.clone().or(prior);
6295 outcome.map_err(|error| fresh.map(ClientError::from).unwrap_or(error))
6296 }
6297
6298 fn record_outbox_commit(
6301 &mut self,
6302 ops: Vec<OutboxOp>,
6303 client_commit_id: Option<String>,
6304 decides: Option<&str>,
6305 ) -> Result<String, String> {
6306 let commit = OutboxCommit {
6307 client_commit_id: client_commit_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
6308 ops,
6309 };
6310 self.begin_observation("syncular_mutation")?;
6311 let mut batch = ChangeAccumulator::default();
6312 for op in &commit.ops {
6313 let mut precise = self.record_row_scopes(&mut batch, &op.table, &op.row_id, false);
6314 if let Some(values) = &op.values {
6315 if let Some(table) = self.schema.table(&op.table) {
6316 for scope in &table.scope_variables {
6317 if let Some(Value::String(value)) = values.get(&scope.column) {
6318 batch.scope(&op.table, format!("{}:{value}", scope.prefix));
6319 precise = true;
6320 }
6321 }
6322 }
6323 }
6324 if !precise {
6325 batch.table(&op.table);
6326 }
6327 }
6328 let persisted = self.persist_outbox_insert(&commit).and_then(|()| {
6329 let Some(outcome) = decides else {
6330 return Ok(());
6331 };
6332 batch.outcomes = true;
6333 let updated = self
6334 .conn
6335 .execute(
6336 "UPDATE _syncular_commit_outcomes SET replacement_client_commit_id = ?1
6337 WHERE client_commit_id = ?2 AND resolution = 'active'
6338 AND replacement_client_commit_id IS NULL",
6339 rusqlite::params![commit.client_commit_id, outcome],
6340 )
6341 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6342 if updated == 1 {
6343 Ok(())
6344 } else {
6345 Err(REPLACEMENT_PENDING.to_owned())
6346 }
6347 });
6348 if let Err(error) = persisted {
6349 self.rollback_observation("syncular_mutation");
6350 return Err(error);
6351 }
6352 let was_dirty = self.overlay_dirty.snapshot();
6358 let id = commit.client_commit_id.clone();
6359 let appended = self.rebuild_overlay_if_dirty().and_then(|()| {
6360 commit
6361 .ops
6362 .iter()
6363 .try_for_each(|op| self.apply_outbox_op(op))?;
6364 self.outbox.push(Arc::new(commit));
6365 batch.status = true;
6366 self.finish_observation("syncular_mutation", batch)
6367 .inspect_err(|_| drop(self.outbox.pop()))
6368 });
6369 if let Err(error) = appended {
6370 self.rollback_observation("syncular_mutation");
6371 self.overlay_dirty.restore(was_dirty);
6372 return Err(error);
6373 }
6374 Ok(id)
6375 }
6376
6377 pub fn patch(
6383 &mut self,
6384 table: &str,
6385 row_id: &str,
6386 partial: Map<String, Value>,
6387 base_version: Option<i64>,
6388 ) -> Result<String, ClientError> {
6389 let prior = self.storage_failure.borrow_mut().take();
6390 let outcome = self.perform_patch(table, row_id, partial, base_version);
6391 self.finish_authoring(prior, outcome)
6392 }
6393
6394 fn perform_patch(
6397 &mut self,
6398 table: &str,
6399 row_id: &str,
6400 partial: Map<String, Value>,
6401 base_version: Option<i64>,
6402 ) -> Result<String, ClientError> {
6403 let operation = self.prepare_patch(table, row_id, partial, base_version, None)?;
6404 Ok(self.record_outbox_commit(vec![operation], None, None)?)
6405 }
6406
6407 fn prepare_patch(
6410 &self,
6411 table: &str,
6412 row_id: &str,
6413 partial: Map<String, Value>,
6414 base_version: Option<i64>,
6415 staged: Option<&Option<Map<String, Value>>>,
6416 ) -> Result<OutboxOp, ClientError> {
6417 let schema_table = self
6418 .schema
6419 .table(table)
6420 .ok_or_else(|| format!("sync.unknown_table: unknown table {table:?}"))?;
6421 let partial = normalize_values_casing(schema_table, partial)?;
6422 if let Some(pk) = partial.get(&schema_table.primary_key) {
6423 if render_row_id_json(Some(pk)).ok().as_deref() != Some(row_id) {
6424 return Err(invalid_authoring(
6425 "patch cannot change the primary key",
6426 json!({ "table": table }),
6427 ));
6428 }
6429 }
6430 let exists = match staged {
6431 Some(row) => row.is_some(),
6432 None => self.visible_row_exists(schema_table, row_id)?,
6433 };
6434 if !exists {
6435 return Err("sync.row_missing: a sparse patch requires a local row"
6436 .to_owned()
6437 .into());
6438 }
6439 self.refuse_sealed_row(schema_table, row_id)?;
6440 for scope in &schema_table.scope_variables {
6450 if !partial.contains_key(&scope.column) || scope.column == schema_table.primary_key {
6451 continue;
6452 }
6453 let Some(column) = schema_table
6454 .columns
6455 .iter()
6456 .find(|column| column.name == scope.column)
6457 else {
6458 continue;
6459 };
6460 let stored = match staged {
6461 Some(row) => row.as_ref().and_then(|row| {
6462 json_to_column_value(column, row.get(&scope.column))
6463 .ok()
6464 .map(|value| column_value_to_json(&value))
6465 }),
6466 None => self
6467 .conn
6468 .query_row(
6469 &format!(
6470 "SELECT {} FROM {} WHERE {}",
6471 quote_ident(&scope.column),
6472 visible_table(&schema_table.name),
6473 row_id_predicate(schema_table)
6474 ),
6475 rusqlite::params![row_id],
6476 |row| Ok(sql_ref_to_json(column, row.get_ref(0)?)),
6477 )
6478 .optional()
6479 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
6480 };
6481 let incoming = json_to_column_value(column, partial.get(&scope.column))
6486 .ok()
6487 .map(|value| column_value_to_json(&value));
6488 let equal = stored.as_ref().is_some_and(|stored| {
6492 stored.get("$bytes").is_none() && incoming.as_ref() == Some(stored)
6493 });
6494 if !equal {
6495 return Err(invalid_authoring(
6496 "patch cannot write a scope column (§3.4)",
6497 json!({ "table": table, "column": scope.column }),
6498 ));
6499 }
6500 }
6501 let mut values = partial;
6502 for scope in &schema_table.scope_variables {
6505 values.remove(&scope.column);
6506 }
6507 let pk_value = match schema_table.columns[schema_table.pk_index].ty {
6508 ColumnType::Integer => match row_id.parse::<i64>() {
6510 Ok(v)
6511 if v.to_string() == row_id
6512 && (-ssp2::primitives::I64_SAFE_MAX..=ssp2::primitives::I64_SAFE_MAX)
6513 .contains(&v) =>
6514 {
6515 Value::from(v)
6516 }
6517 _ => {
6518 return Err(format!(
6519 "sync.invalid_request: table {table:?}: invalid integer primary key {row_id:?}"
6520 )
6521 .into())
6522 }
6523 },
6524 ColumnType::Boolean => match row_id {
6525 "true" => Value::Bool(true),
6526 "false" => Value::Bool(false),
6527 _ => {
6528 return Err(format!(
6529 "sync.invalid_request: table {table:?}: invalid boolean primary key {row_id:?}"
6530 )
6531 .into())
6532 }
6533 },
6534 _ => Value::from(row_id.to_owned()),
6535 };
6536 values.insert(schema_table.primary_key.clone(), pk_value);
6537 if let Some(column) = schema_table
6539 .columns
6540 .iter()
6541 .find(|column| !column.nullable && values.get(&column.name) == Some(&Value::Null))
6542 {
6543 return Err(invalid_authoring(
6544 "a non-nullable column is null (§6.1)",
6545 json!({ "table": table, "column": column.name }),
6546 ));
6547 }
6548 self.validate_author_encode(schema_table, row_id, &values)?;
6554 Ok(OutboxOp {
6555 upsert: true,
6556 table: table.to_owned(),
6557 row_id: row_id.to_owned(),
6558 base_version,
6559 values: Some(values),
6560 insert: false,
6561 })
6562 }
6563
6564 fn stored_key_fallback(
6569 &self,
6570 table: &TableSchema,
6571 row_id: &str,
6572 ) -> Result<Option<Row>, String> {
6573 let Some(selector) = self.encryption.key_id_columns.get(&table.name) else {
6574 return Ok(None);
6575 };
6576 let Some(index) = table
6577 .columns
6578 .iter()
6579 .position(|column| &column.name == selector)
6580 else {
6581 return Ok(None);
6582 };
6583 let sql = format!(
6584 "SELECT {} FROM {} WHERE {}",
6585 quote_ident(selector),
6586 visible_table(&table.name),
6587 row_id_predicate(table)
6588 );
6589 let key = self
6590 .conn
6591 .query_row(&sql, rusqlite::params![row_id], |row| {
6592 row.get::<_, Option<String>>(0)
6593 })
6594 .optional()
6595 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6596 .flatten()
6597 .filter(|key| !key.is_empty());
6598 let Some(key) = key else {
6599 return Ok(None);
6600 };
6601 let mut fallback: Row = vec![None; table.columns.len()];
6602 fallback[index] = Some(ColumnValue::String(key));
6603 Ok(Some(fallback))
6604 }
6605
6606 fn validate_author_encode(
6611 &self,
6612 table: &TableSchema,
6613 row_id: &str,
6614 values: &Map<String, Value>,
6615 ) -> Result<(), String> {
6616 match encode_sparse_row_json(table, row_id, values, &self.encryption, None) {
6617 Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => Ok(()),
6618 result => result.map(|_| ()),
6619 }
6620 }
6621
6622 fn drop_unencodable_outbox(
6636 &mut self,
6637 with_encryption: bool,
6638 batch: Option<&mut ChangeAccumulator>,
6639 ) -> Result<bool, String> {
6640 let mut failures = Vec::new();
6641 for commit in self.outbox.iter() {
6642 for op in &commit.ops {
6643 let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6644 continue;
6645 };
6646 let Some(values) = op.presented_values(table) else {
6649 continue;
6650 };
6651 let fallback = self.stored_key_fallback(table, &op.row_id)?;
6652 let failure = match encode_sparse_row_json(
6653 table,
6654 &op.row_id,
6655 &values,
6656 &self.encryption,
6657 fallback.as_ref(),
6658 ) {
6659 Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => {
6660 with_encryption.then_some((error, ENCRYPT_FAILED_CODE))
6661 }
6662 Err(error) if error.starts_with(INVALID_REQUEST_CODE) => Some((
6667 LEGACY_VALUE_REFUSAL_MESSAGE.to_owned(),
6668 OUTBOX_INCOMPATIBLE_CODE,
6669 )),
6670 _ => None,
6671 };
6672 if let Some((error, code)) = failure {
6673 failures.push((commit.clone(), error, code));
6674 break;
6675 }
6676 }
6677 }
6678 if failures.is_empty() {
6679 return Ok(false);
6680 }
6681 self.reject_outbox_commits(
6682 failures
6683 .into_iter()
6684 .map(|(commit, message, code)| {
6685 let details = (code == OUTBOX_INCOMPATIBLE_CODE).then(|| RejectionDetails {
6686 field_paths: None,
6687 reason: Some(INVALID_STORED_VALUES_REASON.to_owned()),
6688 required_action: None,
6689 references: None,
6690 });
6691 (commit, message, code, details)
6692 })
6693 .collect(),
6694 batch,
6695 )?;
6696 Ok(true)
6697 }
6698
6699 #[allow(clippy::type_complexity)]
6703 fn reject_outbox_commits(
6704 &mut self,
6705 failures: Vec<(
6706 Arc<OutboxCommit>,
6707 String,
6708 &'static str,
6709 Option<RejectionDetails>,
6710 )>,
6711 batch: Option<&mut ChangeAccumulator>,
6712 ) -> Result<(), String> {
6713 let rollback = self.capture();
6719 let owns_observation = batch.is_none();
6720 let owns_transaction = self.conn.is_autocommit();
6721 let mut domains = ChangeAccumulator::default();
6722 if owns_observation {
6723 self.begin_observation("syncular_value_recovery")?;
6724 }
6725 let dropped = (|| -> Result<(), String> {
6726 for (commit, message, code, details) in failures {
6727 if self.retain_failed_commits && code != OUTBOX_INCOMPATIBLE_CODE {
6728 self.retain_failed_commit(&commit.client_commit_id, &commit.ops)?;
6729 }
6730 let representable = commit.ops.iter().all(Self::outbox_op_is_journalable);
6731 let rejection = RejectionRecord {
6732 client_commit_id: commit.client_commit_id.clone(),
6733 op_index: 0,
6734 code: code.to_owned(),
6735 message,
6736 retryable: false,
6737 details,
6738 operation: representable
6739 .then(|| commit.ops.first())
6740 .flatten()
6741 .map(CommitOperation::from),
6742 };
6743 self.persist_commit_outcome(
6744 &commit.client_commit_id,
6745 CommitOutcomeStatus::Rejected,
6746 &[CommitOperationOutcome::Error {
6747 rejection: rejection.clone(),
6748 }],
6749 representable.then_some(commit.ops.as_slice()),
6750 )?;
6751 self.delete_outbox_persisted(&commit.client_commit_id)?;
6752 self.outbox
6753 .retain(|candidate| candidate.client_commit_id != commit.client_commit_id);
6754 self.rejections.push(rejection);
6755 for operation in &commit.ops {
6756 domains.table(operation.table.as_str());
6757 }
6758 }
6759 domains.status = true;
6760 domains.rejections = true;
6761 domains.outcomes = true;
6762 self.prune_commit_outcomes()?;
6763 self.overlay_dirty.set(true);
6765 self.rebuild_overlay()?;
6766 Ok(())
6767 })();
6768 let result = match batch {
6769 Some(batch) => {
6770 if dropped.is_ok() {
6771 for table in domains.tables.keys() {
6772 batch.table(table.as_str());
6773 }
6774 batch.status |= domains.status;
6775 batch.rejections |= domains.rejections;
6776 batch.outcomes |= domains.outcomes;
6777 }
6778 dropped
6779 }
6780 None => {
6781 dropped.and_then(|()| self.finish_observation("syncular_value_recovery", domains))
6782 }
6783 };
6784 if let Err(error) = result {
6785 if owns_observation {
6786 if owns_transaction {
6787 if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
6788 let mut failure = self.storage_failure.borrow_mut();
6789 let failure =
6790 failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
6791 failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
6792 }
6793 } else {
6794 self.rollback_observation("syncular_value_recovery");
6795 }
6796 }
6797 self.restore(rollback);
6798 return Err(error);
6799 }
6800 Ok(())
6801 }
6802
6803 pub fn pending_commit_ids(&self) -> Vec<String> {
6804 self.outbox
6805 .iter()
6806 .map(|c| c.client_commit_id.clone())
6807 .collect()
6808 }
6809
6810 pub fn pending_commits(&self) -> Result<Vec<PendingCommit>, String> {
6813 let mut stmt = self
6814 .conn
6815 .prepare_cached(
6816 "SELECT seq, commit_id, created_at_ms, ops_json FROM _syncular_outbox ORDER BY seq",
6817 )
6818 .map_err(|error| error.to_string())?;
6819 let rows = stmt
6820 .query_map([], |row| {
6821 Ok((
6822 row.get(0)?,
6823 row.get(1)?,
6824 row.get(2)?,
6825 row.get::<_, String>(3)?,
6826 ))
6827 })
6828 .map_err(|error| error.to_string())?;
6829 rows.map(|row| {
6830 let (seq, client_commit_id, created_at_ms, raw) =
6831 row.map_err(|error| error.to_string())?;
6832 let operations = serde_json::from_str(&raw).map_err(|error| {
6833 format!("invalid persisted outbox {client_commit_id:?}: {error}")
6834 })?;
6835 Ok(PendingCommit {
6836 seq,
6837 client_commit_id,
6838 created_at_ms,
6839 operations,
6840 })
6841 })
6842 .collect()
6843 }
6844
6845 pub fn pending_payloads(&self) -> Result<Vec<Vec<u8>>, String> {
6849 let mut payloads = Vec::new();
6850 for commit in self.outbox.iter() {
6851 for op in &commit.ops {
6852 let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6853 continue;
6854 };
6855 let Some(values) = op.presented_values(table) else {
6856 continue;
6857 };
6858 let fallback = self.stored_key_fallback(table, &op.row_id)?;
6859 if let Ok(payload) = encode_sparse_row_json(
6860 table,
6861 &op.row_id,
6862 &values,
6863 &self.encryption,
6864 fallback.as_ref(),
6865 ) {
6866 payloads.push(payload);
6867 }
6868 }
6869 }
6870 Ok(payloads)
6871 }
6872
6873 pub fn conflicts(&self) -> &[ConflictRecord] {
6874 &self.conflicts
6875 }
6876
6877 pub fn rejections(&self) -> &[RejectionRecord] {
6878 &self.rejections
6879 }
6880
6881 pub fn resolve_commit_outcome(
6882 &mut self,
6883 input: ResolveCommitOutcomeInput,
6884 ) -> Result<CommitOutcome, String> {
6885 let current = self
6886 .commit_outcome(&input.client_commit_id)?
6887 .ok_or_else(|| {
6888 format!(
6889 "sync.outcome_not_found: no durable outcome exists for {:?}",
6890 input.client_commit_id
6891 )
6892 })?;
6893 if current.resolution != CommitOutcomeResolution::Active {
6894 return Ok(current);
6895 }
6896 if current.replacement_client_commit_id.is_some() {
6897 return Err(REPLACEMENT_PENDING.to_owned());
6898 }
6899 if input.resolution == CommitOutcomeResolution::Active {
6900 return Err("sync.invalid_request: resolution must leave active state".to_owned());
6901 }
6902 match input.resolution {
6903 CommitOutcomeResolution::Superseded => {
6904 let replacement = input
6905 .replacement_client_commit_id
6906 .as_deref()
6907 .filter(|value| !value.is_empty() && *value != input.client_commit_id)
6908 .ok_or_else(|| {
6909 "sync.invalid_request: superseded outcomes require a distinct replacementClientCommitId"
6910 .to_owned()
6911 })?;
6912 let _ = replacement;
6913 }
6914 _ if input.replacement_client_commit_id.is_some() => {
6915 return Err(
6916 "sync.invalid_request: replacementClientCommitId is valid only for superseded outcomes"
6917 .to_owned(),
6918 );
6919 }
6920 _ => {}
6921 }
6922 let allowed = match current.status {
6923 CommitOutcomeStatus::Conflict => matches!(
6924 input.resolution,
6925 CommitOutcomeResolution::ResolvedKeepServer | CommitOutcomeResolution::Superseded
6926 ),
6927 CommitOutcomeStatus::Rejected => {
6928 matches!(
6929 input.resolution,
6930 CommitOutcomeResolution::Superseded
6931 | CommitOutcomeResolution::ResolvedKeepServer
6932 )
6933 }
6934 CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => {
6935 input.resolution == CommitOutcomeResolution::Dismissed
6936 }
6937 };
6938 if !allowed {
6939 return Err(format!(
6940 "sync.invalid_request: resolution {:?} is invalid for {:?} outcome",
6941 input.resolution, current.status
6942 ));
6943 }
6944
6945 let rollback = self.capture();
6946 self.begin_observation("syncular_outcome_resolution")?;
6947 let mut batch = ChangeAccumulator::default();
6948 let result = self
6949 .release_outcome(
6950 ¤t,
6951 input.resolution,
6952 input.replacement_client_commit_id.as_deref(),
6953 &mut batch,
6954 )
6955 .and_then(|()| self.rebuild_overlay_if_dirty())
6956 .and_then(|()| self.finish_observation("syncular_outcome_resolution", batch));
6957 if let Err(error) = result {
6958 self.rollback_observation("syncular_outcome_resolution");
6959 self.restore(rollback);
6960 return Err(error);
6961 }
6962 self.commit_outcome(¤t.client_commit_id)?
6963 .ok_or_else(|| "sync.outcome_not_found: outcome disappeared".to_owned())
6964 }
6965
6966 pub fn replace_commit_outcome(
6971 &mut self,
6972 client_commit_id: &str,
6973 sequence: i64,
6974 replacement: Option<Vec<Mutation>>,
6975 ) -> Result<String, ClientError> {
6976 let prior = self.storage_failure.borrow_mut().take();
6977 let outcome = (|| -> Result<String, ClientError> {
6978 let Some(current) = self.commit_outcome(client_commit_id)? else {
6979 return Err(ClientError {
6980 code: "sync.outcome_not_found".to_owned(),
6981 message: "no durable outcome exists for the commit".to_owned(),
6982 details: Some(json!({ "clientCommitId": client_commit_id })),
6983 retryable: false,
6984 });
6985 };
6986 if current.resolution == CommitOutcomeResolution::Active
6987 && current.replacement_client_commit_id.is_some()
6988 {
6989 return Err(ClientError {
6990 code: "client.replacement_pending".to_owned(),
6991 message: "the outcome has a pending replacement".to_owned(),
6992 details: Some(json!({ "clientCommitId": client_commit_id })),
6993 retryable: false,
6994 });
6995 }
6996 let (Some(envelope), Some(rows)) = (current.operations, current.retained_rows) else {
6997 return Err(invalid_authoring(
6998 "the outcome cannot be replaced",
6999 json!({ "clientCommitId": client_commit_id }),
7000 ));
7001 };
7002 if current.sequence != sequence
7003 || current.resolution != CommitOutcomeResolution::Active
7004 || !matches!(
7005 current.status,
7006 CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
7007 )
7008 || rows.is_empty()
7009 || envelope.len() != rows.len()
7010 {
7011 return Err(invalid_authoring(
7012 "the outcome cannot be replaced",
7013 json!({ "clientCommitId": client_commit_id }),
7014 ));
7015 }
7016 let ops = match replacement {
7017 None => envelope
7018 .into_iter()
7019 .zip(&rows)
7020 .map(|(operation, row)| OutboxOp {
7021 base_version: Some(row.server_version.unwrap_or(0)),
7022 ..OutboxOp::from(operation)
7023 })
7024 .collect(),
7025 Some(mutations) => {
7026 let mut ops = self.prepare_mutations(mutations)?;
7027 for op in &mut ops {
7028 let Some(row) = rows
7029 .iter()
7030 .find(|row| row.table == op.table && row.row_id == op.row_id)
7031 else {
7032 continue;
7033 };
7034 if op.base_version.is_some() {
7035 return Err(invalid_authoring(
7036 "an operation on a retained row takes its base version",
7037 json!({ "table": op.table }),
7038 ));
7039 }
7040 op.base_version = Some(row.server_version.unwrap_or(0));
7041 }
7042 ops
7043 }
7044 };
7045 Ok(self.record_outbox_commit(ops, None, Some(client_commit_id))?)
7046 })();
7047 self.finish_authoring(prior, outcome)
7048 }
7049
7050 #[doc(hidden)]
7053 pub fn prepare_replacements(&self) -> Result<Vec<CurrentBasePreparation>, String> {
7054 let mut stmt = self
7055 .conn
7056 .prepare_cached(
7057 "SELECT client_commit_id, seq, replacement_client_commit_id
7058 FROM _syncular_commit_outcomes
7059 WHERE resolution = 'active' AND replacement_client_commit_id IS NOT NULL
7060 ORDER BY seq ASC",
7061 )
7062 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7063 let decisions = stmt
7064 .query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))
7065 .and_then(|rows| rows.collect::<Result<Vec<(String, i64, String)>, _>>())
7066 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7067 if decisions.is_empty() {
7068 return Ok(Vec::new());
7069 }
7070 let units = self.stored(load_units(&self.conn))?;
7071 Ok(decisions
7072 .into_iter()
7073 .map(
7074 |(client_commit_id, sequence, replacement)| CurrentBasePreparation {
7075 client_commit_id,
7076 sequence,
7077 replacement: Some(replacement),
7078 units: units.clone(),
7079 transport_epoch: self.transport_epoch,
7080 registration_epoch: self.registration_epoch,
7081 security_epoch: self.security_epoch,
7082 },
7083 )
7084 .collect())
7085 }
7086
7087 #[doc(hidden)]
7091 pub fn settle_replacements(
7092 &mut self,
7093 decisions: &[CurrentBasePreparation],
7094 drive: &SyncOutcome,
7095 ) -> Result<bool, String> {
7096 if !self.transport_enabled {
7097 return Ok(false);
7098 }
7099 let mut written = false;
7100 for decision in decisions {
7101 if decision.registration_epoch != self.registration_epoch {
7104 continue;
7105 }
7106 let Some(replacement) = decision.replacement.as_deref() else {
7107 continue;
7108 };
7109 let Some(current) =
7110 self.commit_outcome(&decision.client_commit_id)?
7111 .filter(|current| {
7112 current.resolution == CommitOutcomeResolution::Active
7113 && current.replacement_client_commit_id.as_deref() == Some(replacement)
7114 })
7115 else {
7116 continue;
7117 };
7118 let held = self
7119 .outbox
7120 .iter()
7121 .find(|commit| commit.client_commit_id == replacement)
7122 .cloned();
7123 let refused = match &held {
7124 None => None,
7127 Some(commit) => match self.finish_current_base(decision.clone(), drive.clone()) {
7128 CurrentBaseProof {
7129 rows: Some(rows), ..
7130 } => {
7131 let proven = commit.ops.iter().all(|op| {
7132 rows.iter()
7133 .find(|row| row.table == op.table && row.row_id == op.row_id)
7134 .is_none_or(|row| {
7135 op.base_version == Some(row.server_version.unwrap_or(0))
7136 })
7137 });
7138 written |= proven;
7139 (!proven).then(|| "base_moved".to_owned())
7140 }
7141 CurrentBaseProof {
7142 reason:
7143 Some(
7144 reason @ (CurrentBaseProofReason::SchemaFloor
7145 | CurrentBaseProofReason::MissingCoverage
7146 | CurrentBaseProofReason::Revoked
7147 | CurrentBaseProofReason::OutcomeUnavailable),
7148 ),
7149 ..
7150 } => Some(
7151 serde_json::to_value(reason)
7152 .ok()
7153 .and_then(|reason| reason.as_str().map(str::to_owned))
7154 .ok_or("sync.local_corrupt")?,
7155 ),
7156 _ => continue,
7157 },
7158 };
7159 let rollback = self.capture();
7163 self.begin_observation("syncular_replacement")?;
7164 let mut batch = ChangeAccumulator::default();
7165 let result = self
7166 .release_outcome(
7167 ¤t,
7168 CommitOutcomeResolution::Superseded,
7169 Some(replacement),
7170 &mut batch,
7171 )
7172 .and_then(|()| self.rebuild_overlay_if_dirty())
7173 .and_then(|()| match (refused, held) {
7174 (Some(reason), Some(commit)) => self.reject_outbox_commits(
7175 vec![(
7176 commit,
7177 "the replacement could not be written on a proven base".to_owned(),
7178 REPLACEMENT_REFUSED_CODE,
7179 Some(RejectionDetails {
7180 field_paths: None,
7181 reason: Some(reason),
7182 required_action: None,
7183 references: None,
7184 }),
7185 )],
7186 Some(&mut batch),
7187 ),
7188 _ => Ok(()),
7189 })
7190 .and_then(|()| self.finish_observation("syncular_replacement", batch));
7191 if let Err(error) = result {
7192 self.rollback_observation("syncular_replacement");
7193 self.restore(rollback);
7194 return Err(error);
7195 }
7196 }
7197 if written {
7198 self.set_sync_needed(true, true);
7199 }
7200 Ok(written)
7201 }
7202
7203 fn release_outcome(
7208 &mut self,
7209 current: &CommitOutcome,
7210 resolution: CommitOutcomeResolution,
7211 replacement: Option<&str>,
7212 batch: &mut ChangeAccumulator,
7213 ) -> Result<(), String> {
7214 self.conn
7215 .execute(
7216 "UPDATE _syncular_commit_outcomes
7217 SET resolution = ?1, resolved_at_ms = ?2,
7218 replacement_client_commit_id = ?3
7219 WHERE client_commit_id = ?4 AND resolution = 'active'",
7220 rusqlite::params![
7221 Self::outcome_resolution_name(resolution),
7222 self.clock_now_ms(),
7223 replacement,
7224 current.client_commit_id
7225 ],
7226 )
7227 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7228 self.conn
7229 .execute(
7230 "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
7231 rusqlite::params![current.client_commit_id],
7232 )
7233 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7234 for (commit, _) in self.failed_commits.iter() {
7235 if commit.client_commit_id == current.client_commit_id {
7236 for operation in &commit.ops {
7237 self.overlay_dirty.table(&operation.table);
7238 }
7239 }
7240 }
7241 self.failed_commits
7242 .retain(|(commit, _)| commit.client_commit_id != current.client_commit_id);
7243 self.prune_commit_outcomes()?;
7244 self.conflicts
7245 .retain(|record| record.client_commit_id != current.client_commit_id);
7246 self.rejections
7247 .retain(|record| record.client_commit_id != current.client_commit_id);
7248 batch.conflicts |= current.status == CommitOutcomeStatus::Conflict;
7249 batch.rejections |= current.status == CommitOutcomeStatus::Rejected;
7250 batch.outcomes = true;
7251 for operation in current.operations.iter().flatten() {
7252 batch.table(&operation.table);
7253 }
7254 Ok(())
7255 }
7256
7257 pub fn schema_floor(&self) -> Option<&SchemaFloor> {
7258 self.schema_floor.as_ref()
7259 }
7260
7261 pub fn lease_state(&self) -> Option<&LeaseState> {
7263 self.lease_state.as_ref()
7264 }
7265
7266 fn record_lease_error(&mut self, code: &str) -> Result<(), String> {
7269 if code != "sync.auth_lease_required" && code != "sync.auth_lease_revoked" {
7270 return Ok(());
7271 }
7272 let mut next = self.lease_state.clone().unwrap_or_default();
7273 next.error_code = Some(code.to_owned());
7274 self.set_lease_state(Some(next))
7275 }
7276
7277 fn set_lease_state(&mut self, next: Option<LeaseState>) -> Result<(), String> {
7278 if self.lease_state == next {
7279 return Ok(());
7280 }
7281 self.begin_observation("syncular_lease")?;
7282 let rollback = self.capture();
7283 self.lease_state = next;
7284 let persisted = match &self.lease_state {
7285 Some(lease) => serde_json::to_string(lease)
7286 .map_err(|error| error.to_string())
7287 .and_then(|json| self.set_meta(LEASE_STATE_KEY, &json)),
7288 None => self.delete_meta(LEASE_STATE_KEY),
7289 };
7290 let batch = ChangeAccumulator {
7291 status: true,
7292 ..ChangeAccumulator::default()
7293 };
7294 if let Err(error) =
7295 persisted.and_then(|()| self.finish_observation("syncular_lease", batch))
7296 {
7297 self.rollback_observation("syncular_lease");
7298 self.restore(rollback);
7299 return Err(error);
7300 }
7301 Ok(())
7302 }
7303
7304 fn set_schema_floor(&mut self, next: Option<SchemaFloor>) -> Result<(), String> {
7305 if self.schema_floor == next {
7306 return Ok(());
7307 }
7308 self.begin_observation("syncular_schema_floor")?;
7309 let rollback = self.capture();
7310 self.stopped = next.is_some();
7311 self.schema_floor = next;
7312 let persisted = match &self.schema_floor {
7313 Some(floor) => serde_json::to_string(floor)
7314 .map_err(|error| error.to_string())
7315 .and_then(|json| self.set_meta(SCHEMA_FLOOR_KEY, &json)),
7316 None => self.delete_meta(SCHEMA_FLOOR_KEY),
7317 };
7318 let batch = ChangeAccumulator {
7319 status: true,
7320 ..ChangeAccumulator::default()
7321 };
7322 if let Err(error) =
7323 persisted.and_then(|()| self.finish_observation("syncular_schema_floor", batch))
7324 {
7325 self.rollback_observation("syncular_schema_floor");
7326 self.restore(rollback);
7327 return Err(error);
7328 }
7329 Ok(())
7330 }
7331
7332 fn set_upgrading(&mut self, value: bool) {
7333 if self.upgrading == value {
7334 return;
7335 }
7336 if self.begin_observation("syncular_upgrading").is_err() {
7337 return;
7338 }
7339 self.upgrading = value;
7340 let batch = ChangeAccumulator {
7341 status: true,
7342 ..ChangeAccumulator::default()
7343 };
7344 if self
7345 .finish_observation("syncular_upgrading", batch)
7346 .is_err()
7347 {
7348 self.rollback_observation("syncular_upgrading");
7349 }
7350 }
7351
7352 pub fn sync_needed(&self) -> bool {
7353 self.sync_needed
7354 }
7355
7356 pub fn read_rows(&self, table: &str) -> Result<Vec<RowState>, String> {
7357 let schema_table = self
7358 .schema
7359 .table(table)
7360 .ok_or_else(|| format!("unknown table {table:?}"))?;
7361 let sql = format!(
7362 "SELECT * FROM {} ORDER BY {} ASC",
7363 visible_table(table),
7364 quote_ident(&schema_table.primary_key)
7365 );
7366 let mut stmt = self
7367 .conn
7368 .prepare(&sql)
7369 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7370 let mut rows = stmt
7371 .query([])
7372 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7373 let mut out = Vec::new();
7374 while let Some(row) = rows
7375 .next()
7376 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
7377 {
7378 let mut values = Map::new();
7379 for (i, column) in schema_table.columns.iter().enumerate() {
7380 let value = row
7381 .get_ref(i)
7382 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7383 values.insert(column.name.clone(), sql_ref_to_json(column, value));
7384 }
7385 let version: i64 = row
7386 .get(schema_table.columns.len())
7387 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
7388 let row_id = match values.get(&schema_table.primary_key) {
7389 Some(Value::String(s)) => s.clone(),
7390 Some(Value::Number(n)) => n.to_string(),
7391 Some(Value::Bool(b)) => b.to_string(),
7392 other => format!("{}", other.cloned().unwrap_or(Value::Null)),
7393 };
7394 let sealed_key = if schema_table.has_encrypted_columns() {
7395 row.get(schema_table.columns.len() + 1)
7396 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
7397 } else {
7398 None
7399 };
7400 out.push(RowState {
7401 row_id,
7402 version,
7403 values,
7404 sealed_key,
7405 });
7406 }
7407 Ok(out)
7408 }
7409
7410 #[cfg(feature = "crdt-yjs")]
7426 fn crdt_column_bytes(
7427 &self,
7428 table: &str,
7429 row_id: &str,
7430 column: &str,
7431 ) -> Result<Option<Vec<u8>>, String> {
7432 let schema_table = self
7433 .schema
7434 .table(table)
7435 .ok_or_else(|| format!("unknown table {table:?}"))?;
7436 let col = schema_table
7437 .columns
7438 .iter()
7439 .find(|c| c.name == column)
7440 .ok_or_else(|| format!("table {table:?} has no column {column:?}"))?;
7441 if col.ty != ColumnType::Crdt {
7442 return Err(format!("column {column:?} is not a crdt column (§5.10.1)"));
7443 }
7444 let sql = format!(
7445 "SELECT {} FROM {} WHERE {}",
7446 quote_ident(column),
7447 visible_table(table),
7448 row_id_predicate(schema_table)
7449 );
7450 let bytes: Option<Vec<u8>> = self
7451 .conn
7452 .prepare_cached(&sql)
7453 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
7454 .query_row(rusqlite::params![row_id], |row| {
7455 row.get::<_, Option<Vec<u8>>>(0)
7456 })
7457 .map_err(|e| match e {
7458 rusqlite::Error::QueryReturnedNoRows => "no such row".to_owned(),
7459 other => Self::sqlite_failure(&self.storage_failure, other),
7460 })?;
7461 Ok(bytes)
7462 }
7463
7464 #[cfg(feature = "crdt-yjs")]
7468 pub fn crdt_text(
7469 &self,
7470 table: &str,
7471 row_id: &str,
7472 column: &str,
7473 name: &str,
7474 ) -> Result<String, String> {
7475 let bytes = self
7476 .crdt_column_bytes(table, row_id, column)?
7477 .unwrap_or_default();
7478 crate::crdt::text(&bytes, name)
7479 }
7480
7481 #[cfg(feature = "crdt-yjs")]
7485 pub fn crdt_insert_text(
7486 &mut self,
7487 table: &str,
7488 row_id: &str,
7489 column: &str,
7490 name: &str,
7491 index: u32,
7492 value: &str,
7493 ) -> Result<String, ClientError> {
7494 let prior = self.storage_failure.borrow_mut().take();
7495 let outcome = (|| -> Result<String, ClientError> {
7496 let current = self
7497 .crdt_column_bytes(table, row_id, column)?
7498 .unwrap_or_default();
7499 let update = crate::crdt::insert_text(¤t, name, index, value)?;
7500 self.perform_crdt_push_update(table, row_id, column, &update)
7501 })();
7502 self.finish_authoring(prior, outcome)
7503 }
7504
7505 #[cfg(feature = "crdt-yjs")]
7509 pub fn crdt_delete_text(
7510 &mut self,
7511 table: &str,
7512 row_id: &str,
7513 column: &str,
7514 name: &str,
7515 index: u32,
7516 len: u32,
7517 ) -> Result<String, ClientError> {
7518 let prior = self.storage_failure.borrow_mut().take();
7519 let outcome = (|| -> Result<String, ClientError> {
7520 let current = self
7521 .crdt_column_bytes(table, row_id, column)?
7522 .unwrap_or_default();
7523 let update = crate::crdt::delete_text(¤t, name, index, len)?;
7524 self.perform_crdt_push_update(table, row_id, column, &update)
7525 })();
7526 self.finish_authoring(prior, outcome)
7527 }
7528
7529 #[cfg(feature = "crdt-yjs")]
7534 pub fn crdt_apply_update(
7535 &mut self,
7536 table: &str,
7537 row_id: &str,
7538 column: &str,
7539 update: &[u8],
7540 ) -> Result<String, ClientError> {
7541 let prior = self.storage_failure.borrow_mut().take();
7542 let outcome = (|| -> Result<String, ClientError> {
7543 let current = self
7544 .crdt_column_bytes(table, row_id, column)?
7545 .unwrap_or_default();
7546 let next = crate::crdt::apply_update(¤t, update)?;
7547 self.perform_crdt_push_update(table, row_id, column, &next)
7548 })();
7549 self.finish_authoring(prior, outcome)
7550 }
7551
7552 #[cfg(feature = "crdt-yjs")]
7559 fn perform_crdt_push_update(
7560 &mut self,
7561 table: &str,
7562 row_id: &str,
7563 column: &str,
7564 crdt_bytes: &[u8],
7565 ) -> Result<String, ClientError> {
7566 let mut bytes_obj = Map::new();
7567 bytes_obj.insert("$bytes".to_owned(), Value::from(bytes_to_hex(crdt_bytes)));
7568 let mut partial = Map::new();
7569 partial.insert(column.to_owned(), Value::Object(bytes_obj));
7570 self.perform_patch(table, row_id, partial, None)
7571 }
7572
7573 pub fn query(&self, sql: &str, params: &[QueryValue]) -> Result<Vec<QueryRow>, String> {
7588 query_connection(&self.conn, sql, params).map_err(|failure| failure.to_string())
7589 }
7590
7591 #[cfg(feature = "bench-internals")]
7593 #[doc(hidden)]
7594 pub fn benchmark_connection(&mut self) -> &mut Connection {
7595 &mut self.conn
7596 }
7597
7598 #[cfg(feature = "bench-internals")]
7600 #[doc(hidden)]
7601 pub fn benchmark_phases(
7602 &self,
7603 enabled: Option<bool>,
7604 reset: bool,
7605 ) -> Result<Option<Value>, String> {
7606 self.benchmark_phases.configure(enabled, reset)?;
7607 Ok(self.benchmark_phases.snapshot())
7608 }
7609
7610 pub fn authority_snapshot(&self) -> Result<Value, String> {
7612 validate_authority_reads(&self.schema, &self.limits.authority_reads)?;
7613 if self.limits.authority_reads.is_empty() {
7614 return Err("client.authority_read_forbidden: no authority reads were declared at client creation".into());
7615 }
7616 self.conn
7617 .execute_batch("SAVEPOINT authority_snapshot")
7618 .map_err(|e| e.to_string())?;
7619 let result = (|| {
7620 let revision = self
7621 .get_meta(LOCAL_REVISION_KEY)?
7622 .ok_or("sync.local_corrupt: authority revision is missing")?;
7623 let parsed_revision = revision
7624 .parse::<u64>()
7625 .map_err(|_| "sync.local_corrupt: authority revision is invalid")?;
7626 if parsed_revision.to_string() != revision {
7627 return Err("sync.local_corrupt: authority revision is invalid".into());
7628 }
7629 let mut tables = Vec::new();
7630 for read in &self.limits.authority_reads {
7631 let table = self
7632 .schema
7633 .table(&read.table)
7634 .ok_or("client.authority_read_forbidden: authority table is not declared")?;
7635 let scalar = |column: &str, value: &Value| -> Result<String, String> {
7636 let ty = table
7637 .columns
7638 .iter()
7639 .find(|c| c.name == column)
7640 .expect("validated authority column")
7641 .ty;
7642 if ty == ColumnType::Boolean {
7643 if let Some(value) = value.as_bool() {
7644 return Ok(value.to_string());
7645 }
7646 return match value.as_i64() {
7647 Some(0) => Ok("false".into()),
7648 Some(1) => Ok("true".into()),
7649 _ => Err("sync.local_corrupt: authority boolean is invalid".into()),
7650 };
7651 }
7652 match value {
7653 Value::String(s) => Ok(s.clone()),
7654 Value::Number(n) => Ok(n.to_string()),
7655 Value::Object(o) if ty == ColumnType::Integer && o.len() == 1 => o
7656 .get("$bigint")
7657 .and_then(Value::as_str)
7658 .map(str::to_owned)
7659 .ok_or("sync.local_corrupt: authority integer is invalid".into()),
7660 _ => {
7661 Err("sync.local_corrupt: authority scalar is missing or invalid".into())
7662 }
7663 }
7664 };
7665 let matches = |row: &QueryRow| -> Result<bool, String> {
7666 for (variable, values) in &read.scopes {
7667 let column = table
7668 .scope_column(variable)
7669 .expect("validated authority scope");
7670 let value = row
7671 .get(column)
7672 .ok_or("sync.local_corrupt: authority scope column is missing")?;
7673 if value.is_null() || !values.contains(&scalar(column, value)?) {
7674 return Ok(false);
7675 }
7676 }
7677 Ok(true)
7678 };
7679 let selected = read
7680 .columns
7681 .iter()
7682 .map(|c| quote_ident(c))
7683 .collect::<Vec<_>>()
7684 .join(",");
7685 let mut intent = BTreeSet::new();
7686 let mut relevant = BTreeSet::new();
7687 for row in query_connection(&self.conn,
7688 "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=?",
7689 &[Value::String(read.table.clone())]).map_err(|e| e.to_string())? {
7690 let id = row.get("id").and_then(Value::as_str).ok_or("sync.local_corrupt: authority intent id is invalid")?.to_owned();
7691 intent.insert(id.clone());
7692 if let Some(raw) = row.get("values_json").and_then(Value::as_str) {
7693 let values: QueryRow = serde_json::from_str(raw).map_err(|_| "sync.local_corrupt: authority intent values are invalid")?;
7694 if read.scopes.keys().all(|v| values.contains_key(table.scope_column(v).expect("validated scope"))) && matches(&values)? {relevant.insert(id);}
7695 }
7696 }
7697 let mut rows = BTreeMap::new();
7698 for full in [base_table(&read.table), visible_table(&read.table)] {
7699 for mut values in query_connection(
7700 &self.conn,
7701 &format!(
7702 "SELECT {selected},_syncular_version AS authority_version FROM {full}"
7703 ),
7704 &[],
7705 )
7706 .map_err(|e| e.to_string())?
7707 {
7708 if !matches(&values)? {
7709 continue;
7710 }
7711 let id = scalar(
7712 &table.primary_key,
7713 values
7714 .get(&table.primary_key)
7715 .expect("selected primary key"),
7716 )?;
7717 relevant.insert(id.clone());
7718 if full == base_table(&read.table) {
7719 let version = values
7720 .remove("authority_version")
7721 .expect("selected version");
7722 let version = version
7723 .as_i64()
7724 .ok_or("sync.local_corrupt: authority server version is invalid")?;
7725 if version >= 0 {
7726 rows.insert(id.clone(), json!({"values": values, "version": version, "hasLocalIntent": intent.contains(&id)}));
7727 }
7728 }
7729 }
7730 }
7731 intent.retain(|id| relevant.contains(id));
7732 let rows = rows.into_values().collect::<Vec<_>>();
7733 let replica = self.stored(replica_cursor(&self.conn))?;
7735 let persisted = self
7736 .stored(load_units(&self.conn))?
7737 .into_iter()
7738 .filter(|unit| covers(table, &unit.scopes))
7739 .map(|unit| {
7740 let effective = unit.echo.as_deref().and_then(|echo| {
7741 pair_scopes(&unit.scopes, &read.table, Some(echo))
7742 });
7743 let requested = read
7744 .scopes
7745 .keys()
7746 .map(|v| (v.clone(), json!(unit.scopes.get(v).into_iter().collect::<Vec<_>>())))
7747 .collect::<Map<_, _>>();
7748 let complete = effective
7749 .as_ref()
7750 .is_some_and(|scopes| scopes.len() == read.scopes.len())
7751 && unit.status == UnitStatus::Active
7752 && !unit.bootstrapping();
7753 let exposed = effective.map(|scopes| {
7754 read.scopes
7755 .keys()
7756 .map(|v| {
7757 let held = scopes.iter().find(|(variable, _)| variable == v);
7758 (v.clone(), json!(held.map_or(&Vec::new(), |(_, values)| values)))
7759 })
7760 .collect::<Map<_, _>>()
7761 });
7762 json!({"requestedScopes": requested, "status": unit.status, "cursor": unit.cursor.unwrap_or(replica), "effectiveScopes": exposed, "complete": complete})
7763 })
7764 .collect::<Vec<_>>();
7765 fn covered(selectors: &[(&String, &Vec<String>)], candidates: &[&Value]) -> bool {
7766 match selectors.split_first() {
7767 None => !candidates.is_empty(),
7768 Some(((variable, values), rest)) => values.iter().all(|value| {
7769 covered(
7770 rest,
7771 &candidates
7772 .iter()
7773 .copied()
7774 .filter(|p| {
7775 p["effectiveScopes"][variable.as_str()]
7776 .as_array()
7777 .is_some_and(|held| {
7778 held.contains(&Value::String(value.clone()))
7779 || held.contains(&Value::String("*".into()))
7780 })
7781 })
7782 .collect::<Vec<_>>(),
7783 )
7784 }),
7785 }
7786 }
7787 let coverage = if covered(
7788 &read.scopes.iter().collect::<Vec<_>>(),
7789 &persisted
7790 .iter()
7791 .filter(|p| p["complete"] == true)
7792 .collect::<Vec<_>>(),
7793 ) {
7794 "complete"
7795 } else if persisted.iter().any(|p| {
7796 p["status"] == "active"
7797 && read.scopes.iter().all(|(v, values)| {
7798 values.iter().any(|value| {
7799 p["requestedScopes"][v].as_array().is_some_and(|held| {
7800 held.contains(&Value::String(value.clone()))
7801 })
7802 })
7803 })
7804 }) {
7805 "pending"
7806 } else {
7807 "missing"
7808 };
7809 tables.push(json!({"table": read.table, "rows": rows, "localIntentRowIds": intent, "scopes": read.scopes, "coverage": coverage, "persisted": persisted}));
7810 }
7811 Ok(
7812 json!({"revision": revision, "complete": tables.iter().all(|t| t["coverage"] == "complete"), "tables": tables}),
7813 )
7814 })();
7815 match result {
7816 Ok(snapshot) => {
7817 self.conn
7818 .execute_batch("RELEASE authority_snapshot")
7819 .map_err(|e| e.to_string())?;
7820 Ok(snapshot)
7821 }
7822 Err(error) => {
7823 self.conn
7824 .execute_batch("ROLLBACK TO authority_snapshot; RELEASE authority_snapshot")
7825 .map_err(|e| format!("{error}; rollback failed: {e}"))?;
7826 Err(error)
7827 }
7828 }
7829 }
7830
7831 pub fn query_snapshot(
7835 &mut self,
7836 sql: &str,
7837 params: &[QueryValue],
7838 coverage: &[WindowCoverage],
7839 owner: Option<QueryOwner<'_>>,
7840 ) -> Result<QuerySnapshot, String> {
7841 let result = snapshot_connection(&self.conn, sql, params, coverage);
7842 if let Some(owner) = owner {
7843 self.record_query_read(owner, result.as_ref().err());
7844 }
7845 result.map_err(|failure| failure.to_string())
7846 }
7847
7848 pub fn record_query_read(&mut self, owner: QueryOwner<'_>, failure: Option<&QueryReadFailure>) {
7852 let position = self
7853 .query_failures
7854 .iter()
7855 .position(|entry| entry.id == owner.id);
7856 let Some(failure) = failure else {
7857 if let Some(index) = position {
7858 self.query_failures.remove(index);
7859 }
7860 return;
7861 };
7862 let tables: Vec<String> = BTreeSet::from_iter(owner.tables.iter().copied())
7863 .into_iter()
7864 .map(str::to_owned)
7865 .collect();
7866 let code = failure.code.unwrap_or("client.query_failed").to_owned();
7867 if position.is_some_and(|index| {
7868 let entry = &self.query_failures[index];
7869 entry.tables == tables && entry.code == code && entry.sqlite_code == failure.sqlite_code
7870 }) {
7871 return;
7872 }
7873 if let Some(index) = position {
7874 self.query_failures.remove(index);
7875 }
7876 self.query_failures.push(DiagnosticQueryFailure {
7877 id: owner.id.to_owned(),
7878 tables,
7879 code,
7880 sqlite_code: failure.sqlite_code,
7881 at_ms: self.clock_now_ms(),
7882 });
7883 if self.query_failures.len() > MAX_DIAGNOSTIC_QUERY_FAILURES {
7884 self.query_failures.remove(0);
7885 }
7886 }
7887
7888 fn build_request(&self, url_capable: bool) -> Result<(Message, RequestMeta), Box<SyncOutcome>> {
7891 #[cfg(feature = "bench-internals")]
7892 let _phase = self.benchmark_phases.start(Phase::RequestPrepare);
7893 let log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7894 Box::new(SyncOutcome::Failed {
7895 error_code: "storage.failed".into(),
7896 message,
7897 details: None,
7898 recommended_action: None,
7899 })
7900 })?;
7901 let max_commits = self.limits.max_push_commits_per_request;
7902 let max_ops = self
7903 .limits
7904 .max_push_operations_per_request
7905 .unwrap_or(PUSH_OPS_PER_REQUEST);
7906 let byte_cap = self.limits.max_push_request_bytes;
7907 let accept = self.limits.accept.unwrap_or(if url_capable {
7910 DEFAULT_ACCEPT | ACCEPT_SIGNED_URLS
7911 } else {
7912 DEFAULT_ACCEPT
7913 });
7914 let storage_failed = |message: String| {
7915 Box::new(SyncOutcome::Failed {
7916 error_code: "storage.failed".into(),
7917 message,
7918 details: None,
7919 recommended_action: None,
7920 })
7921 };
7922 let header = Frame::ReqHeader {
7923 client_id: self.client_id.clone(),
7924 schema_version: self.schema.version,
7925 log_epoch: log_epoch.clone(),
7926 outbox_id: self.get_meta(OUTBOX_ID_KEY).map_err(storage_failed)?,
7927 };
7928 let mut lead = vec![header];
7932 lead.extend(
7933 self.round_failure
7934 .iter()
7935 .map(|code| Frame::RoundFailure { code: code.clone() }),
7936 );
7937 let registered: Vec<UnitRecord> = self
7938 .stored(load_units(&self.conn))
7939 .map_err(storage_failed)?
7940 .into_iter()
7941 .filter(|unit| unit.status == UnitStatus::Active)
7942 .collect();
7943 let registration_digest = ssp2::registration::registration_digest(
7944 registered
7945 .iter()
7946 .map(|unit| scope_pairs(&unit.scopes))
7947 .collect::<Vec<_>>()
7948 .iter()
7949 .map(Vec::as_slice),
7950 );
7951 let echo_digest = self
7952 .get_meta(ECHO_DIGEST_KEY)
7953 .map_err(storage_failed)?
7954 .filter(|hex| !hex.is_empty())
7955 .map(|hex| {
7956 crate::values::hex_to_bytes(&hex)
7957 .ok()
7958 .and_then(|bytes| <[u8; 32]>::try_from(bytes).ok())
7959 .ok_or_else(|| {
7960 "sync.local_corrupt: persisted echo digest is invalid".to_owned()
7961 })
7962 })
7963 .transpose()
7964 .map_err(storage_failed)?;
7965 let pull = Frame::PullHeader {
7966 limit_commits: self.limits.limit_commits.unwrap_or(0),
7967 limit_snapshot_rows: self.limits.limit_snapshot_rows.unwrap_or(0),
7968 max_snapshot_pages: self.limits.max_snapshot_pages.unwrap_or(0),
7969 accept,
7970 cursor: self
7971 .stored(replica_cursor(&self.conn))
7972 .map_err(storage_failed)?,
7973 registration_digest,
7974 echo_digest,
7975 };
7976 let registration_digest = bytes_to_hex(®istration_digest);
7977 let travels = self
7980 .get_meta(REGISTERED_DIGEST_KEY)
7981 .map_err(storage_failed)?
7982 .as_deref()
7983 != Some(registration_digest.as_str());
7984 let mut sub_frames: Vec<Frame> = Vec::new();
7985 if travels {
7986 sub_frames.extend(registered.iter().map(|unit| Frame::Unit {
7987 scopes: scope_pairs(&unit.scopes),
7988 }));
7989 }
7990 for unit in ®istered {
7993 let Some(cursor) = unit.cursor else {
7994 continue;
7995 };
7996 sub_frames.push(Frame::Progress {
7997 id: unit.id.clone(),
7998 cursor,
7999 bootstrap_state: unit.bootstrap_state.clone().map(RawJson),
8000 });
8001 sub_frames.extend(
8002 unit.restriction
8003 .as_ref()
8004 .map(|restriction| Frame::Restrict {
8005 cursor: restriction.cursor,
8006 tables: restriction.tables.clone(),
8007 }),
8008 );
8009 }
8010 let fixed_bytes = match byte_cap {
8013 Some(_) => {
8014 let mut frames = lead.clone();
8015 frames.push(pull.clone());
8016 frames.extend(sub_frames.iter().cloned());
8017 encode_message(&Message {
8018 wire_version: WIRE_VERSION,
8019 msg_kind: MsgKind::Request,
8020 frames,
8021 })
8022 .len()
8023 }
8024 None => 0,
8025 };
8026 if let Some(cap) = byte_cap {
8027 if fixed_bytes > cap {
8028 return Err(Self::push_capacity_outcome("bytes", cap, fixed_bytes, None));
8029 }
8030 }
8031 let base_bytes = match byte_cap {
8032 Some(_) => {
8033 let mut frames = lead.clone();
8034 frames.push(pull.clone());
8035 encode_message(&Message {
8036 wire_version: WIRE_VERSION,
8037 msg_kind: MsgKind::Request,
8038 frames,
8039 })
8040 .len()
8041 }
8042 None => 0,
8043 };
8044 let total_outbox = if log_epoch.is_some() {
8045 self.outbox.len()
8046 } else {
8047 0
8048 };
8049 let mut push_frames: Vec<Frame> = Vec::new();
8050 let mut pushed_ids = Vec::new();
8051 let mut ops_in_request = 0usize;
8052 let mut bytes_in_request = 0usize;
8053 let mut deferred_commits = 0usize;
8054 let held: HashSet<String> = self
8057 .prepare_replacements()
8058 .map_err(storage_failed)?
8059 .into_iter()
8060 .filter_map(|decision| decision.replacement)
8061 .collect();
8062 #[cfg(feature = "bench-internals")]
8063 let outbox_phase = self.benchmark_phases.start(Phase::OutboxEncode);
8064 for (index, commit) in self.outbox.iter().take(total_outbox).enumerate() {
8065 if held.contains(&commit.client_commit_id) {
8066 break;
8067 }
8068 if max_commits.is_some_and(|cap| push_frames.len() >= cap) {
8072 deferred_commits = total_outbox - index;
8073 break;
8074 }
8075 if ops_in_request + commit.ops.len() > max_ops {
8076 if push_frames.is_empty() {
8077 return Err(Self::push_capacity_outcome(
8078 "operations",
8079 max_ops,
8080 commit.ops.len(),
8081 Some(commit.client_commit_id.as_str()),
8082 ));
8083 }
8084 deferred_commits = total_outbox - index;
8085 break;
8086 }
8087 if self.outbox[..index]
8090 .iter()
8091 .flat_map(|earlier| &earlier.ops)
8092 .any(|earlier| commit.ops.iter().any(|op| chains_on(earlier, op)))
8093 {
8094 deferred_commits = total_outbox - index;
8095 break;
8096 }
8097 let operations = commit
8098 .ops
8099 .iter()
8100 .map(|op| {
8101 let payload = match self
8102 .schema
8103 .table(&op.table)
8104 .and_then(|table| Some((table, op.presented_values(table)?)))
8105 {
8106 Some((table, values)) => {
8107 let fallback =
8117 self.stored_key_fallback(table, &op.row_id)
8118 .map_err(|message| {
8119 Box::new(SyncOutcome::Failed {
8120 error_code: "storage.failed".into(),
8121 message,
8122 details: None,
8123 recommended_action: None,
8124 })
8125 })?;
8126 encode_sparse_row_json(
8127 table,
8128 &op.row_id,
8129 &values,
8130 &self.encryption,
8131 fallback.as_ref(),
8132 )
8133 .ok()
8134 }
8135 None => None,
8136 };
8137 Ok(ssp2::model::Operation {
8138 table: op.table.clone(),
8139 row_id: op.row_id.clone(),
8140 op: if op.upsert { Op::Upsert } else { Op::Delete },
8141 base_version: op.base_version,
8142 payload,
8143 })
8144 })
8145 .collect::<Result<Vec<_>, Box<SyncOutcome>>>()?;
8146 let client_seq = self
8148 .conn
8149 .prepare_cached("SELECT seq FROM _syncular_outbox WHERE commit_id = ?1")
8150 .and_then(|mut statement| {
8151 statement.query_row([&commit.client_commit_id], |row| row.get(0))
8152 })
8153 .map_err(|error| {
8154 storage_failed(Self::sqlite_failure(&self.storage_failure, error))
8155 })?;
8156 let frame = Frame::PushCommit {
8157 client_commit_id: commit.client_commit_id.clone(),
8158 client_seq,
8159 operations,
8160 };
8161 let frame_bytes = match byte_cap {
8162 Some(_) => {
8163 let mut frames = lead.clone();
8164 frames.push(frame.clone());
8165 frames.push(pull.clone());
8166 encode_message(&Message {
8167 wire_version: WIRE_VERSION,
8168 msg_kind: MsgKind::Request,
8169 frames,
8170 })
8171 .len()
8172 - base_bytes
8173 }
8174 None => 0,
8175 };
8176 if let Some(cap) = byte_cap {
8180 if !push_frames.is_empty() && fixed_bytes + bytes_in_request + frame_bytes > cap {
8181 deferred_commits = total_outbox - index;
8182 break;
8183 }
8184 }
8185 push_frames.push(frame);
8186 pushed_ids.push(commit.client_commit_id.clone());
8187 ops_in_request += commit.ops.len();
8188 bytes_in_request += frame_bytes;
8189 }
8190 #[cfg(feature = "bench-internals")]
8191 drop(outbox_phase);
8192 if let Some(cap) = byte_cap {
8193 if fixed_bytes + bytes_in_request > cap {
8194 let blocked = if push_frames.is_empty() {
8197 None
8198 } else {
8199 self.outbox.first().map(|c| c.client_commit_id.as_str())
8200 };
8201 return Err(Self::push_capacity_outcome(
8202 "bytes",
8203 cap,
8204 fixed_bytes + bytes_in_request,
8205 blocked,
8206 ));
8207 }
8208 }
8209 let mut frames = lead;
8210 frames.extend(push_frames);
8211 frames.push(pull);
8212 frames.extend(sub_frames);
8213 let message = Message {
8214 wire_version: WIRE_VERSION,
8215 msg_kind: MsgKind::Request,
8216 frames,
8217 };
8218 Ok((
8219 message,
8220 RequestMeta {
8221 pushed_ids,
8222 registration_digest,
8223 accept,
8224 deferred_commits,
8225 applied: BTreeMap::new(),
8226 deferred: BTreeSet::new(),
8227 },
8228 ))
8229 }
8230
8231 fn push_capacity_outcome(
8233 kind: &str,
8234 limit: usize,
8235 size: usize,
8236 client_commit_id: Option<&str>,
8237 ) -> Box<SyncOutcome> {
8238 let mut details = Map::new();
8239 details.insert("kind".to_owned(), Value::from(kind));
8240 details.insert("limit".to_owned(), Value::from(limit as u64));
8241 details.insert("size".to_owned(), Value::from(size as u64));
8242 if let Some(id) = client_commit_id {
8243 details.insert("clientCommitId".to_owned(), Value::from(id));
8244 }
8245 Box::new(SyncOutcome::Failed {
8246 error_code: "client.push_request_too_large".into(),
8247 message: "the push request exceeds a configured capacity limit".into(),
8248 details: Some(Value::Object(details)),
8249 recommended_action: None,
8250 })
8251 }
8252
8253 pub fn progress(&self) -> ProgressObserver {
8257 self.progress.clone()
8258 }
8259
8260 pub fn sync(&mut self, transport: &mut dyn Transport) -> SyncOutcome {
8261 self.sync_bounded(transport, None)
8262 }
8263
8264 fn sync_bounded(
8266 &mut self,
8267 transport: &mut dyn Transport,
8268 idle_bound: Option<(u64, u32)>,
8269 ) -> SyncOutcome {
8270 let mut prepared = match self.prepare_sync_round(transport.supports_url_fetch()) {
8271 Ok(prepared) => prepared,
8272 Err(outcome) => return *outcome,
8273 };
8274 prepared.idle_bound = idle_bound;
8275 let mut next = prepared;
8280 loop {
8281 match self.apply_sync_round(next.exchange(transport)) {
8282 crate::AppliedSyncRound::Continue(prepared) => next = prepared,
8283 crate::AppliedSyncRound::Complete {
8284 outcome, controls, ..
8285 } => {
8286 if self.transport_enabled {
8287 for text in controls {
8288 let _ = transport.realtime_send(&text);
8289 }
8290 } else {
8291 self.disconnect_realtime(transport);
8292 }
8293 return outcome;
8294 }
8295 }
8296 }
8297 }
8298
8299 fn finish_sync_round(
8300 &mut self,
8301 started_at_ms: i64,
8302 attempt: u64,
8303 mut outcome: SyncOutcome,
8304 ) -> SyncOutcome {
8305 if let SyncOutcome::Failed {
8306 error_code,
8307 message,
8308 details,
8309 ..
8310 } = &mut outcome
8311 {
8312 if let Some((failure, code)) = self
8313 .storage_failure
8314 .borrow()
8315 .as_ref()
8316 .and_then(|failure| failure.code.map(|code| (failure, code)))
8317 {
8318 *error_code = code.to_owned();
8319 *message = match code {
8320 "client.storage_busy" => "local SQLite storage is busy",
8321 "client.storage_full" => "local SQLite storage is full",
8322 "client.storage_io" => "local SQLite storage I/O failed",
8323 "client.storage_corrupt" => "local SQLite storage is corrupt",
8324 _ => unreachable!("unrecognized classified storage failure"),
8325 }
8326 .to_owned();
8327 *details = failure.details();
8328 }
8329 }
8330 let details = match &outcome {
8331 SyncOutcome::Failed { details, .. } => details.as_ref(),
8332 _ => None,
8333 };
8334 let cause_kind = details
8335 .and_then(|details| details.get("causeKind"))
8336 .and_then(Value::as_str)
8337 .and_then(|cause| match cause {
8338 "network" => Some(crate::TransportCauseKind::Network),
8339 "connect" => Some(crate::TransportCauseKind::Connect),
8340 "tls" => Some(crate::TransportCauseKind::Tls),
8341 "io" => Some(crate::TransportCauseKind::Io),
8342 "request" => Some(crate::TransportCauseKind::Request),
8343 "protocol" => Some(crate::TransportCauseKind::Protocol),
8344 "timeout" => Some(crate::TransportCauseKind::Timeout),
8345 "round_deadline" => Some(crate::TransportCauseKind::RoundDeadline),
8346 "aborted" => Some(crate::TransportCauseKind::Aborted),
8347 "body" => Some(crate::TransportCauseKind::Body),
8348 "status" => Some(crate::TransportCauseKind::Status),
8349 "redirect" => Some(crate::TransportCauseKind::Redirect),
8350 "unknown" => Some(crate::TransportCauseKind::Unknown),
8351 _ => None,
8352 });
8353 let http_status = if matches!(
8354 cause_kind,
8355 Some(
8356 crate::TransportCauseKind::Status
8357 | crate::TransportCauseKind::Body
8358 | crate::TransportCauseKind::Redirect
8359 )
8360 ) {
8361 details
8362 .and_then(|details| details.get("httpStatus"))
8363 .and_then(Value::as_f64)
8364 .filter(|status| status.fract() == 0.0 && (100.0..=599.0).contains(status))
8365 .map(|status| status as u16)
8366 } else {
8367 None
8368 };
8369 let retry_delay_ms = self.round_retry_delay_ms;
8370 self.progress.update(|p| match &outcome {
8371 SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report)
8372 if report.failed.is_empty() =>
8373 {
8374 p.state = ProgressState::Complete
8375 }
8376 SyncOutcome::Ok(_) | SyncOutcome::BudgetExhausted(_) => {
8377 p.state = ProgressState::Failed;
8378 p.error_code = Some("sync.scope_revoked".into());
8379 }
8380 SyncOutcome::Failed { error_code, .. } => {
8381 p.state = ProgressState::Failed;
8382 p.error_code = Some(Self::diagnostic_code(error_code));
8383 p.cause_kind = cause_kind;
8384 p.http_status = http_status;
8385 p.retry_delay_ms = retry_delay_ms;
8386 }
8387 SyncOutcome::RealtimeUnavailable { .. } => {
8388 p.state = ProgressState::Failed;
8389 p.error_code = Some(REALTIME_UNAVAILABLE_CODE.to_owned());
8390 p.retry_delay_ms = retry_delay_ms;
8391 }
8392 });
8393 let completed_at_ms = self.clock_now_ms();
8394 self.last_round = Some(match &outcome {
8395 SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report) => DiagnosticLastRound {
8396 epoch: self.epoch.clone(),
8397 attempt,
8398 status: "succeeded".to_owned(),
8399 started_at_ms,
8400 completed_at_ms,
8401 duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
8402 counters: Some(DiagnosticRoundCounters {
8403 pushed: report.pushed,
8404 applied: report.applied.len(),
8405 rejected: report.rejected.len(),
8406 retryable: report.retryable.len(),
8407 conflicts: report.conflicts,
8408 commits_applied: report.commits_applied,
8409 segment_rows_applied: report.segment_rows_applied,
8410 bootstrapping: report.bootstrapping.len(),
8411 resets: report.resets.len(),
8412 revoked: report.revoked.len(),
8413 failed: report.failed.len(),
8414 deferred_commits: report.deferred_commits,
8415 }),
8416 error_code: None,
8417 cause_kind: None,
8418 http_status: None,
8419 },
8420 SyncOutcome::Failed { error_code, .. } => DiagnosticLastRound {
8421 epoch: self.epoch.clone(),
8422 attempt,
8423 status: "failed".to_owned(),
8424 started_at_ms,
8425 completed_at_ms,
8426 duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
8427 counters: None,
8428 error_code: Some(Self::diagnostic_code(error_code)),
8429 cause_kind,
8430 http_status,
8431 },
8432 SyncOutcome::RealtimeUnavailable { .. } => DiagnosticLastRound {
8433 epoch: self.epoch.clone(),
8434 attempt,
8435 status: "failed".to_owned(),
8436 started_at_ms,
8437 completed_at_ms,
8438 duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
8439 counters: None,
8440 error_code: Some(REALTIME_UNAVAILABLE_CODE.to_owned()),
8441 cause_kind: None,
8442 http_status: None,
8443 },
8444 });
8445 outcome
8446 }
8447
8448 pub fn prepare_sync_round(
8451 &mut self,
8452 url_capable: bool,
8453 ) -> Result<crate::PreparedSyncRound, Box<SyncOutcome>> {
8454 if !self.transport_enabled {
8455 return Err(Box::new(SyncOutcome::Failed {
8456 error_code: "sync.offline".into(),
8457 message: "transport gate is closed".into(),
8458 details: None,
8459 recommended_action: None,
8460 }));
8461 }
8462 if self.active_round.is_some() {
8463 return Err(Box::new(SyncOutcome::Failed {
8464 error_code: "client.round_in_progress".into(),
8465 message: "a sync round is already in flight".into(),
8466 details: None,
8467 recommended_action: None,
8468 }));
8469 }
8470 self.storage_failure.borrow_mut().take();
8471 let attempt = self.progress.start(&self.epoch);
8472 self.round_retry_delay_ms = None;
8473 let started_at_ms = self.clock_now_ms();
8474 let prepared = (|| {
8475 if self.stopped {
8476 return Err(Box::new(SyncOutcome::Ok(SyncReport {
8477 schema_floor: self.schema_floor.clone(),
8478 ..SyncReport::default()
8479 })));
8480 }
8481 if self.security_preflight {
8482 return Err(Box::new(SyncOutcome::Failed {
8483 error_code: SECURITY_PREFLIGHT_REQUIRED_CODE.into(),
8484 message: "security preflight must complete before syncing".into(),
8485 details: None,
8486 recommended_action: None,
8487 }));
8488 }
8489 self.set_sync_needed(false, false);
8490 self.drain_pending_evictions()
8491 .and_then(|_| self.drop_incompatible_outbox())
8492 .and_then(|_| self.drop_unencodable_outbox(true, None))
8493 .map_err(|message| {
8494 Box::new(SyncOutcome::Failed {
8495 error_code: "storage.failed".into(),
8496 message,
8497 details: None,
8498 recommended_action: None,
8499 })
8500 })?;
8501 self.reveal_sealed_rows().map_err(|error| {
8503 Box::new(SyncOutcome::Failed {
8504 error_code: error.code,
8505 message: error.message,
8506 details: error.details,
8507 recommended_action: None,
8508 })
8509 })?;
8510 let has_log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
8511 Box::new(SyncOutcome::Failed {
8512 error_code: "storage.failed".into(),
8513 message,
8514 details: None,
8515 recommended_action: None,
8516 })
8517 })?;
8518 let uploads = if has_log_epoch.is_some() && self.schema_has_blobs() {
8519 self.pending_blob_uploads().map_err(|e| {
8520 Box::new(SyncOutcome::Failed {
8521 error_code: e.code,
8522 message: e.message,
8523 details: e.details,
8524 recommended_action: None,
8525 })
8526 })?
8527 } else {
8528 Vec::new()
8529 };
8530 if self.realtime_state != RealtimeState::Connected
8531 && self.realtime_policy == RealtimePolicy::Required
8532 {
8533 let retry_delay_ms = self.schedule_background_retry();
8534 self.realtime_retry_delay_ms = Some(retry_delay_ms);
8535 return Err(Box::new(SyncOutcome::RealtimeUnavailable {
8536 state: self.realtime_state,
8537 reason_code: self.realtime_reason_code.clone(),
8538 retry_delay_ms,
8539 }));
8540 }
8541 let (message, mut meta) = self.build_request(url_capable)?;
8542 let units = self.stored(load_units(&self.conn)).map_err(|message| {
8543 Box::new(SyncOutcome::Failed {
8544 error_code: "storage.failed".into(),
8545 message,
8546 details: None,
8547 recommended_action: None,
8548 })
8549 })?;
8550 for unit in &units {
8551 let applied =
8552 self.stored(applied_rows(&self.conn, &unit.id))
8553 .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 if !applied.is_empty() {
8562 meta.applied.insert(unit.id.clone(), applied);
8563 }
8564 }
8565 let id = uuid::Uuid::new_v4();
8566 self.active_round = Some((id, started_at_ms, attempt));
8567 let phase = if uploads.is_empty() {
8568 crate::round::RoundPhase::Sync
8569 } else {
8570 crate::round::RoundPhase::UploadGrant
8571 };
8572 Ok(crate::PreparedSyncRound {
8573 id,
8574 started_at_ms,
8575 attempt,
8576 message,
8577 meta,
8578 uploads: uploads.into(),
8579 phase,
8580 encoded: None,
8581 continuation: None,
8582 completed: None,
8583 realtime: self.realtime_state == RealtimeState::Connected,
8584 scopes: units
8586 .into_iter()
8587 .map(|unit| {
8588 (
8589 unit.id,
8590 canonical_scope_json(&unit_scope_lists(&unit.scopes)),
8591 )
8592 })
8593 .collect(),
8594 #[cfg(feature = "bench-internals")]
8595 benchmark_phases: self.benchmark_phases.clone(),
8596 progress: self.progress.clone(),
8597 fixed_now: self
8598 .now_ms
8599 .as_ref()
8600 .map(|clock| clock.load(std::sync::atomic::Ordering::Relaxed)),
8601 round_deadline_at: None,
8602 idle_bound: None,
8603 })
8604 })();
8605 prepared
8606 .map_err(|outcome| Box::new(self.finish_sync_round(started_at_ms, attempt, *outcome)))
8607 }
8608
8609 pub fn cancel_sync_round(&mut self) {
8613 if let Some((_, started_at_ms, attempt)) = self.active_round.take() {
8614 self.storage_failure.borrow_mut().take();
8616 self.finish_sync_round(
8617 started_at_ms,
8618 attempt,
8619 SyncOutcome::Failed {
8620 error_code: "client.round_cancelled".into(),
8621 message: "sync round belongs to a released client context".into(),
8622 details: None,
8623 recommended_action: None,
8624 },
8625 );
8626 }
8627 }
8628
8629 pub fn apply_sync_round(
8632 &mut self,
8633 completed: crate::CompletedSyncRound,
8634 ) -> crate::AppliedSyncRound {
8635 let mut prepared = completed.prepared;
8636 if self.active_round.map(|(id, ..)| id) != Some(prepared.id) || self.security_preflight {
8637 return crate::AppliedSyncRound::Complete {
8638 outcome: SyncOutcome::Failed {
8639 error_code: "client.round_cancelled".into(),
8640 message: "sync round belongs to a released client context".into(),
8641 details: None,
8642 recommended_action: None,
8643 },
8644 controls: Vec::new(),
8645 more: false,
8646 bootstrap_advanced: false,
8647 };
8648 }
8649 self.storage_failure.borrow_mut().take();
8650 let (response, mut downloads, transport_failed) = match completed.exchange {
8651 crate::round::ExchangeResult::Upload { id, result } => {
8652 let result = match result {
8653 Err(error)
8658 if error
8659 .details
8660 .as_ref()
8661 .and_then(|details| details.get("retryable"))
8662 == Some(&Value::Bool(false)) =>
8663 {
8664 self.conn
8665 .prepare(
8666 "SELECT commit_id FROM _syncular_blob_commit_refs WHERE blob_id = ?",
8667 )
8668 .and_then(|mut statement| {
8669 statement
8670 .query_map(rusqlite::params![id], |row| row.get::<_, String>(0))?
8671 .collect::<Result<HashSet<_>, _>>()
8672 })
8673 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
8674 .and_then(|refused| {
8675 let commits = self
8676 .outbox
8677 .iter()
8678 .filter(|commit| refused.contains(&commit.client_commit_id))
8679 .cloned()
8680 .collect::<Vec<_>>();
8681 if !commits.is_empty() {
8682 self.drop_outbox_commits(&commits, &error.code, &error.message)?;
8683 }
8684 prepared.message.frames.retain(|frame| {
8685 !matches!(frame, Frame::PushCommit { client_commit_id, .. }
8686 if refused.contains(client_commit_id))
8687 });
8688 prepared.meta.pushed_ids.retain(|id| !refused.contains(id));
8689 prepared.continuation = Some(crate::round::RoundPhase::UploadGrant);
8690 Ok(())
8691 })
8692 .map_err(|message| TransportError::new("client.failed", message))
8693 }
8694 result => result,
8695 };
8696 let result = result.and_then(|()| {
8697 self.conn
8698 .execute(
8699 "DELETE FROM _syncular_blob_uploads WHERE blob_id = ?",
8700 rusqlite::params![id],
8701 )
8702 .map(|_| ())
8703 .map_err(|error| {
8704 TransportError::new(
8705 "client.failed",
8706 Self::sqlite_failure(&self.storage_failure, error),
8707 )
8708 })
8709 });
8710 match result {
8711 Ok(()) => return crate::AppliedSyncRound::Continue(prepared),
8712 Err(TransportError {
8713 code,
8714 message,
8715 details,
8716 }) => {
8717 self.active_round = None;
8718 if Self::unreachable_transport(&details) {
8719 self.set_sync_needed(true, false);
8722 } else if Self::retryable_failure_code(&code) {
8723 self.schedule_background_retry();
8724 }
8725 let recommended_action = recommended_action_of(&details);
8726 let outcome = self.finish_sync_round(
8727 prepared.started_at_ms,
8728 prepared.attempt,
8729 SyncOutcome::Failed {
8730 error_code: code,
8731 message,
8732 details,
8733 recommended_action,
8734 },
8735 );
8736 return crate::AppliedSyncRound::Complete {
8737 outcome,
8738 controls: Vec::new(),
8739 more: false,
8740 bootstrap_advanced: false,
8741 };
8742 }
8743 }
8744 }
8745 crate::round::ExchangeResult::Reply {
8746 response,
8747 downloads,
8748 transport_failed,
8749 } => (response, downloads, transport_failed),
8750 };
8751 self.active_round = None;
8752 let before = self.resume_tokens();
8753 let outcome = (|| {
8754 let response = match response {
8755 Ok(response) => {
8756 self.round_failure = None;
8759 response
8760 }
8761 Err(TransportError {
8762 code,
8763 message,
8764 details,
8765 }) => {
8766 if code != "sync.idle_timeout" && ssp2::model::valid_round_failure_code(&code) {
8772 self.round_failure = Some(code.clone());
8773 }
8774 if transport_failed {
8775 if prepared.realtime {
8776 self.set_realtime_state(RealtimeState::Lost, Some(&code));
8777 }
8778 if let Err(message) = self.record_lease_error(&code) {
8779 return SyncOutcome::Failed {
8780 error_code: "storage.failed".to_owned(),
8781 message,
8782 details: None,
8783 recommended_action: None,
8784 };
8785 }
8786 }
8787 if Self::retryable_failure_code(&code) && !Self::unreachable_transport(&details)
8788 {
8789 let delay = self.schedule_background_retry();
8790 if prepared.realtime && transport_failed {
8791 self.realtime_retry_delay_ms = Some(delay);
8792 }
8793 }
8794 let recommended_action = recommended_action_of(&details);
8795 return SyncOutcome::Failed {
8796 error_code: code,
8797 message,
8798 details,
8799 recommended_action,
8800 };
8801 }
8802 };
8803 let mut outcome = self.process_response(&mut downloads, response, &prepared.meta);
8804 if let SyncOutcome::Ok(report) = &mut outcome {
8805 report.deferred_commits = prepared.meta.deferred_commits;
8806 }
8807 match &outcome {
8808 SyncOutcome::Ok(_) => self.reset_background_retry(),
8809 SyncOutcome::Failed {
8810 error_code,
8811 details,
8812 ..
8813 } if Self::retryable_failure_code(error_code)
8814 && !Self::unreachable_transport(details) =>
8815 {
8816 self.schedule_background_retry();
8817 }
8818 _ => {}
8819 }
8820 if prepared.meta.deferred_commits > 0 {
8821 self.set_sync_needed(true, true);
8822 }
8823 self.previous_version_lifetime_check();
8824 outcome
8825 })();
8826 match &outcome {
8827 SyncOutcome::Ok(report) if !report.bootstrapping.is_empty() => {
8830 self.set_sync_needed(true, false)
8831 }
8832 SyncOutcome::Failed { details, .. } if Self::unreachable_transport(details) => {
8835 self.set_sync_needed(true, false)
8836 }
8837 _ => {}
8838 }
8839 let more = self.transport_enabled
8840 && matches!(&outcome, SyncOutcome::Ok(report)
8841 if report.schema_floor.is_none()
8842 && (!report.bootstrapping.is_empty()
8843 || report.commits_applied > 0
8844 || report.segment_rows_applied > 0
8845 || !report.resets.is_empty()
8846 || report.deferred_commits > 0
8847 || self.sync_needed));
8848 let bootstrap_advanced = matches!(&outcome, SyncOutcome::Ok(report) if report.segment_rows_applied > 0 && !report.bootstrapping.is_empty())
8849 && before != self.resume_tokens();
8850 crate::AppliedSyncRound::Complete {
8851 outcome: self.finish_sync_round(prepared.started_at_ms, prepared.attempt, outcome),
8852 controls: if self.transport_enabled {
8853 downloads.controls
8854 } else {
8855 Vec::new()
8856 },
8857 more,
8858 bootstrap_advanced,
8859 }
8860 }
8861
8862 #[allow(clippy::type_complexity)]
8866 fn resume_tokens(&self) -> Option<Vec<(String, Option<String>, Option<String>)>> {
8867 self.conn
8868 .prepare_cached(
8869 "SELECT id, bootstrap_state, applied FROM _syncular_units ORDER BY rowid",
8870 )
8871 .and_then(|mut stmt| {
8872 stmt.query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?
8873 .collect()
8874 })
8875 .ok()
8876 }
8877
8878 pub const SYNC_IDLE_TIMEOUT_MS: u64 = 60_000;
8880
8881 pub fn sync_until_idle(
8882 &mut self,
8883 transport: &mut dyn Transport,
8884 max_rounds: Option<u32>,
8885 ) -> SyncOutcome {
8886 self.sync_until_idle_with_deadline(transport, max_rounds, Some(Self::SYNC_IDLE_TIMEOUT_MS))
8887 }
8888
8889 pub fn sync_until_idle_with_deadline(
8896 &mut self,
8897 transport: &mut dyn Transport,
8898 max_rounds: Option<u32>,
8899 timeout_ms: Option<u64>,
8900 ) -> SyncOutcome {
8901 if max_rounds == Some(0) {
8904 return SyncOutcome::Failed {
8905 details: None,
8906 error_code: "sync.invalid_request".into(),
8907 message: "maxRounds must be a positive integer".into(),
8908 recommended_action: None,
8909 };
8910 }
8911 if timeout_ms.is_some_and(|ms| ms == 0 || i64::try_from(ms).is_err()) {
8912 return SyncOutcome::Failed {
8913 details: None,
8914 error_code: "sync.invalid_request".into(),
8915 message: "timeoutMs must be a positive integer".into(),
8916 recommended_action: None,
8917 };
8918 }
8919 let started_at_ms = self.clock_now_ms();
8920 let rounds = max_rounds.unwrap_or(20);
8921 let mut aggregate = SyncReport::default();
8922 let decisions = match self.prepare_replacements() {
8925 Ok(decisions) => decisions,
8926 Err(message) => {
8927 return SyncOutcome::Failed {
8928 details: None,
8929 error_code: "storage.failed".into(),
8930 message,
8931 recommended_action: None,
8932 }
8933 }
8934 };
8935 let mut spent = 0;
8936 let mut completed = false;
8937 while spent < rounds {
8938 if completed
8941 && timeout_ms.is_some_and(|ms| {
8942 self.clock_now_ms() >= started_at_ms.saturating_add(ms as i64)
8943 })
8944 {
8945 return SyncOutcome::BudgetExhausted(aggregate);
8946 }
8947 let idle_bound = timeout_ms.map(|ms| (ms, spent));
8948 spent += 1;
8949 let before = self.resume_tokens();
8950 match self.sync_bounded(transport, idle_bound) {
8951 SyncOutcome::Failed {
8952 error_code,
8953 message,
8954 details,
8955 recommended_action,
8956 } => {
8957 return SyncOutcome::Failed {
8958 details,
8959 error_code,
8960 message,
8961 recommended_action,
8962 };
8963 }
8964 outcome @ SyncOutcome::RealtimeUnavailable { .. } => return outcome,
8965 SyncOutcome::BudgetExhausted(_) => {
8966 unreachable!("sync() never exhausts a round budget")
8967 }
8968 SyncOutcome::Ok(report) => {
8969 completed = true;
8970 if max_rounds.is_none()
8971 && report.segment_rows_applied > 0
8972 && !report.bootstrapping.is_empty()
8973 && before != self.resume_tokens()
8974 {
8975 spent = 0;
8976 }
8977 let stop = !self.transport_enabled() || report.schema_floor.is_some();
8980 aggregate.merge(&report);
8981 let more = !stop
8987 && (!report.bootstrapping.is_empty()
8988 || report.commits_applied > 0
8989 || report.segment_rows_applied > 0
8990 || !report.resets.is_empty()
8991 || report.deferred_commits > 0
8992 || self.sync_needed);
8993 if more {
8994 continue;
8995 }
8996 match self.settle_replacements(&decisions, &SyncOutcome::Ok(aggregate.clone()))
8999 {
9000 Ok(true) if !stop => {}
9001 Ok(_) => return SyncOutcome::Ok(aggregate),
9002 Err(message) => {
9003 return SyncOutcome::Failed {
9004 details: None,
9005 error_code: "storage.failed".into(),
9006 message,
9007 recommended_action: None,
9008 }
9009 }
9010 }
9011 }
9012 }
9013 }
9014 SyncOutcome::BudgetExhausted(aggregate)
9017 }
9018
9019 fn process_response(
9020 &mut self,
9021 transport: &mut dyn Transport,
9022 response: Message,
9023 meta: &RequestMeta,
9024 ) -> SyncOutcome {
9025 #[cfg(feature = "bench-internals")]
9026 let _phase = self.benchmark_phases.start(Phase::ResponseApply);
9027 let mut report = SyncReport {
9028 pushed: meta.pushed_ids.len() as u32,
9029 ..SyncReport::default()
9030 };
9031 let mut rejection_details_by_commit: HashMap<String, BTreeMap<i32, RejectionDetails>> =
9032 HashMap::new();
9033 let pushed_ids = meta
9034 .pushed_ids
9035 .iter()
9036 .map(String::as_str)
9037 .collect::<HashSet<_>>();
9038 let mut last_final_push_result_id: Option<String> = None;
9039 for frame in &response.frames {
9040 match frame {
9041 Frame::PushResultDetails {
9042 client_commit_id,
9043 entries,
9044 } => {
9045 let details = rejection_details_by_commit
9046 .entry(client_commit_id.clone())
9047 .or_default();
9048 for entry in entries {
9049 let parsed = match RejectionDetails::parse(&entry.details.0) {
9050 Ok(value) => value,
9051 Err(message) => {
9052 return SyncOutcome::Failed {
9053 details: None,
9054 error_code: "sync.invalid_request".to_owned(),
9055 message,
9056 recommended_action: None,
9057 };
9058 }
9059 };
9060 details.insert(entry.op_index, parsed);
9061 }
9062 }
9063 Frame::PushResult {
9064 client_commit_id,
9065 status,
9066 results,
9067 ..
9068 } if pushed_ids.contains(client_commit_id.as_str())
9069 && Self::push_result_is_final(*status, results) =>
9070 {
9071 last_final_push_result_id = Some(client_commit_id.clone());
9072 }
9073 _ => {}
9074 }
9075 }
9076 let mut frames = response.frames.into_iter().peekable();
9077 match frames.next() {
9078 Some(Frame::RespHeader {
9079 required_schema_version,
9080 latest_schema_version,
9081 log_epoch,
9082 reset_required,
9083 }) => {
9084 if let Some(required) = required_schema_version {
9085 let floor = SchemaFloor {
9088 required_schema_version: Some(required),
9089 latest_schema_version,
9090 };
9091 if let Err(message) = self.set_schema_floor(Some(floor.clone())) {
9092 return SyncOutcome::Failed {
9093 details: None,
9094 error_code: "storage.failed".to_owned(),
9095 message,
9096 recommended_action: None,
9097 };
9098 }
9099 report.schema_floor = Some(floor);
9100 return SyncOutcome::Ok(report);
9101 }
9102 if reset_required {
9103 if frames.next().is_some() {
9104 return SyncOutcome::Failed {
9105 details: None,
9106 error_code: "client.invalid_host_response".to_owned(),
9107 message: "log-epoch reset response contains body frames".to_owned(),
9108 recommended_action: None,
9109 };
9110 }
9111 match self.run_log_epoch_reset(&log_epoch) {
9112 Ok(resets) => {
9113 report.resets = resets;
9114 return SyncOutcome::Ok(report);
9115 }
9116 Err(message) => {
9117 return SyncOutcome::Failed {
9118 details: None,
9119 error_code: "sync.local_corrupt".to_owned(),
9120 message,
9121 recommended_action: None,
9122 };
9123 }
9124 }
9125 }
9126 let stored_epoch = match self.get_meta(LOG_EPOCH_KEY) {
9127 Ok(stored) => stored,
9128 Err(message) => {
9129 return SyncOutcome::Failed {
9130 details: None,
9131 error_code: "storage.failed".to_owned(),
9132 message,
9133 recommended_action: None,
9134 };
9135 }
9136 };
9137 if stored_epoch.as_deref() != Some(log_epoch.as_str()) {
9138 return SyncOutcome::Failed {
9139 details: None,
9140 error_code: "client.invalid_host_response".to_owned(),
9141 message: "server changed logEpoch without requiring a reset".to_owned(),
9142 recommended_action: None,
9143 };
9144 }
9145 }
9146 _ => {
9147 return SyncOutcome::Failed {
9148 details: None,
9149 error_code: "sync.invalid_request".to_owned(),
9150 message: "response does not start with RESP_HEADER".to_owned(),
9151 recommended_action: None,
9152 };
9153 }
9154 }
9155
9156 if let Err(message) = self.begin_coalesced_apply() {
9157 return SyncOutcome::Failed {
9158 details: None,
9159 error_code: "storage.failed".into(),
9160 message,
9161 recommended_action: None,
9162 };
9163 }
9164 let mut failure: Option<(String, String, Option<String>, Option<Value>)> = None;
9165 let mut live: Option<(LiveStatus, String, Vec<UnitRecord>)> = None;
9168 let mut live_ended = false;
9169 while let Some(frame) = frames.next() {
9170 match frame {
9171 frame @ Frame::PushResult { .. } => {
9172 let successful = matches!(
9173 &frame,
9174 Frame::PushResult {
9175 status: PushStatus::Applied | PushStatus::Cached,
9176 ..
9177 }
9178 );
9179 let mut results = vec![frame];
9180 if successful {
9181 while matches!(
9182 frames.peek(),
9183 Some(Frame::PushResult {
9184 status: PushStatus::Applied | PushStatus::Cached,
9185 ..
9186 })
9187 ) {
9188 if let Some(next) = frames.next() {
9189 results.push(next);
9190 }
9191 }
9192 }
9193 if self
9194 .handle_push_results(
9195 &results,
9196 &pushed_ids,
9197 &rejection_details_by_commit,
9198 &mut report,
9199 last_final_push_result_id.as_deref(),
9200 )
9201 .is_err()
9202 {
9203 failure = Some((
9204 "client.outcome_persistence_failed".to_owned(),
9205 "local commit outcome could not be persisted".to_owned(),
9206 None,
9207 None,
9208 ));
9209 break;
9210 }
9211 }
9212 Frame::PushResultDetails { .. } => {}
9213 Frame::SubStart {
9214 id,
9215 status,
9216 reason_code,
9217 bootstrap,
9218 fenced,
9219 } => {
9220 let mut body = Vec::new();
9223 let mut sub_end: Option<(i64, Option<String>)> = None;
9224 let mut error: Option<Frame> = None;
9225 for inner in frames.by_ref() {
9226 match inner {
9227 Frame::SubEnd {
9228 next_cursor,
9229 bootstrap_state,
9230 } => {
9231 sub_end = Some((next_cursor, bootstrap_state.map(|r| r.0)));
9232 break;
9233 }
9234 inner @ Frame::Error { .. } => {
9235 error = Some(inner);
9236 break;
9237 }
9238 Frame::Unknown { .. } => {}
9239 other => body.push(other),
9240 }
9241 }
9242 let ended = sub_end.is_some();
9243 let section = SectionStart {
9244 id,
9245 status,
9246 reason_code,
9247 bootstrap,
9248 fenced,
9249 };
9250 let completed = match self.process_section(
9251 transport,
9252 §ion,
9253 body,
9254 sub_end,
9255 meta,
9256 &mut report,
9257 ) {
9258 Err(SectionError::Abort(code, message)) => {
9259 failure = Some((code, message, None, None));
9260 break;
9261 }
9262 Err(SectionError::Transport(error)) => {
9263 failure = Some((error.code, error.message, None, error.details));
9264 break;
9265 }
9266 Ok(completed) => completed,
9267 Err(_) => false,
9268 };
9269 if ended {
9270 self.progress.update(|p| {
9274 p.unit_id = None;
9275 p.table = None;
9276 p.segment_id = None;
9277 if completed && p.unit_rows_total.is_some() {
9278 p.unit_rows_total = p.unit_rows_processed;
9279 }
9280 });
9281 }
9282 match error {
9283 Some(Frame::Error {
9284 code,
9285 message,
9286 recommended_action,
9287 details,
9288 ..
9289 }) => {
9290 failure = Some(Self::error_frame_failure(
9291 code,
9292 message,
9293 recommended_action,
9294 details,
9295 ));
9296 break;
9297 }
9298 Some(_) => unreachable!("only an ERROR closes a section early"),
9299 None if !ended => {
9300 failure = Some((
9301 "sync.invalid_request".to_owned(),
9302 "unit section without SUB_END".to_owned(),
9303 None,
9304 None,
9305 ));
9306 break;
9307 }
9308 None => {}
9309 }
9310 }
9311 Frame::LiveStart {
9312 status,
9313 reason_code,
9314 } => {
9315 let receivers = match self.stored(load_units(&self.conn)) {
9316 Ok(units) => units
9317 .into_iter()
9318 .filter(|unit| {
9319 unit.status == UnitStatus::Active
9320 && unit.echo.is_some()
9321 && !unit.bootstrapping()
9322 })
9323 .collect(),
9324 Err(message) => {
9325 failure = Some(("storage.failed".to_owned(), message, None, None));
9326 break;
9327 }
9328 };
9329 live = Some((status, reason_code, receivers));
9330 }
9331 Frame::Commit {
9332 commit_seq,
9333 tables,
9334 changes,
9335 ..
9336 } => {
9337 let Some((LiveStatus::Active, _, receivers)) = &live else {
9338 continue;
9339 };
9340 let receivers = receivers.clone();
9341 match self.apply_live_commit(
9342 &receivers,
9343 &tables,
9344 changes,
9345 commit_seq,
9346 AppliedServerCommitSource::Pull,
9347 ) {
9348 Ok(applied) => report.commits_applied += u32::from(applied),
9349 Err(error) => {
9350 failure = Some((error.code, error.message, None, error.details));
9351 break;
9352 }
9353 }
9354 }
9355 Frame::LiveEnd {
9356 through_seq,
9357 echo_digest,
9358 } => {
9359 let Some((status, reason_code, _)) = live.take() else {
9360 continue;
9361 };
9362 live_ended = true;
9363 live = Some((status, String::new(), Vec::new()));
9364 if let Err(message) = self.finish_live_section(
9365 status,
9366 &reason_code,
9367 through_seq,
9368 echo_digest,
9369 &meta.registration_digest,
9370 &mut report,
9371 ) {
9372 failure = Some(("storage.failed".to_owned(), message, None, None));
9373 break;
9374 }
9375 }
9376 Frame::Lease {
9377 lease_id,
9378 expires_at_ms,
9379 } => {
9380 if let Err(message) = self.set_lease_state(Some(LeaseState {
9383 lease_id: Some(lease_id),
9384 expires_at_ms: Some(expires_at_ms),
9385 error_code: None,
9386 })) {
9387 failure = Some(("storage.failed".to_owned(), message, None, None));
9388 break;
9389 }
9390 }
9391 Frame::Error {
9392 code,
9393 message,
9394 recommended_action,
9395 details,
9396 ..
9397 } => {
9398 failure = Some(Self::error_frame_failure(
9401 code,
9402 message,
9403 recommended_action,
9404 details,
9405 ));
9406 break;
9407 }
9408 Frame::Unknown { .. } => {}
9409 _ => {
9410 failure = Some((
9411 "sync.invalid_request".to_owned(),
9412 "unexpected frame in response".to_owned(),
9413 None,
9414 None,
9415 ));
9416 break;
9417 }
9418 }
9419 }
9420
9421 let applied = match failure {
9422 Some(failure) => Err(failure),
9423 None => self
9428 .rebuild_overlay_if_dirty()
9429 .and_then(|()| self.drain_pending_evictions())
9430 .map_err(|message| ("storage.failed".to_owned(), message, None, None)),
9431 };
9432 if let Err(message) = self.finish_coalesced_apply() {
9435 return SyncOutcome::Failed {
9436 details: None,
9437 error_code: "storage.failed".into(),
9438 message,
9439 recommended_action: None,
9440 };
9441 }
9442 if let Err((error_code, message, recommended_action, details)) = applied {
9443 return SyncOutcome::Failed {
9444 details,
9445 error_code,
9446 message,
9447 recommended_action,
9448 };
9449 }
9450 let catching_up = match self.stored(load_units(&self.conn)) {
9451 Ok(units) => units
9452 .into_iter()
9453 .filter(|unit| unit.status == UnitStatus::Active && unit.cursor.is_some())
9454 .map(|unit| unit.id)
9455 .collect::<Vec<_>>(),
9456 Err(message) => {
9457 return SyncOutcome::Failed {
9458 details: None,
9459 error_code: "storage.failed".into(),
9460 message,
9461 recommended_action: None,
9462 }
9463 }
9464 };
9465 let status = live.map(|(status, _, _)| status);
9469 if !live_ended || status != Some(LiveStatus::Active) || !catching_up.is_empty() {
9470 self.set_sync_needed(true, status == Some(LiveStatus::Unregistered));
9471 }
9472 self.ack_after_pull(transport);
9473 if self.upgrading && catching_up.is_empty() {
9476 self.set_upgrading(false);
9477 }
9478 report.bootstrapping = catching_up;
9479 SyncOutcome::Ok(report)
9480 }
9481
9482 fn error_frame_failure(
9484 code: String,
9485 message: String,
9486 recommended_action: String,
9487 details: Option<RawJson>,
9488 ) -> (String, String, Option<String>, Option<Value>) {
9489 let recommended_action = (!recommended_action.is_empty()).then_some(recommended_action);
9490 let details = details
9491 .and_then(|details| serde_json::from_str::<Value>(&details.0).ok())
9492 .filter(Value::is_object);
9493 (code, message, recommended_action, details)
9494 }
9495
9496 fn finish_live_section(
9501 &mut self,
9502 status: LiveStatus,
9503 reason_code: &str,
9504 through_seq: i64,
9505 echo_digest: Option<[u8; 32]>,
9506 registration_digest: &str,
9507 report: &mut SyncReport,
9508 ) -> Result<(), String> {
9509 let rollback = self.capture();
9510 let resets = report.resets.len();
9511 self.begin_observation("syncular_live_end")?;
9512 let finished = (|| {
9513 let mut batch = ChangeAccumulator::default();
9514 let before = self.stored(replica_cursor(&self.conn))?;
9515 let mut cursor = if status == LiveStatus::Unregistered {
9516 before
9517 } else {
9518 -1
9519 };
9520 let joined = before.max(through_seq);
9521 for unit in self.stored(load_units(&self.conn))? {
9522 if unit.status != UnitStatus::Active || unit.bootstrapping() {
9523 continue;
9524 }
9525 match status {
9526 LiveStatus::Reset if unit.cursor.is_none() => {
9529 for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9530 batch.window(&base_key, &value);
9531 }
9532 report.resets.push(unit.id.clone());
9533 self.stored(save_unit(
9534 &self.conn,
9535 &UnitRecord {
9536 reason_code: Some(reason_code.to_owned()),
9537 cursor: Some(-1),
9538 seeded: Vec::new(),
9539 ..unit
9540 },
9541 ))?;
9542 }
9543 LiveStatus::Active => {
9545 let next = unit.cursor.unwrap_or(joined).max(through_seq);
9546 if next >= joined {
9547 cursor = joined;
9548 }
9549 if unit.cursor.is_some() {
9550 self.stored(save_unit(
9551 &self.conn,
9552 &UnitRecord {
9553 cursor: (next < joined).then_some(next),
9554 ..unit
9555 },
9556 ))?;
9557 }
9558 }
9559 _ => {}
9560 }
9561 }
9562 self.set_meta(REPLICA_CURSOR_KEY, &cursor.to_string())?;
9563 self.set_meta(
9564 ECHO_DIGEST_KEY,
9565 &echo_digest
9566 .map(|digest| bytes_to_hex(&digest))
9567 .unwrap_or_default(),
9568 )?;
9569 if status == LiveStatus::Unregistered {
9570 self.delete_meta(REGISTERED_DIGEST_KEY)?;
9571 } else {
9572 self.set_meta(REGISTERED_DIGEST_KEY, registration_digest)?;
9573 }
9574 self.finish_observation("syncular_live_end", batch)
9575 })();
9576 if finished.is_err() {
9577 self.rollback_observation("syncular_live_end");
9578 self.restore(rollback);
9579 report.resets.truncate(resets);
9580 }
9581 finished
9582 }
9583
9584 fn handle_push_results(
9587 &mut self,
9588 frames: &[Frame],
9589 pushed_ids: &HashSet<&str>,
9590 rejection_details_by_commit: &HashMap<String, BTreeMap<i32, RejectionDetails>>,
9591 report: &mut SyncReport,
9592 last_final_push_result_id: Option<&str>,
9593 ) -> Result<(), String> {
9594 self.begin_observation("syncular_push_results")?;
9595 let rollback = self.capture();
9596 let conflict_count = self.conflicts.len();
9597 let applied_count = report.applied.len();
9598 let rejected_count = report.rejected.len();
9599 let retryable_count = report.retryable.len();
9600 let mut drained = Vec::new();
9601 let mut batch = ChangeAccumulator::default();
9602 let persisted = (|| {
9603 for frame in frames {
9604 let Frame::PushResult {
9605 client_commit_id,
9606 status,
9607 results,
9608 commit_seq,
9609 } = frame
9610 else {
9611 return Err("unexpected acknowledgement frame".to_owned());
9612 };
9613 if !pushed_ids.contains(client_commit_id.as_str()) {
9614 continue;
9615 }
9616 let Some(index) = self
9617 .outbox
9618 .iter()
9619 .position(|commit| commit.client_commit_id == *client_commit_id)
9620 else {
9621 continue;
9622 };
9623 let status = *status;
9624 let rejection_details = rejection_details_by_commit.get(client_commit_id);
9625 let operations = self.outbox[index].ops.clone();
9626 match status {
9627 PushStatus::Applied | PushStatus::Cached => {
9628 let sequence =
9631 commit_seq.ok_or_else(|| "ACK lacks a commit sequence".to_owned())?;
9632 let affected: HashSet<_> = operations
9633 .iter()
9634 .map(|op| (op.table.as_str(), op.row_id.as_str()))
9635 .collect();
9636 let prior = self.acknowledged_operations(Some(&affected), None)?;
9637 for (op_index, operation) in operations.iter().enumerate() {
9638 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))
9639 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9640 if delivered {
9641 continue;
9642 }
9643 let table = self
9644 .schema
9645 .table(&operation.table)
9646 .ok_or_else(|| "sync.unknown_table".to_owned())?;
9647 let mut intended: Map<String, Value> = self
9648 .stored_row(table, &operation.row_id, true)?
9649 .map(|(row, _)| {
9650 table
9651 .columns
9652 .iter()
9653 .zip(&row)
9654 .map(|(column, value)| {
9655 (column.name.clone(), column_value_to_json(value))
9656 })
9657 .collect()
9658 })
9659 .unwrap_or_default();
9660 let mut scope_image = intended.clone();
9661 for op in prior
9662 .iter()
9663 .chain(
9664 self.failed_commits
9665 .iter()
9666 .flat_map(|(commit, _)| &commit.ops),
9667 )
9668 .chain(
9669 self.outbox
9670 .iter()
9671 .take(index)
9672 .flat_map(|commit| &commit.ops),
9673 )
9674 .chain(operations.iter().take(op_index + 1))
9675 {
9676 if op.table != operation.table || op.row_id != operation.row_id {
9677 continue;
9678 }
9679 if let Some(values) = &op.values {
9680 intended.extend(values.clone());
9681 } else {
9682 scope_image = intended.clone();
9683 intended.clear();
9684 }
9685 }
9686 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)",
9687 rusqlite::params![client_commit_id, op_index as i64, operation.table, operation.row_id, sequence,
9688 serde_json::to_string(&CommitOperation::from(operation)).map_err(|_| "sync.local_corrupt".to_owned())?,
9689 serde_json::to_string(if operation.upsert { &intended } else { &scope_image }).map_err(|_| "sync.local_corrupt".to_owned())?])
9690 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9691 }
9692 let journal_results = results
9693 .iter()
9694 .map(|result| {
9695 let op_index = match result {
9696 OpResult::Applied { op_index }
9697 | OpResult::Conflict { op_index, .. }
9698 | OpResult::Error { op_index, .. } => *op_index,
9699 };
9700 CommitOperationOutcome::Applied { op_index }
9701 })
9702 .collect::<Vec<_>>();
9703 let outcome_status = if status == PushStatus::Applied {
9704 CommitOutcomeStatus::Applied
9705 } else {
9706 CommitOutcomeStatus::Cached
9707 };
9708 let persisted = self
9709 .persist_commit_outcome(
9710 client_commit_id,
9711 outcome_status,
9712 &journal_results,
9713 None,
9714 )
9715 .and_then(|()| self.delete_outbox_persisted(client_commit_id));
9716 persisted?;
9717 self.sync_needed = true;
9718 batch.status = true;
9719 batch.outcomes = true;
9720 }
9721 PushStatus::Rejected => {
9722 if results.iter().any(|result| {
9723 matches!(
9724 result,
9725 OpResult::Error {
9726 code,
9727 retryable: true,
9728 ..
9729 } if code == "sync.idempotency_cache_miss"
9730 )
9731 }) {
9732 report.retryable.push(client_commit_id.to_owned());
9735 continue;
9736 }
9737
9738 let mut journal_results = Vec::with_capacity(results.len());
9739 let mut conflicts = Vec::new();
9740 let mut rejections = Vec::new();
9741 for result in results {
9742 match result {
9743 OpResult::Applied { op_index } => {
9744 journal_results.push(CommitOperationOutcome::Applied {
9745 op_index: *op_index,
9746 });
9747 }
9748 OpResult::Conflict {
9749 op_index,
9750 code,
9751 message,
9752 server_version,
9753 server_row,
9754 conflict_columns: conflict_columns_bitmap,
9755 } => {
9756 let operation = operations
9757 .get(*op_index as usize)
9758 .map(CommitOperation::from);
9759 let (table, row_id) = operation
9760 .as_ref()
9761 .map(|op| (op.table.clone(), op.row_id.clone()))
9762 .unwrap_or_default();
9763 let server_row_json = self
9764 .schema
9765 .table(&table)
9766 .and_then(|t| {
9767 decode_row_bytes(t, server_row, &self.encryption)
9768 .ok()
9769 .map(|(row, _)| (t, row))
9770 })
9771 .map(|(t, row)| {
9772 let mut map = Map::new();
9773 for (i, column) in t.columns.iter().enumerate() {
9774 map.insert(
9775 column.name.clone(),
9776 column_value_to_json(
9777 row.get(i).unwrap_or(&None),
9778 ),
9779 );
9780 }
9781 map
9782 })
9783 .unwrap_or_default();
9784 let conflict_columns = self
9787 .schema
9788 .table(&table)
9789 .map(|t| {
9790 t.columns
9791 .iter()
9792 .enumerate()
9793 .filter(|(index, _)| {
9794 conflict_columns_bitmap
9795 .get(index / 8)
9796 .is_some_and(|byte| {
9797 byte & (1 << (index % 8)) != 0
9798 })
9799 })
9800 .map(|(_, column)| column.name.clone())
9801 .collect::<Vec<_>>()
9802 })
9803 .unwrap_or_default();
9804 let conflict = ConflictRecord {
9805 client_commit_id: client_commit_id.to_owned(),
9806 op_index: *op_index,
9807 table,
9808 row_id,
9809 code: code.clone(),
9810 message: message.clone(),
9811 server_version: *server_version,
9812 server_row: server_row_json,
9813 conflict_columns,
9814 operation,
9815 };
9816 journal_results.push(CommitOperationOutcome::Conflict {
9817 conflict: conflict.clone(),
9818 });
9819 conflicts.push(conflict);
9820 }
9821 OpResult::Error {
9822 op_index,
9823 code,
9824 message,
9825 retryable,
9826 } => {
9827 let rejection = RejectionRecord {
9828 client_commit_id: client_commit_id.to_owned(),
9829 op_index: *op_index,
9830 code: code.clone(),
9831 message: message.clone(),
9832 retryable: *retryable,
9833 details: rejection_details
9834 .and_then(|details| details.get(op_index))
9835 .cloned(),
9836 operation: operations
9837 .get(*op_index as usize)
9838 .map(CommitOperation::from),
9839 };
9840 journal_results.push(CommitOperationOutcome::Error {
9841 rejection: rejection.clone(),
9842 });
9843 rejections.push(rejection);
9844 }
9845 }
9846 }
9847 if self.retain_failed_commits {
9848 self.retain_failed_commit(client_commit_id, &operations)?;
9849 }
9850 let outcome_status = if conflicts.is_empty() {
9851 CommitOutcomeStatus::Rejected
9852 } else {
9853 CommitOutcomeStatus::Conflict
9854 };
9855 let persisted = self
9856 .persist_commit_outcome(
9857 client_commit_id,
9858 outcome_status,
9859 &journal_results,
9860 Some(&operations),
9861 )
9862 .and_then(|()| self.delete_outbox_persisted(client_commit_id));
9863 persisted?;
9864 batch.conflicts = !conflicts.is_empty();
9865 batch.rejections = !rejections.is_empty();
9866 batch.status = true;
9867 batch.outcomes = true;
9868 self.conflicts.extend(conflicts);
9869 self.rejections.extend(rejections);
9870 }
9871 }
9872 drained.push(self.outbox.remove(index));
9873 if batch.status {
9874 for operation in &operations {
9875 if !self.record_row_scopes(
9876 &mut batch,
9877 &operation.table,
9878 &operation.row_id,
9879 false,
9880 ) {
9881 batch.table(&operation.table);
9882 }
9883 }
9884 }
9885 match status {
9886 PushStatus::Applied | PushStatus::Cached => {
9887 report.applied.push(client_commit_id.to_owned())
9888 }
9889 PushStatus::Rejected => report.rejected.push(client_commit_id.to_owned()),
9890 }
9891 }
9892 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)) {
9893 self.prune_commit_outcomes()?;
9894 }
9895 self.reconcile_rows(&drained)?;
9896 self.rebuild_overlay_if_dirty()?;
9897 self.finish_observation("syncular_push_results", batch)
9898 })();
9899 if let Err(error) = persisted {
9900 self.rollback_observation("syncular_push_results");
9901 self.restore(rollback);
9902 report.applied.truncate(applied_count);
9903 report.rejected.truncate(rejected_count);
9904 report.retryable.truncate(retryable_count);
9905 return Err(error);
9906 }
9907 if !rollback.sync_needed && self.sync_needed {
9908 self.sync_intent_queue.push_back(SyncIntent::Interactive);
9909 }
9910 report.conflicts += (self.conflicts.len() - conflict_count) as u32;
9911 Ok(())
9912 }
9913
9914 fn push_result_is_final(status: PushStatus, results: &[OpResult]) -> bool {
9915 status != PushStatus::Rejected
9916 || !results.iter().any(|result| {
9917 matches!(
9918 result,
9919 OpResult::Error {
9920 code,
9921 retryable: true,
9922 ..
9923 } if code == "sync.idempotency_cache_miss"
9924 )
9925 })
9926 }
9927
9928 fn process_section(
9937 &mut self,
9938 transport: &mut dyn Transport,
9939 start: &SectionStart,
9940 body: Vec<Frame>,
9941 sub_end: Option<(i64, Option<String>)>,
9942 meta: &RequestMeta,
9943 report: &mut SyncReport,
9944 ) -> Result<bool, SectionError> {
9945 let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
9946 let unit = self
9947 .stored(get_unit(&self.conn, &start.id))
9948 .map_err(storage)?
9949 .filter(|unit| unit.status == UnitStatus::Active);
9950 let extent = match (&unit, body.first()) {
9953 (
9954 Some(_),
9955 Some(Frame::UnitExtent {
9956 rows_total,
9957 rows_done,
9958 }),
9959 ) => u64::try_from(*rows_total)
9960 .ok()
9961 .zip(u64::try_from(*rows_done).ok()),
9962 _ => None,
9963 };
9964 self.progress.update(|p| {
9965 p.phase = ProgressPhase::Import;
9966 p.unit_id = unit.as_ref().map(|unit| unit.id.clone());
9967 p.unit_rows_total = extent.map(|(total, _)| total);
9968 p.unit_rows_processed = extent.map(|(_, done)| done);
9969 p.table = None;
9970 p.segment_id = None;
9971 p.bytes_received = 0;
9972 p.bytes_total = None;
9973 p.rows_processed = 0;
9974 p.rows_total = None;
9975 p.import_write_ms = None;
9976 p.import_commit_ms = None;
9977 });
9978 let Some(unit) = unit else {
9979 return Ok(false);
9980 };
9981 let echo: Vec<EchoRecord> = start
9982 .fenced
9983 .iter()
9984 .map(|record| EchoRecord {
9985 table: record.table.clone(),
9986 status: record.status.name().to_owned(),
9987 scopes: record.scopes.iter().cloned().collect(),
9988 })
9989 .collect();
9990 let applied_record = self
9992 .stored(applied_rows(&self.conn, &unit.id))
9993 .map_err(storage)?;
9994 let mut seeded: BTreeSet<String> = if unit.bootstrap_state.is_none() {
9996 BTreeSet::new()
9997 } else {
9998 unit.seeded.iter().cloned().collect()
9999 };
10000 let applied = (|| {
10001 for frame in body {
10002 match frame {
10003 Frame::SegmentInline { payload } => {
10004 let segment = decode_rows_segment(&payload).map_err(|e| {
10005 SectionError::Abort(e.code.as_str().to_owned(), e.detail)
10006 })?;
10007 self.progress.update(|p| {
10008 p.phase = ProgressPhase::Import;
10009 p.unit_id = Some(unit.id.clone());
10010 p.table = Some(segment.table.clone());
10011 p.segment_id = None;
10012 p.bytes_received = payload.len() as u64;
10013 p.bytes_total = Some(payload.len() as u64);
10014 p.rows_processed = 0;
10015 p.rows_total =
10016 Some(segment.blocks.iter().map(|block| block.len() as u64).sum());
10017 p.import_write_ms = None;
10018 p.import_commit_ms = None;
10019 });
10020 let (pair, clear, effective) =
10021 self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
10022 report.segment_rows_applied +=
10023 self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
10024 seeded.insert(segment.table);
10025 }
10026 Frame::SegmentRef {
10027 segment_id,
10028 byte_length,
10029 media_type,
10030 table,
10031 row_count,
10032 as_of_commit_seq,
10033 scope_digest,
10034 row_cursor,
10035 next_row_cursor,
10036 url,
10037 url_expires_at_ms,
10038 ..
10039 } => {
10040 let advertised = match media_type {
10043 MediaType::Rows => {
10044 meta.accept & ACCEPT_EXTERNAL_ROWS != 0
10045 || meta.accept & ACCEPT_INLINE_ROWS != 0
10046 }
10047 MediaType::Sqlite => meta.accept & ACCEPT_SQLITE != 0,
10048 };
10049 if !advertised {
10050 return Err(SectionError::Abort(
10051 "sync.invalid_request".to_owned(),
10052 format!(
10053 "SEGMENT_REF mediaType {} was not advertised in accept (§4.2)",
10054 media_type.name()
10055 ),
10056 ));
10057 }
10058 let resumed = applied_record.get(&segment_id).copied();
10061 if resumed.is_some() {
10062 seeded.insert(table.clone());
10063 }
10064 if resumed == Some(row_count) {
10065 self.progress.update(|p| {
10068 p.phase = ProgressPhase::Import;
10069 p.unit_id = Some(unit.id.clone());
10070 p.table = Some(table.clone());
10071 p.segment_id = Some(segment_id.clone());
10072 p.bytes_received = 0;
10073 p.bytes_total = None;
10074 p.rows_processed = 0;
10075 p.rows_total = u64::try_from(row_count).ok();
10076 p.import_write_ms = None;
10077 p.import_commit_ms = None;
10078 });
10079 self.progress.update(|p| {
10080 p.rows_processed = u64::try_from(row_count).unwrap_or(0)
10081 });
10082 continue;
10083 }
10084 if meta
10085 .deferred
10086 .contains(&(unit.id.clone(), segment_id.clone()))
10087 {
10088 return Err(SectionError::Deferred);
10089 }
10090 self.progress.update(|p| {
10091 p.phase = ProgressPhase::Download;
10092 p.unit_id = Some(unit.id.clone());
10093 p.table = Some(table.clone());
10094 p.segment_id = Some(segment_id.clone());
10095 p.bytes_received = 0;
10096 p.bytes_total = u64::try_from(byte_length).ok();
10097 p.rows_processed = 0;
10098 p.rows_total = u64::try_from(row_count).ok();
10099 p.import_write_ms = None;
10100 p.import_commit_ms = None;
10101 });
10102 let observer = self.progress.clone();
10103 let mut on_progress = |bytes| observer.update(|p| p.bytes_received = bytes);
10104 let bytes = if let Some(url) = url {
10105 if meta.accept & ACCEPT_SIGNED_URLS == 0 {
10110 return Err(SectionError::Abort(
10111 "sync.invalid_request".to_owned(),
10112 "SEGMENT_REF carries a url but accept bit 3 was not advertised (§5.4)"
10113 .to_owned(),
10114 ));
10115 }
10116 if url_expires_at_ms.is_some_and(|exp| {
10118 exp <= transport
10119 .segment_fetch_started_at(&url)
10120 .unwrap_or_else(|| self.clock_now_ms())
10121 }) {
10122 return Err(SectionError::Abort(
10123 "sync.segment_expired".to_owned(),
10124 format!(
10125 "signed URL for segment {segment_id} expired before fetch — re-pull mints fresh descriptors (§5.4)"
10126 ),
10127 ));
10128 }
10129 transport
10130 .fetch_url(
10131 &url,
10132 u64::try_from(byte_length).unwrap_or(0),
10133 &mut on_progress,
10134 )
10135 .map_err(|e| self.segment_fetch_failed(e))?
10136 } else {
10137 let requested_scopes_json =
10139 canonical_scope_json(&unit_scope_lists(&unit.scopes));
10140 transport
10141 .download_segment(
10142 &SegmentRequest {
10143 segment_id: segment_id.clone(),
10144 table: table.clone(),
10145 requested_scopes_json,
10146 byte_length: u64::try_from(byte_length).unwrap_or(0),
10147 },
10148 &mut on_progress,
10149 )
10150 .map_err(|e| {
10151 if e.code == "sync.forbidden" {
10154 SectionError::Refused
10155 } else {
10156 self.segment_fetch_failed(e)
10157 }
10158 })?
10159 };
10160 if bytes.len() as i64 > byte_length {
10164 self.schedule_background_retry();
10165 return Err(SectionError::Abort(
10166 "sync.invalid_request".to_owned(),
10167 "segment exceeds its byteLength".to_owned(),
10168 ));
10169 }
10170 on_progress(bytes.len() as u64);
10171 let digest = Sha256::digest(&bytes);
10172 let expected = segment_id
10173 .strip_prefix("sha256:")
10174 .unwrap_or(segment_id.as_str());
10175 if bytes_to_hex(&digest) != expected {
10176 self.schedule_background_retry();
10178 return Err(SectionError::Abort(
10179 "sync.invalid_request".to_owned(),
10180 "segment bytes do not match the content address (§5.1)".to_owned(),
10181 ));
10182 }
10183 self.progress.update(|p| p.phase = ProgressPhase::Import);
10184 if media_type == MediaType::Sqlite {
10185 if row_cursor.is_some() || next_row_cursor.is_some() {
10188 return Err(SectionError::Abort(
10189 "sync.invalid_request".to_owned(),
10190 "sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)"
10191 .to_owned(),
10192 ));
10193 }
10194 let (pair, clear, effective) =
10195 self.segment_pair(&unit, &echo, &seeded, &table)?;
10196 report.segment_rows_applied += self.apply_sqlite_segment(
10197 &pair,
10198 &bytes,
10199 clear,
10200 &effective,
10201 &unit.id,
10202 &segment_id,
10203 resumed.unwrap_or(0),
10204 row_count,
10205 as_of_commit_seq,
10206 &scope_digest,
10207 )?;
10208 seeded.insert(table);
10209 } else {
10210 let segment = decode_rows_segment(&bytes).map_err(|e| {
10211 SectionError::Abort(e.code.as_str().to_owned(), e.detail)
10212 })?;
10213 let (pair, clear, effective) =
10214 self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
10215 report.segment_rows_applied +=
10216 self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
10217 seeded.insert(segment.table);
10218 self.stored(record_applied_rows(
10220 &self.conn,
10221 &unit.id,
10222 &segment_id,
10223 row_count,
10224 ))
10225 .map_err(storage)?;
10226 }
10227 }
10228 Frame::UnitExtent { .. } => {}
10229 _ => {
10230 return Err(SectionError::Abort(
10231 "sync.invalid_request".to_owned(),
10232 "unexpected frame inside a unit section".to_owned(),
10233 ));
10234 }
10235 }
10236 }
10237 Ok(())
10238 })();
10239 match applied {
10240 Ok(()) => {}
10241 Err(SectionError::Refused | SectionError::Deferred) => return Ok(false),
10243 Err(SectionError::FailClosed) => {
10244 self.begin_observation("syncular_section_failure")
10247 .map_err(storage)?;
10248 let failed = (|| {
10249 let mut batch = ChangeAccumulator::default();
10250 for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
10251 batch.window(&base_key, &value);
10252 }
10253 batch.status = true;
10254 self.stored(save_unit(
10255 &self.conn,
10256 &UnitRecord {
10257 status: UnitStatus::Failed,
10258 reason_code: Some("sync.scope_revoked".to_owned()),
10259 restriction: None,
10260 ..unit.clone()
10261 },
10262 ))?;
10263 self.finish_observation("syncular_section_failure", batch)
10264 })();
10265 if let Err(message) = failed {
10266 self.rollback_observation("syncular_section_failure");
10267 return Err(storage(message));
10268 }
10269 report.failed.push(unit.id);
10270 return Ok(false);
10271 }
10272 Err(error) => return Err(error),
10273 }
10274 let Some((next_cursor, bootstrap_state)) = sub_end else {
10275 return Ok(false);
10276 };
10277 let completes = start.bootstrap && bootstrap_state.is_none();
10278 let rollback = self.capture();
10279 let counts = (
10280 report.resets.len(),
10281 report.revoked.len(),
10282 report.failed.len(),
10283 );
10284 self.begin_observation("syncular_sub_end")
10285 .map_err(storage)?;
10286 let finished = self
10287 .finish_section(start, echo, next_cursor, bootstrap_state, seeded, report)
10288 .and_then(|batch| {
10289 self.rebuild_overlay_if_dirty()?;
10290 self.finish_observation("syncular_sub_end", batch)
10291 });
10292 if let Err(message) = finished {
10293 self.rollback_observation("syncular_sub_end");
10294 self.restore(rollback);
10295 report.resets.truncate(counts.0);
10296 report.revoked.truncate(counts.1);
10297 report.failed.truncate(counts.2);
10298 return Err(storage(message));
10299 }
10300 Ok(completes)
10301 }
10302
10303 #[allow(clippy::type_complexity)]
10306 fn segment_pair(
10307 &self,
10308 unit: &UnitRecord,
10309 echo: &[EchoRecord],
10310 seeded: &BTreeSet<String>,
10311 name: &str,
10312 ) -> Result<(TableSchema, bool, Vec<(String, Vec<String>)>), SectionError> {
10313 let table = self.schema.table(name).cloned().ok_or_else(|| {
10314 SectionError::Abort(
10315 "sync.schema_mismatch".to_owned(),
10316 format!("segment table {name:?} is not in the client schema"),
10317 )
10318 })?;
10319 let effective = covers(&table, &unit.scopes)
10320 .then(|| pair_scopes(&unit.scopes, name, Some(echo)))
10321 .flatten()
10322 .ok_or_else(|| {
10323 SectionError::Abort(
10324 "sync.invalid_request".to_owned(),
10325 "a segment names no active pair of its unit".to_owned(),
10326 )
10327 })?;
10328 let first_page = !seeded.contains(name);
10329 if first_page
10333 && unit
10334 .restriction
10335 .as_ref()
10336 .is_some_and(|restriction| !restriction.tables.iter().any(|t| t == name))
10337 {
10338 self.conn
10339 .execute(
10340 "UPDATE _syncular_units SET restriction=NULL WHERE id=?1",
10341 [&unit.id],
10342 )
10343 .map_err(|error| {
10344 SectionError::Abort(
10345 "storage.failed".to_owned(),
10346 Self::sqlite_failure(&self.storage_failure, error),
10347 )
10348 })?;
10349 }
10350 Ok((table, first_page, effective))
10351 }
10352
10353 fn finish_section(
10360 &mut self,
10361 start: &SectionStart,
10362 echo: Vec<EchoRecord>,
10363 next_cursor: i64,
10364 bootstrap_state: Option<String>,
10365 seeded: BTreeSet<String>,
10366 report: &mut SyncReport,
10367 ) -> Result<ChangeAccumulator, String> {
10368 #[cfg(feature = "bench-internals")]
10369 let _phase = self.benchmark_phases.start(Phase::CursorPersist);
10370 let mut batch = ChangeAccumulator::default();
10371 let Some(unit) = self
10373 .stored(get_unit(&self.conn, &start.id))?
10374 .filter(|unit| unit.status == UnitStatus::Active)
10375 else {
10376 return Ok(batch);
10377 };
10378 for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
10379 batch.window(&base_key, &value);
10380 }
10381 if start.status == SubStatus::Reset {
10382 report.resets.push(unit.id.clone());
10385 self.stored(save_unit(
10386 &self.conn,
10387 &UnitRecord {
10388 reason_code: Some(start.reason_code.clone()),
10389 cursor: Some(-1),
10390 bootstrap_state: None,
10391 seeded: Vec::new(),
10392 restriction: None,
10393 ..unit
10394 },
10395 ))?;
10396 return Ok(batch);
10397 }
10398 let revoked = start.status == SubStatus::Revoked;
10399 let mut units = None;
10400 let mut failed = false;
10401 let mut rearmed = false;
10402 for table in self.schema.tables.clone() {
10403 if !covers(&table, &unit.scopes) {
10404 continue;
10405 }
10406 let last = unit
10407 .echo
10408 .as_deref()
10409 .and_then(|last| pair_scopes(&unit.scopes, &table.name, Some(last)));
10410 let next = (!revoked)
10411 .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
10412 .flatten();
10413 rearmed |= unit.echo.is_some() && last.is_none() && next.is_some();
10415 if let (Some(last), None) = (&last, &next) {
10418 let units = match units {
10419 Some(ref units) => units,
10420 None => units.insert(self.stored(load_units(&self.conn))?),
10421 };
10422 let owners = unit_owners(units, &table, &unit.id);
10423 failed |= !self.purge_pair(&mut batch, &table, last, &owners)?;
10424 }
10425 }
10426 if revoked || failed {
10427 if revoked {
10428 report.revoked.push(unit.id.clone());
10429 }
10430 if failed {
10431 report.failed.push(unit.id.clone());
10432 }
10433 batch.status = true;
10434 self.stored(save_unit(
10435 &self.conn,
10436 &UnitRecord {
10437 status: if failed {
10438 UnitStatus::Failed
10439 } else {
10440 UnitStatus::Revoked
10441 },
10442 reason_code: Some(if failed {
10443 "sync.scope_revoked".to_owned()
10444 } else {
10445 start.reason_code.clone()
10446 }),
10447 cursor: Some(-1),
10448 bootstrap_state: None,
10449 seeded: Vec::new(),
10450 echo: None,
10451 restriction: None,
10452 ..unit
10453 },
10454 ))?;
10455 return Ok(batch);
10456 }
10457 let completed = start.bootstrap && !rearmed && bootstrap_state.is_none();
10458 let (cursor, bootstrap_state, seeded) = if rearmed {
10459 (Some(-1), None, Vec::new())
10460 } else if start.bootstrap {
10461 let seeded = if bootstrap_state.is_none() {
10462 Vec::new()
10463 } else {
10464 seeded.into_iter().collect()
10465 };
10466 (Some(next_cursor), bootstrap_state, seeded)
10467 } else {
10468 (
10469 unit.cursor,
10470 unit.bootstrap_state.clone(),
10471 unit.seeded.clone(),
10472 )
10473 };
10474 self.stored(save_unit(
10475 &self.conn,
10476 &UnitRecord {
10477 reason_code: None,
10478 echo: Some(echo.clone()),
10479 cursor,
10480 bootstrap_state,
10481 seeded,
10482 restriction: unit.restriction.clone().filter(|_| !rearmed && !completed),
10485 ..unit.clone()
10486 },
10487 ))?;
10488 if !completed {
10489 return Ok(batch);
10490 }
10491 for table in self.schema.tables.clone() {
10494 let Some(effective) = covers(&table, &unit.scopes)
10495 .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
10496 .flatten()
10497 else {
10498 continue;
10499 };
10500 let mut statement = self
10501 .conn
10502 .prepare("SELECT id,intent_json FROM _syncular_acked_rows WHERE tbl=?1 AND commit_seq<=?2")
10503 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10504 let rows = statement
10505 .query_map(rusqlite::params![table.name, next_cursor], |row| {
10506 Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
10507 })
10508 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10509 let mut covered = HashSet::new();
10510 for row in rows {
10511 let (id, intent) =
10512 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10513 let values: Map<String, Value> =
10514 serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
10515 if owns_local_row(&table, &effective, &[], &values) {
10516 covered.insert(id);
10517 }
10518 }
10519 drop(statement);
10520 for id in covered {
10521 self.conn
10522 .execute(
10523 "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3",
10524 rusqlite::params![table.name, id, next_cursor],
10525 )
10526 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10527 self.overlay_dirty.table(&table.name);
10528 batch.table(&table.name);
10529 }
10530 }
10531 Ok(batch)
10532 }
10533
10534 fn purge_pair(
10540 &mut self,
10541 batch: &mut ChangeAccumulator,
10542 table: &TableSchema,
10543 last: &[(String, Vec<String>)],
10544 owners: &[Vec<(String, Vec<String>)>],
10545 ) -> Result<bool, String> {
10546 if local_scope_predicate(table, last, owners).is_err() {
10547 return Ok(false);
10548 }
10549 for commit in self.drop_failed_commits(|name, values| {
10550 name == table.name && owns_local_row(table, last, owners, values)
10551 })? {
10552 batch.conflicts = true;
10553 batch.rejections = true;
10554 batch.outcomes = true;
10555 for operation in commit.ops {
10556 batch.table(&operation.table);
10557 }
10558 }
10559 if !self.purge_scope_rows(&table.name, last, owners)? {
10560 return Err("storage.failed: the revoked scope purge failed".to_owned());
10561 }
10562 self.record_scope_map(batch, &table.name, last);
10563 if self.drop_doomed_outbox(table, last, owners)? {
10564 batch.status = true;
10565 batch.rejections = true;
10566 batch.outcomes = true;
10567 }
10568 self.delete_unreferenced_cached_blobs()?;
10570 Ok(true)
10571 }
10572
10573 fn apply_live_commit(
10578 &mut self,
10579 receivers: &[UnitRecord],
10580 tables: &[String],
10581 changes: Vec<ssp2::model::Change>,
10582 commit_seq: i64,
10583 source: AppliedServerCommitSource,
10584 ) -> Result<bool, TransportError> {
10585 let changes: Vec<ssp2::model::Change> = changes
10586 .into_iter()
10587 .filter(|change| {
10588 let Some(table) = tables
10590 .get(change.table_index as usize)
10591 .and_then(|name| self.schema.table(name))
10592 else {
10593 return true;
10594 };
10595 receivers.iter().any(|unit| {
10596 covers(table, &unit.scopes)
10597 && pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()).is_some_and(
10598 |scopes| {
10599 scopes.iter().all(|(variable, values)| {
10600 change
10601 .scopes
10602 .iter()
10603 .find(|(key, _)| key == variable)
10604 .is_some_and(|(_, value)| values.contains(value))
10605 })
10606 },
10607 )
10608 })
10609 })
10610 .collect();
10611 if changes.is_empty() {
10612 return Ok(false);
10613 }
10614 let affected_tables = changes
10615 .iter()
10616 .filter_map(|change| tables.get(change.table_index as usize))
10617 .cloned()
10618 .collect::<BTreeSet<_>>();
10619 let previous_batches = self.change_queue.len();
10620 self.apply_commit_frame(tables, &changes, commit_seq)?;
10621 if self.change_queue.len() > previous_batches {
10622 if let Some(batch) = self.change_queue.back_mut() {
10623 batch
10624 .applied_commits
10625 .extend(
10626 affected_tables
10627 .into_iter()
10628 .map(|table| AppliedServerCommit {
10629 table,
10630 commit_seq,
10631 source,
10632 }),
10633 );
10634 }
10635 }
10636 Ok(true)
10637 }
10638
10639 fn apply_commit_frame(
10641 &mut self,
10642 tables: &[String],
10643 changes: &[ssp2::model::Change],
10644 sequence: i64,
10645 ) -> Result<(), TransportError> {
10646 #[cfg(feature = "bench-internals")]
10647 let _phase = self.benchmark_phases.start(Phase::CommitApply);
10648 let rollback = self.capture();
10649 self.coalesce_unit(changes.len())
10650 .and_then(|()| self.begin_observation("syncular_commit"))
10651 .map_err(|message| TransportError::new("storage.failed", message))?;
10652 let applied = (|| {
10653 let mut batch = ChangeAccumulator::default();
10654 self.record_commit_changes(&mut batch, tables, changes);
10655 for change in changes {
10658 let Some(table) = tables.get(change.table_index as usize) else {
10659 continue;
10660 };
10661 let acknowledged = self
10662 .conn
10663 .prepare_cached("SELECT op_json FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq=?3")
10664 .and_then(|mut statement| {
10665 statement
10666 .query_map(rusqlite::params![table, change.row_id, sequence], |row| row.get::<_, String>(0))?
10667 .collect::<Result<Vec<_>, _>>()
10668 })
10669 .map_err(|error| TransportError::new("storage.failed", Self::sqlite_failure(&self.storage_failure, error)))?
10670 .iter()
10671 .map(|op| serde_json::from_str::<CommitOperation>(op).map(OutboxOp::from))
10672 .collect::<Result<Vec<_>, _>>()
10673 .map_err(|_| TransportError::new("storage.failed", "sync.local_corrupt: invalid acknowledged operation".to_owned()))?;
10674 for index in 0..self.outbox.len() {
10675 if !self.outbox[index]
10676 .ops
10677 .iter()
10678 .any(|op| acknowledged.iter().any(|earlier| chains_on(earlier, op)))
10679 {
10680 continue;
10681 }
10682 let commit = Arc::make_mut(&mut self.outbox[index]);
10683 for op in &mut commit.ops {
10684 if acknowledged.iter().any(|earlier| chains_on(earlier, op)) {
10685 op.base_version = Some(change.row_version);
10686 }
10687 }
10688 let ops = serde_json::to_string(
10689 &commit
10690 .ops
10691 .iter()
10692 .map(CommitOperation::from)
10693 .collect::<Vec<_>>(),
10694 )
10695 .map_err(|_| {
10696 TransportError::new(
10697 "storage.failed",
10698 "sync.local_corrupt: unencodable outbox".to_owned(),
10699 )
10700 })?;
10701 let id = commit.client_commit_id.clone();
10702 self.conn
10703 .execute(
10704 "UPDATE _syncular_outbox SET ops_json=?1 WHERE commit_id=?2",
10705 rusqlite::params![ops, id],
10706 )
10707 .map_err(|error| {
10708 TransportError::new(
10709 "storage.failed",
10710 Self::sqlite_failure(&self.storage_failure, error),
10711 )
10712 })?;
10713 }
10714 }
10715 {
10716 let storage_failed = |error| {
10717 TransportError::new(
10718 "storage.failed",
10719 Self::sqlite_failure(&self.storage_failure, error),
10720 )
10721 };
10722 let pinned: HashSet<(&str, &str)> = self
10723 .outbox
10724 .iter()
10725 .flat_map(|commit| &commit.ops)
10726 .map(|op| (op.table.as_str(), op.row_id.as_str()))
10727 .collect();
10728 for change in changes {
10729 let table = tables.get(change.table_index as usize).ok_or_else(|| {
10730 TransportError::new(
10731 "sync.invalid_request",
10732 "change tableIndex out of range".to_owned(),
10733 )
10734 })?;
10735 if pinned.contains(&(table.as_str(), change.row_id.as_str())) {
10736 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)")
10737 .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
10738 .map_err(storage_failed)?;
10739 }
10740 self.conn.prepare_cached("DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3")
10741 .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
10742 .map_err(storage_failed)?;
10743 }
10744 }
10745 self.apply_commit_changes(tables, changes)?;
10746 self.rebuild_overlay_if_dirty()
10747 .map_err(|message| TransportError::new("storage.failed", message))?;
10748 self.finish_observation("syncular_commit", batch)
10749 .map_err(|message| TransportError::new("storage.failed", message))
10750 })();
10751 if applied.is_err() {
10752 self.rollback_observation("syncular_commit");
10753 self.restore(rollback);
10754 }
10755 applied
10756 }
10757
10758 fn apply_commit_changes(
10759 &mut self,
10760 tables: &[String],
10761 changes: &[ssp2::model::Change],
10762 ) -> Result<(), TransportError> {
10763 let changed_tables: BTreeSet<&str> = changes
10768 .iter()
10769 .filter_map(|change| tables.get(change.table_index as usize))
10770 .map(String::as_str)
10771 .collect();
10772 let mut mirror_visible = !self.overlay_dirty.get();
10773 for name in &changed_tables {
10774 if mirror_visible
10775 && self
10776 .schema
10777 .table(name)
10778 .is_some_and(|table| table.indexes.iter().any(|index| index.unique))
10779 {
10780 let (pending, protected) = self
10781 .table_intent(name)
10782 .map_err(|message| TransportError::new("storage.failed", message))?;
10783 mirror_visible = !pending && !protected;
10784 }
10785 }
10786 for change in changes {
10787 let table_name = tables.get(change.table_index as usize).ok_or_else(|| {
10788 TransportError::new(
10789 "sync.invalid_request",
10790 "change tableIndex out of range".to_owned(),
10791 )
10792 })?;
10793 let table = self.schema.table(table_name).ok_or_else(|| {
10794 TransportError::new(
10795 "sync.schema_mismatch",
10796 format!("change targets unknown table {table_name:?}"),
10797 )
10798 })?;
10799 let landed = match change.op {
10800 Op::Upsert => {
10801 let payload = change.row.as_ref().ok_or_else(|| {
10802 TransportError::new(
10803 "sync.invalid_request",
10804 "upsert change without row payload".to_owned(),
10805 )
10806 })?;
10807 let (row, sealed) = {
10809 #[cfg(feature = "bench-internals")]
10810 let _phase = self.benchmark_phases.start(Phase::RowDecode);
10811 decode_row_bytes(table, payload, &self.encryption)?
10813 };
10814 let table_name = table.name.clone();
10815 let landed = self
10817 .write_base_row(&table_name, &row, change.row_version, sealed.as_ref())
10818 .map_err(|m| TransportError::new("sync.invalid_request", m))?;
10819 if mirror_visible && landed {
10820 self.write_row(
10821 &visible_table(&table_name),
10822 &table_name,
10823 &row,
10824 change.row_version,
10825 sealed.as_ref(),
10826 )
10827 .map_err(|m| TransportError::new("sync.invalid_request", m))?;
10828 }
10829 landed
10830 }
10831 Op::Delete => self
10834 .delete_base_row(table_name, &change.row_id, change.row_version)
10835 .map_err(|m| TransportError::new("sync.invalid_request", m))?,
10836 };
10837 self.overlay_dirty.table(table_name);
10841 if mirror_visible && !(landed && change.op == Op::Upsert) {
10842 let predicate = row_id_predicate(table);
10843 let visible = visible_table(table_name);
10844 let mut statements = vec![format!("DELETE FROM {visible} WHERE {predicate}")];
10845 if !landed {
10846 statements.push(format!(
10847 "INSERT INTO {visible} SELECT * FROM {} WHERE {predicate}",
10848 base_table(table_name)
10849 ));
10850 }
10851 for statement in &statements {
10852 self.conn
10853 .prepare_cached(statement)
10854 .and_then(|mut statement| {
10855 statement.execute(rusqlite::params![change.row_id])
10856 })
10857 .map_err(|error| {
10858 TransportError::new("sync.invalid_request", error.to_string())
10859 })?;
10860 }
10861 }
10862 }
10863 if mirror_visible {
10864 let changed_rows: HashSet<(&str, &str)> = changes
10865 .iter()
10866 .map(|change| {
10867 (
10868 tables[change.table_index as usize].as_str(),
10869 change.row_id.as_str(),
10870 )
10871 })
10872 .collect();
10873 self.replay_overlay(&changed_tables, Some(&changed_rows))
10874 .map_err(|message| TransportError::new("storage.failed", message))?;
10875 self.overlay_dirty.set(false);
10876 }
10877 Ok(())
10878 }
10879
10880 fn apply_segment(
10885 &mut self,
10886 table: &TableSchema,
10887 segment: &RowsSegment,
10888 first_page: bool,
10889 effective: &[(String, Vec<String>)],
10890 unit_id: &str,
10891 ) -> Result<u32, SectionError> {
10892 let column = if segment.columns.len() != table.wire_columns.len() {
10897 Some(Value::from("count"))
10898 } else {
10899 segment
10900 .columns
10901 .iter()
10902 .zip(table.wire_columns.iter())
10903 .position(|(a, b)| a.name != b.name || a.ty != b.ty || a.nullable != b.nullable)
10904 .map(Value::from)
10905 };
10906 if segment.table != table.name
10907 || segment.schema_version != self.schema.version
10908 || column.is_some()
10909 {
10910 let mut details = Map::new();
10911 details.insert("table".to_owned(), Value::from(table.name.as_str()));
10912 if let Some(column) = column {
10913 details.insert("column".to_owned(), column);
10914 }
10915 return Err(SectionError::Transport(TransportError {
10916 code: "sync.schema_mismatch".to_owned(),
10917 message: "rows segment columns do not match the generated schema (§5.2)".to_owned(),
10918 details: Some(Value::Object(details)),
10919 }));
10920 }
10921 let mut applied = 0u32;
10922 let empty = Vec::new();
10923 let blocks = if segment.blocks.is_empty() {
10924 std::slice::from_ref(&empty)
10925 } else {
10926 &segment.blocks
10927 };
10928 for (index, block) in blocks.iter().enumerate() {
10929 let clear = first_page && index == 0;
10930 if !clear && block.is_empty() {
10931 continue;
10932 }
10933 let rollback = self.capture();
10934 let (pending, protected) = self
10935 .table_intent(&table.name)
10936 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10937 let reconcile_pending =
10938 !protected && pending && table.indexes.iter().any(|index| index.unique);
10939 let mirror_visible = !protected && !reconcile_pending;
10940 self.coalesce_unit(block.len())
10941 .and_then(|()| self.begin_observation("syncular_segment_block"))
10942 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10943 let outcome = (|| {
10944 self.rebuild_overlay_if_dirty()
10945 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10946 let mut changed_keys = Vec::new();
10947 let mut batch = ChangeAccumulator::default();
10948 if clear && self.clear_scope(table, effective, unit_id)? || !block.is_empty() {
10949 batch.table(&table.name);
10950 }
10951 for (row_index, row) in block.iter().enumerate() {
10952 let decrypted;
10953 let mut sealed = None;
10954 let values = if table.has_encrypted_columns() {
10955 let mut values = row.values.clone();
10956 sealed = crate::values::decrypt_segment_row(
10957 table,
10958 &mut values,
10959 &self.encryption,
10960 )
10961 .map_err(SectionError::Transport)?;
10962 decrypted = values;
10963 &decrypted
10964 } else {
10965 &row.values
10966 };
10967 if !self
10968 .write_base_row(&table.name, values, row.server_version, sealed.as_ref())
10969 .map_err(|message| {
10970 SectionError::Abort("sync.invalid_request".into(), message)
10971 })?
10972 {
10973 continue;
10974 }
10975 if reconcile_pending {
10976 changed_keys.push(
10977 owned_sql_value(RowParam::Cell(&values[table.pk_index])).map_err(
10978 |message| SectionError::Abort("storage.failed".into(), message),
10979 )?,
10980 );
10981 }
10982 if mirror_visible {
10983 self.write_row(
10984 &visible_table(&table.name),
10985 &table.name,
10986 values,
10987 row.server_version,
10988 sealed.as_ref(),
10989 )
10990 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10991 }
10992 let processed = u64::from(applied) + row_index as u64 + 1;
10993 if processed.is_multiple_of(1024) {
10994 self.progress.update(|p| p.rows_processed = processed);
10995 }
10996 }
10997 self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
10998 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10999 self.finish_observation("syncular_segment_block", batch)
11000 .map_err(|message| SectionError::Abort("storage.failed".into(), message))
11001 })();
11002 if let Err(error) = outcome {
11003 self.rollback_observation("syncular_segment_block");
11004 self.restore(rollback);
11005 return Err(error);
11006 }
11007 applied += block.len() as u32;
11008 self.progress
11009 .update(|p| p.rows_processed = u64::from(applied));
11010 std::thread::yield_now();
11011 }
11012 self.progress
11013 .update(|p| p.rows_processed = u64::from(applied));
11014 Ok(applied)
11015 }
11016
11017 #[allow(clippy::too_many_arguments)]
11025 fn apply_sqlite_segment(
11026 &mut self,
11027 table: &TableSchema,
11028 bytes: &[u8],
11029 first_page: bool,
11030 effective: &[(String, Vec<String>)],
11031 unit_id: &str,
11032 segment_id: &str,
11033 resumed: i64,
11034 row_count: i64,
11035 as_of_commit_seq: i64,
11036 scope_digest: &str,
11037 ) -> Result<u32, SectionError> {
11038 let invalid = |detail: &str| {
11039 SectionError::Abort(
11040 "sync.invalid_request".to_owned(),
11041 format!("sqlite segment rejected: {detail} (§5.3)"),
11042 )
11043 };
11044 if table.has_encrypted_columns() {
11047 return Err(invalid("table has encrypted columns"));
11048 }
11049
11050 let directory = self
11054 .previous_version_replica_path()
11055 .and_then(|replica| std::path::Path::new(&replica).parent().map(Into::into))
11056 .unwrap_or_else(std::env::temp_dir);
11057 let path = directory.join(format!(".syncular-image-{}.tmp", uuid::Uuid::new_v4()));
11058 let outcome = (|| {
11059 let mut options = std::fs::OpenOptions::new();
11060 options.write(true).create_new(true);
11061 #[cfg(unix)]
11062 std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600);
11063 std::io::Write::write_all(
11064 &mut options
11065 .open(&path)
11066 .map_err(|_| invalid("image temp file write failed"))?,
11067 bytes,
11068 )
11069 .map_err(|_| invalid("image temp file write failed"))?;
11070 let img = rusqlite::Connection::open_with_flags(
11071 &path,
11072 rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY,
11073 )
11074 .map_err(|_| invalid("bytes do not open as a SQLite database"))?;
11075 self.apply_sqlite_image(
11076 &img,
11077 table,
11078 first_page,
11079 effective,
11080 unit_id,
11081 segment_id,
11082 resumed,
11083 row_count,
11084 as_of_commit_seq,
11085 scope_digest,
11086 )
11087 })();
11088 let _ = std::fs::remove_file(&path);
11089 outcome
11090 }
11091
11092 #[allow(clippy::too_many_arguments)]
11093 fn apply_sqlite_image(
11094 &mut self,
11095 img: &rusqlite::Connection,
11096 table: &crate::schema::TableSchema,
11097 first_fresh_page: bool,
11098 effective: &[(String, Vec<String>)],
11099 unit_id: &str,
11100 segment_id: &str,
11101 resumed: i64,
11102 row_count: i64,
11103 as_of_commit_seq: i64,
11104 scope_digest: &str,
11105 ) -> Result<u32, SectionError> {
11106 let invalid = |detail: String| {
11107 SectionError::Abort(
11108 "sync.invalid_request".to_owned(),
11109 format!("sqlite segment rejected: {detail} (§5.3)"),
11110 )
11111 };
11112
11113 type MetaRow = (i64, String, i64, i64, String, i64, i64);
11116 let meta: MetaRow = img
11117 .query_row(
11118 "SELECT format, \"table\", \"schemaVersion\", \"asOfCommitSeq\",
11119 \"scopeDigest\", \"rowCount\",
11120 (SELECT count(*) FROM _syncular_segment)
11121 FROM _syncular_segment",
11122 [],
11123 |row| {
11124 Ok((
11125 row.get(0)?,
11126 row.get(1)?,
11127 row.get(2)?,
11128 row.get(3)?,
11129 row.get(4)?,
11130 row.get(5)?,
11131 row.get(6)?,
11132 ))
11133 },
11134 )
11135 .map_err(|_| invalid("missing or unreadable _syncular_segment metadata".to_owned()))?;
11136 let (format, meta_table, schema_version, pin, digest, meta_rows, meta_count) = meta;
11137 if meta_count != 1 {
11138 return Err(invalid(format!(
11139 "_syncular_segment must contain exactly one row, found {meta_count}"
11140 )));
11141 }
11142 if format != 1 {
11143 return Err(invalid(format!("format {format}")));
11144 }
11145 if meta_table != table.name {
11146 return Err(invalid(format!("image table {meta_table:?}")));
11147 }
11148 if schema_version != i64::from(self.schema.version) {
11149 return Err(invalid(format!("schemaVersion {schema_version}")));
11150 }
11151 if pin != as_of_commit_seq {
11152 return Err(invalid(format!("asOfCommitSeq {pin}")));
11153 }
11154 if digest != scope_digest {
11155 return Err(invalid("scopeDigest mismatch".to_owned()));
11156 }
11157 if meta_rows != row_count {
11158 return Err(invalid(format!("rowCount {meta_rows}")));
11159 }
11160
11161 let mut names: Vec<String> = Vec::new();
11163 let mut primary_keys: Vec<String> = Vec::new();
11164 {
11165 let mut stmt = img
11166 .prepare(&format!("PRAGMA table_info({})", quote_ident(&table.name)))
11167 .map_err(|_| invalid("image data table missing".to_owned()))?;
11168 let mut rows = stmt
11169 .query([])
11170 .map_err(|_| invalid("image data table unreadable".to_owned()))?;
11171 while let Some(row) = rows
11172 .next()
11173 .map_err(|_| invalid("image data table unreadable".to_owned()))?
11174 {
11175 if row
11176 .get::<_, i64>(5)
11177 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?
11178 > 0
11179 {
11180 primary_keys.push(row.get(1).map_err(|error| {
11181 invalid(Self::sqlite_failure(&self.storage_failure, error))
11182 })?);
11183 }
11184 names.push(
11185 row.get::<_, String>(1)
11186 .map_err(|_| invalid("image data table unreadable".to_owned()))?,
11187 );
11188 }
11189 }
11190 let mut expected: Vec<&str> = table.columns.iter().map(|c| c.name.as_str()).collect();
11191 expected.push("_syncular_version");
11192 if names.len() != expected.len() || names.iter().zip(expected.iter()).any(|(a, b)| a != b) {
11193 return Err(SectionError::Transport(TransportError {
11194 code: "sync.schema_mismatch".to_owned(),
11195 message: "sqlite segment columns do not match the generated schema (§5.3)"
11196 .to_owned(),
11197 details: Some(serde_json::json!({ "table": table.name })),
11198 }));
11199 }
11200
11201 if primary_keys != vec![table.primary_key.clone()] {
11202 return Err(invalid(
11203 "image primary key does not match generated schema".into(),
11204 ));
11205 }
11206 let actual_count: i64 = img
11207 .query_row(
11208 &format!("SELECT count(*) FROM {}", quote_ident(&table.name)),
11209 [],
11210 |row| row.get(0),
11211 )
11212 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
11213 if actual_count != row_count {
11214 return Err(invalid("image row count does not match descriptor".into()));
11215 }
11216 let insert = self.insert_row_sql(&base_table(&table.name), table);
11217 let visible_insert = self.insert_row_sql(&visible_table(&table.name), table);
11218 let column_list = names
11219 .iter()
11220 .map(|n| quote_ident(n))
11221 .collect::<Vec<_>>()
11222 .join(", ");
11223 let mut stmt = img
11226 .prepare(&format!(
11227 "SELECT {column_list} FROM {} ORDER BY {} LIMIT -1 OFFSET ?1",
11228 quote_ident(&table.name),
11229 quote_ident(&table.primary_key)
11230 ))
11231 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
11232 let mut rows = stmt
11233 .query([resumed])
11234 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
11235 let resumed = u32::try_from(resumed)
11236 .ok()
11237 .filter(|rows| i64::from(*rows) <= actual_count)
11238 .ok_or_else(|| invalid("applied-segment record exceeds the image".into()))?;
11239 let mut applied = resumed;
11240 let mut limit = if first_fresh_page {
11241 1024
11242 } else {
11243 self.image_chunk_rows
11244 .get(&table.name)
11245 .copied()
11246 .unwrap_or(1024)
11247 };
11248 let (mut write, mut commit) = (std::time::Duration::ZERO, std::time::Duration::ZERO);
11249 loop {
11250 let clear = applied == 0 && first_fresh_page;
11251 let rollback = self.capture();
11252 let (pending, protected) = self
11253 .table_intent(&table.name)
11254 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11255 let reconcile_pending =
11256 !protected && pending && table.indexes.iter().any(|index| index.unique);
11257 let mirror_visible = !protected && !reconcile_pending;
11258 let chunk = if pending || protected {
11265 limit.min(1024)
11266 } else {
11267 limit
11268 };
11269 self.coalesce_unit(chunk as usize)
11270 .and_then(|()| self.begin_observation("syncular_image_chunk"))
11271 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11272 let started = std::time::Instant::now();
11273 let result = (|| {
11274 self.rebuild_overlay_if_dirty()
11275 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11276 let mut changed_keys = Vec::new();
11277 let mut batch = ChangeAccumulator::default();
11278 if clear && self.clear_scope(table, effective, unit_id)? {
11279 batch.table(&table.name);
11280 }
11281 let mut processed = 0u32;
11282 {
11283 let mut ins = self.conn.prepare_cached(&insert).map_err(|error| {
11284 invalid(Self::sqlite_failure(&self.storage_failure, error))
11285 })?;
11286 let mut mirror = if mirror_visible {
11287 Some(self.conn.prepare_cached(&visible_insert).map_err(|error| {
11288 invalid(Self::sqlite_failure(&self.storage_failure, error))
11289 })?)
11290 } else {
11291 None
11292 };
11293 for _ in 0..chunk {
11294 let Some(row) = rows.next().map_err(|error| {
11295 invalid(Self::sqlite_failure(&self.storage_failure, error))
11296 })?
11297 else {
11298 break;
11299 };
11300 for (i, column) in table.columns.iter().enumerate() {
11301 let cell = row.get_ref(i).map_err(|error| {
11302 invalid(Self::sqlite_failure(&self.storage_failure, error))
11303 })?;
11304 let param = image_cell_param(column, cell).map_err(invalid)?;
11305 ins.raw_bind_parameter(i + 1, ¶m).map_err(|error| {
11306 invalid(Self::sqlite_failure(&self.storage_failure, error))
11307 })?;
11308 if let Some(mirror) = &mut mirror {
11309 mirror.raw_bind_parameter(i + 1, ¶m).map_err(|error| {
11310 invalid(Self::sqlite_failure(&self.storage_failure, error))
11311 })?;
11312 }
11313 }
11314 let version_index = table.columns.len();
11315 let version: i64 = row.get(version_index).map_err(|error| {
11316 invalid(Self::sqlite_failure(&self.storage_failure, error))
11317 })?;
11318 if version < 1 {
11319 return Err(invalid("image row version must be positive".into()));
11320 }
11321 ins.raw_bind_parameter(version_index + 1, version)
11322 .map_err(|error| {
11323 invalid(Self::sqlite_failure(&self.storage_failure, error))
11324 })?;
11325 let landed = ins.raw_execute().map_err(|error| {
11327 invalid(Self::sqlite_failure(&self.storage_failure, error))
11328 })? > 0;
11329 processed += 1;
11330 if processed.is_multiple_of(1024) && processed < chunk {
11331 self.progress
11332 .update(|p| p.rows_processed = u64::from(applied + processed));
11333 }
11334 if !landed {
11335 continue;
11336 }
11337 if let Some(mirror) = &mut mirror {
11338 mirror
11339 .raw_bind_parameter(version_index + 1, version)
11340 .map_err(|error| {
11341 invalid(Self::sqlite_failure(&self.storage_failure, error))
11342 })?;
11343 mirror.raw_execute().map_err(|error| {
11344 invalid(Self::sqlite_failure(&self.storage_failure, error))
11345 })?;
11346 }
11347 if reconcile_pending {
11348 changed_keys.push(row.get::<_, SqlValue>(table.pk_index).map_err(
11349 |error| invalid(Self::sqlite_failure(&self.storage_failure, error)),
11350 )?);
11351 }
11352 }
11353 }
11354 if processed > 0 {
11355 batch.table(&table.name);
11356 self.overlay_dirty.table(&table.name);
11357 }
11358 self.stored(record_applied_rows(
11359 &self.conn,
11360 unit_id,
11361 segment_id,
11362 i64::from(applied + processed),
11363 ))
11364 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11365 self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
11366 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11367 let written = std::time::Instant::now();
11368 self.finish_observation("syncular_image_chunk", batch)
11369 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11370 Ok((processed, written))
11371 })();
11372 let (processed, written) = match result {
11373 Ok(done) => done,
11374 Err(error) => {
11375 self.rollback_observation("syncular_image_chunk");
11376 self.restore(rollback);
11377 return Err(error);
11378 }
11379 };
11380 let coalesced = self.coalesced.is_some();
11382 if coalesced {
11383 self.commit_coalesced_apply()
11384 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11385 }
11386 write += written - started;
11387 commit += written.elapsed();
11388 applied += processed;
11389 let last = processed < chunk || i64::from(applied) == actual_count;
11390 if last && self.conn.is_autocommit() {
11392 self.conn
11393 .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
11394 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
11395 }
11396 if coalesced {
11397 self.begin_coalesced_apply()
11398 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
11399 }
11400 self.progress.update(|p| {
11401 p.rows_processed = u64::from(applied);
11402 p.import_write_ms = u64::try_from(write.as_millis()).ok();
11403 p.import_commit_ms = u64::try_from(commit.as_millis()).ok();
11404 });
11405 let duration = started.elapsed().as_secs_f64() * 1000.0;
11406 #[cfg(test)]
11407 let duration = self.image_chunk_ms.get().unwrap_or(duration);
11408 std::thread::yield_now();
11409 if last {
11410 break;
11411 }
11412 limit = (processed * 2)
11414 .min(65_536)
11415 .min((f64::from(processed) * 250.0 / duration) as u32)
11416 .max(1024);
11417 self.image_chunk_rows.insert(table.name.clone(), limit);
11418 }
11419 if i64::from(applied) != actual_count {
11420 return Err(invalid(format!(
11421 "image yielded {applied} rows, expected {actual_count}"
11422 )));
11423 }
11424 Ok(applied - resumed)
11425 }
11426
11427 fn reconcile_rows(&self, drained: &[Arc<OutboxCommit>]) -> Result<(), String> {
11432 let names: BTreeSet<&str> = drained
11433 .iter()
11434 .flat_map(|commit| &commit.ops)
11435 .map(|op| op.table.as_str())
11436 .collect();
11437 for name in names {
11438 let Some(table) = self.schema.table(name) else {
11439 continue;
11440 };
11441 let ops = drained.iter().flat_map(|commit| &commit.ops);
11442 let tables = BTreeSet::from([name]);
11443 let rows: HashSet<_> = ops
11444 .clone()
11445 .map(|op| (op.table.as_str(), op.row_id.as_str()))
11446 .collect();
11447 let unique = table.indexes.iter().any(|index| index.unique);
11448 let acknowledged = if unique {
11449 self.acknowledged_operations(None, Some(&tables))?
11450 } else {
11451 Vec::new()
11452 };
11453 let peers = acknowledged
11454 .iter()
11455 .chain(
11456 self.failed_commits
11457 .iter()
11458 .flat_map(|(commit, _)| &commit.ops),
11459 )
11460 .chain(self.outbox.iter().flat_map(|commit| &commit.ops))
11461 .filter(|_| unique);
11462 self.restore_base_rows(table, &mut Vec::new(), peers.chain(ops.clone()))?;
11463 self.replay_overlay(&tables, (!unique).then_some(&rows))?;
11464 }
11465 Ok(())
11466 }
11467
11468 fn table_intent(&self, table: &str) -> Result<(bool, bool), String> {
11471 let touches = |op: &OutboxOp| op.table == table;
11472 Ok((
11473 self.outbox
11474 .iter()
11475 .flat_map(|commit| &commit.ops)
11476 .any(touches),
11477 self.failed_commits
11478 .iter()
11479 .flat_map(|(commit, _)| &commit.ops)
11480 .any(touches)
11481 || self
11482 .conn
11483 .query_row(
11484 "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows WHERE tbl=?1)",
11485 [table],
11486 |row| row.get(0),
11487 )
11488 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
11489 ))
11490 }
11491
11492 fn reconcile_import(
11496 &mut self,
11497 table: &TableSchema,
11498 keys: &mut Vec<SqlValue>,
11499 protected: bool,
11500 restore: bool,
11501 ) -> Result<(), String> {
11502 if protected {
11503 return self.rebuild_overlay_if_dirty();
11504 }
11505 let pending = self.outbox.iter().flat_map(|commit| &commit.ops);
11506 if restore {
11507 self.restore_base_rows(table, keys, pending.clone())?;
11508 }
11509 self.apply_outbox_ops(pending.filter(|op| op.table == table.name))?;
11510 self.overlay_dirty.set(false);
11511 Ok(())
11512 }
11513
11514 fn restore_base_rows<'a>(
11518 &self,
11519 table: &TableSchema,
11520 keys: &mut Vec<SqlValue>,
11521 ops: impl IntoIterator<Item = &'a OutboxOp>,
11522 ) -> Result<(), String> {
11523 let visible = visible_table(&table.name);
11524 let base = base_table(&table.name);
11525 let pk = quote_ident(&table.primary_key);
11526 let predicate = row_id_predicate(table);
11527 let mut lookup = self.conn.prepare_cached(&format!(
11528 "SELECT {pk} FROM {base} WHERE {predicate} UNION SELECT {pk} FROM {visible} WHERE {predicate}"
11529 )).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11530 let mut deleted = HashSet::new();
11531 for op in ops.into_iter().filter(|op| op.table == table.name) {
11532 if op.upsert {
11533 if let Some(values) = &op.values {
11534 let key = json_to_column_value(
11535 &table.columns[table.pk_index],
11536 values.get(&table.primary_key),
11537 )?;
11538 keys.push(owned_sql_value(RowParam::Cell(&key))?);
11539 }
11540 } else if deleted.insert(&op.row_id) {
11541 keys.extend(
11542 lookup
11543 .query_map([&op.row_id], |row| row.get::<_, SqlValue>(0))
11544 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11545 .collect::<Result<Vec<_>, _>>()
11546 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
11547 );
11548 }
11549 }
11550 for chunk in keys.chunks(400) {
11553 let holes = vec!["?"; chunk.len()].join(",");
11554 self.conn
11555 .prepare_cached(&format!("DELETE FROM {visible} WHERE {pk} IN ({holes})"))
11556 .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
11557 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11558 }
11559 let updates = table
11560 .columns
11561 .iter()
11562 .map(|column| column.name.as_str())
11563 .chain(std::iter::once("_syncular_version"))
11564 .chain(table.sealed_columns().iter().copied())
11565 .filter(|name| *name != table.primary_key)
11566 .map(|name| {
11567 let name = quote_ident(name);
11568 format!("{name}=excluded.{name}")
11569 })
11570 .collect::<Vec<_>>()
11571 .join(",");
11572 for chunk in keys.chunks(400) {
11573 let holes = vec!["?"; chunk.len()].join(",");
11574 self.conn.prepare_cached(&format!("INSERT INTO {visible} SELECT * FROM {base} WHERE {pk} IN ({holes}) ON CONFLICT ({pk}) DO UPDATE SET {updates}"))
11575 .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
11576 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11577 }
11578 Ok(())
11579 }
11580
11581 fn compile_local_data_purge(
11584 &self,
11585 input: &LocalDataPurgeInput,
11586 ) -> Result<(Vec<CompiledLocalDataPurgeTarget>, String), String> {
11587 let invalid = |message: String| format!("sync.invalid_request: {message}");
11588 if input.purge_id.is_empty()
11589 || input.purge_id.len() > 128
11590 || !is_local_operation_code_like(&input.purge_id)
11591 {
11592 return Err(invalid(
11593 "local purge purgeId must be a 1–128 character code-like identifier".to_owned(),
11594 ));
11595 }
11596 if input.targets.is_empty() || input.targets.len() > MAX_LOCAL_PURGE_TARGETS {
11597 return Err(invalid(format!(
11598 "local purge needs between 1 and {MAX_LOCAL_PURGE_TARGETS} targets"
11599 )));
11600 }
11601
11602 let mut deduplicated: BTreeMap<
11603 String,
11604 (CompiledLocalDataPurgeTarget, LocalDataPurgeTarget),
11605 > = BTreeMap::new();
11606 for target in &input.targets {
11607 let table = self.schema.table(&target.table).ok_or_else(|| {
11608 invalid(format!(
11609 "local purge names unknown table {:?}",
11610 target.table
11611 ))
11612 })?;
11613 if target.selectors.is_empty() || target.selectors.len() > MAX_LOCAL_PURGE_SELECTORS {
11614 return Err(invalid(format!(
11615 "local purge target {:?} needs between 1 and {MAX_LOCAL_PURGE_SELECTORS} selectors",
11616 target.table
11617 )));
11618 }
11619 let mut selectors = Vec::with_capacity(target.selectors.len());
11620 let mut canonical_selectors = BTreeMap::new();
11621 for (column_name, raw_values) in &target.selectors {
11622 let Some((column_index, column)) = table
11623 .columns
11624 .iter()
11625 .enumerate()
11626 .find(|(_, column)| column.name == *column_name)
11627 else {
11628 return Err(invalid(format!(
11629 "local purge target {:?} names unknown column {:?}",
11630 target.table, column_name
11631 )));
11632 };
11633 let encrypted = table
11634 .encrypted_columns
11635 .iter()
11636 .any(|candidate| candidate.index == column_index);
11637 if column.ty != ColumnType::String || encrypted {
11638 return Err(invalid(format!(
11639 "local purge selector {:?}.{:?} must be a plaintext string column",
11640 target.table, column_name
11641 )));
11642 }
11643 if raw_values.is_empty() || raw_values.len() > MAX_LOCAL_PURGE_VALUES {
11644 return Err(invalid(format!(
11645 "local purge selector {:?}.{:?} needs between 1 and {MAX_LOCAL_PURGE_VALUES} values",
11646 target.table, column_name
11647 )));
11648 }
11649 let mut values = raw_values.clone();
11650 values.sort();
11651 values.dedup();
11652 if values.iter().any(|value| {
11653 value.is_empty()
11654 || value.len() > MAX_LOCAL_PURGE_VALUE_LENGTH
11655 || !is_local_operation_code_like(value)
11656 }) {
11657 return Err(invalid(format!(
11658 "local purge selector values must be 1–{MAX_LOCAL_PURGE_VALUE_LENGTH} character code-like identifiers"
11659 )));
11660 }
11661 selectors.push((column_name.clone(), values.clone()));
11662 canonical_selectors.insert(column_name.clone(), values);
11663 }
11664 let canonical = LocalDataPurgeTarget {
11665 table: target.table.clone(),
11666 selectors: canonical_selectors,
11667 };
11668 let key = serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
11669 deduplicated.insert(
11670 key,
11671 (
11672 CompiledLocalDataPurgeTarget {
11673 table: target.table.clone(),
11674 selectors,
11675 },
11676 canonical,
11677 ),
11678 );
11679 }
11680 let targets = deduplicated
11681 .values()
11682 .map(|(compiled, _)| compiled.clone())
11683 .collect::<Vec<_>>();
11684 let canonical = deduplicated
11685 .values()
11686 .map(|(_, target)| target.clone())
11687 .collect::<Vec<_>>();
11688 let canonical_plan =
11689 serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
11690 Ok((targets, canonical_plan))
11691 }
11692
11693 fn local_purge_base_row_ids(
11694 &self,
11695 targets: &[CompiledLocalDataPurgeTarget],
11696 ) -> Result<BTreeMap<String, BTreeSet<String>>, String> {
11697 let mut by_table: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
11698 for target in targets {
11699 let table = self
11700 .schema
11701 .table(&target.table)
11702 .ok_or_else(|| format!("sync.invalid_request: unknown table {:?}", target.table))?;
11703 let mut clauses = Vec::with_capacity(target.selectors.len());
11704 let mut params = Vec::new();
11705 for (column, values) in &target.selectors {
11706 clauses.push(format!(
11707 "{} IN ({})",
11708 quote_ident(column),
11709 values.iter().map(|_| "?").collect::<Vec<_>>().join(", ")
11710 ));
11711 params.extend(values.iter().cloned().map(SqlValue::Text));
11712 }
11713 let sql = format!(
11714 "SELECT CAST({} AS TEXT) FROM {} WHERE {}",
11715 quote_ident(&table.primary_key),
11716 base_table(&target.table),
11717 clauses.join(" AND ")
11718 );
11719 let mut statement = self
11720 .conn
11721 .prepare(&sql)
11722 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11723 let rows = statement
11724 .query_map(rusqlite::params_from_iter(params), |row| {
11725 let value = sql_ref_to_json(&table.columns[table.pk_index], row.get_ref(0)?);
11726 render_row_id_json(Some(&value))
11727 .map_err(|message| rusqlite::Error::ToSqlConversionFailure(message.into()))
11728 })
11729 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11730 let ids = by_table.entry(target.table.clone()).or_default();
11731 for row in rows {
11732 ids.insert(
11733 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
11734 );
11735 }
11736 }
11737 Ok(by_table)
11738 }
11739
11740 fn local_purge_values_match(
11741 target: &CompiledLocalDataPurgeTarget,
11742 values: &Map<String, Value>,
11743 ) -> bool {
11744 target.selectors.iter().all(|(column, allowed)| {
11745 values
11746 .get(column)
11747 .and_then(Value::as_str)
11748 .is_some_and(|value| allowed.iter().any(|candidate| candidate == value))
11749 })
11750 }
11751
11752 pub fn purge_local_data(
11756 &mut self,
11757 input: &LocalDataPurgeInput,
11758 ) -> Result<LocalDataPurgeResult, String> {
11759 let (targets, canonical_plan) = self.compile_local_data_purge(input)?;
11760 let meta_key = format!("localPurge:{}", input.purge_id);
11761 let applied_plan = self
11762 .conn
11763 .query_row(
11764 "SELECT value FROM _syncular_meta WHERE key = ?1",
11765 rusqlite::params![meta_key],
11766 |row| row.get::<_, String>(0),
11767 )
11768 .optional()
11769 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11770 if let Some(applied_plan) = applied_plan {
11771 if applied_plan != canonical_plan {
11772 return Err(format!(
11773 "sync.invalid_request: local purge id {:?} was already used with a different plan",
11774 input.purge_id
11775 ));
11776 }
11777 self.erase_purged_pages()?;
11779 return Ok(LocalDataPurgeResult {
11780 already_applied: true,
11781 purged_rows: 0,
11782 dropped_commits: 0,
11783 });
11784 }
11785
11786 let _ = self.drop_previous_version();
11790
11791 let rollback = self.capture();
11792 self.begin_observation("syncular_local_purge")?;
11793 let applied = (|| -> Result<(ChangeAccumulator, LocalDataPurgeResult), String> {
11794 let row_ids = self.local_purge_base_row_ids(&targets)?;
11795 let retained_dropped = self.drop_failed_commits(|table, values| {
11796 targets.iter().any(|target| {
11797 target.table == table && Self::local_purge_values_match(target, values)
11798 })
11799 })?;
11800 let doomed = self
11801 .outbox
11802 .iter()
11803 .filter(|commit| {
11804 commit.ops.iter().any(|operation| {
11805 let matching_targets = targets
11806 .iter()
11807 .filter(|target| target.table == operation.table)
11808 .collect::<Vec<_>>();
11809 if matching_targets.is_empty() {
11810 return false;
11811 }
11812 if row_ids
11813 .get(&operation.table)
11814 .is_some_and(|ids| ids.contains(&operation.row_id))
11815 {
11816 return true;
11817 }
11818 operation.values.as_ref().is_some_and(|values| {
11819 matching_targets
11820 .iter()
11821 .any(|target| Self::local_purge_values_match(target, values))
11822 })
11823 })
11824 })
11825 .cloned()
11826 .collect::<Vec<_>>();
11827 let doomed_ids = doomed
11828 .iter()
11829 .map(|commit| commit.client_commit_id.clone())
11830 .collect::<BTreeSet<_>>();
11831 let mut batch = ChangeAccumulator::default();
11832 for commit in &retained_dropped {
11833 batch.conflicts = true;
11834 batch.rejections = true;
11835 batch.outcomes = true;
11836 for operation in &commit.ops {
11837 batch.table(&operation.table);
11838 }
11839 }
11840 let mut rejections = Vec::new();
11841 for commit in &doomed {
11844 for operation in &commit.ops {
11845 batch.table(&operation.table);
11846 self.overlay_dirty.table(&operation.table);
11847 }
11848 let results = (0..commit.ops.len())
11849 .map(|op_index| {
11850 let rejection = RejectionRecord {
11851 client_commit_id: commit.client_commit_id.clone(),
11852 op_index: op_index as i32,
11853 code: "client.local_data_purged".to_owned(),
11854 message: "the commit was dropped by an application-authorized local data purge".to_owned(),
11855 retryable: false,
11856 details: None,
11857 operation: None,
11858 };
11859 rejections.push(rejection.clone());
11860 CommitOperationOutcome::Error { rejection }
11861 })
11862 .collect::<Vec<_>>();
11863 self.persist_commit_outcome(
11864 &commit.client_commit_id,
11865 CommitOutcomeStatus::Rejected,
11866 &results,
11867 None,
11868 )?;
11869 self.delete_outbox_persisted(&commit.client_commit_id)?;
11870 }
11871 if !doomed.is_empty() {
11872 self.outbox
11873 .retain(|commit| !doomed_ids.contains(&commit.client_commit_id));
11874 self.rejections.extend(rejections);
11875 self.prune_commit_outcomes()?;
11876 batch.status = true;
11877 batch.rejections = true;
11878 batch.outcomes = true;
11879 }
11880
11881 let mut purged_rows = 0usize;
11882 for (table, ids) in &row_ids {
11883 if ids.is_empty() {
11884 continue;
11885 }
11886 batch.table(table);
11887 self.overlay_dirty.table(table);
11888 for row_id in ids {
11889 self.delete_base_row(table, row_id, i64::MAX)?;
11890 purged_rows += 1;
11891 }
11892 }
11893 let touches = |table: &str, row_id: &str, values: Option<&Map<String, Value>>| {
11897 targets.iter().any(|target| {
11898 target.table == table
11899 && (row_ids.get(table).is_some_and(|ids| ids.contains(row_id))
11900 || values.is_some_and(|values| {
11901 Self::local_purge_values_match(target, values)
11902 }))
11903 })
11904 };
11905 let entries = self
11906 .conn
11907 .prepare("SELECT client_commit_id, results_json, operations_json FROM _syncular_commit_outcomes")
11908 .and_then(|mut statement| {
11909 statement
11910 .query_map([], |row| {
11911 Ok((
11912 row.get::<_, String>(0)?,
11913 row.get::<_, String>(1)?,
11914 row.get::<_, Option<String>>(2)?,
11915 ))
11916 })?
11917 .collect::<Result<Vec<_>, _>>()
11918 })
11919 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11920 for (client_commit_id, results_json, operations_json) in entries {
11921 let corrupt = |_| "sync.local_corrupt: persisted commit outcome is invalid".to_owned();
11922 let mut results: Vec<CommitOperationOutcome> =
11923 serde_json::from_str(&results_json).map_err(corrupt)?;
11924 let operations: Vec<CommitOperation> = operations_json
11925 .map(|json| serde_json::from_str(&json))
11926 .transpose()
11927 .map_err(corrupt)?
11928 .unwrap_or_default();
11929 let named = operations
11930 .iter()
11931 .chain(results.iter().filter_map(|result| match result {
11932 CommitOperationOutcome::Conflict { conflict } => conflict.operation.as_ref(),
11933 CommitOperationOutcome::Error { rejection } => rejection.operation.as_ref(),
11934 CommitOperationOutcome::Applied { .. } => None,
11935 }))
11936 .any(|operation| touches(&operation.table, &operation.row_id, operation.values.as_ref()))
11937 || results.iter().any(|result| {
11938 matches!(result, CommitOperationOutcome::Conflict { conflict }
11939 if touches(&conflict.table, &conflict.row_id, Some(&conflict.server_row)))
11940 });
11941 if !named {
11942 continue;
11943 }
11944 for result in &mut results {
11945 match result {
11946 CommitOperationOutcome::Conflict { conflict } => {
11947 conflict.server_row = Map::new();
11948 conflict.conflict_columns.clear();
11949 conflict.operation = None;
11950 }
11951 CommitOperationOutcome::Error { rejection } => {
11952 rejection.details = None;
11953 rejection.operation = None;
11954 }
11955 CommitOperationOutcome::Applied { .. } => {}
11956 }
11957 }
11958 let results_json = serde_json::to_string(&results).map_err(|error| error.to_string())?;
11959 self.conn
11960 .execute(
11961 "UPDATE _syncular_commit_outcomes SET results_json = ?1, operations_json = NULL WHERE client_commit_id = ?2",
11962 rusqlite::params![results_json, client_commit_id],
11963 )
11964 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11965 batch.outcomes = true;
11966 }
11967 self.rebuild_overlay_if_dirty()?;
11968 self.delete_unreferenced_cached_blobs()?;
11969 self.conn
11970 .execute(
11971 "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
11972 rusqlite::params![meta_key, canonical_plan],
11973 )
11974 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11975 Ok((
11976 batch,
11977 LocalDataPurgeResult {
11978 already_applied: false,
11979 purged_rows,
11980 dropped_commits: doomed.len(),
11981 },
11982 ))
11983 })()
11984 .and_then(|(batch, result)| {
11985 self.finish_observation("syncular_local_purge", batch)
11986 .map(|()| result)
11987 });
11988 let result = match applied {
11989 Ok(result) => result,
11990 Err(error) => {
11991 self.rollback_observation("syncular_local_purge");
11992 self.restore(rollback);
11993 return Err(error);
11994 }
11995 };
11996 self.cancel_sync_round();
11997 self.erase_purged_pages()?;
11998 Ok(result)
11999 }
12000
12001 fn erase_purged_pages(&self) -> Result<(), String> {
12006 let erased = self
12007 .conn
12008 .execute_batch("PRAGMA secure_delete = ON; VACUUM;")
12009 .and_then(|()| {
12010 self.conn
12011 .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
12012 });
12013 let reset = self.conn.execute_batch("PRAGMA secure_delete = OFF");
12014 erased
12015 .and(reset)
12016 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
12017 }
12018
12019 pub fn rebootstrap_local_data(
12025 &mut self,
12026 input: &LocalDataRebootstrapInput,
12027 ) -> Result<LocalDataRebootstrapResult, String> {
12028 if input.rebootstrap_id.is_empty()
12029 || input.rebootstrap_id.len() > 128
12030 || !is_local_operation_code_like(&input.rebootstrap_id)
12031 {
12032 return Err(
12033 "sync.invalid_request: local rebootstrap rebootstrapId must be a 1–128 character code-like identifier"
12034 .to_owned(),
12035 );
12036 }
12037 let meta_key = format!("localRebootstrap:{}", input.rebootstrap_id);
12038 if let Some(persisted) = meta_get(&self.conn, &meta_key).map_err(|_| {
12039 "sync.local_corrupt: persisted local rebootstrap receipt is unreadable".to_owned()
12040 })? {
12041 let (retained_commits, reset_subscriptions) =
12042 decode_local_rebootstrap_receipt(&persisted)?;
12043 return Ok(LocalDataRebootstrapResult {
12044 already_applied: true,
12045 retained_commits,
12046 reset_subscriptions,
12047 });
12048 }
12049 if self.stopped || self.schema_floor.is_some() {
12050 return Err(
12051 "sync.invalid_request: local rebootstrap cannot bypass an active schema-floor stop; update the application first"
12052 .to_owned(),
12053 );
12054 }
12055
12056 let retained_commits = self.outbox.len();
12057 let reset_subscriptions = self.stored(load_units(&self.conn))?.len();
12058 let receipt = encode_local_rebootstrap_receipt(retained_commits, reset_subscriptions)?;
12059 let rollback = self.capture();
12060 self.begin_observation("syncular_local_rebootstrap")?;
12061 let mut batch = ChangeAccumulator::default();
12062 let applied = (|| -> Result<(), String> {
12063 self.run_schema_reset_observed(&mut batch, false)?;
12064 self.conn
12065 .execute(
12066 "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
12067 rusqlite::params![meta_key, receipt],
12068 )
12069 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12070 self.sync_needed = true;
12071 self.sync_intent_queue.push_back(SyncIntent::Interactive);
12072 batch.status = true;
12073 Ok(())
12074 })()
12075 .and_then(|()| self.finish_observation("syncular_local_rebootstrap", batch));
12076 if let Err(error) = applied {
12077 self.rollback_observation("syncular_local_rebootstrap");
12078 self.restore(rollback);
12079 return Err(error);
12080 }
12081 self.cancel_sync_round();
12082
12083 Ok(LocalDataRebootstrapResult {
12084 already_applied: false,
12085 retained_commits,
12086 reset_subscriptions,
12087 })
12088 }
12089
12090 fn purge_scope_rows(
12096 &mut self,
12097 table_name: &str,
12098 effective: &[(String, Vec<String>)],
12099 owners: &[Vec<(String, Vec<String>)>],
12100 ) -> Result<bool, String> {
12101 let Some(table) = self.schema.table(table_name) else {
12102 return Ok(false);
12103 };
12104 let Ok(predicate) = local_scope_predicate(table, effective, owners) else {
12105 return Ok(false);
12106 };
12107 let Some((predicate, params)) = predicate else {
12108 return Ok(true);
12109 };
12110 self.overlay_dirty.table(table_name);
12111 for source in [base_table(table_name), visible_table(table_name)] {
12112 self.conn
12113 .execute(
12114 &format!("DELETE FROM {source} WHERE {predicate}"),
12115 rusqlite::params_from_iter(¶ms),
12116 )
12117 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12118 }
12119 Ok(true)
12120 }
12121
12122 fn drop_doomed_outbox(
12126 &mut self,
12127 table: &TableSchema,
12128 effective: &[(String, Vec<String>)],
12129 owners: &[Vec<(String, Vec<String>)>],
12130 ) -> Result<bool, String> {
12131 let doomed: Vec<_> =
12132 self.outbox
12133 .iter()
12134 .filter(|commit| {
12135 commit.ops.iter().any(|op| {
12136 op.upsert
12137 && op.table == table.name
12138 && op.values.as_ref().is_some_and(|values| {
12139 owns_local_row(table, effective, owners, values)
12140 })
12141 })
12142 })
12143 .cloned()
12144 .collect();
12145 if doomed.is_empty() {
12146 return Ok(false);
12147 }
12148 let mut rejections = Vec::new();
12149 for commit in &doomed {
12150 let results = commit
12151 .ops
12152 .iter()
12153 .enumerate()
12154 .map(|(op_index, operation)| {
12155 self.overlay_dirty.table(&operation.table);
12156 let rejection = RejectionRecord {
12157 client_commit_id: commit.client_commit_id.clone(),
12158 op_index: op_index as i32,
12159 code: "sync.scope_revoked".to_owned(),
12160 message: "the commit was dropped because its effective scope was revoked"
12161 .to_owned(),
12162 retryable: false,
12163 details: None,
12164 operation: Some(CommitOperation::from(operation)),
12165 };
12166 rejections.push(rejection.clone());
12167 CommitOperationOutcome::Error { rejection }
12168 })
12169 .collect::<Vec<_>>();
12170 self.persist_commit_outcome(
12171 &commit.client_commit_id,
12172 CommitOutcomeStatus::Rejected,
12173 &results,
12174 Some(&commit.ops),
12175 )?;
12176 self.delete_outbox_persisted(&commit.client_commit_id)?;
12177 }
12178 self.prune_commit_outcomes()?;
12179 let doomed_ids = doomed
12180 .iter()
12181 .map(|commit| commit.client_commit_id.as_str())
12182 .collect::<BTreeSet<_>>();
12183 self.outbox
12184 .retain(|commit| !doomed_ids.contains(commit.client_commit_id.as_str()));
12185 self.rejections.extend(rejections);
12186 Ok(true)
12187 }
12188
12189 pub fn upload_blob(
12196 &mut self,
12197 bytes: &[u8],
12198 media_type: Option<String>,
12199 name: Option<String>,
12200 ) -> Result<Value, String> {
12201 let blob_id = blob_id_for(bytes);
12202 let now = self.clock_now_ms();
12203 let tx = self
12204 .conn
12205 .transaction()
12206 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12207 tx.execute(
12208 "INSERT INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,?,?)
12209 ON CONFLICT(blob_id) DO NOTHING",
12210 rusqlite::params![blob_id, bytes, bytes.len() as i64, media_type, now],
12211 )
12212 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12213 tx.execute(
12214 "INSERT OR IGNORE INTO _syncular_blob_uploads(blob_id, media_type, created_at_ms) VALUES (?,?,?)",
12215 rusqlite::params![blob_id, media_type, now],
12216 )
12217 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12218 tx.commit()
12219 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12220 self.enforce_blob_cache_cap();
12221 let mut obj = Map::new();
12222 obj.insert("blobId".to_owned(), Value::from(blob_id));
12223 obj.insert("byteLength".to_owned(), Value::from(bytes.len() as i64));
12224 if let Some(mt) = media_type {
12225 obj.insert("mediaType".to_owned(), Value::from(mt));
12226 }
12227 if let Some(n) = name {
12228 obj.insert("name".to_owned(), Value::from(n));
12229 }
12230 Ok(Value::Object(obj))
12231 }
12232
12233 pub fn fetch_blob_bytes(
12237 &mut self,
12238 transport: &mut dyn Transport,
12239 blob_id_or_ref: &str,
12240 ) -> Result<FetchedBlob, (String, String)> {
12241 let simple = |m: String| ("client.failed".to_owned(), m);
12242 let (blob_id, byte_length) = if blob_id_or_ref.starts_with("sha256:") {
12245 (blob_id_or_ref.to_owned(), None)
12246 } else {
12247 let value: Value = serde_json::from_str(blob_id_or_ref)
12248 .map_err(|_| simple("blob ref is not JSON".to_owned()))?;
12249 (
12250 value
12251 .get("blobId")
12252 .and_then(Value::as_str)
12253 .ok_or_else(|| simple("blob ref has no blobId".to_owned()))?
12254 .to_owned(),
12255 value.get("byteLength").and_then(Value::as_u64),
12256 )
12257 };
12258 if let Some(cached) = self.get_cached_blob_bytes(&blob_id).map_err(simple)? {
12259 return Ok(cached);
12260 }
12261 if !self.transport_enabled {
12262 return Err(("sync.offline".into(), "transport gate is closed".into()));
12263 }
12264 #[cfg(feature = "bench-internals")]
12270 let download_phase = self.benchmark_phases.start(Phase::BlobDownload);
12271 let bytes = match transport
12272 .blob_download(&blob_id, byte_length)
12273 .map_err(|e| (e.code, e.message))?
12274 {
12275 BlobDownload::Bytes(bytes) => bytes,
12276 BlobDownload::Url {
12277 url,
12278 url_expires_at_ms,
12279 } => {
12280 if url_expires_at_ms.is_some_and(|exp| exp <= self.clock_now_ms()) {
12282 return Err((
12283 "sync.segment_expired".to_owned(),
12284 format!(
12285 "blob url for {blob_id} expired before fetch — re-request mints a fresh url (§5.9.5)"
12286 ),
12287 ));
12288 }
12289 transport
12290 .fetch_blob_url(&url, byte_length)
12291 .map_err(|e| (e.code, e.message))?
12292 }
12293 };
12294 #[cfg(feature = "bench-internals")]
12295 drop(download_phase);
12296 #[cfg(feature = "bench-internals")]
12297 let validate_phase = self.benchmark_phases.start(Phase::BlobValidate);
12298 if byte_length.is_some_and(|cap| bytes.len() as u64 > cap) {
12301 return Err((
12302 "sync.invalid_request".to_owned(),
12303 "blob exceeds its byteLength".to_owned(),
12304 ));
12305 }
12306 if blob_id_for(&bytes) != blob_id {
12307 return Err(simple(format!(
12308 "blob content address mismatch for {blob_id}"
12309 )));
12310 }
12311 #[cfg(feature = "bench-internals")]
12312 drop(validate_phase);
12313 #[cfg(feature = "bench-internals")]
12314 let insert_phase = self.benchmark_phases.start(Phase::BlobCacheInsert);
12315 let now = self.clock_now_ms();
12316 self.conn
12317 .execute(
12318 "INSERT OR IGNORE INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,NULL,?)",
12319 rusqlite::params![blob_id, bytes, bytes.len() as i64, now],
12320 )
12321 .map_err(|e| simple(e.to_string()))?;
12322 self.conn
12323 .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
12324 .map_err(|e| simple(e.to_string()))?;
12325 self.enforce_blob_cache_cap();
12326 #[cfg(feature = "bench-internals")]
12327 drop(insert_phase);
12328 self.get_cached_blob_bytes(&blob_id)
12329 .map_err(simple)?
12330 .ok_or_else(|| simple("blob cache write failed".to_owned()))
12331 }
12332
12333 fn get_cached_blob_bytes(&self, blob_id: &str) -> Result<Option<FetchedBlob>, String> {
12334 #[cfg(feature = "bench-internals")]
12335 let _phase = self.benchmark_phases.start(Phase::BlobCacheRead);
12336 let mut stmt = self
12337 .conn
12338 .prepare("SELECT bytes, byte_length, media_type FROM _syncular_blobs WHERE blob_id = ?")
12339 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12340 let mut rows = stmt
12341 .query(rusqlite::params![blob_id])
12342 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12343 if let Some(row) = rows
12344 .next()
12345 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
12346 {
12347 let bytes: Vec<u8> = row
12348 .get(0)
12349 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12350 let byte_length: i64 = row
12351 .get(1)
12352 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12353 let media_type: Option<String> = row
12354 .get(2)
12355 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12356 return Ok(Some(FetchedBlob {
12357 blob_id: blob_id.to_owned(),
12358 byte_length,
12359 bytes,
12360 media_type,
12361 }));
12362 }
12363 Ok(None)
12364 }
12365
12366 fn pending_blob_uploads(&self) -> Result<Vec<crate::round::PendingUpload>, TransportError> {
12368 let pending: Vec<(String, Option<String>)> = {
12369 let mut stmt = self
12370 .conn
12371 .prepare(
12372 "SELECT blob_id, media_type FROM (
12373 SELECT blob_id, media_type, created_at_ms FROM _syncular_blob_uploads
12374 UNION ALL
12375 SELECT DISTINCT r.blob_id, b.media_type, 9223372036854775807 AS created_at_ms
12376 FROM _syncular_blob_commit_refs r LEFT JOIN _syncular_blobs b ON b.blob_id = r.blob_id
12377 WHERE NOT EXISTS (SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id = r.blob_id)
12378 ) ORDER BY created_at_ms, blob_id",
12379 )
12380 .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
12381 let rows = stmt
12382 .query_map([], |row| {
12383 Ok((row.get::<_, String>(0)?, row.get::<_, Option<String>>(1)?))
12384 })
12385 .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
12386 rows.collect::<Result<_, _>>()
12387 .map_err(|error| match error {
12388 rusqlite::Error::InvalidColumnType(..)
12389 | rusqlite::Error::FromSqlConversionFailure(..) => TransportError::new(
12390 "sync.local_corrupt",
12391 "Pending blob upload metadata is invalid",
12392 ),
12393 _ => TransportError::new("client.failed", error.to_string()),
12394 })?
12395 };
12396 let mut uploads = Vec::new();
12397 for (blob_id, media_type) in pending {
12398 let bytes = (|| {
12399 let stored: Option<(SqlValue, SqlValue)> = self
12400 .conn
12401 .query_row(
12402 "SELECT bytes, byte_length FROM _syncular_blobs WHERE blob_id = ?",
12403 rusqlite::params![blob_id],
12404 |row| Ok((row.get(0)?, row.get(1)?)),
12405 )
12406 .optional()
12407 .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
12408 let Some((SqlValue::Blob(bytes), SqlValue::Integer(byte_length))) = stored else {
12409 return Err(TransportError::new(
12410 "sync.local_corrupt",
12411 "Pending blob upload body is missing or corrupt",
12412 ));
12413 };
12414 if byte_length != bytes.len() as i64 || blob_id_for(&bytes) != blob_id {
12415 return Err(TransportError::new(
12416 "sync.local_corrupt",
12417 "Pending blob upload body is missing or corrupt",
12418 ));
12419 }
12420 Ok(bytes)
12421 })();
12422 let failed = bytes.is_err();
12423 uploads.push(crate::round::PendingUpload {
12424 id: blob_id,
12425 bytes,
12426 media_type,
12427 });
12428 if failed {
12429 break;
12430 }
12431 }
12432 Ok(uploads)
12433 }
12434
12435 fn visible_blob_ids_sql(&self) -> String {
12436 let mut selects = Vec::new();
12437 for table in &self.schema.tables {
12438 for column in table
12439 .columns
12440 .iter()
12441 .filter(|column| column.ty == ColumnType::BlobRef)
12442 {
12443 let identifier = quote_ident(&column.name);
12444 selects.push(format!(
12445 "SELECT json_extract({identifier}, '$.blobId') AS blob_id FROM {} \
12446 WHERE typeof({identifier}) = 'text' AND json_valid({identifier}) \
12447 AND json_type({identifier}, '$.blobId') = 'text'",
12448 quote_ident(&table.name),
12449 ));
12450 }
12451 }
12452 if selects.is_empty() {
12453 "SELECT NULL AS blob_id WHERE 0".to_owned()
12454 } else {
12455 selects.join(" UNION ")
12456 }
12457 }
12458
12459 fn enforce_blob_cache_cap(&self) {
12462 let Some(max_bytes) = self.limits.blob_cache_max_bytes else {
12463 return;
12464 };
12465 let mut total: i64 = self
12466 .conn
12467 .query_row(
12468 "SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs",
12469 [],
12470 |row| row.get(0),
12471 )
12472 .unwrap_or(0);
12473 if total <= max_bytes {
12474 return;
12475 }
12476 let query = format!(
12477 "SELECT blob_id, byte_length FROM _syncular_blobs
12478 WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
12479 AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
12480 AND blob_id NOT IN ({})
12481 ORDER BY created_at_ms ASC, blob_id ASC",
12482 self.visible_blob_ids_sql(),
12483 );
12484 let candidates: Vec<(String, i64)> = {
12485 let Ok(mut stmt) = self.conn.prepare(&query) else {
12486 return;
12487 };
12488 let Ok(rows) = stmt.query_map([], |row| {
12489 Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
12490 }) else {
12491 return;
12492 };
12493 rows.filter_map(Result::ok).collect()
12494 };
12495 for (blob_id, byte_length) in candidates {
12496 if total <= max_bytes {
12497 break;
12498 }
12499 let _ = self.conn.execute(
12500 "DELETE FROM _syncular_blobs WHERE blob_id = ?",
12501 rusqlite::params![blob_id],
12502 );
12503 total -= byte_length;
12504 }
12505 }
12506
12507 fn delete_unreferenced_cached_blobs(&mut self) -> Result<(), String> {
12508 #[cfg(feature = "bench-internals")]
12509 let _phase = self.benchmark_phases.start(Phase::BlobRetention);
12510 if !self.schema_has_blobs() {
12511 return Ok(());
12512 }
12513 self.rebuild_overlay_if_dirty()?;
12514 self.conn
12515 .execute(
12516 &format!(
12517 "DELETE FROM _syncular_blobs
12518 WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
12519 AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
12520 AND blob_id NOT IN ({})",
12521 self.visible_blob_ids_sql(),
12522 ),
12523 [],
12524 )
12525 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12526 Ok(())
12527 }
12528
12529 fn insert_row_sql(&self, full_table: &str, table: &crate::schema::TableSchema) -> String {
12534 if let Some(sql) = self.insert_sql.borrow().get(full_table) {
12535 return sql.clone();
12536 }
12537 let mut columns: Vec<String> = table.columns.iter().map(|c| quote_ident(&c.name)).collect();
12538 columns.push(quote_ident("_syncular_version"));
12539 columns.extend(table.sealed_columns().iter().map(|name| quote_ident(name)));
12540 let placeholders: Vec<&str> = columns.iter().map(|_| "?").collect();
12541 let primary_key = quote_ident(&table.primary_key);
12542 let updates = columns
12543 .iter()
12544 .filter(|column| **column != primary_key)
12545 .map(|column| format!("{column}=excluded.{column}"))
12546 .collect::<Vec<_>>()
12547 .join(", ");
12548 let guard = if full_table == base_table(&table.name) {
12551 format!(" WHERE excluded._syncular_version > {full_table}._syncular_version")
12552 } else {
12553 String::new()
12554 };
12555 let sql = format!(
12556 "INSERT INTO {full_table} ({}) VALUES ({}) ON CONFLICT ({primary_key}) DO UPDATE SET {updates}{guard}",
12557 columns.join(", "),
12558 placeholders.join(", ")
12559 );
12560 self.insert_sql
12561 .borrow_mut()
12562 .insert(full_table.to_owned(), sql.clone());
12563 sql
12564 }
12565
12566 fn write_base_row(
12569 &self,
12570 table_name: &str,
12571 row: &Row,
12572 version: i64,
12573 sealed: Option<&SealedRow>,
12574 ) -> Result<bool, String> {
12575 let landed = self.write_row(&base_table(table_name), table_name, row, version, sealed)?;
12576 if landed {
12577 self.overlay_dirty.table(table_name);
12578 }
12579 Ok(landed)
12580 }
12581
12582 fn write_row(
12583 &self,
12584 full_table: &str,
12585 table_name: &str,
12586 row: &Row,
12587 version: i64,
12588 sealed: Option<&SealedRow>,
12589 ) -> Result<bool, String> {
12590 #[cfg(feature = "bench-internals")]
12591 let _phase = self.benchmark_phases.start(Phase::RowWrite);
12592 let table = self
12593 .schema
12594 .table(table_name)
12595 .ok_or_else(|| format!("unknown table {table_name:?}"))?;
12596 let sql = self.insert_row_sql(full_table, table);
12597 let mut stmt = self
12598 .conn
12599 .prepare_cached(&sql)
12600 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12601 let params = row
12602 .iter()
12603 .map(RowParam::Cell)
12604 .chain(std::iter::once(RowParam::Version(version)))
12605 .chain(
12606 [
12607 sealed.map(|sealed| sealed.key_id.as_str()),
12608 sealed.map(|sealed| sealed.envelopes.as_str()),
12609 ]
12610 .into_iter()
12611 .take(table.sealed_columns().len())
12612 .map(RowParam::Text),
12613 );
12614 stmt.execute(rusqlite::params_from_iter(params))
12615 .map(|changed| changed > 0)
12616 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
12617 }
12618
12619 fn delete_base_row(
12622 &self,
12623 table_name: &str,
12624 row_id: &str,
12625 version: i64,
12626 ) -> Result<bool, String> {
12627 let table = self
12628 .schema
12629 .table(table_name)
12630 .ok_or_else(|| format!("unknown table {table_name:?}"))?;
12631 let sql = format!(
12632 "DELETE FROM {} WHERE {} AND _syncular_version < ?2",
12633 base_table(table_name),
12634 row_id_predicate(table)
12635 );
12636 let mut stmt = self
12637 .conn
12638 .prepare_cached(&sql)
12639 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12640 let landed = stmt
12641 .execute(rusqlite::params![row_id, version])
12642 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
12643 > 0;
12644 if landed {
12645 self.overlay_dirty.table(table_name);
12646 }
12647 Ok(landed)
12648 }
12649
12650 fn has_acknowledged_rows(&self) -> Result<bool, String> {
12651 self.conn
12652 .query_row(
12653 "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows)",
12654 [],
12655 |row| row.get(0),
12656 )
12657 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
12658 }
12659
12660 fn acknowledged_operations(
12661 &self,
12662 rows: Option<&HashSet<(&str, &str)>>,
12663 tables: Option<&BTreeSet<&str>>,
12664 ) -> Result<Vec<OutboxOp>, String> {
12665 let keys = rows.map(|rows| serde_json::to_string(&rows).expect("row keys"));
12666 let mut statement = self
12667 .conn
12668 .prepare_cached(if keys.is_some() {
12669 ACKED_ROWS_BY_ROW
12670 } else {
12671 "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"
12672 })
12673 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12674 let rows = statement
12675 .query_map(
12676 rusqlite::params![
12677 keys,
12678 tables.map(|tables| serde_json::to_string(tables).expect("table keys"))
12679 ],
12680 |row| {
12681 #[cfg(test)]
12682 self.acknowledged_replay_count
12683 .set(self.acknowledged_replay_count.get() + 1);
12684 Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
12685 },
12686 )
12687 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12688 rows.map(|row| {
12689 let (op, intent) =
12690 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12691 let op: CommitOperation =
12692 serde_json::from_str(&op).map_err(|_| "sync.local_corrupt".to_owned())?;
12693 let table = self
12694 .schema
12695 .table(&op.table)
12696 .ok_or_else(|| "sync.unknown_table".to_owned())?;
12697 let values = if op.op == "upsert" && self.visible_row(table, &op.row_id)?.is_none() {
12698 Some(serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?)
12699 } else {
12700 op.values.clone()
12701 };
12702 Ok(OutboxOp {
12703 values,
12704 ..op.into()
12705 })
12706 })
12707 .collect()
12708 }
12709
12710 fn drop_acknowledged_rows(
12711 &self,
12712 matches: impl Fn(&str, &Map<String, Value>) -> bool,
12713 ) -> Result<Vec<OutboxCommit>, String> {
12714 let mut statement = self
12715 .conn
12716 .prepare("SELECT commit_id,tbl,intent_json,id FROM _syncular_acked_rows")
12717 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12718 let rows = statement
12719 .query_map([], |row| {
12720 Ok((
12721 row.get::<_, String>(0)?,
12722 row.get::<_, String>(1)?,
12723 row.get::<_, String>(2)?,
12724 row.get::<_, String>(3)?,
12725 ))
12726 })
12727 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12728 let mut doomed = HashSet::new();
12729 for row in rows {
12730 let (id, table, intent, row_id) =
12731 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12732 let values =
12733 serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
12734 let base_matches = self
12735 .schema
12736 .table(&table)
12737 .map(|schema| self.stored_row(schema, &row_id, true))
12738 .transpose()?
12739 .flatten()
12740 .is_some_and(|(base, _)| {
12741 let schema = self.schema.table(&table).expect("acknowledged table");
12742 let values = schema
12743 .columns
12744 .iter()
12745 .zip(base.iter())
12746 .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
12747 .collect();
12748 matches(&table, &values)
12749 });
12750 if matches(&table, &values) || base_matches {
12751 doomed.insert(id);
12752 }
12753 }
12754 let mut dropped = Vec::new();
12755 for id in doomed {
12756 let mut statement = self
12757 .conn
12758 .prepare("SELECT op_json FROM _syncular_acked_rows WHERE commit_id=?1 ORDER BY idx")
12759 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12760 let operations = statement
12761 .query_map([&id], |row| row.get::<_, String>(0))
12762 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12763 let mut ops = Vec::new();
12764 for operation in operations {
12765 let json = operation
12766 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12767 let op: CommitOperation =
12768 serde_json::from_str(&json).map_err(|_| "sync.local_corrupt".to_owned())?;
12769 self.overlay_dirty.table(&op.table);
12770 ops.push(OutboxOp {
12771 table: op.table,
12772 row_id: op.row_id,
12773 upsert: op.op == "upsert",
12774 base_version: op.base_version,
12775 values: op.values,
12776 insert: op.insert,
12777 });
12778 }
12779 dropped.push(OutboxCommit {
12780 client_commit_id: id.clone(),
12781 ops,
12782 });
12783 self.conn
12784 .execute("DELETE FROM _syncular_acked_rows WHERE commit_id=?1", [id])
12785 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12786 }
12787 Ok(dropped)
12788 }
12789
12790 fn rebuild_overlay_if_dirty(&mut self) -> Result<(), String> {
12793 if self.overlay_dirty.get() {
12794 self.rebuild_overlay()?;
12795 }
12796 Ok(())
12797 }
12798
12799 fn rebuild_overlay(&mut self) -> Result<(), String> {
12803 #[cfg(feature = "bench-internals")]
12804 let _phase = self.benchmark_phases.start(Phase::OverlayRebuild);
12805 #[cfg(test)]
12806 self.overlay_rebuild_count
12807 .set(self.overlay_rebuild_count.get() + 1);
12808 let dirty = self.overlay_dirty.snapshot();
12809 let tables: Vec<_> = self
12810 .schema
12811 .tables
12812 .iter()
12813 .filter(|table| {
12814 dirty
12815 .as_ref()
12816 .is_none_or(|names| names.is_empty() || names.contains(&table.name))
12817 })
12818 .cloned()
12819 .collect();
12820 let names: BTreeSet<_> = tables.iter().map(|table| table.name.as_str()).collect();
12821 self.begin_observation("syncular_overlay")?;
12822 let rebuilt = (|| {
12823 for table in &tables {
12824 for index in &table.fts_indexes {
12825 self.drop_fts_triggers(index)?;
12826 }
12827 let visible = visible_table(&table.name);
12828 let base = base_table(&table.name);
12829 self.conn
12830 .execute_batch(&format!(
12831 "DELETE FROM {visible}; INSERT INTO {visible} SELECT * FROM {base}"
12832 ))
12833 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12834 }
12835 self.replay_overlay(&names, None)?;
12836 for table in &tables {
12837 for index in &table.fts_indexes {
12838 self.rebuild_fts_projection(table, index)?;
12839 self.create_fts_triggers(table, index)?;
12840 }
12841 }
12842 self.conn
12843 .execute_batch("RELEASE syncular_overlay")
12844 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12845 Ok(())
12846 })();
12847 if rebuilt.is_err() {
12848 self.conn
12849 .execute_batch("ROLLBACK TO syncular_overlay; RELEASE syncular_overlay")
12850 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12851 } else {
12852 self.overlay_dirty.set(false);
12853 }
12854 rebuilt
12855 }
12856
12857 fn replay_overlay(
12861 &self,
12862 tables: &BTreeSet<&str>,
12863 rows: Option<&HashSet<(&str, &str)>>,
12864 ) -> Result<(), String> {
12865 let replays = |op: &&OutboxOp| {
12866 tables.contains(op.table.as_str())
12867 && rows.is_none_or(|rows| rows.contains(&(op.table.as_str(), op.row_id.as_str())))
12868 };
12869 self.apply_outbox_ops(&self.acknowledged_operations(rows, Some(tables))?)?;
12870 for (commit, initial) in self.failed_commits.iter() {
12871 for operation in commit.ops.iter().filter(replays) {
12872 let Some(table) = self.schema.table(&operation.table) else {
12873 continue;
12874 };
12875 if operation.upsert
12876 && self.visible_row(table, &operation.row_id)?.is_none()
12877 && operation.presented_values(table).is_some_and(|values| {
12878 table
12879 .columns
12880 .iter()
12881 .all(|column| values.contains_key(&column.name))
12882 })
12883 {
12884 let key = serde_json::to_string(&(&operation.table, &operation.row_id))
12885 .expect("row key serialization");
12886 if let Some(Value::Object(values)) = initial.get(&key) {
12887 self.apply_outbox_ops(&[OutboxOp {
12888 values: Some(values.clone()),
12889 ..operation.clone()
12890 }])?;
12891 }
12892 }
12893 }
12894 self.apply_outbox_ops(commit.ops.iter().filter(replays))?;
12895 }
12896 self.apply_outbox_ops(
12897 self.outbox
12898 .iter()
12899 .flat_map(|commit| &commit.ops)
12900 .filter(replays),
12901 )
12902 }
12903
12904 fn apply_outbox_ops<'a>(
12909 &self,
12910 ops: impl IntoIterator<Item = &'a OutboxOp>,
12911 ) -> Result<(), String> {
12912 #[cfg(feature = "bench-internals")]
12913 let mut phase = self.benchmark_phases.start(Phase::PendingReplay);
12914 for op in ops {
12915 #[cfg(feature = "bench-internals")]
12916 if let Some(phase) = &mut phase {
12917 phase.unit();
12918 }
12919 if op.upsert {
12920 if let Some((table, values)) = self
12921 .schema
12922 .table(&op.table)
12923 .filter(|table| table.indexes.iter().any(|index| index.unique))
12924 .and_then(|table| Some((table, op.presented_values(table)?)))
12925 {
12926 let mut intended: Map<String, Value> = self
12927 .visible_row(table, &op.row_id)?
12928 .map(|(row, _)| {
12929 table
12930 .columns
12931 .iter()
12932 .zip(&row)
12933 .map(|(column, value)| {
12934 (column.name.clone(), column_value_to_json(value))
12935 })
12936 .collect()
12937 })
12938 .unwrap_or_default();
12939 intended.extend(values.into_owned());
12940 if !self.unique_conflicts(table, &intended, false)?.is_empty() {
12941 continue;
12942 }
12943 }
12944 }
12945 self.apply_outbox_op(op)?;
12946 }
12947 Ok(())
12948 }
12949
12950 fn apply_outbox_op(&self, op: &OutboxOp) -> Result<(), String> {
12951 let Some(table) = self.schema.table(&op.table) else {
12952 return Ok(());
12953 };
12954 let visible = visible_table(&table.name);
12955 if !op.upsert {
12956 let sql = format!("DELETE FROM {visible} WHERE {}", row_id_predicate(table));
12957 self.conn
12958 .prepare_cached(&sql)
12959 .and_then(|mut statement| statement.execute(rusqlite::params![op.row_id]))
12960 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12961 return Ok(());
12962 }
12963 let Some(values) = op.presented_values(table) else {
12967 return Ok(());
12968 };
12969 let full = table
12975 .columns
12976 .iter()
12977 .all(|column| values.contains_key(&column.name));
12978 let local = self.visible_row(table, &op.row_id)?;
12979 if local.is_none() && !full {
12980 return Ok(());
12981 }
12982 let mut row: Row = Vec::with_capacity(table.columns.len());
12983 for (index, column) in table.columns.iter().enumerate() {
12984 let incoming = match values.get(&column.name) {
12985 Some(raw) => json_to_column_value(
12986 if raw.get("$bytes").is_some()
12987 && table
12988 .encrypted_columns
12989 .iter()
12990 .any(|encrypted| encrypted.index == index)
12991 {
12992 &table.wire_columns[index]
12993 } else {
12994 column
12995 },
12996 Some(raw),
12997 ),
12998 None => Ok(local
12999 .as_ref()
13000 .and_then(|(values, _)| values.get(index).cloned())
13001 .flatten()),
13002 };
13003 row.push(incoming.map_err(|_| {
13004 "sync.local_corrupt: persisted optimistic row value is invalid".to_owned()
13005 })?);
13006 }
13007 let version = local.as_ref().map_or(-1, |(_, version)| *version);
13008 self.write_row(&visible, &table.name, &row, version, None)
13009 .map(|_| ())
13010 .map_err(|error| {
13011 if error.starts_with("UNIQUE constraint failed:") {
13012 "sync.constraint_violation: local write violates a unique constraint".to_owned()
13013 } else {
13014 error
13015 }
13016 })
13017 }
13018
13019 fn visible_row_exists(&self, table: &TableSchema, row_id: &str) -> Result<bool, String> {
13023 self.conn
13024 .query_row(
13025 &format!(
13026 "SELECT EXISTS(SELECT 1 FROM {} WHERE {})",
13027 visible_table(&table.name),
13028 row_id_predicate(table)
13029 ),
13030 rusqlite::params![row_id],
13031 |row| row.get(0),
13032 )
13033 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
13034 }
13035
13036 fn refuse_sealed_row(&self, table: &TableSchema, row_id: &str) -> Result<(), ClientError> {
13039 if !table.has_encrypted_columns() {
13040 return Ok(());
13041 }
13042 let key_id: Option<String> = self
13043 .conn
13044 .query_row(
13045 &format!(
13046 "SELECT \"_sync_sealed_key\" FROM {} WHERE {}",
13047 visible_table(&table.name),
13048 row_id_predicate(table)
13049 ),
13050 rusqlite::params![row_id],
13051 |row| row.get(0),
13052 )
13053 .optional()
13054 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
13055 .flatten();
13056 match key_id {
13057 None => Ok(()),
13058 Some(key_id) => Err(ClientError {
13059 code: "client.encryption_key_missing".to_owned(),
13060 message: "the row is sealed under a key this device does not hold".to_owned(),
13061 details: Some(json!({ "table": table.name, "keyId": key_id })),
13062 retryable: false,
13063 }),
13064 }
13065 }
13066
13067 fn reveal_sealed_rows(&mut self) -> Result<(), TransportError> {
13071 let storage = |message: String| TransportError::new("storage.failed", message);
13072 let tables: Vec<TableSchema> = self
13073 .schema
13074 .tables
13075 .iter()
13076 .filter(|table| table.has_encrypted_columns())
13077 .cloned()
13078 .collect();
13079 for table in &tables {
13080 let base = base_table(&table.name);
13081 let pk = quote_ident(&table.primary_key);
13082 let sealed: Vec<(SqlValue, i64, String)> = self
13083 .conn
13084 .prepare_cached(&format!(
13085 "SELECT {pk}, \"_syncular_version\", \"_sync_sealed\" FROM {base} WHERE \"_sync_sealed_key\" IS NOT NULL"
13086 ))
13087 .and_then(|mut statement| {
13088 statement
13089 .query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?
13090 .collect()
13091 })
13092 .map_err(|error| storage(Self::sqlite_failure(&self.storage_failure, error)))?;
13093 let mut revealed = Vec::new();
13094 for (key, version, envelopes) in sealed {
13095 if let Some(row) =
13096 crate::values::reveal_sealed_row(table, &envelopes, &self.encryption)?
13097 {
13098 revealed.push((key, version, row));
13099 }
13100 }
13101 if revealed.is_empty() {
13102 continue;
13103 }
13104 self.begin_observation("syncular_reveal").map_err(storage)?;
13105 let outcome = (|| {
13106 let assignments = table
13107 .encrypted_columns
13108 .iter()
13109 .map(|enc| format!("{}=?", quote_ident(&table.columns[enc.index].name)))
13110 .collect::<Vec<_>>()
13111 .join(",");
13112 let mut statement = self
13113 .conn
13114 .prepare_cached(&format!(
13115 "UPDATE {base} SET {assignments},\"_sync_sealed_key\"=NULL,\"_sync_sealed\"=NULL WHERE {pk}=? AND \"_syncular_version\"=?"
13116 ))
13117 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13118 for (key, version, row) in &revealed {
13119 let mut params = table
13120 .encrypted_columns
13121 .iter()
13122 .map(|enc| owned_sql_value(RowParam::Cell(&row[enc.index])))
13123 .collect::<Result<Vec<_>, _>>()?;
13124 params.push(key.clone());
13125 params.push(SqlValue::Integer(*version));
13126 statement
13127 .execute(rusqlite::params_from_iter(params))
13128 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13129 }
13130 drop(statement);
13131 self.overlay_dirty.table(&table.name);
13132 self.rebuild_overlay()?;
13133 let mut batch = ChangeAccumulator::default();
13134 batch.table(&table.name);
13135 self.finish_observation("syncular_reveal", batch)
13136 })();
13137 if outcome.is_err() {
13138 self.rollback_observation("syncular_reveal");
13139 }
13140 outcome.map_err(storage)?;
13141 }
13142 Ok(())
13143 }
13144
13145 fn visible_row(&self, table: &TableSchema, row_id: &str) -> Result<Option<(Row, i64)>, String> {
13148 self.stored_row(table, row_id, false)
13149 }
13150
13151 fn stored_row(
13152 &self,
13153 table: &TableSchema,
13154 row_id: &str,
13155 base: bool,
13156 ) -> Result<Option<(Row, i64)>, String> {
13157 let sql = format!(
13158 "SELECT * FROM {} WHERE {}",
13159 if base {
13160 base_table(&table.name)
13161 } else {
13162 visible_table(&table.name)
13163 },
13164 row_id_predicate(table)
13165 );
13166 let mut stmt = self
13167 .conn
13168 .prepare_cached(&sql)
13169 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13170 let mut rows = stmt
13171 .query(rusqlite::params![row_id])
13172 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13173 let Some(row) = rows
13174 .next()
13175 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
13176 else {
13177 return Ok(None);
13178 };
13179 let mut values = Vec::with_capacity(table.columns.len());
13180 for (index, column) in table.columns.iter().enumerate() {
13181 let raw = row
13182 .get_ref(index)
13183 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13184 if let rusqlite::types::ValueRef::Blob(bytes) = raw {
13185 if table
13186 .encrypted_columns
13187 .iter()
13188 .any(|encrypted| encrypted.index == index)
13189 {
13190 values.push(Some(ColumnValue::Bytes(bytes.to_vec())));
13191 continue;
13192 }
13193 }
13194 let json = sql_ref_to_json(column, raw);
13195 values.push(json_to_column_value(column, Some(&json)).map_err(|_| {
13196 "sync.local_corrupt: persisted local row value is invalid".to_owned()
13197 })?);
13198 }
13199 let version: i64 = row
13200 .get(table.columns.len())
13201 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
13202 Ok(Some((values, version)))
13203 }
13204
13205 #[must_use]
13209 pub fn realtime_policy(&self) -> RealtimePolicy {
13210 self.realtime_policy
13211 }
13212
13213 #[must_use]
13215 pub fn realtime_state(&self) -> RealtimeState {
13216 self.realtime_state
13217 }
13218
13219 pub fn set_realtime_policy(&mut self, policy: RealtimePolicy) -> Result<(), String> {
13222 if self.realtime_state == RealtimeState::Connected && policy != self.realtime_policy {
13223 return Err(
13224 "sync.invalid_request: disconnect realtime before changing the realtime policy"
13225 .to_owned(),
13226 );
13227 }
13228 self.realtime_policy = policy;
13229 match policy {
13230 RealtimePolicy::Off => self.set_realtime_state(RealtimeState::Disabled, None),
13231 RealtimePolicy::Required | RealtimePolicy::Optional
13232 if self.realtime_state == RealtimeState::Disabled =>
13233 {
13234 self.set_realtime_state(RealtimeState::Disconnected, None);
13235 }
13236 RealtimePolicy::Required | RealtimePolicy::Optional => {}
13237 }
13238 Ok(())
13239 }
13240
13241 fn set_realtime_state(&mut self, state: RealtimeState, reason_code: Option<&str>) {
13244 self.realtime_state = state;
13245 self.realtime_reason_code = reason_code.map(Self::diagnostic_code);
13246 if matches!(state, RealtimeState::Connected | RealtimeState::Disabled) {
13247 self.realtime_reason_code = None;
13248 self.realtime_retry_delay_ms = None;
13249 }
13250 }
13251
13252 #[must_use]
13253 fn realtime_connected(&self) -> bool {
13254 self.realtime_state == RealtimeState::Connected
13255 }
13256
13257 pub fn connect_realtime(&mut self, transport: &mut dyn Transport) -> Result<(), String> {
13258 if !self.transport_enabled {
13259 return Err("sync.offline: transport gate is closed".into());
13260 }
13261 if self.realtime_policy == RealtimePolicy::Off {
13262 return Err(
13263 "sync.invalid_request: realtime is off; realtime connect is refused".to_owned(),
13264 );
13265 }
13266 if self.realtime_connected() {
13267 return Ok(());
13268 }
13269 self.realtime_state = RealtimeState::Connecting;
13270 match transport.realtime_connect(&self.client_id) {
13271 Ok(()) => {
13272 self.set_realtime_state(RealtimeState::Connected, None);
13273 Ok(())
13274 }
13275 Err(error) => {
13276 self.set_realtime_state(RealtimeState::Refused, Some(&error.code));
13277 Err(format!("{}: {}", error.code, error.message))
13278 }
13279 }
13280 }
13281
13282 pub fn disconnect_realtime(&mut self, transport: &mut dyn Transport) {
13283 self.cancel_sync_round();
13284 if self.realtime_state == RealtimeState::Disconnected
13287 || self.realtime_state == RealtimeState::Disabled
13288 {
13289 return;
13290 }
13291 let _ = transport.realtime_close();
13292 self.set_realtime_state(
13293 if self.realtime_policy == RealtimePolicy::Off {
13294 RealtimeState::Disabled
13295 } else {
13296 RealtimeState::Disconnected
13297 },
13298 None,
13299 );
13300 self.presence.clear(); }
13302
13303 pub fn realtime_lost(&mut self, transport: &mut dyn Transport, error: &TransportError) {
13309 if self.realtime_state != RealtimeState::Connected {
13310 return;
13311 }
13312 self.cancel_sync_round();
13313 let _ = transport.realtime_close();
13314 self.set_realtime_state(RealtimeState::Lost, Some(&error.code));
13315 self.realtime_retry_delay_ms = Some(self.schedule_background_retry());
13316 self.presence.clear();
13317 }
13318
13319 pub fn set_presence(
13325 &mut self,
13326 transport: &mut dyn Transport,
13327 scope_key: &str,
13328 doc: Option<&Value>,
13329 ) -> Result<(), String> {
13330 if !self.transport_enabled {
13331 return Err("sync.offline: transport gate is closed".into());
13332 }
13333 if !self.realtime_connected() {
13334 return Err("setPresence requires a connected realtime socket (§8.6)".to_string());
13335 }
13336 let text = encode_presence_publish(scope_key, doc);
13337 transport
13338 .realtime_send(&text)
13339 .map_err(|e| format!("{}: {}", e.code, e.message))
13340 }
13341
13342 pub fn presence(&self, scope_key: &str) -> Vec<PresencePeer> {
13344 self.presence
13345 .get(scope_key)
13346 .map(|peers| peers.values().cloned().collect())
13347 .unwrap_or_default()
13348 }
13349
13350 fn apply_presence(
13352 &mut self,
13353 scope_key: String,
13354 kind: Option<PresenceKind>,
13355 actor_id: Option<String>,
13356 client_id: Option<String>,
13357 doc: Option<Value>,
13358 error: Option<String>,
13359 ) {
13360 if error.is_some() {
13363 return;
13364 }
13365 let (Some(kind), Some(actor_id), Some(client_id)) = (kind, actor_id, client_id) else {
13366 return;
13367 };
13368 let peer_key = format!("{actor_id} {client_id}");
13369 match kind {
13370 PresenceKind::Leave => {
13371 if let Some(peers) = self.presence.get_mut(&scope_key) {
13372 peers.remove(&peer_key);
13373 if peers.is_empty() {
13374 self.presence.remove(&scope_key);
13375 }
13376 }
13377 }
13378 _ => {
13379 let doc = match doc {
13380 Some(Value::Object(_)) => doc.unwrap(),
13381 _ => return,
13382 };
13383 self.presence.entry(scope_key).or_default().insert(
13384 peer_key,
13385 PresencePeer {
13386 actor_id,
13387 client_id,
13388 doc,
13389 },
13390 );
13391 }
13392 }
13393 }
13394
13395 pub fn on_realtime_text(&mut self, text: &str) {
13397 if self.stopped || !self.transport_enabled || self.security_preflight {
13398 return;
13399 }
13400 match parse_control(text) {
13401 Ok(ControlMessage::Hello { requires_sync, .. }) => {
13402 if requires_sync {
13403 self.set_sync_needed(true, true);
13405 }
13406 }
13407 Ok(ControlMessage::Presence {
13408 scope_key,
13409 kind,
13410 actor_id,
13411 client_id,
13412 doc,
13413 error,
13414 ..
13415 }) => {
13416 self.apply_presence(scope_key, kind, actor_id, client_id, doc, error);
13417 }
13418 Ok(ControlMessage::Wake { .. }) => {
13419 self.set_sync_needed(true, true);
13421 }
13422 Ok(ControlMessage::Scopes { .. }) => {
13423 self.scopes_changed += 1;
13425 }
13426 _ => {}
13427 }
13428 }
13429
13430 pub fn on_realtime_binary_queued(&mut self, bytes: &[u8]) -> Vec<String> {
13434 let mut transport = crate::round::DownloadResults::default();
13435 self.on_realtime_binary(&mut transport, bytes);
13436 transport.controls
13437 }
13438
13439 pub fn on_realtime_binary(&mut self, transport: &mut dyn Transport, bytes: &[u8]) {
13445 if self.stopped || !self.transport_enabled || self.security_preflight {
13446 return;
13447 }
13448 #[cfg(feature = "bench-internals")]
13449 let decode_phase = self.benchmark_phases.start(Phase::ResponseDecode);
13450 let message = match decode_message(bytes) {
13451 Ok(m) if m.msg_kind == MsgKind::Response => m,
13452 _ => {
13453 self.set_sync_needed(true, true);
13454 return;
13455 }
13456 };
13457 #[cfg(feature = "bench-internals")]
13458 drop(decode_phase);
13459 if let Some(Frame::RespHeader {
13462 required_schema_version: Some(required),
13463 latest_schema_version,
13464 ..
13465 }) = message.frames.first()
13466 {
13467 let floor = SchemaFloor {
13468 required_schema_version: Some(*required),
13469 latest_schema_version: *latest_schema_version,
13470 };
13471 if self.set_schema_floor(Some(floor)).is_err() {
13472 self.set_sync_needed(true, true);
13473 }
13474 return;
13475 }
13476 let through = message.frames.iter().find_map(|frame| match frame {
13477 Frame::LiveEnd { through_seq, .. } => Some(*through_seq),
13478 _ => None,
13479 });
13480 let epoch = self.get_meta(LOG_EPOCH_KEY).ok().flatten();
13481 let mut dropped = !matches!(message.frames.first(), Some(Frame::RespHeader {
13482 reset_required: false,
13483 log_epoch,
13484 ..
13485 }) if Some(log_epoch) == epoch.as_ref());
13486 let mut applied: Option<i64> = None;
13487 dropped |= self.begin_coalesced_apply().is_err();
13488 let mut receivers: Option<Vec<UnitRecord>> = None;
13489 for frame in message.frames {
13490 if dropped {
13491 break;
13492 }
13493 match frame {
13494 Frame::LiveStart { status, .. } => {
13495 let Ok(cursor) = self.stored(replica_cursor(&self.conn)) else {
13496 dropped = true;
13497 break;
13498 };
13499 if status != LiveStatus::Active || cursor < 0 {
13500 dropped = true;
13501 } else if !through.is_some_and(|through| through <= cursor) {
13502 receivers = self.stored(load_units(&self.conn)).ok().map(|units| {
13504 units
13505 .into_iter()
13506 .filter(|unit| {
13507 unit.status == UnitStatus::Active
13508 && unit.echo.is_some()
13509 && unit.cursor.is_none()
13510 })
13511 .collect()
13512 });
13513 dropped = receivers.is_none();
13514 }
13515 }
13516 Frame::Commit {
13517 commit_seq,
13518 tables,
13519 changes,
13520 ..
13521 } => {
13522 let Some(receivers) = receivers.clone() else {
13523 continue;
13524 };
13525 dropped = self
13526 .apply_live_commit(
13527 &receivers,
13528 &tables,
13529 changes,
13530 commit_seq,
13531 AppliedServerCommitSource::Delta,
13532 )
13533 .is_err();
13534 }
13535 Frame::LiveEnd { through_seq, .. } if receivers.is_some() => {
13536 dropped = self
13537 .set_meta(REPLICA_CURSOR_KEY, &through_seq.to_string())
13538 .is_err();
13539 applied = Some(through_seq);
13540 }
13541 Frame::Error { .. } => dropped = true,
13542 _ => {}
13543 }
13544 }
13545 if self.finish_coalesced_apply().is_err() || dropped {
13548 applied = None;
13549 dropped = true;
13550 }
13551 if let Some(cursor) = applied {
13552 let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
13554 let _ = transport.realtime_send(&ack);
13555 }
13556 if dropped {
13557 self.set_sync_needed(true, true);
13558 }
13559 }
13560
13561 fn ack_after_pull(&mut self, transport: &mut dyn Transport) {
13564 if !self.realtime_connected() {
13565 return;
13566 }
13567 if let Ok(cursor @ 0..) = self.stored(replica_cursor(&self.conn)) {
13568 let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
13569 let _ = transport.realtime_send(&ack);
13570 }
13571 }
13572}
13573
13574#[cfg(test)]
13575mod previous_version_wiring_tests;
13576
13577#[cfg(test)]
13578mod identity_tests;
13579
13580#[cfg(test)]
13581mod insert_intent_tests;
13582
13583#[cfg(test)]
13584mod robustness_tests;
13585
13586#[cfg(test)]
13587mod range_image_tests;