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, 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, UnitScopes, UnitStatus,
48 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 OUTBOX_ID_KEY: &str = "outboxId";
98const CLIENT_ID_KEY: &str = "clientId";
99const LEASE_STATE_KEY: &str = "leaseState";
100const SCHEMA_FLOOR_KEY: &str = "schemaFloor";
101pub(crate) const LOG_EPOCH_KEY: &str = "logEpoch";
102const SECURITY_PREFLIGHT_PENDING_KEY: &str = "securityPreflightPending";
107const LOCAL_REBOOTSTRAP_RECEIPT_VERSION: u8 = 2;
108const MAX_JS_SAFE_INTEGER: u64 = 9_007_199_254_740_991;
109const OUTBOX_INCOMPATIBLE_CODE: &str = "sync.outbox_incompatible";
112const ENCRYPT_FAILED_CODE: &str = "client.encrypt_failed";
115const INVALID_REQUEST_CODE: &str = "sync.invalid_request:";
116const LEGACY_VALUE_REFUSAL_MESSAGE: &str =
118 "the persisted commit carries values the current codec refuses";
119const INVALID_STORED_VALUES_REASON: &str = "invalid_stored_values";
121
122#[derive(Debug, Serialize, Deserialize)]
123#[serde(rename_all = "camelCase", deny_unknown_fields)]
124struct PersistedLocalDataRebootstrapReceipt {
125 version: u8,
126 retained_commits: u64,
127 reset_subscriptions: u64,
128}
129
130fn invalid_local_rebootstrap_receipt() -> String {
131 "sync.local_corrupt: persisted local rebootstrap receipt is invalid".to_owned()
132}
133
134fn encode_local_rebootstrap_receipt(
135 retained_commits: usize,
136 reset_subscriptions: usize,
137) -> Result<String, String> {
138 let retained_commits =
139 u64::try_from(retained_commits).map_err(|_| invalid_local_rebootstrap_receipt())?;
140 let reset_subscriptions =
141 u64::try_from(reset_subscriptions).map_err(|_| invalid_local_rebootstrap_receipt())?;
142 if retained_commits > MAX_JS_SAFE_INTEGER || reset_subscriptions > MAX_JS_SAFE_INTEGER {
143 return Err(invalid_local_rebootstrap_receipt());
144 }
145 serde_json::to_string(&PersistedLocalDataRebootstrapReceipt {
146 version: LOCAL_REBOOTSTRAP_RECEIPT_VERSION,
147 retained_commits,
148 reset_subscriptions,
149 })
150 .map_err(|_| invalid_local_rebootstrap_receipt())
151}
152
153fn decode_local_rebootstrap_receipt(value: &str) -> Result<(usize, usize), String> {
154 if value == "v1" {
156 return Ok((0, 0));
157 }
158 let receipt: PersistedLocalDataRebootstrapReceipt =
159 serde_json::from_str(value).map_err(|_| invalid_local_rebootstrap_receipt())?;
160 if receipt.version != LOCAL_REBOOTSTRAP_RECEIPT_VERSION
161 || receipt.retained_commits > MAX_JS_SAFE_INTEGER
162 || receipt.reset_subscriptions > MAX_JS_SAFE_INTEGER
163 {
164 return Err(invalid_local_rebootstrap_receipt());
165 }
166 Ok((
167 usize::try_from(receipt.retained_commits)
168 .map_err(|_| invalid_local_rebootstrap_receipt())?,
169 usize::try_from(receipt.reset_subscriptions)
170 .map_err(|_| invalid_local_rebootstrap_receipt())?,
171 ))
172}
173
174#[cfg(test)]
175mod observation_tests;
176
177#[doc(hidden)]
179pub struct CurrentBasePreparation {
180 client_commit_id: String,
181 sequence: i64,
182 units: Vec<UnitRecord>,
183 transport_epoch: u64,
184 registration_epoch: u64,
185 security_epoch: u64,
186}
187
188#[cfg(test)]
189mod units_tests;
190
191#[derive(Debug, Clone)]
192struct OutboxOp {
193 upsert: bool,
194 table: String,
195 row_id: String,
196 base_version: Option<i64>,
197 values: Option<Map<String, Value>>,
201 insert: bool,
205}
206
207impl OutboxOp {
208 fn presented_values(&self, table: &TableSchema) -> Option<Cow<'_, Map<String, Value>>> {
213 let values = self.values.as_ref()?;
214 if !self.insert || table.columns.iter().all(|c| values.contains_key(&c.name)) {
215 return Some(Cow::Borrowed(values));
216 }
217 full_row_values(table, values.clone()).ok().map(Cow::Owned)
218 }
219}
220
221impl From<CommitOperation> for OutboxOp {
222 fn from(operation: CommitOperation) -> Self {
223 Self {
224 upsert: operation.op == "upsert",
225 table: operation.table,
226 row_id: operation.row_id,
227 base_version: operation.base_version,
228 values: operation.values,
229 insert: operation.insert,
230 }
231 }
232}
233
234fn invalid_authoring(message: &str, details: Value) -> ClientError {
236 ClientError {
237 code: "sync.invalid_request".to_owned(),
238 message: message.to_owned(),
239 details: Some(details),
240 retryable: false,
241 }
242}
243
244fn chains_on(earlier: &OutboxOp, later: &OutboxOp) -> bool {
247 earlier.row_id == later.row_id
249 && earlier.table == later.table
250 && later.base_version.is_some_and(|base| base > 0)
251 && earlier.base_version == later.base_version
252 && later.values.as_ref().is_some_and(|values| {
253 values.keys().all(|column| {
254 earlier
255 .values
256 .as_ref()
257 .is_some_and(|earlier| earlier.contains_key(column))
258 })
259 })
260}
261
262impl From<&OutboxOp> for CommitOperation {
263 fn from(operation: &OutboxOp) -> Self {
264 Self {
265 table: operation.table.clone(),
266 row_id: operation.row_id.clone(),
267 op: if operation.upsert { "upsert" } else { "delete" }.to_owned(),
268 base_version: operation.base_version,
269 values: operation.values.clone(),
270 insert: operation.insert,
271 }
272 }
273}
274
275#[derive(Debug, Clone)]
276struct OutboxCommit {
277 client_commit_id: String,
278 ops: Vec<OutboxOp>,
279}
280
281fn commit_audit_operations(commit: &OutboxCommit) -> Vec<(&str, Vec<&str>, bool)> {
285 commit
286 .ops
287 .iter()
288 .filter(|operation| operation.upsert)
289 .map(|operation| {
290 (
291 operation.table.as_str(),
292 operation
293 .values
294 .as_ref()
295 .map(|values| values.keys().map(String::as_str).collect())
296 .unwrap_or_default(),
297 operation.insert,
298 )
299 })
300 .collect()
301}
302
303type FailedCommit = (OutboxCommit, Map<String, Value>);
304
305#[derive(Debug, Clone)]
306struct CompiledLocalDataPurgeTarget {
307 table: String,
308 selectors: Vec<(String, Vec<String>)>,
309}
310
311struct StoredCommitOutcomeRow {
312 sequence: i64,
313 client_commit_id: String,
314 status: String,
315 recorded_at_ms: i64,
316 results_json: String,
317 operations_json: Option<String>,
318 resolution: String,
319 resolved_at_ms: Option<i64>,
320 replacement_client_commit_id: Option<String>,
321}
322
323impl StoredCommitOutcomeRow {
324 fn from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<Self> {
325 Ok(Self {
326 sequence: row.get(0)?,
327 client_commit_id: row.get(1)?,
328 status: row.get(2)?,
329 recorded_at_ms: row.get(3)?,
330 results_json: row.get(4)?,
331 operations_json: row.get(5)?,
332 resolution: row.get(6)?,
333 resolved_at_ms: row.get(7)?,
334 replacement_client_commit_id: row.get(8)?,
335 })
336 }
337}
338
339struct SectionStart {
343 id: String,
344 status: SubStatus,
345 reason_code: String,
346 bootstrap: bool,
347 fenced: Vec<FencedRecord>,
348}
349
350enum SectionError {
351 FailClosed,
352 Refused,
354 Deferred,
357 Abort(String, String),
358 Transport(TransportError),
359}
360
361#[derive(Debug)]
362pub(crate) struct RequestMeta {
363 pushed_ids: Vec<String>,
364 registration_digest: String,
367 pub(crate) accept: u8,
368 deferred_commits: usize,
372 pub(crate) applied: BTreeMap<String, BTreeSet<String>>,
375 pub(crate) deferred: BTreeSet<(String, String)>,
379}
380
381#[derive(Default)]
382struct ChangeAccumulator {
383 tables: BTreeMap<String, Option<BTreeSet<String>>>,
385 windows: BTreeMap<String, BTreeSet<String>>,
386 status: bool,
387 conflicts: bool,
388 rejections: bool,
389 outcomes: bool,
390}
391
392impl ChangeAccumulator {
393 fn table(&mut self, table: &str) {
394 self.tables.insert(table.to_owned(), None);
395 }
396
397 fn scope(&mut self, table: &str, key: String) {
398 match self.tables.get_mut(table) {
399 Some(None) => {}
400 Some(Some(keys)) => {
401 keys.insert(key);
402 }
403 None => {
404 self.tables
405 .insert(table.to_owned(), Some(BTreeSet::from([key])));
406 }
407 }
408 }
409
410 fn window(&mut self, base_key: &str, value: &str) {
411 self.windows
412 .entry(base_key.to_owned())
413 .or_default()
414 .insert(value.to_owned());
415 }
416
417 fn touched(&self) -> bool {
418 !self.tables.is_empty()
419 || !self.windows.is_empty()
420 || self.status
421 || self.conflicts
422 || self.rejections
423 || self.outcomes
424 }
425}
426
427const PUSH_OPS_PER_REQUEST: usize = 500;
433const MAX_LOCAL_PURGE_TARGETS: usize = 64;
434const MAX_LOCAL_PURGE_SELECTORS: usize = 8;
435const MAX_LOCAL_PURGE_VALUES: usize = 128;
436const MAX_LOCAL_PURGE_VALUE_LENGTH: usize = 256;
437pub const SECURITY_PREFLIGHT_REQUIRED_CODE: &str = "client.security_preflight_required";
438
439struct OverlayDirty(RefCell<Option<BTreeSet<String>>>);
441
442impl OverlayDirty {
443 fn clean() -> Self {
444 Self(RefCell::new(Some(BTreeSet::new())))
445 }
446 fn get(&self) -> bool {
447 self.0
448 .borrow()
449 .as_ref()
450 .is_none_or(|tables| !tables.is_empty())
451 }
452 fn set(&self, dirty: bool) {
453 *self.0.borrow_mut() = if dirty { None } else { Some(BTreeSet::new()) };
454 }
455 fn table(&self, table: &str) {
456 if let Some(tables) = self.0.borrow_mut().as_mut() {
457 tables.insert(table.to_owned());
458 }
459 }
460 fn snapshot(&self) -> Option<BTreeSet<String>> {
461 self.0.borrow().clone()
462 }
463 fn restore(&self, tables: Option<BTreeSet<String>>) {
464 *self.0.borrow_mut() = tables;
465 }
466}
467
468#[derive(Debug, Clone, Default)]
471struct Shared<T>(Arc<T>);
472
473impl<T> std::ops::Deref for Shared<T> {
474 type Target = T;
475 fn deref(&self) -> &T {
476 &self.0
477 }
478}
479
480impl<T: Clone> std::ops::DerefMut for Shared<T> {
481 fn deref_mut(&mut self) -> &mut T {
482 Arc::make_mut(&mut self.0)
483 }
484}
485
486impl<T> From<T> for Shared<T> {
487 fn from(value: T) -> Self {
488 Self(Arc::new(value))
489 }
490}
491
492#[derive(Debug, Clone)]
496struct Rollback {
497 outbox: Shared<Vec<Arc<OutboxCommit>>>,
498 failed_commits: Shared<Vec<FailedCommit>>,
499 conflicts: Shared<Vec<ConflictRecord>>,
500 rejections: Shared<Vec<RejectionRecord>>,
501 schema_floor: Option<SchemaFloor>,
502 lease_state: Option<LeaseState>,
503 stopped: bool,
504 upgrading: bool,
505 sync_needed: bool,
506 active_round: Option<uuid::Uuid>,
507 overlay_dirty: Option<BTreeSet<String>>,
508 change_queue: usize,
509 sync_intent_queue: usize,
510 last_change: Option<DiagnosticLastChange>,
511}
512
513pub struct SyncClient {
514 #[cfg(feature = "bench-internals")]
515 benchmark_phases: Recorder,
516 conn: Connection,
517 schema: ClientSchema,
518 client_id: String,
519 limits: ClientLimits,
520 outbox: Shared<Vec<Arc<OutboxCommit>>>,
521 failed_commits: Shared<Vec<FailedCommit>>,
522 retain_failed_commits: bool,
523 conflicts: Shared<Vec<ConflictRecord>>,
524 rejections: Shared<Vec<RejectionRecord>>,
525 schema_floor: Option<SchemaFloor>,
526 lease_state: Option<LeaseState>,
528 stopped: bool,
530 upgrading: bool,
532 sync_needed: bool,
534 realtime_policy: RealtimePolicy,
537 realtime_state: RealtimeState,
538 realtime_reason_code: Option<String>,
539 realtime_retry_delay_ms: Option<u64>,
540 presence: HashMap<String, HashMap<String, PresencePeer>>,
542 now_ms: Option<i64>,
545 encryption: crate::values::EncryptionConfig,
549 security_preflight: bool,
552 security_epoch: u64,
553 transport_enabled: bool,
554 transport_epoch: u64,
555 registration_epoch: u64,
558 previous_version: Option<PreviousVersionContextConfig>,
562 insert_sql: RefCell<HashMap<String, String>>,
568 overlay_dirty: OverlayDirty,
571 storage_failure: RefCell<Option<QueryReadFailure>>,
573 #[cfg(test)]
576 overlay_rebuild_count: Cell<usize>,
577 #[cfg(test)]
578 acknowledged_replay_count: Cell<usize>,
579 #[cfg(test)]
582 outcome_prune_count: Cell<usize>,
583 #[cfg(test)]
585 image_chunk_ms: Cell<Option<f64>>,
586 progress: ProgressObserver,
588 change_queue: VecDeque<ClientChangeBatch>,
589 sync_intent_queue: VecDeque<SyncIntent>,
590 retry_delay_ms: u64,
592 round_retry_delay_ms: Option<u64>,
594 #[allow(clippy::type_complexity)]
598 applied_segments: HashMap<String, (Option<i64>, Option<String>, BTreeSet<String>)>,
599 image_chunk_rows: HashMap<String, u32>,
602 round_failure: Option<String>,
607 active_round: Option<uuid::Uuid>,
608 last_round: Option<DiagnosticLastRound>,
609 last_change: Option<DiagnosticLastChange>,
610 query_failures: Vec<DiagnosticQueryFailure>,
612 coalesced: Option<CoalescedApply>,
614 coalesced_failure: Option<String>,
617}
618
619struct CoalescedApply {
623 rows: usize,
624 rollback: Rollback,
625}
626
627const COALESCED_APPLY_ROWS: usize = 1024;
628
629pub(crate) fn quote_ident(name: &str) -> String {
630 format!("\"{}\"", name.replace('"', "\"\""))
631}
632pub(crate) fn meta_get(conn: &Connection, key: &str) -> rusqlite::Result<Option<String>> {
636 conn.query_row(
637 "SELECT value FROM _syncular_meta WHERE key = ?1",
638 rusqlite::params![key],
639 |row| row.get::<_, String>(0),
640 )
641 .optional()
642}
643
644pub(crate) fn meta_set(conn: &Connection, key: &str, value: &str) -> rusqlite::Result<()> {
645 conn.execute(
646 "INSERT OR REPLACE INTO _syncular_meta (key, value) VALUES (?1, ?2)",
647 rusqlite::params![key, value],
648 )
649 .map(|_| ())
650}
651
652pub(crate) fn meta_delete(conn: &Connection, key: &str) -> rusqlite::Result<()> {
653 conn.execute(
654 "DELETE FROM _syncular_meta WHERE key = ?1",
655 rusqlite::params![key],
656 )
657 .map(|_| ())
658}
659
660fn row_id_predicate(table: &TableSchema) -> String {
662 let key = quote_ident(&table.primary_key);
663 let text_match = format!("CAST({key} AS TEXT) = ?1");
664 match table.columns[table.pk_index].ty {
665 ColumnType::String | ColumnType::Json => {
666 format!("{key} = ?1 AND {text_match}")
667 }
668 ColumnType::Integer | ColumnType::Boolean => {
672 format!("{key} = +CAST(?1 AS INTEGER) AND {text_match}")
673 }
674 _ => text_match,
677 }
678}
679
680fn local_scope_predicate(
687 table: &TableSchema,
688 effective: &[(String, Vec<String>)],
689 owners: &[Vec<(String, Vec<String>)>],
690) -> Result<Option<(String, Vec<SqlValue>)>, ()> {
691 if effective.is_empty() || effective.iter().any(|(_, values)| values.is_empty()) {
692 return Ok(None);
693 }
694 let column = |variable: &str| {
695 let name = table.scope_column(variable).ok_or(())?;
696 let column = table
697 .columns
698 .iter()
699 .find(|column| column.name == name)
700 .ok_or(())?;
701 Ok((quote_ident(name), column.ty == ColumnType::Integer))
702 };
703 let mut clauses = Vec::new();
704 let mut params = Vec::new();
705 for (variable, values) in effective {
706 let (key, integer) = column(variable)?;
707 let holes = vec!["?"; values.len()].join(", ");
708 clauses.push(if integer {
709 params.extend(values.iter().cloned().map(SqlValue::Text));
710 let seek = vec!["+CAST(? AS INTEGER)"; values.len()].join(", ");
711 format!("{key} IN ({seek}) AND CAST({key} AS TEXT) IN ({holes})")
712 } else {
713 format!("{key} IN ({holes})")
714 });
715 params.extend(values.iter().cloned().map(SqlValue::Text));
716 }
717 let mut groups: BTreeMap<Vec<&str>, Vec<Vec<&[String]>>> = BTreeMap::new();
723 for owner in owners {
724 if owner.is_empty()
725 || owner.iter().any(|(variable, values)| {
726 values.is_empty()
727 || effective.iter().any(|(name, wanted)| {
728 name == variable && wanted.iter().all(|value| !values.contains(value))
729 })
730 })
731 {
732 continue;
733 }
734 let mut owner: Vec<_> = owner.iter().collect();
735 owner.sort_by(|a, b| a.0.cmp(&b.0));
736 groups
737 .entry(
738 owner
739 .iter()
740 .map(|(variable, _)| variable.as_str())
741 .collect(),
742 )
743 .or_default()
744 .push(owner.iter().map(|(_, values)| values.as_slice()).collect());
745 }
746 let within = |variable: &str, list: &str| {
747 let (key, integer) = column(variable)?;
748 let key = if integer {
749 format!("CAST({key} AS TEXT)")
750 } else {
751 key
752 };
753 Ok(format!("{key} IN (SELECT value FROM json_each({list}))"))
754 };
755 for (variables, tuples) in groups {
756 if let [variable] = variables[..] {
757 let values: BTreeSet<&String> = tuples.iter().flatten().copied().flatten().collect();
758 params.push(SqlValue::Text(
759 Value::from_iter(values.into_iter().cloned()).to_string(),
760 ));
761 clauses.push(format!("NOT {}", within(variable, "?")?));
762 } else {
763 params.push(SqlValue::Text(
764 serde_json::to_string(&tuples).expect("owner tuples serialize"),
765 ));
766 let matches = variables
767 .iter()
768 .enumerate()
769 .map(|(index, variable)| within(variable, &format!("o.value,'$[{index}]'")))
770 .collect::<Result<Vec<_>, ()>>()?;
771 clauses.push(format!(
772 "NOT EXISTS (SELECT 1 FROM json_each(?) o WHERE {})",
773 matches.join(" AND ")
774 ));
775 }
776 }
777 Ok(Some((clauses.join(" AND "), params)))
778}
779
780fn owns_local_row(
782 table: &TableSchema,
783 effective: &[(String, Vec<String>)],
784 owners: &[Vec<(String, Vec<String>)>],
785 values: &Map<String, Value>,
786) -> bool {
787 let matches = |scopes: &[(String, Vec<String>)]| {
788 !scopes.is_empty()
789 && scopes.iter().all(|(variable, allowed)| {
790 table
791 .scope_column(variable)
792 .and_then(|column| values.get(column))
793 .filter(|value| !value.is_null())
794 .is_some_and(|value| {
795 allowed.contains(
796 &value
797 .as_str()
798 .map_or_else(|| value.to_string(), str::to_owned),
799 )
800 })
801 })
802 };
803 matches(effective) && !owners.iter().any(|owner| matches(owner))
804}
805
806fn is_local_operation_code_like(value: &str) -> bool {
807 let bytes = value.as_bytes();
808 bytes.first().is_some_and(u8::is_ascii_alphanumeric)
809 && bytes
810 .iter()
811 .all(|byte| byte.is_ascii_alphanumeric() || matches!(*byte, b'.' | b'_' | b':' | b'-'))
812}
813
814fn base_table(name: &str) -> String {
815 quote_ident(&format!("_syncular_base_{name}"))
816}
817
818type PendingEvict = (String, String, Vec<(String, Vec<String>)>);
820
821fn window_base_key(base: &WindowBase) -> String {
823 format!(
824 "{}\0{}",
825 base.variable,
826 ssp2::registration::canonical_unit_json(&scope_pairs(&base.fixed_scopes))
827 )
828}
829
830fn window_unit_scopes(base: &WindowBase, value: &str) -> UnitScopes {
832 let mut scopes = base.fixed_scopes.clone();
833 scopes.insert(base.variable.clone(), value.to_owned());
834 scopes
835}
836
837fn scope_pairs(scopes: &UnitScopes) -> Vec<(String, String)> {
839 let mut pairs: Vec<(String, String)> = scopes
840 .iter()
841 .map(|(variable, value)| (variable.clone(), value.clone()))
842 .collect();
843 pairs.sort_by(|a, b| a.0.encode_utf16().cmp(b.0.encode_utf16()));
844 pairs
845}
846
847fn covers(table: &TableSchema, scopes: &UnitScopes) -> bool {
849 scopes
850 .keys()
851 .all(|variable| table.scope_column(variable).is_some())
852}
853
854fn pair_scopes(
858 scopes: &UnitScopes,
859 table: &str,
860 echo: Option<&[EchoRecord]>,
861) -> Option<Vec<(String, Vec<String>)>> {
862 let fenced = echo.and_then(|echo| echo.iter().find(|record| record.table == table));
863 if fenced.is_some_and(|record| record.status == "revoked") {
864 return None;
865 }
866 let mut effective: BTreeMap<String, Vec<String>> = fenced
867 .map(|record| record.scopes.clone())
868 .unwrap_or_default();
869 for (variable, value) in scopes {
870 effective.insert(variable.clone(), vec![value.clone()]);
871 }
872 Some(effective.into_iter().collect())
873}
874
875fn unit_owners(
880 units: &[UnitRecord],
881 table: &TableSchema,
882 except_id: &str,
883) -> Vec<Vec<(String, Vec<String>)>> {
884 units
885 .iter()
886 .filter(|unit| {
887 unit.id != except_id
888 && unit.status == UnitStatus::Active
889 && unit.echo.is_some()
890 && (!unit.bootstrapping() || unit.seeded.contains(&table.name))
891 && covers(table, &unit.scopes)
892 })
893 .filter_map(|unit| pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()))
894 .collect()
895}
896
897fn unit_scope_lists(scopes: &UnitScopes) -> Vec<(String, Vec<String>)> {
899 scopes
900 .iter()
901 .map(|(variable, value)| (variable.clone(), vec![value.clone()]))
902 .collect()
903}
904
905const 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";
909
910const UNIT_COLUMNS: &str =
911 "id, scopes, explicit, status, reason_code, cursor, bootstrap_state, seeded, echo";
912
913fn unit_from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<UnitRecord> {
916 fn json<T: serde::de::DeserializeOwned>(index: usize, raw: &str) -> rusqlite::Result<T> {
917 serde_json::from_str(raw).map_err(|error| {
918 rusqlite::Error::FromSqlConversionFailure(
919 index,
920 rusqlite::types::Type::Text,
921 Box::new(error),
922 )
923 })
924 }
925 Ok(UnitRecord {
926 id: row.get(0)?,
927 scopes: json(1, &row.get::<_, String>(1)?)?,
928 explicit: row.get::<_, i64>(2)? == 1,
929 status: json(
930 3,
931 &serde_json::to_string(&row.get::<_, String>(3)?).expect("text"),
932 )?,
933 reason_code: row.get(4)?,
934 cursor: row.get(5)?,
935 bootstrap_state: row.get(6)?,
936 seeded: json(7, &row.get::<_, String>(7)?)?,
937 echo: row
938 .get::<_, Option<String>>(8)?
939 .map(|echo| json::<Vec<EchoRecord>>(8, &echo))
940 .transpose()?
941 .map(|echo| {
942 if echo
943 .iter()
944 .all(|record| record.status == "active" || record.status == "revoked")
945 {
946 Ok(echo)
947 } else {
948 Err(rusqlite::Error::FromSqlConversionFailure(
949 8,
950 rusqlite::types::Type::Text,
951 "echo status is neither active nor revoked".into(),
952 ))
953 }
954 })
955 .transpose()?,
956 })
957}
958
959fn load_units(conn: &Connection) -> rusqlite::Result<Vec<UnitRecord>> {
961 conn.prepare_cached(&format!(
962 "SELECT {UNIT_COLUMNS} FROM _syncular_units ORDER BY rowid"
963 ))?
964 .query_map([], unit_from_row)?
965 .collect()
966}
967
968fn get_unit(conn: &Connection, id: &str) -> rusqlite::Result<Option<UnitRecord>> {
969 conn.query_row(
970 &format!("SELECT {UNIT_COLUMNS} FROM _syncular_units WHERE id = ?1"),
971 [id],
972 unit_from_row,
973 )
974 .optional()
975}
976
977fn save_unit(conn: &Connection, unit: &UnitRecord) -> rusqlite::Result<()> {
979 conn.prepare_cached(&format!(
980 "INSERT INTO _syncular_units({UNIT_COLUMNS}) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9)
981 ON CONFLICT(id) DO UPDATE SET explicit=excluded.explicit, status=excluded.status,
982 reason_code=excluded.reason_code, cursor=excluded.cursor,
983 bootstrap_state=excluded.bootstrap_state, seeded=excluded.seeded, echo=excluded.echo"
984 ))?
985 .execute(rusqlite::params![
986 unit.id,
987 serde_json::to_string(&unit.scopes).expect("scope map serializes"),
988 i64::from(unit.explicit),
989 unit.status.name(),
990 unit.reason_code,
991 unit.cursor,
992 unit.bootstrap_state,
993 serde_json::to_string(&unit.seeded).expect("table list serializes"),
994 unit.echo
995 .as_ref()
996 .map(|echo| serde_json::to_string(echo).expect("echo serializes")),
997 ])
998 .map(|_| ())
999}
1000
1001fn window_refs(conn: &Connection, unit_id: &str) -> rusqlite::Result<Vec<(String, String)>> {
1003 conn.prepare_cached("SELECT base, unit FROM _syncular_windows WHERE sub_id = ?1")?
1004 .query_map([unit_id], |row| Ok((row.get(0)?, row.get(1)?)))?
1005 .collect()
1006}
1007
1008fn reset_units(conn: &Connection) -> rusqlite::Result<()> {
1012 conn.execute_batch(
1013 "UPDATE _syncular_units SET status='active', reason_code=NULL, cursor=-1,
1014 bootstrap_state=NULL, seeded='[]', echo=NULL;
1015 DELETE FROM _syncular_meta WHERE key IN ('replicaCursor','echoDigest','registrationDigest');",
1016 )
1017}
1018
1019fn replica_cursor(conn: &Connection) -> rusqlite::Result<i64> {
1021 meta_get(conn, REPLICA_CURSOR_KEY)?.map_or(Ok(-1), |raw| {
1022 raw.parse().map_err(|error| {
1023 rusqlite::Error::FromSqlConversionFailure(
1024 0,
1025 rusqlite::types::Type::Text,
1026 Box::new(error),
1027 )
1028 })
1029 })
1030}
1031
1032fn visible_table(name: &str) -> String {
1033 quote_ident(name)
1034}
1035
1036const FTS_SOURCE_ID_COLUMN: &str = "_syncular_source_id";
1037
1038fn is_synced_table_name(name: &str) -> bool {
1041 if name.starts_with("sqlite_") {
1042 return false;
1043 }
1044 if name.starts_with("_syncular_base_") {
1045 return true; }
1047 !name.starts_with("_syncular_")
1049}
1050
1051fn blob_id_for(bytes: &[u8]) -> String {
1053 let digest = Sha256::digest(bytes);
1054 format!("sha256:{}", bytes_to_hex(&digest))
1055}
1056
1057enum RowParam<'a> {
1061 Cell(&'a Option<ColumnValue>),
1062 Version(i64),
1063 Text(Option<&'a str>),
1064}
1065
1066impl rusqlite::ToSql for RowParam<'_> {
1067 fn to_sql(&self) -> rusqlite::Result<ToSqlOutput<'_>> {
1068 Ok(match self {
1069 RowParam::Version(v) => ToSqlOutput::Owned(SqlValue::Integer(*v)),
1070 RowParam::Text(text) => match text {
1071 Some(text) => ToSqlOutput::Borrowed(ValueRef::Text(text.as_bytes())),
1072 None => ToSqlOutput::Owned(SqlValue::Null),
1073 },
1074 RowParam::Cell(cell) => match cell {
1075 None => ToSqlOutput::Owned(SqlValue::Null),
1076 Some(ColumnValue::String(s)) => ToSqlOutput::Borrowed(ValueRef::Text(s.as_bytes())),
1077 Some(ColumnValue::Integer(i)) => ToSqlOutput::Owned(SqlValue::Integer(*i)),
1078 Some(ColumnValue::Float(f)) => ToSqlOutput::Owned(SqlValue::Real(*f)),
1079 Some(ColumnValue::Boolean(b)) => {
1080 ToSqlOutput::Owned(SqlValue::Integer(i64::from(*b)))
1081 }
1082 Some(ColumnValue::Json(raw)) | Some(ColumnValue::BlobRef(raw)) => {
1083 ToSqlOutput::Borrowed(ValueRef::Text(raw.0.as_bytes()))
1084 }
1085 Some(ColumnValue::Bytes(b)) | Some(ColumnValue::Crdt(b)) => {
1087 ToSqlOutput::Borrowed(ValueRef::Blob(b))
1088 }
1089 },
1090 })
1091 }
1092}
1093
1094fn owned_sql_value(param: impl rusqlite::ToSql) -> Result<SqlValue, String> {
1096 match param.to_sql().map_err(|error| error.to_string())? {
1097 ToSqlOutput::Owned(value) => Ok(value),
1098 ToSqlOutput::Borrowed(value) => {
1099 SqlValue::try_from(value).map_err(|error| error.to_string())
1100 }
1101 _ => Err("sync.invalid_request: unsupported SQLite key parameter".into()),
1102 }
1103}
1104
1105fn image_cell_param<'a>(column: &Column, value: ValueRef<'a>) -> Result<ToSqlOutput<'a>, String> {
1113 use ssp2::segment::ColumnType;
1114 let mismatch = || {
1115 Err(format!(
1116 "image column {:?} holds a value of the wrong type",
1117 column.name
1118 ))
1119 };
1120 match value {
1121 ValueRef::Null => {
1122 if !column.nullable {
1123 return Err(format!(
1124 "image column {:?} is NULL but not nullable",
1125 column.name
1126 ));
1127 }
1128 Ok(ToSqlOutput::Owned(SqlValue::Null))
1129 }
1130 ValueRef::Integer(i) => match column.ty {
1131 ColumnType::Integer => Ok(ToSqlOutput::Borrowed(value)),
1132 ColumnType::Boolean => Ok(ToSqlOutput::Owned(SqlValue::Integer(i64::from(i != 0)))),
1133 ColumnType::Float => Ok(ToSqlOutput::Owned(SqlValue::Real(i as f64))),
1134 _ => mismatch(),
1135 },
1136 ValueRef::Real(_) => match column.ty {
1137 ColumnType::Float => Ok(ToSqlOutput::Borrowed(value)),
1138 _ => mismatch(),
1139 },
1140 ValueRef::Text(t) => {
1141 std::str::from_utf8(t)
1142 .map_err(|_| format!("image column {:?} is not UTF-8", column.name))?;
1143 match column.ty {
1144 ColumnType::String | ColumnType::Json | ColumnType::BlobRef => {
1145 Ok(ToSqlOutput::Borrowed(value))
1146 }
1147 _ => mismatch(),
1148 }
1149 }
1150 ValueRef::Blob(_) => match column.ty {
1151 ColumnType::Bytes | ColumnType::Crdt => Ok(ToSqlOutput::Borrowed(value)),
1153 _ => mismatch(),
1154 },
1155 }
1156}
1157
1158pub(crate) fn sql_ref_to_json(column: &Column, value: rusqlite::types::ValueRef<'_>) -> Value {
1159 use rusqlite::types::ValueRef;
1160 match value {
1161 ValueRef::Null => Value::Null,
1162 ValueRef::Integer(i) => match column.ty {
1163 ssp2::segment::ColumnType::Boolean => Value::Bool(i != 0),
1164 ssp2::segment::ColumnType::Float => {
1165 serde_json::Number::from_f64(i as f64).map_or(Value::Null, Value::Number)
1166 }
1167 _ => Value::from(i),
1168 },
1169 ValueRef::Real(f) => serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number),
1170 ValueRef::Text(t) => Value::from(String::from_utf8_lossy(t).into_owned()),
1171 ValueRef::Blob(b) => {
1172 let mut map = Map::new();
1173 map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(b)));
1174 Value::Object(map)
1175 }
1176 }
1177}
1178
1179fn json_param_to_sql(value: &Value) -> Result<SqlValue, String> {
1183 Ok(match value {
1184 Value::Null => SqlValue::Null,
1185 Value::Bool(b) => SqlValue::Integer(i64::from(*b)),
1186 Value::Number(n) => {
1187 if let Some(i) = n.as_i64() {
1188 SqlValue::Integer(i)
1189 } else if let Some(f) = n.as_f64() {
1190 SqlValue::Real(f)
1191 } else {
1192 return Err(format!("query param number {n} is out of range"));
1193 }
1194 }
1195 Value::String(s) => SqlValue::Text(s.clone()),
1196 Value::Object(_) => {
1197 if let Some(hex) = value.get("$bytes").and_then(Value::as_str) {
1198 SqlValue::Blob(crate::values::hex_to_bytes(hex)?)
1199 } else if let Some(decimal) = value.get("$bigint").and_then(Value::as_str) {
1200 SqlValue::Integer(decimal.parse::<i64>().map_err(|_| {
1201 format!("query bigint param {decimal:?} is outside SQLite's i64 range")
1202 })?)
1203 } else {
1204 return Err(
1205 "query object param must be a {$bytes: hex} or {$bigint: decimal} value"
1206 .to_owned(),
1207 );
1208 }
1209 }
1210 Value::Array(_) => return Err("query array params are not supported".to_owned()),
1211 })
1212}
1213
1214fn sql_ref_to_json_dynamic(value: rusqlite::types::ValueRef<'_>) -> Value {
1219 use rusqlite::types::ValueRef;
1220 match value {
1221 ValueRef::Null => Value::Null,
1222 ValueRef::Integer(i) => {
1223 const MAX_SAFE_INTEGER: i64 = 9_007_199_254_740_991;
1227 if (-MAX_SAFE_INTEGER..=MAX_SAFE_INTEGER).contains(&i) {
1228 Value::from(i)
1229 } else {
1230 let mut map = Map::new();
1231 map.insert("$bigint".to_owned(), Value::from(i.to_string()));
1232 Value::Object(map)
1233 }
1234 }
1235 ValueRef::Real(f) => serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number),
1236 ValueRef::Text(t) => Value::from(String::from_utf8_lossy(t).into_owned()),
1237 ValueRef::Blob(b) => {
1238 let mut map = Map::new();
1239 map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(b)));
1240 Value::Object(map)
1241 }
1242 }
1243}
1244
1245fn query_connection(
1247 conn: &Connection,
1248 sql: &str,
1249 params: &[QueryValue],
1250) -> Result<Vec<QueryRow>, QueryReadFailure> {
1251 let lowered_sql = crate::query_guard::lower_public_query_sql(sql);
1252 let mut stmt = crate::query_guard::prepare_read_only(conn, &lowered_sql)?;
1253 let bound: Vec<SqlValue> = params
1254 .iter()
1255 .map(json_param_to_sql)
1256 .collect::<Result<_, _>>()?;
1257 let columns: Vec<(usize, String)> = stmt
1262 .column_names()
1263 .enumerate()
1264 .filter(|(_, name)| {
1265 !matches!(
1266 *name,
1267 "_syncular_version" | "_sync_sealed_key" | "_sync_sealed"
1268 )
1269 })
1270 .map(|(i, name)| (i, name.to_owned()))
1271 .collect();
1272 let bound_refs: Vec<&dyn rusqlite::ToSql> =
1273 bound.iter().map(|v| v as &dyn rusqlite::ToSql).collect();
1274 let mut sql_rows = stmt.query(bound_refs.as_slice())?;
1275 let mut out = Vec::new();
1276 while let Some(row) = sql_rows.next()? {
1277 let mut record = Map::new();
1278 for (i, name) in &columns {
1279 let value = row.get_ref(*i)?;
1280 record.insert(name.clone(), sql_ref_to_json_dynamic(value));
1281 }
1282 out.push(record);
1283 }
1284 Ok(out)
1285}
1286
1287fn persisted_window_state(
1288 conn: &Connection,
1289 base: &WindowBase,
1290) -> Result<WindowState, QueryReadFailure> {
1291 let mut stmt = conn.prepare(
1292 "SELECT windows.unit, units.status, units.cursor, units.bootstrap_state
1293 FROM _syncular_windows AS windows
1294 LEFT JOIN _syncular_units AS units ON units.id = windows.sub_id
1295 WHERE windows.base = ?1
1296 ORDER BY windows.unit ASC",
1297 )?;
1298 let rows = stmt.query_map(rusqlite::params![window_base_key(base)], |row| {
1299 Ok((
1300 row.get::<_, String>(0)?,
1301 row.get::<_, Option<String>>(1)?,
1302 row.get::<_, Option<i64>>(2)?,
1303 row.get::<_, Option<String>>(3)?,
1304 ))
1305 })?;
1306 let mut units = Vec::new();
1307 let mut pending = Vec::new();
1308 for row in rows {
1309 let (unit, status, cursor, bootstrap_state) = row?;
1310 if status.as_deref() != Some("active")
1312 || cursor.is_some_and(|cursor| cursor < 0 || bootstrap_state.is_some())
1313 {
1314 pending.push(unit.clone());
1315 }
1316 units.push(unit);
1317 }
1318 Ok(WindowState { units, pending })
1319}
1320
1321#[derive(Debug, Clone, Copy)]
1323pub struct SnapshotStatement<'a> {
1324 pub sql: &'a str,
1325 pub params: &'a [Value],
1326}
1327
1328#[derive(Debug, Clone, Default)]
1332pub struct SnapshotReadRequest<'a> {
1333 pub statements: Vec<SnapshotStatement<'a>>,
1334 pub coverage: &'a [WindowCoverage],
1335 pub units: Vec<String>,
1336 pub commit_ids: Vec<String>,
1337}
1338
1339#[cfg(test)]
1340thread_local! {
1341 static SNAPSHOT_READ_HOOK: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
1345 std::cell::RefCell::new(None);
1346}
1347
1348#[cfg(test)]
1349fn run_snapshot_read_hook() {
1350 SNAPSHOT_READ_HOOK.with(|slot| {
1351 if let Some(hook) = slot.borrow_mut().take() {
1352 hook();
1353 }
1354 });
1355}
1356
1357fn snapshot_read_connection(
1362 conn: &Connection,
1363 request: &SnapshotReadRequest<'_>,
1364) -> Result<SnapshotRead, QueryReadFailure> {
1365 conn.execute_batch("SAVEPOINT syncular_snapshot_read")?;
1366 let corrupt = |message: &str| QueryReadFailure {
1367 code: Some("sync.local_corrupt"),
1368 sqlite_code: None,
1369 sqlite_message: None,
1370 rollback_failure: None,
1371 message: message.to_owned(),
1372 };
1373 let stored_failure = |error: rusqlite::Error, message: &str| match error {
1374 rusqlite::Error::Utf8Error(..)
1375 | rusqlite::Error::InvalidColumnType(..)
1376 | rusqlite::Error::FromSqlConversionFailure(..)
1377 | rusqlite::Error::IntegralValueOutOfRange(..) => corrupt(message),
1378 _ => QueryReadFailure::from(error),
1379 };
1380 let result: Result<SnapshotRead, QueryReadFailure> = (|| {
1381 let revision: Option<String> = conn
1384 .query_row(
1385 "SELECT value FROM _syncular_meta WHERE key = ?1",
1386 rusqlite::params![LOCAL_REVISION_KEY],
1387 |row| row.get(0),
1388 )
1389 .optional()
1390 .map_err(|error| stored_failure(error, "persisted local revision is invalid"))?;
1391 let revision = match revision {
1392 None => "0".to_owned(),
1393 Some(value)
1394 if value == "0"
1395 || (matches!(value.as_bytes().first(), Some(b'1'..=b'9'))
1396 && value.bytes().all(|b| b.is_ascii_digit())
1397 && value.parse::<u64>().is_ok()) =>
1398 {
1399 value
1400 }
1401 Some(_) => return Err(corrupt("persisted local revision is invalid")),
1402 };
1403 let mut queries = Vec::with_capacity(request.statements.len());
1404 for statement in &request.statements {
1405 queries.push(query_connection(conn, statement.sql, statement.params)?);
1406 #[cfg(test)]
1407 run_snapshot_read_hook();
1408 }
1409 let mut pending = Vec::new();
1410 let mut missing = Vec::new();
1411 for requested in request.coverage {
1412 let base_key = window_base_key(&requested.base);
1413 let state = persisted_window_state(conn, &requested.base)?;
1414 for unit in BTreeSet::from_iter(requested.units.iter().cloned()) {
1415 let reference = WindowUnitRef {
1416 base_key: base_key.clone(),
1417 unit: unit.clone(),
1418 };
1419 if !state.units.iter().any(|held| held == &unit) {
1420 missing.push(reference);
1421 } else if state.pending.iter().any(|held| held == &unit) {
1422 pending.push(reference);
1423 }
1424 }
1425 }
1426 let mut units = Vec::with_capacity(request.units.len());
1427 for id in &request.units {
1428 let exists: bool = conn.query_row(
1429 "SELECT EXISTS(SELECT 1 FROM _syncular_units WHERE id = ?1)",
1430 [id],
1431 |row| row.get(0),
1432 )?;
1433 if !exists {
1434 units.push(UnitCatchup::Unknown { id: id.clone() });
1435 continue;
1436 }
1437 let unit = get_unit(conn, id)
1440 .map_err(|error| stored_failure(error, "persisted unit state is invalid"))?
1441 .ok_or_else(|| corrupt("persisted unit state is invalid"))?;
1442 let cursor = match unit.cursor {
1443 Some(cursor) => cursor,
1444 None => replica_cursor(conn)
1445 .map_err(|error| stored_failure(error, "persisted unit state is invalid"))?,
1446 };
1447 if cursor.unsigned_abs() > MAX_JS_SAFE_INTEGER {
1448 return Err(corrupt("persisted unit state is invalid"));
1449 }
1450 let active = unit.status == UnitStatus::Active;
1451 let pending = unit.bootstrapping();
1452 units.push(UnitCatchup::Known {
1453 id: id.clone(),
1454 status: unit.status,
1455 live: unit.cursor.is_none(),
1456 cursor,
1457 has_resume_token: unit.bootstrap_state.is_some(),
1458 bootstrap_complete: active && !pending,
1459 known_pending_pages: active && pending,
1460 reason_code: unit.reason_code,
1461 });
1462 }
1463 let mut deliveries = Vec::with_capacity(request.commit_ids.len());
1464 for id in &request.commit_ids {
1465 let pending: bool = conn.query_row(
1466 "SELECT EXISTS(SELECT 1 FROM _syncular_outbox WHERE commit_id = ?1)",
1467 rusqlite::params![id],
1468 |row| row.get(0),
1469 )?;
1470 if pending {
1471 deliveries.push(CommitDelivery::Pending {
1472 client_commit_id: id.clone(),
1473 });
1474 continue;
1475 }
1476 let row = conn
1477 .query_row(
1478 "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
1479 resolution, resolved_at_ms, replacement_client_commit_id
1480 FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
1481 rusqlite::params![id],
1482 StoredCommitOutcomeRow::from_row,
1483 )
1484 .optional()
1485 .map_err(|error| stored_failure(error, "persisted commit outcome is invalid"))?;
1486 deliveries.push(match row {
1487 Some(row) => CommitDelivery::Known {
1488 client_commit_id: id.clone(),
1489 outcome: SyncClient::outcome_from_row(row)
1490 .map_err(|_| corrupt("persisted commit outcome is invalid"))?,
1491 },
1492 None => CommitDelivery::Unknown {
1493 client_commit_id: id.clone(),
1494 },
1495 });
1496 }
1497 Ok(SnapshotRead {
1498 revision,
1499 queries,
1500 coverage: CoverageSnapshot {
1501 complete: pending.is_empty() && missing.is_empty(),
1502 pending,
1503 missing,
1504 },
1505 units,
1506 deliveries,
1507 })
1508 })();
1509 match result {
1510 Ok(read) => {
1511 conn.execute_batch("RELEASE syncular_snapshot_read")?;
1512 Ok(read)
1513 }
1514 Err(mut error) => {
1515 if let Err(rollback) = conn
1516 .execute_batch("ROLLBACK TO syncular_snapshot_read; RELEASE syncular_snapshot_read")
1517 {
1518 error.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
1519 }
1520 Err(error)
1521 }
1522 }
1523}
1524
1525fn snapshot_connection(
1526 conn: &Connection,
1527 sql: &str,
1528 params: &[Value],
1529 coverage: &[WindowCoverage],
1530) -> Result<QuerySnapshot, QueryReadFailure> {
1531 let read = snapshot_read_connection(
1532 conn,
1533 &SnapshotReadRequest {
1534 statements: vec![SnapshotStatement { sql, params }],
1535 coverage,
1536 units: Vec::new(),
1537 commit_ids: Vec::new(),
1538 },
1539 )?;
1540 Ok(QuerySnapshot {
1541 revision: read.revision,
1542 rows: read
1543 .queries
1544 .into_iter()
1545 .next()
1546 .expect("single-query snapshot returns one result"),
1547 coverage: read.coverage,
1548 })
1549}
1550
1551pub struct FileQuerySnapshotReader {
1556 path: String,
1557 conn: Option<Connection>,
1558}
1559
1560impl FileQuerySnapshotReader {
1561 #[must_use]
1562 pub fn new(path: impl Into<String>) -> Self {
1563 Self {
1564 path: path.into(),
1565 conn: None,
1566 }
1567 }
1568
1569 fn connection(&mut self) -> Result<&Connection, QueryReadFailure> {
1570 if self.conn.is_none() {
1571 let conn = Connection::open_with_flags(
1572 &self.path,
1573 OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
1574 )
1575 .map_err(QueryReadFailure::from)?;
1576 conn.busy_timeout(std::time::Duration::from_millis(250))
1577 .map_err(QueryReadFailure::from)?;
1578 self.conn = Some(conn);
1579 }
1580 self.conn
1581 .as_ref()
1582 .ok_or_else(|| QueryReadFailure::from("read sidecar connection missing".to_owned()))
1583 }
1584
1585 pub fn snapshot_read(
1588 &mut self,
1589 request: &SnapshotReadRequest<'_>,
1590 ) -> Result<SnapshotRead, QueryReadFailure> {
1591 snapshot_read_connection(self.connection()?, request)
1592 }
1593
1594 pub fn local_revision(&mut self) -> Result<String, QueryReadFailure> {
1597 Ok(self
1598 .snapshot_read(&SnapshotReadRequest::default())?
1599 .revision)
1600 }
1601
1602 pub fn unit_catchup(&mut self, id: &str) -> Result<UnitCatchup, QueryReadFailure> {
1604 let read = self.snapshot_read(&SnapshotReadRequest {
1605 units: vec![id.to_owned()],
1606 ..Default::default()
1607 })?;
1608 Ok(read
1609 .units
1610 .into_iter()
1611 .next()
1612 .expect("one requested catch-up"))
1613 }
1614
1615 pub fn commit_delivery(&mut self, id: &str) -> Result<CommitDelivery, QueryReadFailure> {
1618 let read = self.snapshot_read(&SnapshotReadRequest {
1619 commit_ids: vec![id.to_owned()],
1620 ..Default::default()
1621 })?;
1622 Ok(read
1623 .deliveries
1624 .into_iter()
1625 .next()
1626 .expect("one requested delivery"))
1627 }
1628
1629 pub fn query_snapshot(
1632 &mut self,
1633 sql: &str,
1634 params: &[Value],
1635 coverage: &[WindowCoverage],
1636 ) -> Result<QuerySnapshot, QueryReadFailure> {
1637 snapshot_connection(self.connection()?, sql, params, coverage)
1638 }
1639}
1640
1641fn validate_authority_reads(
1642 schema: &ClientSchema,
1643 declarations: &[crate::api::AuthorityReadDeclaration],
1644) -> Result<(), String> {
1645 let mut seen = BTreeSet::new();
1646 for read in declarations {
1647 let table = schema
1648 .table(&read.table)
1649 .ok_or("client.authority_read_forbidden: authority table is not declared")?;
1650 let plain = |name: &str| {
1651 table.columns.iter().enumerate().any(|(i, c)| {
1652 c.name == name
1653 && name != "authority_version"
1654 && !name.starts_with("_sync")
1655 && !table.encrypted_columns.iter().any(|e| e.index == i)
1656 && matches!(
1657 c.ty,
1658 ssp2::segment::ColumnType::String
1659 | ssp2::segment::ColumnType::Integer
1660 | ssp2::segment::ColumnType::Float
1661 | ssp2::segment::ColumnType::Boolean
1662 | ssp2::segment::ColumnType::Json
1663 )
1664 })
1665 };
1666 if !seen.insert(&read.table)
1667 || read.columns.is_empty()
1668 || read.columns.iter().collect::<BTreeSet<_>>().len() != read.columns.len()
1669 || !read.columns.contains(&table.primary_key)
1670 || !read.columns.iter().all(|c| plain(c))
1671 || read.scopes.is_empty()
1672 || !read.scopes.iter().all(|(v, values)| {
1673 table
1674 .scope_column(v)
1675 .is_some_and(|c| read.columns.iter().any(|column| column == c) && plain(c))
1676 && !values.is_empty()
1677 && values.iter().all(|v| !v.is_empty() && v != "*")
1678 })
1679 {
1680 return Err("client.authority_read_forbidden: authority reads require plain columns, a primary key and nonempty plain scope selectors".into());
1681 }
1682 }
1683 Ok(())
1684}
1685
1686fn schema_marker_read_failure(error: rusqlite::Error) -> String {
1691 let failure = QueryReadFailure::from(error);
1692 if failure.code.is_some() {
1693 failure.to_string()
1694 } else {
1695 "sync.local_corrupt: persisted local schema marker is unreadable or invalid".to_owned()
1696 }
1697}
1698
1699fn validate_client_limits(limits: &crate::api::ClientLimits) -> Result<(), String> {
1703 if limits.outcome_retention_max_entries == Some(0) {
1704 return Err("sync.invalid_request: outcomeRetentionMaxEntries must be positive".to_owned());
1705 }
1706 if [
1707 limits.max_push_commits_per_request,
1708 limits.max_push_operations_per_request,
1709 limits.max_push_request_bytes,
1710 ]
1711 .into_iter()
1712 .flatten()
1713 .any(|value| value == 0 || value > u32::MAX as usize)
1714 {
1715 return Err(
1716 "sync.invalid_request: push limit must be an integer in 1..=4294967295".to_owned(),
1717 );
1718 }
1719 Ok(())
1720}
1721
1722fn read_local_schema_version(conn: &Connection, requested: i32) -> Result<Option<i32>, String> {
1723 let corrupt =
1724 || "sync.local_corrupt: persisted local schema marker is unreadable or invalid".to_owned();
1725 let table_type: Option<String> = conn
1726 .query_row(
1727 "SELECT type FROM sqlite_master WHERE name = '_syncular_meta'",
1728 [],
1729 |row| row.get(0),
1730 )
1731 .optional()
1732 .map_err(schema_marker_read_failure)?;
1733 let Some(table_type) = table_type else {
1734 return Ok(None);
1735 };
1736 if table_type != "table" {
1737 return Err(corrupt());
1738 }
1739 let mut statement = conn
1743 .prepare("SELECT value FROM _syncular_meta WHERE key = ?1")
1744 .map_err(schema_marker_read_failure)?;
1745 let mut rows = statement
1746 .query([LOCAL_SCHEMA_VERSION_KEY])
1747 .map_err(schema_marker_read_failure)?;
1748 let value: Option<String> = rows
1749 .next()
1750 .map_err(schema_marker_read_failure)?
1751 .map(|row| row.get(0))
1752 .transpose()
1753 .map_err(schema_marker_read_failure)?;
1754 if rows.next().map_err(schema_marker_read_failure)?.is_some() {
1755 return Err(corrupt());
1756 }
1757 let Some(value) = value else {
1758 let has_descriptor = conn
1759 .query_row(
1760 "SELECT 1 FROM _syncular_meta WHERE key = ?1 LIMIT 1",
1761 [crate::previous_version::LOCAL_SCHEMA_DESCRIPTOR_KEY],
1762 |_| Ok(()),
1763 )
1764 .optional()
1765 .map_err(schema_marker_read_failure)?
1766 .is_some();
1767 if has_descriptor {
1768 return Err(corrupt());
1769 }
1770 return Ok(None);
1771 };
1772 if !matches!(value.as_bytes().first(), Some(b'1'..=b'9'))
1773 || !value.bytes().all(|b| b.is_ascii_digit())
1774 {
1775 return Err(corrupt());
1776 }
1777 let version = value.parse::<i32>().map_err(|_| corrupt())?;
1778 if version > requested {
1779 return Err(
1780 "client.schema_downgrade: persisted local schema is newer than the requested schema"
1781 .to_owned(),
1782 );
1783 }
1784 Ok(Some(version))
1785}
1786
1787#[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
1791fn prepare_wasm_replica(path: &str) -> Result<(), String> {
1792 if path.is_empty() || path == ":memory:" {
1793 return Ok(());
1794 }
1795 crate::wasm_vfs::disable_foreign_lock_check()
1796}
1797
1798#[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
1799fn prepare_wasm_replica(_path: &str) -> Result<(), String> {
1800 Ok(())
1801}
1802
1803impl SyncClient {
1804 pub fn new_with_identity(
1805 client_id: Option<String>,
1806 schema_json: &Value,
1807 limits: ClientLimits,
1808 ) -> Result<Self, String> {
1809 let resolved = client_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
1810 let conn = Connection::open_in_memory().map_err(|e| e.to_string())?;
1811 Self::with_connection(resolved, schema_json, limits, conn)
1812 }
1813
1814 pub fn new(
1815 client_id: String,
1816 schema_json: &Value,
1817 limits: ClientLimits,
1818 ) -> Result<Self, String> {
1819 let conn = Connection::open_in_memory().map_err(|e| e.to_string())?;
1820 Self::with_connection(client_id, schema_json, limits, conn)
1821 }
1822
1823 pub fn open_path(
1829 client_id: String,
1830 schema_json: &Value,
1831 limits: ClientLimits,
1832 path: &str,
1833 ) -> Result<Self, String> {
1834 validate_client_limits(&limits)?;
1835 parse_schema_json(schema_json)?;
1836 prepare_wasm_replica(path)?;
1837 let conn = Connection::open(path).map_err(|e| format!("open db {path:?}: {e}"))?;
1838 Self::with_connection(client_id, schema_json, limits, conn)
1839 }
1840
1841 pub fn open_path_with_identity(
1845 client_id: Option<String>,
1846 schema_json: &Value,
1847 limits: ClientLimits,
1848 path: &str,
1849 ) -> Result<Self, String> {
1850 Self::open_path_with_identity_journal(
1851 client_id,
1852 schema_json,
1853 limits,
1854 path,
1855 !cfg!(all(target_arch = "wasm32", target_os = "unknown")),
1856 )
1857 }
1858
1859 fn open_path_with_identity_journal(
1860 client_id: Option<String>,
1861 schema_json: &Value,
1862 limits: ClientLimits,
1863 path: &str,
1864 require_wal: bool,
1865 ) -> Result<Self, String> {
1866 validate_client_limits(&limits)?;
1867 parse_schema_json(schema_json)?;
1870 prepare_wasm_replica(path)?;
1871 let conn = Connection::open(path).map_err(|e| format!("open db {path:?}: {e}"))?;
1872 conn.busy_timeout(std::time::Duration::from_millis(250))
1880 .map_err(|error| format!("configure db {path:?} busy timeout: {error}"))?;
1881 conn.pragma_update(None, "synchronous", "FULL")
1886 .map_err(|error| format!("configure db {path:?} synchronous: {error}"))?;
1887 let client = Self::with_connection_identity(client_id, schema_json, limits, conn)?;
1888 if require_wal {
1892 let journal_mode: String = client
1893 .conn
1894 .pragma_update_and_check(None, "journal_mode", "WAL", |row| row.get(0))
1895 .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
1896 if journal_mode != "wal" {
1897 return Err(
1898 "sync.invalid_request: file-backed client requires WAL journal mode".to_owned(),
1899 );
1900 }
1901 }
1902 Ok(client)
1903 }
1904
1905 pub fn reset_replica(path: &str) -> Result<(), String> {
1919 if path.is_empty() || path == ":memory:" {
1920 return Err("sync.invalid_request: a memory replica has nothing to reset".to_owned());
1921 }
1922 let vfs = unsafe { rusqlite::ffi::sqlite3_vfs_find(std::ptr::null()) };
1926 if vfs.is_null() {
1927 return Err("client.storage_io: no SQLite VFS is registered".to_owned());
1928 }
1929 let delete = unsafe { (*vfs).xDelete }
1930 .ok_or_else(|| "client.storage_io: the SQLite VFS cannot delete files".to_owned())?;
1931 for suffix in ["-wal", "-shm", "-journal", ""] {
1932 let file_name = format!("{path}{suffix}");
1933 let c_name = std::ffi::CString::new(file_name.as_str()).map_err(|_| {
1934 format!("sync.invalid_request: replica path {file_name:?} contains a NUL byte")
1935 })?;
1936 let code = unsafe { delete(vfs, c_name.as_ptr(), 1) };
1939 if code != rusqlite::ffi::SQLITE_OK && code != rusqlite::ffi::SQLITE_IOERR_DELETE_NOENT
1942 {
1943 return Err(format!(
1944 "client.storage_io: deleting replica file {file_name:?} failed with SQLite code {code}"
1945 ));
1946 }
1947 }
1948 Ok(())
1949 }
1950
1951 #[must_use]
1952 pub fn client_id(&self) -> &str {
1953 &self.client_id
1954 }
1955
1956 pub fn reset_client_id(&mut self, transport: &mut dyn Transport) -> Result<String, String> {
1963 self.disconnect_realtime(transport);
1964 let client_id = uuid::Uuid::new_v4().to_string();
1965 self.set_meta(CLIENT_ID_KEY, &client_id)?;
1966 self.client_id.clone_from(&client_id);
1967 self.round_failure = None;
1968 Ok(client_id)
1969 }
1970
1971 pub fn with_connection(
1978 client_id: String,
1979 schema_json: &Value,
1980 limits: ClientLimits,
1981 conn: Connection,
1982 ) -> Result<Self, String> {
1983 Self::with_connection_identity(Some(client_id), schema_json, limits, conn)
1984 }
1985
1986 fn with_connection_identity(
1989 client_id: Option<String>,
1990 schema_json: &Value,
1991 limits: ClientLimits,
1992 conn: Connection,
1993 ) -> Result<Self, String> {
1994 validate_client_limits(&limits)?;
1995 let schema = parse_schema_json(schema_json)?;
1996 validate_authority_reads(&schema, &limits.authority_reads)?;
1997 let previous_version = match limits.previous_version_context {
2000 Some(config) => {
2001 config.validate()?;
2002 Some(config)
2003 }
2004 None => None,
2005 };
2006 let mut client = SyncClient {
2007 #[cfg(feature = "bench-internals")]
2008 benchmark_phases: Recorder::default(),
2009 conn,
2010 schema,
2011 client_id: client_id
2012 .clone()
2013 .unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
2014 limits,
2015 outbox: Shared::default(),
2016 failed_commits: Shared::default(),
2017 retain_failed_commits: false,
2018 conflicts: Shared::default(),
2019 rejections: Shared::default(),
2020 schema_floor: None,
2021 lease_state: None,
2022 stopped: false,
2023 upgrading: false,
2024 sync_needed: false,
2025 realtime_policy: RealtimePolicy::Optional,
2026 realtime_state: RealtimeState::Disconnected,
2027 realtime_reason_code: None,
2028 realtime_retry_delay_ms: None,
2029 presence: HashMap::new(),
2030 now_ms: None,
2031 encryption: crate::values::EncryptionConfig::default(),
2032 security_preflight: false,
2033 security_epoch: 0,
2034 transport_enabled: true,
2035 transport_epoch: 0,
2036 registration_epoch: 0,
2037 previous_version,
2038 insert_sql: RefCell::new(HashMap::new()),
2039 overlay_dirty: OverlayDirty::clean(),
2040 storage_failure: RefCell::new(None),
2041 #[cfg(test)]
2042 overlay_rebuild_count: Cell::new(0),
2043 #[cfg(test)]
2044 acknowledged_replay_count: Cell::new(0),
2045 #[cfg(test)]
2046 outcome_prune_count: Cell::new(0),
2047 #[cfg(test)]
2048 image_chunk_ms: Cell::new(None),
2049 progress: ProgressObserver::default(),
2050 change_queue: VecDeque::new(),
2051 sync_intent_queue: VecDeque::new(),
2052 retry_delay_ms: 250,
2053 round_retry_delay_ms: None,
2054 applied_segments: HashMap::new(),
2055 image_chunk_rows: HashMap::new(),
2056 round_failure: None,
2057 active_round: None,
2058 last_round: None,
2059 last_change: None,
2060 query_failures: Vec::new(),
2061 coalesced: None,
2062 coalesced_failure: None,
2063 };
2064 client
2068 .conn
2069 .set_prepared_statement_cache_capacity(64.max(client.schema.tables.len() * 4));
2070 client
2076 .conn
2077 .execute_batch("BEGIN IMMEDIATE")
2078 .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
2079 let startup = (|| -> Result<(), String> {
2080 let marker = read_local_schema_version(&client.conn, client.schema.version)?;
2083 client.create_bookkeeping_tables()?;
2086 match client.get_meta(CLIENT_ID_KEY)? {
2087 Some(existing) => match client_id {
2088 Some(requested) if existing != requested => {
2089 return Err(format!(
2090 "client.identity_mismatch: this database belongs to {existing:?}; refusing to rebind it to {requested:?}"
2091 ))
2092 }
2093 _ => client.client_id = existing,
2094 },
2095 None => client.set_meta(CLIENT_ID_KEY, &client.client_id)?,
2096 }
2097 client.restore_persisted_state()?;
2098 client.failed_commits = client.load_failed_commits()?.into();
2099 match marker {
2100 None => {
2101 client.create_synced_tables()?;
2102 client.persist_schema_version()?;
2103 client.save_unit_scope_schema()?;
2104 }
2105 Some(version) if version == client.schema.version => {
2106 client.create_synced_tables()?;
2107 set_local_schema_descriptor(&client.conn, &client.schema)
2111 .map_err(|error| Self::sqlite_failure(&client.storage_failure, error))?;
2112 client.save_unit_scope_schema()?;
2113 }
2114 Some(_) => client.run_schema_reset()?,
2115 }
2116 client.reconcile_previous_version_at_boot()?;
2122 client.clear_satisfied_persisted_schema_floor()?;
2123 client.prune_unknown_units(false)?;
2124 client.drop_unencodable_outbox(false, None)?;
2133 if marker == Some(client.schema.version)
2134 && (!client.outbox.is_empty()
2135 || !client.failed_commits.is_empty()
2136 || client.has_acknowledged_rows()?)
2137 {
2138 client.overlay_dirty.set(true);
2142 client.rebuild_overlay()?;
2143 }
2144 client.enqueue_startup_sync_if_needed()?;
2151 Ok(())
2152 })();
2153 match startup {
2154 Ok(()) => match client.conn.execute_batch("COMMIT") {
2155 Ok(()) => {
2159 if !client.security_preflight {
2160 client.drain_pending_evictions()?;
2161 }
2162 Ok(client)
2163 }
2164 Err(error) => {
2165 let failure = Self::sqlite_failure(&client.storage_failure, error);
2166 if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2167 let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2169 }
2170 Err(failure)
2171 }
2172 },
2173 Err(error) => {
2174 if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2175 let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2177 }
2178 Err(error)
2179 }
2180 }
2181 }
2182
2183 pub fn set_now_ms(&mut self, now_ms: i64) {
2186 self.now_ms = Some(now_ms);
2187 }
2188
2189 pub fn set_encryption(&mut self, encryption: crate::values::EncryptionConfig) {
2193 self.encryption = encryption;
2194 }
2195
2196 #[must_use]
2197 pub fn security_lifecycle(&self) -> &'static str {
2198 if self.security_preflight {
2199 "preflight"
2200 } else {
2201 "active"
2202 }
2203 }
2204
2205 #[must_use]
2206 pub fn security_preflight(&self) -> bool {
2207 self.security_preflight
2208 }
2209
2210 pub fn set_transport_enabled(&mut self, transport: &mut dyn Transport, enabled: bool) {
2212 if self.transport_enabled != enabled {
2213 self.transport_enabled = enabled;
2214 self.transport_epoch = self.transport_epoch.wrapping_add(1);
2215 self.sync_intent_queue.clear();
2216 self.sync_intent_queue
2217 .push_back(if enabled && !self.security_preflight {
2218 SyncIntent::Interactive
2219 } else {
2220 SyncIntent::None
2221 });
2222 }
2223 if !enabled && self.active_round.is_none() {
2225 self.disconnect_realtime(transport);
2226 }
2227 }
2228
2229 pub fn transport_enabled(&self) -> bool {
2230 self.transport_enabled
2231 }
2232
2233 pub fn begin_security_preflight(&mut self) -> Result<(), String> {
2240 let entering = !self.security_preflight;
2241 self.seal_security_on_teardown();
2242 self.set_meta(SECURITY_PREFLIGHT_PENDING_KEY, "1")?;
2245 if entering {
2246 self.emit_status_batch()?;
2247 }
2248 Ok(())
2249 }
2250
2251 fn emit_status_batch(&mut self) -> Result<(), String> {
2253 self.begin_observation("syncular_status")?;
2254 let batch = ChangeAccumulator {
2255 status: true,
2256 ..ChangeAccumulator::default()
2257 };
2258 self.finish_observation("syncular_status", batch)
2259 .inspect_err(|_| self.rollback_observation("syncular_status"))
2260 }
2261
2262 pub fn seal_security_on_teardown(&mut self) {
2272 self.cancel_sync_round();
2273 self.security_preflight = true;
2274 self.security_epoch = self.security_epoch.wrapping_add(1);
2275 self.encryption = crate::values::EncryptionConfig::default();
2276 self.sync_intent_queue.clear();
2277 }
2278
2279 pub fn activate_security(
2281 &mut self,
2282 encryption: crate::values::EncryptionConfig,
2283 ) -> Result<(), String> {
2284 if !self.security_preflight {
2285 return Err(
2286 "sync.invalid_request: activateSecurity requires security preflight".to_owned(),
2287 );
2288 }
2289 self.drain_pending_evictions()?;
2291 self.enqueue_startup_sync_if_needed()?;
2292 self.delete_meta(SECURITY_PREFLIGHT_PENDING_KEY)?;
2293 self.encryption = encryption;
2294 self.security_preflight = false;
2295 self.reveal_sealed_rows()
2297 .map_err(|error| format!("{}: {}", error.code, error.message))?;
2298 self.emit_status_batch()
2299 }
2300
2301 fn clock_now_ms(&self) -> i64 {
2302 self.now_ms.unwrap_or_else(crate::wall_clock_ms)
2303 }
2304
2305 fn create_bookkeeping_tables(&self) -> Result<(), String> {
2306 let exists = |name: &str| {
2307 self.conn
2308 .query_row(
2309 "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?1)",
2310 [name],
2311 |row| row.get::<_, bool>(0),
2312 )
2313 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2314 };
2315 let outbox_existed = exists("_syncular_outbox")?;
2316 self.conn
2318 .execute_batch(
2319 "CREATE TABLE IF NOT EXISTS _syncular_outbox (
2320 seq INTEGER PRIMARY KEY AUTOINCREMENT,
2321 commit_id TEXT NOT NULL UNIQUE, ops_json TEXT NOT NULL);
2322 CREATE TABLE IF NOT EXISTS _syncular_row_deliveries (
2323 tbl TEXT NOT NULL, id TEXT NOT NULL, commit_seq INTEGER NOT NULL, PRIMARY KEY(tbl,id));
2324 CREATE TABLE IF NOT EXISTS _syncular_acked_rows (
2325 commit_id TEXT NOT NULL, idx INTEGER NOT NULL, tbl TEXT NOT NULL, id TEXT NOT NULL,
2326 commit_seq INTEGER NOT NULL, op_json TEXT NOT NULL, intent_json TEXT,
2327 PRIMARY KEY(commit_id, idx));
2328 CREATE INDEX IF NOT EXISTS _syncular_acked_rows_row
2329 ON _syncular_acked_rows(tbl, id);
2330 CREATE TABLE IF NOT EXISTS _syncular_failed_commits (
2331 seq INTEGER PRIMARY KEY AUTOINCREMENT, client_commit_id TEXT NOT NULL UNIQUE,
2332 operations_json TEXT NOT NULL, initial_json TEXT NOT NULL);
2333 CREATE TABLE IF NOT EXISTS _syncular_commit_outcomes (
2334 seq INTEGER PRIMARY KEY AUTOINCREMENT,
2335 client_commit_id TEXT NOT NULL UNIQUE,
2336 status TEXT NOT NULL CHECK(status IN ('applied', 'cached', 'conflict', 'rejected')),
2337 recorded_at_ms INTEGER NOT NULL,
2338 results_json TEXT NOT NULL,
2339 operations_json TEXT,
2340 resolution TEXT NOT NULL DEFAULT 'active'
2341 CHECK(resolution IN ('active', 'resolved_keep_server', 'superseded', 'dismissed')),
2342 resolved_at_ms INTEGER,
2343 replacement_client_commit_id TEXT);
2344 CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq
2345 ON _syncular_commit_outcomes(resolution, seq);
2346 CREATE TABLE IF NOT EXISTS _syncular_units (
2347 id TEXT PRIMARY KEY, scopes TEXT NOT NULL,
2348 explicit INTEGER NOT NULL DEFAULT 0,
2349 status TEXT NOT NULL DEFAULT 'active', reason_code TEXT,
2350 cursor INTEGER DEFAULT -1, bootstrap_state TEXT,
2351 seeded TEXT NOT NULL DEFAULT '[]', echo TEXT);
2352 CREATE TABLE IF NOT EXISTS _syncular_meta (
2353 key TEXT PRIMARY KEY, value TEXT NOT NULL);
2354 CREATE TABLE IF NOT EXISTS _syncular_windows (
2355 base TEXT NOT NULL, unit TEXT NOT NULL, sub_id TEXT NOT NULL,
2356 PRIMARY KEY (base, unit));
2357 CREATE INDEX IF NOT EXISTS _syncular_windows_unit ON _syncular_windows(sub_id);
2358 CREATE TABLE IF NOT EXISTS _syncular_pending_evictions (
2359 unit_id TEXT NOT NULL, tbl TEXT NOT NULL,
2360 effective_scopes TEXT NOT NULL, PRIMARY KEY (unit_id, tbl));
2361 CREATE TABLE IF NOT EXISTS _syncular_blob_commit_refs(
2362 commit_id TEXT NOT NULL, blob_id TEXT NOT NULL,
2363 PRIMARY KEY(commit_id, blob_id));
2364 CREATE INDEX IF NOT EXISTS _syncular_blob_commit_refs_body
2365 ON _syncular_blob_commit_refs(blob_id);",
2366 )
2367 .map_err(|e| e.to_string())?;
2368 let _ = self
2371 .conn
2372 .execute_batch("ALTER TABLE _syncular_commit_outcomes ADD COLUMN operations_json TEXT");
2373 if self.get_meta(LOCAL_REVISION_KEY)?.is_none() {
2374 self.set_meta(LOCAL_REVISION_KEY, "0")?;
2375 }
2376 if !outbox_existed || self.get_meta(OUTBOX_ID_KEY)?.is_none() {
2379 self.set_meta(OUTBOX_ID_KEY, &uuid::Uuid::new_v4().to_string())?;
2380 }
2381 if exists("_syncular_window_pending_evict")? {
2386 let invalid: bool = self
2387 .conn
2388 .query_row(
2389 "SELECT EXISTS(SELECT 1 FROM _syncular_window_pending_evict
2390 WHERE NOT json_valid(effective_scopes)
2391 OR json_type(effective_scopes) <> 'object'
2392 OR EXISTS(SELECT 1 FROM json_each(effective_scopes)
2393 WHERE type <> 'array'
2394 OR EXISTS(SELECT 1 FROM json_each(value) AS v
2395 WHERE v.type <> 'text')))",
2396 [],
2397 |row| row.get(0),
2398 )
2399 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2400 if invalid {
2401 return Err(
2402 "sync.local_corrupt: a version 3 pending eviction cannot be upgraded"
2403 .to_owned(),
2404 );
2405 }
2406 self.conn
2407 .execute_batch(
2408 "INSERT OR REPLACE INTO _syncular_pending_evictions
2409 SELECT sub_id, tbl, effective_scopes FROM _syncular_window_pending_evict;
2410 DROP TABLE _syncular_window_pending_evict;
2411 DROP TABLE IF EXISTS _syncular_subscriptions;
2412 DELETE FROM _syncular_windows;",
2413 )
2414 .and_then(|()| reset_units(&self.conn))
2415 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2416 }
2417 if self.schema_has_blobs() {
2420 if exists("_syncular_blobs")? {
2421 let mut statement = self
2422 .conn
2423 .prepare("PRAGMA table_info(_syncular_blobs)")
2424 .map_err(|e| e.to_string())?;
2425 let mut columns = statement
2426 .query_map([], |row| row.get::<_, String>(1))
2427 .map_err(|e| e.to_string())?
2428 .collect::<Result<Vec<_>, _>>()
2429 .map_err(|e| e.to_string())?;
2430 columns.sort();
2431 let mut expected = vec![
2432 "blob_id",
2433 "byte_length",
2434 "bytes",
2435 "created_at_ms",
2436 "media_type",
2437 ];
2438 expected.sort_unstable();
2439 if columns != expected {
2440 return Err(
2441 "sync.schema_mismatch: Local blob schema is incompatible".to_owned()
2442 );
2443 }
2444 } else {
2445 self.conn
2446 .execute_batch(
2447 "CREATE TABLE _syncular_blobs(
2448 blob_id TEXT PRIMARY KEY,
2449 bytes BLOB NOT NULL,
2450 byte_length INTEGER NOT NULL,
2451 media_type TEXT,
2452 created_at_ms INTEGER NOT NULL);",
2453 )
2454 .map_err(|e| e.to_string())?;
2455 }
2456 self.conn
2457 .execute_batch(
2458 "CREATE TABLE IF NOT EXISTS _syncular_blob_uploads(
2459 blob_id TEXT PRIMARY KEY,
2460 media_type TEXT,
2461 created_at_ms INTEGER NOT NULL);",
2462 )
2463 .map_err(|e| e.to_string())?;
2464 }
2465 Ok(())
2466 }
2467
2468 fn schema_has_blobs(&self) -> bool {
2470 self.schema
2471 .tables
2472 .iter()
2473 .any(|t| t.columns.iter().any(|c| c.ty == ColumnType::BlobRef))
2474 }
2475
2476 fn get_meta(&self, key: &str) -> Result<Option<String>, String> {
2479 meta_get(&self.conn, key)
2480 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2481 }
2482
2483 fn persist_schema_version(&self) -> Result<(), String> {
2486 self.conn
2487 .execute(
2488 "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
2489 rusqlite::params![LOCAL_SCHEMA_VERSION_KEY, self.schema.version.to_string()],
2490 )
2491 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2492 set_local_schema_descriptor(&self.conn, &self.schema)
2493 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2494 }
2495
2496 pub(crate) fn set_meta(&self, key: &str, value: &str) -> Result<(), String> {
2497 meta_set(&self.conn, key, value)
2498 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2499 }
2500
2501 fn delete_meta(&self, key: &str) -> Result<(), String> {
2502 meta_delete(&self.conn, key)
2503 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2504 }
2505
2506 fn load_outbox(&self) -> Result<Vec<Arc<OutboxCommit>>, String> {
2508 let mut stmt = self
2509 .conn
2510 .prepare("SELECT commit_id, ops_json FROM _syncular_outbox ORDER BY seq ASC")
2511 .map_err(|error| error.to_string())?;
2512 let rows = stmt
2513 .query_map([], |row| {
2514 Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
2515 })
2516 .map_err(|error| error.to_string())?;
2517 let mut commits = Vec::new();
2518 for row in rows {
2519 let (client_commit_id, raw) = row.map_err(|error| error.to_string())?;
2520 let entries: Vec<Value> = serde_json::from_str(&raw).map_err(|error| {
2521 format!("invalid persisted outbox {client_commit_id:?}: {error}")
2522 })?;
2523 let mut ops = Vec::with_capacity(entries.len());
2524 for entry in entries {
2525 let op = entry.get("op").and_then(Value::as_str).unwrap_or("delete");
2526 ops.push(OutboxOp {
2527 upsert: op == "upsert",
2528 table: entry
2529 .get("table")
2530 .and_then(Value::as_str)
2531 .ok_or_else(|| "persisted outbox operation missing table".to_owned())?
2532 .to_owned(),
2533 row_id: entry
2534 .get("rowId")
2535 .and_then(Value::as_str)
2536 .ok_or_else(|| "persisted outbox operation missing rowId".to_owned())?
2537 .to_owned(),
2538 base_version: entry.get("baseVersion").and_then(Value::as_i64),
2539 values: entry.get("values").and_then(Value::as_object).cloned(),
2542 insert: entry.get("insert") == Some(&Value::Bool(true)),
2543 });
2544 }
2545 commits.push(Arc::new(OutboxCommit {
2546 client_commit_id,
2547 ops,
2548 }));
2549 }
2550 Ok(commits)
2551 }
2552
2553 fn restore_persisted_state(&mut self) -> Result<(), String> {
2554 self.outbox = self.load_outbox()?.into();
2555
2556 self.prune_commit_outcomes()?;
2557 let active = self.commit_outcomes(CommitOutcomeQuery {
2558 active_only: true,
2559 ..CommitOutcomeQuery::default()
2560 })?;
2561 self.conflicts = active
2562 .iter()
2563 .flat_map(|outcome| outcome.results.iter())
2564 .filter_map(|result| match result {
2565 CommitOperationOutcome::Conflict { conflict } => Some(conflict.clone()),
2566 _ => None,
2567 })
2568 .collect::<Vec<_>>()
2569 .into();
2570 self.rejections = active
2571 .iter()
2572 .flat_map(|outcome| outcome.results.iter())
2573 .filter_map(|result| match result {
2574 CommitOperationOutcome::Error { rejection } => Some(rejection.clone()),
2575 _ => None,
2576 })
2577 .collect::<Vec<_>>()
2578 .into();
2579
2580 self.lease_state = self
2581 .get_meta(LEASE_STATE_KEY)?
2582 .map(|raw| serde_json::from_str(&raw))
2583 .transpose()
2584 .map_err(|error| format!("invalid persisted lease state: {error}"))?;
2585 self.schema_floor = self
2586 .get_meta(SCHEMA_FLOOR_KEY)?
2587 .map(|raw| serde_json::from_str(&raw))
2588 .transpose()
2589 .map_err(|error| format!("invalid persisted schema floor: {error}"))?;
2590 self.stopped = self.schema_floor.is_some();
2591 if self.get_meta(SECURITY_PREFLIGHT_PENDING_KEY)?.as_deref() == Some("1") {
2594 self.security_preflight = true;
2595 }
2596 Ok(())
2597 }
2598
2599 fn save_unit_scope_schema(&self) -> Result<(), String> {
2600 let declarations: BTreeMap<_, BTreeMap<_, _>> = self
2601 .schema
2602 .tables
2603 .iter()
2604 .map(|table| {
2605 (
2606 table.name.clone(),
2607 table
2608 .scope_variables
2609 .iter()
2610 .map(|scope| {
2611 (
2612 scope.variable.clone(),
2613 [scope.prefix.clone(), scope.column.clone()],
2614 )
2615 })
2616 .collect(),
2617 )
2618 })
2619 .collect();
2620 self.set_meta(
2621 "subscriptionScopeSchema",
2622 &serde_json::to_string(&declarations).expect("scope schema serialization"),
2623 )
2624 }
2625
2626 fn prune_unknown_units(&mut self, bump: bool) -> Result<(), String> {
2631 let previous: Option<BTreeMap<String, BTreeMap<String, [String; 2]>>> = if bump {
2632 self.get_meta("subscriptionScopeSchema")?
2633 .map(|raw| serde_json::from_str(&raw))
2634 .transpose()
2635 .map_err(|_| "sync.local_corrupt: invalid persisted scope schema".to_owned())?
2636 } else {
2637 None
2638 };
2639 let unchanged = |name: &str, variables: &[&String]| {
2644 let (Some(old), Some(table)) = (
2645 previous.as_ref().and_then(|previous| previous.get(name)),
2646 self.schema.table(name),
2647 ) else {
2648 return false;
2649 };
2650 variables.iter().all(|variable| {
2651 table
2652 .scope_variables
2653 .iter()
2654 .find(|scope| &scope.variable == *variable)
2655 .is_some_and(|scope| {
2656 old.get(*variable) == Some(&[scope.prefix.clone(), scope.column.clone()])
2657 })
2658 })
2659 };
2660 let compatible = |scopes: &UnitScopes| {
2661 if !self.schema.tables.iter().any(|table| covers(table, scopes)) {
2662 return false;
2663 }
2664 if !bump {
2665 return true;
2666 }
2667 let Some(previous) = &previous else {
2668 return false;
2669 };
2670 previous.iter().all(|(name, old)| {
2671 !scopes.keys().all(|variable| old.contains_key(variable))
2672 || unchanged(name, &scopes.keys().collect::<Vec<_>>())
2673 })
2674 };
2675 let mut stale: BTreeSet<String> = self
2676 .stored(load_units(&self.conn))?
2677 .into_iter()
2678 .filter(|unit| !compatible(&unit.scopes))
2679 .map(|unit| unit.id)
2680 .collect();
2681 for (id, table, effective) in self.load_pending_evictions()? {
2686 if self.schema.table(&table).is_none()
2687 || (bump
2688 && !unchanged(
2689 &table,
2690 &effective
2691 .iter()
2692 .map(|(variable, _)| variable)
2693 .collect::<Vec<_>>(),
2694 ))
2695 {
2696 stale.insert(id);
2697 }
2698 }
2699 for id in &stale {
2700 for sql in [
2701 "DELETE FROM _syncular_windows WHERE sub_id = ?1",
2702 "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
2703 "DELETE FROM _syncular_units WHERE id = ?1",
2704 ] {
2705 self.conn
2706 .execute(sql, rusqlite::params![id])
2707 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2708 }
2709 }
2710 Ok(())
2711 }
2712
2713 pub fn local_revision(&self) -> Result<u64, String> {
2714 Ok(self
2715 .get_meta(LOCAL_REVISION_KEY)?
2716 .and_then(|value| value.parse().ok())
2717 .unwrap_or(0))
2718 }
2719
2720 pub fn snapshot_read(
2726 &mut self,
2727 request: &SnapshotReadRequest<'_>,
2728 owner: Option<QueryOwner<'_>>,
2729 ) -> Result<SnapshotRead, QueryReadFailure> {
2730 let result = snapshot_read_connection(&self.conn, request);
2731 if let Some(owner) = owner {
2732 self.record_query_read(owner, result.as_ref().err());
2733 }
2734 result
2735 }
2736
2737 #[must_use]
2738 pub fn status_snapshot(&self) -> SyncStatusSnapshot {
2739 SyncStatusSnapshot {
2740 current_schema_version: self.schema.version,
2741 outbox: self.outbox.len(),
2742 upgrading: self.upgrading,
2743 lease_state: self.lease_state.clone(),
2744 schema_floor: self.schema_floor.clone(),
2745 sync_needed: self.sync_needed,
2746 previous_version_context: self.previous_version_status(),
2747 security_lifecycle: self.security_lifecycle(),
2748 }
2749 }
2750
2751 fn previous_version_status(&self) -> PreviousVersionStatus {
2754 let Some(replica_path) = self.previous_version_replica_path() else {
2755 return PreviousVersionStatus {
2756 present: false,
2757 created_at_ms: None,
2758 };
2759 };
2760 match crate::previous_version::read_previous_version_record(&replica_path) {
2761 Ok(Some(record)) => PreviousVersionStatus {
2762 present: true,
2763 created_at_ms: Some(record.created_at_ms),
2764 },
2765 _ => PreviousVersionStatus {
2766 present: std::path::Path::new(
2767 &crate::previous_version::previous_version_container_path(&replica_path),
2768 )
2769 .exists(),
2770 created_at_ms: None,
2771 },
2772 }
2773 }
2774
2775 pub fn previous_version_snapshot(
2781 &self,
2782 spec: &PreviousVersionReadSpec,
2783 ) -> Result<PreviousVersionSnapshot, String> {
2784 let now_ms = self.clock_now_ms();
2785 crate::previous_version::previous_version_snapshot(
2786 &self.conn,
2787 self.previous_version_replica_path().as_deref(),
2788 self.previous_version.as_ref(),
2789 PreviousVersionLifecycle {
2790 lease_inactive: self.previous_version_lease_inactive(now_ms),
2791 scope_revoked: self
2792 .stored(load_units(&self.conn))?
2793 .iter()
2794 .any(|unit| unit.status == UnitStatus::Revoked),
2795 coverage_complete: self.previous_version_coverage_complete()?,
2796 },
2797 now_ms,
2798 self.schema.version,
2799 spec,
2800 )
2801 }
2802
2803 pub fn previous_version_audit(
2805 &self,
2806 ) -> Result<Option<crate::previous_version::PreviousVersionAudit>, String> {
2807 crate::previous_version::stored_previous_version_audit(&self.conn)
2808 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2809 }
2810
2811 pub fn previous_version_discard(
2815 &self,
2816 ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2817 self.drop_previous_version()
2818 }
2819
2820 fn drop_previous_version(
2821 &self,
2822 ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2823 let Some(replica_path) = self.previous_version_replica_path() else {
2824 return Ok(crate::previous_version::PreviousVersionDiscardOutcome {
2825 present: false,
2826 discarded: false,
2827 });
2828 };
2829 crate::previous_version::discard_previous_version(&self.conn, &replica_path)
2830 }
2831
2832 fn previous_version_lease_inactive(&self, now_ms: i64) -> bool {
2834 let Some(lease) = &self.lease_state else {
2835 return false;
2836 };
2837 if lease.error_code.is_some() {
2838 return true;
2839 }
2840 lease.expires_at_ms.is_some_and(|expires| expires <= now_ms)
2841 }
2842
2843 fn previous_version_coverage_complete(&self) -> Result<bool, String> {
2847 let units = self.stored(load_units(&self.conn))?;
2848 let mut active = units
2849 .iter()
2850 .filter(|unit| unit.status == UnitStatus::Active)
2851 .peekable();
2852 Ok(active.peek().is_some() && !active.any(UnitRecord::bootstrapping))
2853 }
2854
2855 fn previous_version_lifetime_check(&self) {
2859 let Some(config) = self.previous_version.filter(|config| config.enabled) else {
2860 return;
2861 };
2862 let now_ms = self.clock_now_ms();
2863 if self.previous_version_lease_inactive(now_ms) {
2864 let _ = self.drop_previous_version();
2865 return;
2866 }
2867 let Some(replica_path) = self.previous_version_replica_path() else {
2868 return;
2869 };
2870 let Ok(Some(record)) = crate::previous_version::read_previous_version_record(&replica_path)
2871 else {
2872 return;
2873 };
2874 let Ok(units) = load_units(&self.conn) else {
2875 return;
2876 };
2877 if units.iter().any(|unit| unit.status == UnitStatus::Revoked) {
2878 let _ = self.drop_previous_version();
2879 return;
2880 }
2881 if now_ms - record.created_at_ms > config.max_age_ms {
2882 let _ = self.drop_previous_version();
2883 return;
2884 }
2885 if self.previous_version_coverage_complete() == Ok(true) {
2886 let _ = self.drop_previous_version();
2887 }
2888 }
2889
2890 pub fn diagnostics_snapshot(&self) -> Result<ClientDiagnosticsSnapshot, String> {
2891 let registered = self.stored(load_units(&self.conn))?;
2892 let (local_revision, replica_cursor): (Option<String>, Option<String>) = self.stored(
2895 self.conn
2896 .prepare_cached(
2897 "SELECT (SELECT value FROM _syncular_meta WHERE key = ?1),
2898 (SELECT value FROM _syncular_meta WHERE key = ?2)",
2899 )
2900 .and_then(|mut statement| {
2901 statement.query_row([LOCAL_REVISION_KEY, REPLICA_CURSOR_KEY], |row| {
2902 Ok((row.get(0)?, row.get(1)?))
2903 })
2904 }),
2905 )?;
2906 let mut units = DiagnosticUnits::default();
2907 for unit in ®istered {
2908 *match unit.status {
2909 UnitStatus::Revoked => &mut units.revoked,
2910 UnitStatus::Failed => &mut units.failed,
2911 UnitStatus::Active if !unit.bootstrapping() => &mut units.complete,
2912 UnitStatus::Active
2913 if unit.reason_code.as_deref() == Some("sync.cursor_expired") =>
2914 {
2915 &mut units.reset
2916 }
2917 UnitStatus::Active => &mut units.bootstrapping,
2918 } += 1;
2919 }
2920 units.reason_codes = registered
2921 .iter()
2922 .filter_map(|unit| unit.reason_code.as_deref().map(Self::diagnostic_code))
2923 .collect::<BTreeSet<_>>()
2924 .into_iter()
2925 .collect();
2926 let captured_at_ms = self.clock_now_ms();
2927 let lease = if let Some(error_code) = self
2928 .lease_state
2929 .as_ref()
2930 .and_then(|state| state.error_code.clone())
2931 {
2932 ClientDiagnosticsLease {
2933 state: "stopped".to_owned(),
2934 expires_at_ms: self
2935 .lease_state
2936 .as_ref()
2937 .and_then(|state| state.expires_at_ms),
2938 error_code: Some(Self::diagnostic_code(&error_code)),
2939 }
2940 } else if let Some(expires_at_ms) = self
2941 .lease_state
2942 .as_ref()
2943 .and_then(|state| state.expires_at_ms)
2944 {
2945 ClientDiagnosticsLease {
2946 state: if expires_at_ms <= captured_at_ms {
2947 "expired".to_owned()
2948 } else {
2949 "active".to_owned()
2950 },
2951 expires_at_ms: Some(expires_at_ms),
2952 error_code: None,
2953 }
2954 } else {
2955 ClientDiagnosticsLease {
2956 state: "none".to_owned(),
2957 expires_at_ms: None,
2958 error_code: None,
2959 }
2960 };
2961 let connectivity = match self.last_round.as_ref() {
2962 _ if !self.transport_enabled && self.active_round.is_none() => "offline",
2963 Some(round) if round.status == "succeeded" => "online",
2964 Some(round)
2965 if round.status == "failed"
2966 && matches!(
2967 round.cause_kind,
2968 Some(
2969 crate::TransportCauseKind::Network | crate::TransportCauseKind::Connect
2970 )
2971 ) =>
2972 {
2973 "offline"
2974 }
2975 Some(round) if round.status == "failed" && round.http_status.is_some() => "online",
2976 _ => "unknown",
2977 };
2978 Ok(ClientDiagnosticsSnapshot {
2979 version: CLIENT_DIAGNOSTICS_VERSION,
2980 captured_at_ms,
2981 host: ClientDiagnosticsHost {
2982 kind: "direct".to_owned(),
2983 role: "single".to_owned(),
2984 connectivity: connectivity.to_owned(),
2985 realtime: self.realtime_state,
2986 realtime_policy: self.realtime_policy,
2987 realtime_reason_code: self.realtime_reason_code.clone(),
2988 realtime_retry_delay_ms: self.realtime_retry_delay_ms,
2989 },
2990 security_lifecycle: self.security_lifecycle().to_owned(),
2991 schema: ClientDiagnosticsSchema {
2992 current_version: self.schema.version,
2993 upgrading: self.upgrading,
2994 required_version: self
2995 .schema_floor
2996 .as_ref()
2997 .and_then(|floor| floor.required_schema_version),
2998 latest_version: self
2999 .schema_floor
3000 .as_ref()
3001 .and_then(|floor| floor.latest_schema_version),
3002 },
3003 replica: ClientDiagnosticsReplica {
3004 local_revision: local_revision
3005 .and_then(|value| value.parse::<u64>().ok())
3006 .unwrap_or(0)
3007 .to_string(),
3008 sync_needed: self.sync_needed,
3009 pending_outbox: self.outbox.len(),
3010 },
3011 lease,
3012 active_units: registered
3013 .iter()
3014 .filter(|unit| unit.status == UnitStatus::Active)
3015 .count(),
3016 units,
3017 replica_cursor: replica_cursor.map_or(Ok(-1), |raw| {
3018 raw.parse()
3019 .map_err(|_| "sync.local_corrupt: persisted unit state is invalid".to_owned())
3020 })?,
3021 last_round: self.last_round.clone(),
3022 last_change: self.last_change.clone(),
3023 storage: self.diagnostics_storage(),
3024 query_failures: self.query_failures.clone(),
3025 })
3026 }
3027
3028 fn diagnostics_storage(&self) -> ClientDiagnosticsStorage {
3029 let read = || -> Result<ClientDiagnosticsStorage, rusqlite::Error> {
3030 let page_count: i64 = self
3031 .conn
3032 .query_row("PRAGMA page_count", [], |row| row.get(0))?;
3033 let page_size: i64 = self
3034 .conn
3035 .query_row("PRAGMA page_size", [], |row| row.get(0))?;
3036 let (outbox_bytes, outcome_entries, outcome_bytes): (i64, i64, i64) = self
3039 .conn
3040 .prepare_cached(
3041 "SELECT (SELECT COALESCE(SUM(LENGTH(ops_json)), 0) FROM _syncular_outbox),
3042 COUNT(*), COALESCE(SUM(LENGTH(results_json) + COALESCE(LENGTH(operations_json), 0)), 0)
3043 FROM _syncular_commit_outcomes",
3044 )?
3045 .query_row([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?;
3046 let blob_bytes = if self.schema_has_blobs() {
3047 self.conn
3048 .prepare_cached("SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs")?
3049 .query_row([], |row| row.get(0))?
3050 } else {
3051 0
3052 };
3053 let pressure = self
3054 .limits
3055 .blob_cache_max_bytes
3056 .is_some_and(|limit| blob_bytes > limit);
3057 Ok(ClientDiagnosticsStorage {
3058 status: if pressure { "pressure" } else { "healthy" }.to_owned(),
3059 database_bytes_approx: Some(page_count.saturating_mul(page_size).max(0)),
3060 pending_outbox_bytes_approx: Some(outbox_bytes.max(0)),
3061 retained_outcome_bytes_approx: Some(outcome_bytes.max(0)),
3062 retained_outcome_entries: Some(outcome_entries.max(0)),
3063 blob_cache_bytes_approx: Some(blob_bytes.max(0)),
3064 pressure_reason_code: pressure.then(|| "client.blob_cache_over_limit".to_owned()),
3065 })
3066 };
3067 read().unwrap_or_else(|_| ClientDiagnosticsStorage {
3068 status: "unreadable".to_owned(),
3069 database_bytes_approx: None,
3070 pending_outbox_bytes_approx: None,
3071 retained_outcome_bytes_approx: None,
3072 retained_outcome_entries: None,
3073 blob_cache_bytes_approx: None,
3074 pressure_reason_code: None,
3075 })
3076 }
3077
3078 pub fn drain_change_batches(&mut self) -> Vec<ClientChangeBatch> {
3079 self.change_queue.drain(..).collect()
3080 }
3081
3082 pub fn drain_sync_intents(&mut self) -> Vec<SyncIntent> {
3083 let intents = self.sync_intent_queue.drain(..).collect();
3084 if self.transport_enabled {
3085 intents
3086 } else {
3087 vec![SyncIntent::None]
3088 }
3089 }
3090
3091 fn schedule_background_retry(&mut self) -> u64 {
3092 let delay_ms = self.retry_delay_ms;
3093 self.sync_intent_queue
3094 .push_back(SyncIntent::Background { delay_ms });
3095 self.retry_delay_ms = (self.retry_delay_ms * 2).min(30_000);
3096 self.round_retry_delay_ms = Some(delay_ms);
3097 delay_ms
3098 }
3099
3100 fn reset_background_retry(&mut self) {
3101 self.retry_delay_ms = 250;
3102 }
3103
3104 fn retryable_transport_code(code: &str) -> bool {
3105 code == "transport.failed"
3106 || code == "transport.timeout"
3107 || code == "transport.unavailable"
3108 || code == "sync.transport_failed"
3109 }
3110
3111 fn unreachable_transport(details: &Option<serde_json::Value>) -> bool {
3116 matches!(
3117 details
3118 .as_ref()
3119 .and_then(|details| details.get("causeKind"))
3120 .and_then(serde_json::Value::as_str),
3121 Some("connect" | "network")
3122 )
3123 }
3124
3125 fn segment_fetch_failed(&mut self, error: TransportError) -> SectionError {
3130 if ssp2::model::valid_round_failure_code(&error.code) {
3131 self.round_failure = Some(error.code.clone());
3132 }
3133 SectionError::Transport(error)
3134 }
3135
3136 fn retryable_failure_code(code: &str) -> bool {
3141 Self::retryable_transport_code(code)
3142 || matches!(
3143 code,
3144 "sync.auth_required"
3145 | "sync.auth_lease_required"
3146 | "sync.auth_lease_revoked"
3147 | "sync.internal_error"
3148 | "sync.idempotency_cache_miss"
3149 | "sync.schema_not_ready"
3150 | "sync.segment_expired"
3151 | "sync.rate_limited"
3152 | "sync.websocket_connection_limit"
3153 )
3154 }
3155
3156 fn diagnostic_code(code: &str) -> String {
3157 let valid = !code.is_empty()
3158 && code.len() <= 96
3159 && code.contains('.')
3160 && code
3161 .bytes()
3162 .next()
3163 .is_some_and(|byte| byte.is_ascii_lowercase())
3164 && code.bytes().all(|byte| {
3165 byte.is_ascii_lowercase()
3166 || byte.is_ascii_digit()
3167 || matches!(byte, b'.' | b'_' | b'-')
3168 });
3169 if valid {
3170 code.to_owned()
3171 } else {
3172 "client.unknown_failure".to_owned()
3173 }
3174 }
3175
3176 fn set_sync_needed(&mut self, value: bool, interactive: bool) {
3177 if self.sync_needed != value {
3178 if self.begin_observation("syncular_status").is_ok() {
3179 self.sync_needed = value;
3180 let batch = ChangeAccumulator {
3181 status: true,
3182 ..ChangeAccumulator::default()
3183 };
3184 if self.finish_observation("syncular_status", batch).is_err() {
3185 self.rollback_observation("syncular_status");
3186 }
3187 } else {
3188 self.sync_needed = value;
3189 }
3190 }
3191 if value && interactive {
3192 self.sync_intent_queue.push_back(SyncIntent::Interactive);
3193 }
3194 }
3195
3196 fn stored<T>(&self, result: rusqlite::Result<T>) -> Result<T, String> {
3199 result.map_err(|error| match error {
3200 rusqlite::Error::FromSqlConversionFailure(..) => {
3201 "sync.local_corrupt: persisted unit state is invalid".to_owned()
3202 }
3203 error => Self::sqlite_failure(&self.storage_failure, error),
3204 })
3205 }
3206
3207 fn sqlite_failure(
3208 storage_failure: &RefCell<Option<QueryReadFailure>>,
3209 error: rusqlite::Error,
3210 ) -> String {
3211 let message = error.to_string();
3212 let failure = QueryReadFailure::from(error);
3213 let code = failure.code;
3214 if code.is_some() && storage_failure.borrow().is_none() {
3215 *storage_failure.borrow_mut() = Some(failure);
3216 }
3217 match code {
3218 Some(code) => format!("{code}: {message}"),
3219 None => message,
3220 }
3221 }
3222
3223 fn begin_observation(&self, name: &str) -> Result<(), String> {
3224 if let Some(failure) = &self.coalesced_failure {
3225 return Err(failure.clone());
3226 }
3227 if self.coalesced.is_some() && self.conn.is_autocommit() {
3230 return Err("the coalesced apply transaction was rolled back".to_owned());
3231 }
3232 self.conn
3233 .execute_batch(&format!("SAVEPOINT {name}"))
3234 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3235 }
3236
3237 fn begin_coalesced_apply(&mut self) -> Result<(), String> {
3240 if self.coalesced.is_some() || !self.conn.is_autocommit() {
3241 return Ok(());
3242 }
3243 self.conn
3244 .execute_batch("BEGIN")
3245 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3246 self.coalesced = Some(CoalescedApply {
3247 rows: 0,
3248 rollback: self.capture(),
3249 });
3250 Ok(())
3251 }
3252
3253 fn capture(&self) -> Rollback {
3254 Rollback {
3255 outbox: self.outbox.clone(),
3256 failed_commits: self.failed_commits.clone(),
3257 conflicts: self.conflicts.clone(),
3258 rejections: self.rejections.clone(),
3259 schema_floor: self.schema_floor.clone(),
3260 lease_state: self.lease_state.clone(),
3261 stopped: self.stopped,
3262 upgrading: self.upgrading,
3263 sync_needed: self.sync_needed,
3264 active_round: self.active_round,
3265 overlay_dirty: self.overlay_dirty.snapshot(),
3266 change_queue: self.change_queue.len(),
3267 sync_intent_queue: self.sync_intent_queue.len(),
3268 last_change: self.last_change.clone(),
3269 }
3270 }
3271
3272 fn restore(&mut self, rollback: Rollback) {
3273 self.outbox = rollback.outbox;
3274 self.failed_commits = rollback.failed_commits;
3275 self.conflicts = rollback.conflicts;
3276 self.rejections = rollback.rejections;
3277 self.schema_floor = rollback.schema_floor;
3278 self.lease_state = rollback.lease_state;
3279 self.stopped = rollback.stopped;
3280 self.upgrading = rollback.upgrading;
3281 self.sync_needed = rollback.sync_needed;
3282 self.active_round = rollback.active_round;
3283 self.overlay_dirty.restore(rollback.overlay_dirty);
3284 self.change_queue.truncate(rollback.change_queue);
3285 self.sync_intent_queue.truncate(rollback.sync_intent_queue);
3286 self.last_change = rollback.last_change;
3287 }
3288
3289 fn coalesce_unit(&mut self, rows: usize) -> Result<(), String> {
3292 let Some(open) = &self.coalesced else {
3293 return Ok(());
3294 };
3295 if open.rows > 0 && open.rows + rows > COALESCED_APPLY_ROWS {
3296 self.commit_coalesced_apply()?;
3297 self.begin_coalesced_apply()?;
3298 }
3299 if let Some(open) = &mut self.coalesced {
3300 open.rows += rows;
3301 }
3302 Ok(())
3303 }
3304
3305 fn commit_coalesced_apply(&mut self) -> Result<(), String> {
3310 let Some(open) = self.coalesced.take() else {
3311 return Ok(());
3312 };
3313 let committed = if self.conn.is_autocommit() {
3314 Err("the coalesced apply transaction was rolled back".to_owned())
3315 } else {
3316 self.conn
3317 .execute_batch("COMMIT")
3318 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3319 };
3320 let Err(error) = committed else {
3321 return Ok(());
3322 };
3323 if !self.conn.is_autocommit() {
3324 if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3325 let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3326 }
3327 }
3328 self.restore(open.rollback);
3329 self.coalesced_failure = Some(error.clone());
3330 Err(error)
3331 }
3332
3333 fn finish_coalesced_apply(&mut self) -> Result<(), String> {
3335 let committed = self.commit_coalesced_apply();
3336 match self.coalesced_failure.take() {
3337 Some(failure) => Err(failure),
3338 None => committed,
3339 }
3340 }
3341
3342 fn rollback_observation(&self, name: &str) {
3343 if let Err(error) = self
3344 .conn
3345 .execute_batch(&format!("ROLLBACK TO {name}; RELEASE {name}"))
3346 {
3347 if let Some(failure) = self.storage_failure.borrow_mut().as_mut() {
3348 if failure.rollback_failure.is_none() {
3349 failure.rollback_failure = Some(Box::new(QueryReadFailure::from(error)));
3350 }
3351 }
3352 }
3353 }
3354
3355 fn finish_observation(
3356 &mut self,
3357 name: &str,
3358 mut batch: ChangeAccumulator,
3359 ) -> Result<(), String> {
3360 #[cfg(feature = "bench-internals")]
3361 let _phase = self.benchmark_phases.start(Phase::ObservationCommit);
3362 if self.failed_commits.iter().any(|(commit, _)| {
3363 commit
3364 .ops
3365 .iter()
3366 .any(|operation| batch.tables.contains_key(&operation.table))
3367 }) {
3368 batch.outcomes = true;
3369 }
3370 if !batch.touched() {
3371 self.conn
3372 .execute_batch(&format!("RELEASE {name}"))
3373 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3374 return Ok(());
3375 }
3376 let revision = self
3377 .local_revision()?
3378 .checked_add(1)
3379 .ok_or_else(|| "local revision exhausted u64".to_owned())?;
3380 self.conn
3381 .execute(
3382 "INSERT OR REPLACE INTO _syncular_meta(key, value) VALUES (?1, ?2)",
3383 rusqlite::params![LOCAL_REVISION_KEY, revision.to_string()],
3384 )
3385 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3386 let status = batch.status.then(|| self.status_snapshot());
3387 let event = ClientChangeBatch {
3388 revision: revision.to_string(),
3389 tables: batch
3390 .tables
3391 .into_iter()
3392 .map(|(table, scope_keys)| TableChange {
3393 table,
3394 scope_keys: scope_keys.map(|keys| keys.into_iter().collect()),
3395 })
3396 .collect(),
3397 windows: batch
3398 .windows
3399 .into_iter()
3400 .map(|(base_key, units)| WindowChange {
3401 base_key,
3402 units: units.into_iter().collect(),
3403 })
3404 .collect(),
3405 status,
3406 conflicts_changed: batch.conflicts,
3407 rejections_changed: batch.rejections,
3408 outcomes_changed: batch.outcomes,
3409 applied_commits: Vec::new(),
3410 };
3411 self.conn
3412 .execute_batch(&format!("RELEASE {name}"))
3413 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3414 let mut diagnostic_tables = event
3415 .tables
3416 .iter()
3417 .map(|entry| entry.table.clone())
3418 .collect::<BTreeSet<_>>()
3419 .into_iter()
3420 .collect::<Vec<_>>();
3421 let mut diagnostic_windows = event
3423 .windows
3424 .iter()
3425 .map(|entry| {
3426 entry
3427 .base_key
3428 .split('\0')
3429 .next()
3430 .unwrap_or_default()
3431 .to_owned()
3432 })
3433 .collect::<BTreeSet<_>>()
3434 .into_iter()
3435 .collect::<Vec<_>>();
3436 let domains_truncated = diagnostic_tables.len() > MAX_DIAGNOSTIC_DOMAINS
3437 || diagnostic_windows.len() > MAX_DIAGNOSTIC_DOMAINS;
3438 diagnostic_tables.truncate(MAX_DIAGNOSTIC_DOMAINS);
3439 diagnostic_windows.truncate(MAX_DIAGNOSTIC_DOMAINS);
3440 self.last_change = Some(DiagnosticLastChange {
3441 revision: event.revision.clone(),
3442 recorded_at_ms: self.clock_now_ms(),
3443 tables: diagnostic_tables,
3444 windows: diagnostic_windows,
3445 domains_truncated,
3446 status_changed: event.status.is_some(),
3447 conflicts_changed: event.conflicts_changed,
3448 rejections_changed: event.rejections_changed,
3449 outcomes_changed: event.outcomes_changed,
3450 });
3451 self.change_queue.push_back(event);
3452 Ok(())
3453 }
3454
3455 fn record_scope_map(
3456 &self,
3457 batch: &mut ChangeAccumulator,
3458 table_name: &str,
3459 scopes: &[(String, Vec<String>)],
3460 ) {
3461 let Some(table) = self.schema.table(table_name) else {
3462 return;
3463 };
3464 if table.scope_variables.iter().any(|scope| {
3467 !scopes
3468 .iter()
3469 .any(|(variable, _)| *variable == scope.variable)
3470 }) {
3471 batch.table(table_name);
3472 return;
3473 }
3474 for (variable, values) in scopes {
3475 let Some(scope) = table
3476 .scope_variables
3477 .iter()
3478 .find(|scope| &scope.variable == variable)
3479 else {
3480 continue;
3481 };
3482 for value in values {
3483 batch.scope(table_name, format!("{}:{value}", scope.prefix));
3484 }
3485 }
3486 }
3487
3488 fn record_row_scopes(
3490 &self,
3491 batch: &mut ChangeAccumulator,
3492 table_name: &str,
3493 row_id: &str,
3494 base: bool,
3495 ) -> bool {
3496 let Some(table) = self.schema.table(table_name) else {
3497 return false;
3498 };
3499 if table.scope_variables.is_empty() {
3500 return false;
3501 }
3502 let columns = table
3503 .scope_variables
3504 .iter()
3505 .map(|scope| quote_ident(&scope.column))
3506 .collect::<Vec<_>>()
3507 .join(", ");
3508 let full_table = if base {
3509 base_table(table_name)
3510 } else {
3511 visible_table(table_name)
3512 };
3513 let sql = format!(
3514 "SELECT {columns} FROM {full_table} WHERE {} LIMIT 1",
3515 row_id_predicate(table)
3516 );
3517 let Ok(mut stmt) = self.conn.prepare_cached(&sql) else {
3518 return false;
3519 };
3520 let values = stmt.query_row(rusqlite::params![row_id], |row| {
3521 let mut values = Vec::with_capacity(table.scope_variables.len());
3522 for index in 0..table.scope_variables.len() {
3523 values.push(row.get::<_, Option<String>>(index)?);
3524 }
3525 Ok(values)
3526 });
3527 let Ok(values) = values else {
3528 return false;
3529 };
3530 let mut recorded = false;
3531 for (scope, value) in table.scope_variables.iter().zip(values) {
3532 if let Some(value) = value {
3533 batch.scope(table_name, format!("{}:{value}", scope.prefix));
3534 recorded = true;
3535 }
3536 }
3537 recorded
3538 }
3539
3540 fn record_commit_changes(
3541 &self,
3542 batch: &mut ChangeAccumulator,
3543 tables: &[String],
3544 changes: &[ssp2::model::Change],
3545 ) {
3546 #[cfg(feature = "bench-internals")]
3547 let _phase = self.benchmark_phases.start(Phase::ObservationPrepare);
3548 for change in changes {
3549 let Some(table_name) = tables.get(change.table_index as usize) else {
3550 continue;
3551 };
3552 let mut precise = self.record_row_scopes(batch, table_name, &change.row_id, true);
3553 if let Some(table) = self.schema.table(table_name) {
3554 for (variable, value) in &change.scopes {
3555 if let Some(scope) = table
3556 .scope_variables
3557 .iter()
3558 .find(|scope| &scope.variable == variable)
3559 {
3560 batch.scope(table_name, format!("{}:{value}", scope.prefix));
3561 precise = true;
3562 }
3563 }
3564 }
3565 if !precise {
3566 batch.table(table_name);
3567 }
3568 }
3569 }
3570
3571 fn scoped_rows_exist(
3574 &self,
3575 table_name: &str,
3576 effective: &[(String, Vec<String>)],
3577 owners: &[Vec<(String, Vec<String>)>],
3578 ) -> Result<bool, String> {
3579 let Some(table) = self.schema.table(table_name) else {
3580 return Ok(false);
3581 };
3582 let Ok(Some((predicate, params))) = local_scope_predicate(table, effective, owners) else {
3583 return Ok(false);
3584 };
3585 for source in [base_table(table_name), visible_table(table_name)] {
3586 if self
3587 .conn
3588 .query_row(
3589 &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
3590 rusqlite::params_from_iter(¶ms),
3591 |row| row.get::<_, bool>(0),
3592 )
3593 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
3594 {
3595 return Ok(true);
3596 }
3597 }
3598 Ok(false)
3599 }
3600
3601 fn clear_scope(
3606 &mut self,
3607 table: &TableSchema,
3608 effective: &[(String, Vec<String>)],
3609 unit_id: &str,
3610 ) -> Result<bool, SectionError> {
3611 let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
3612 let matched = self
3613 .scoped_rows_exist(&table.name, effective, &[])
3614 .map_err(storage)?;
3615 let owners = if matched {
3616 unit_owners(
3617 &self.stored(load_units(&self.conn)).map_err(storage)?,
3618 table,
3619 unit_id,
3620 )
3621 } else {
3622 Vec::new()
3623 };
3624 let changed = matched
3625 && (owners.is_empty()
3626 || self
3627 .scoped_rows_exist(&table.name, effective, &owners)
3628 .map_err(storage)?);
3629 if !self
3630 .purge_scope_rows(&table.name, effective, &owners)
3631 .map_err(storage)?
3632 {
3633 return Err(SectionError::FailClosed);
3634 }
3635 Ok(changed)
3636 }
3637
3638 pub fn upgrading(&self) -> bool {
3640 self.upgrading
3641 }
3642
3643 pub fn recreate_with_schema(&mut self, schema_json: &Value) -> Result<(), String> {
3651 let new_schema = parse_schema_json(schema_json)?;
3652 validate_authority_reads(&new_schema, &self.limits.authority_reads)?;
3653 self.conn
3654 .execute_batch("BEGIN IMMEDIATE")
3655 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3656 let prior_schema = std::mem::replace(&mut self.schema, new_schema);
3657 let rollback = self.capture();
3663 let guarded = (|| -> Result<(), String> {
3664 let marker = read_local_schema_version(&self.conn, self.schema.version)?;
3669 self.create_bookkeeping_tables()?;
3670 match marker {
3671 Some(version) if version < self.schema.version => self.run_schema_reset()?,
3672 None => {
3673 self.create_synced_tables()?;
3674 self.persist_schema_version()?;
3675 }
3676 _ => {}
3677 }
3678 self.outbox = self.load_outbox()?.into();
3683 self.drop_unencodable_outbox(false, None)?;
3688 if marker == Some(self.schema.version)
3689 && (!self.outbox.is_empty()
3690 || !self.failed_commits.is_empty()
3691 || self.has_acknowledged_rows()?)
3692 {
3693 self.overlay_dirty.set(true);
3694 self.rebuild_overlay()?;
3695 }
3696 self.prune_unknown_units(false)?;
3697 self.save_unit_scope_schema()?;
3698 self.enqueue_startup_sync_if_needed()?;
3702 Ok(())
3703 })();
3704 let outcome = match guarded {
3705 Ok(()) => self
3706 .conn
3707 .execute_batch("COMMIT")
3708 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error)),
3709 Err(error) => Err(error),
3710 };
3711 if let Err(error) = outcome {
3712 if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3713 let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3715 }
3716 self.schema = prior_schema;
3717 self.restore(rollback);
3718 self.insert_sql.borrow_mut().clear();
3720 return Err(error);
3721 }
3722 if !self.security_preflight {
3723 self.drain_pending_evictions()?;
3724 }
3725 Ok(())
3726 }
3727
3728 fn enqueue_startup_sync_if_needed(&mut self) -> Result<(), String> {
3729 let startup_work = !self.stopped
3730 && (!self.outbox.is_empty()
3731 || self.has_acknowledged_rows()?
3732 || !self.load_pending_evictions()?.is_empty()
3733 || self
3734 .stored(load_units(&self.conn))?
3735 .iter()
3736 .any(|unit| unit.status == UnitStatus::Active));
3737 if startup_work {
3738 self.sync_needed = true;
3739 self.sync_intent_queue.push_back(SyncIntent::Interactive);
3740 }
3741 Ok(())
3742 }
3743
3744 fn clear_satisfied_persisted_schema_floor(&mut self) -> Result<(), String> {
3751 let satisfied = self
3752 .schema_floor
3753 .as_ref()
3754 .and_then(|floor| floor.required_schema_version)
3755 .is_some_and(|required| self.schema.version >= required);
3756 if !satisfied {
3757 return Ok(());
3758 }
3759 self.delete_meta(SCHEMA_FLOOR_KEY)?;
3760 self.schema_floor = None;
3761 self.stopped = false;
3762 Ok(())
3763 }
3764
3765 fn reconcile_previous_version_at_boot(&self) -> Result<(), String> {
3770 let Some(replica_path) = self.previous_version_replica_path() else {
3771 return Ok(());
3772 };
3773 let max_age_ms = self
3774 .previous_version
3775 .filter(|config| config.enabled)
3776 .map(|config| config.max_age_ms);
3777 reconcile_previous_version_at_boot(
3778 &self.conn,
3779 &replica_path,
3780 self.schema.version,
3781 max_age_ms,
3782 self.clock_now_ms(),
3783 )
3784 }
3785
3786 fn previous_version_replica_path(&self) -> Option<String> {
3790 let path = self.conn.path()?;
3791 if path.is_empty() || path.starts_with("file:") {
3792 return None;
3793 }
3794 Some(path.to_owned())
3795 }
3796
3797 fn run_schema_reset(&mut self) -> Result<(), String> {
3803 self.begin_observation("syncular_schema_reset")?;
3804 let rollback = self.capture();
3805 let mut batch = ChangeAccumulator::default();
3806 let result = self
3807 .run_schema_reset_observed(&mut batch, true)
3808 .and_then(|()| self.finish_observation("syncular_schema_reset", batch));
3809 if let Err(error) = result {
3810 self.rollback_observation("syncular_schema_reset");
3811 self.restore(rollback);
3812 return Err(error);
3813 }
3814 Ok(())
3815 }
3816
3817 fn run_log_epoch_reset(&mut self, log_epoch: &str) -> Result<Vec<String>, String> {
3818 if self.get_meta(LOG_EPOCH_KEY)?.is_none() {
3819 self.begin_observation("syncular_epoch_acquisition")?;
3820 let rollback = self.capture();
3821 if let Err(error) = self.conn.execute(
3822 "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
3823 rusqlite::params![LOG_EPOCH_KEY, log_epoch],
3824 ) {
3825 self.rollback_observation("syncular_epoch_acquisition");
3826 return Err(Self::sqlite_failure(&self.storage_failure, error));
3827 }
3828 self.sync_needed = true;
3829 let batch = ChangeAccumulator {
3830 status: true,
3831 ..ChangeAccumulator::default()
3832 };
3833 if let Err(error) = self.finish_observation("syncular_epoch_acquisition", batch) {
3834 self.rollback_observation("syncular_epoch_acquisition");
3835 self.restore(rollback);
3836 return Err(error);
3837 }
3838 self.sync_intent_queue.push_back(SyncIntent::Interactive);
3839 return Ok(Vec::new());
3840 }
3841 let resets = self
3842 .stored(load_units(&self.conn))?
3843 .into_iter()
3844 .map(|unit| unit.id)
3845 .collect();
3846 self.begin_observation("syncular_log_epoch_reset")?;
3847 let rollback = self.capture();
3848 let mut batch = ChangeAccumulator::default();
3849 let result = self
3850 .run_schema_reset_observed(&mut batch, false)
3851 .and_then(|()| {
3852 self.conn
3853 .execute(
3854 "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
3855 rusqlite::params![LOG_EPOCH_KEY, log_epoch],
3856 )
3857 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3858 self.sync_needed = true;
3859 batch.status = true;
3860 self.finish_observation("syncular_log_epoch_reset", batch)
3861 });
3862 if let Err(error) = result {
3863 self.rollback_observation("syncular_log_epoch_reset");
3864 self.restore(rollback);
3865 return Err(error);
3866 }
3867 self.sync_intent_queue.push_back(SyncIntent::Interactive);
3868 Ok(resets)
3869 }
3870
3871 fn run_schema_reset_observed(
3872 &mut self,
3873 batch: &mut ChangeAccumulator,
3874 capture: bool,
3875 ) -> Result<(), String> {
3876 read_local_schema_version(&self.conn, self.schema.version)?;
3882 self.conn
3883 .execute_batch(
3884 "DELETE FROM _syncular_acked_rows; DELETE FROM _syncular_row_deliveries;",
3885 )
3886 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3887 self.cancel_sync_round();
3888 self.upgrading = true;
3889 batch.status = true;
3890 if self.previous_version.is_some_and(|config| config.enabled) {
3898 let previous_version = self
3899 .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
3900 .and_then(|value| value.parse::<i32>().ok())
3901 .unwrap_or(self.schema.version);
3902 let pending = self
3903 .outbox
3904 .iter()
3905 .map(|commit| PendingCommitAudit {
3906 commit_id: &commit.client_commit_id,
3907 operations: commit_audit_operations(commit),
3908 })
3909 .collect::<Vec<_>>();
3910 crate::previous_version::write_previous_version_audit(
3911 &self.conn,
3912 &crate::previous_version::build_previous_version_audit(
3913 &self.schema,
3914 &pending,
3915 previous_version,
3916 self.schema.version,
3917 self.clock_now_ms(),
3918 ),
3919 )?;
3920 }
3921 if let Some(replica_path) = self.previous_version_replica_path() {
3926 sweep_previous_version_container(&self.conn, &replica_path)?;
3927 if capture {
3928 if let Some(config) = self.previous_version.filter(|config| config.enabled) {
3929 let previous_version = self
3930 .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
3931 .and_then(|value| value.parse::<i32>().ok())
3932 .unwrap_or(self.schema.version);
3933 capture_previous_version_from_replica(
3934 &self.conn,
3935 &replica_path,
3936 previous_version,
3937 self.schema.version,
3938 &config,
3939 self.clock_now_ms(),
3940 )?;
3941 }
3942 }
3943 }
3944 for table in &self.schema.tables {
3945 batch.table(&table.name);
3946 }
3947 for (base_key, value) in self.load_window_registry()? {
3948 batch.window(&base_key, &value);
3949 }
3950 if capture {
3951 self.prune_unknown_units(true)?;
3952 }
3953 self.insert_sql.borrow_mut().clear();
3955 self.overlay_dirty.set(true);
3956 let virtual_tables: Vec<String> = {
3964 let mut stmt = self
3965 .conn
3966 .prepare(
3967 "SELECT name FROM sqlite_master WHERE type = 'table' AND sql LIKE 'CREATE VIRTUAL TABLE%'",
3968 )
3969 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3970 let rows = stmt
3971 .query_map([], |row| row.get::<_, String>(0))
3972 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3973 rows.filter_map(Result::ok)
3974 .filter(|name| is_synced_table_name(name))
3975 .collect()
3976 };
3977 for name in virtual_tables {
3978 self.conn
3979 .execute_batch(&format!(
3980 "DROP TABLE IF EXISTS {}",
3981 quote_ident(&format!("_syncular_fts_{name}"))
3982 ))
3983 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3984 self.conn
3985 .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
3986 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3987 }
3988 let existing: Vec<String> = {
3989 let mut stmt = self
3990 .conn
3991 .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
3992 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3993 let rows = stmt
3994 .query_map([], |row| row.get::<_, String>(0))
3995 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3996 rows.filter_map(Result::ok)
3997 .filter(|name| is_synced_table_name(name))
3998 .collect()
3999 };
4000 for name in &existing {
4001 if let Some(table) = name.strip_prefix("_syncular_base_") {
4002 batch.table(table);
4003 } else if !name.starts_with("_syncular_") {
4004 batch.table(name);
4005 }
4006 }
4007 for name in existing {
4008 self.conn
4009 .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
4010 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4011 }
4012 self.create_synced_tables()?;
4014 reset_units(&self.conn)
4016 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4017 self.stopped = false;
4019 self.schema_floor = None;
4020 self.delete_meta(SCHEMA_FLOOR_KEY)?;
4021 self.persist_schema_version()?;
4023 self.save_unit_scope_schema()?;
4024 self.drop_unencodable_outbox(false, Some(batch))?;
4035 self.rebuild_overlay()?;
4037 Ok(())
4038 }
4039
4040 fn drop_incompatible_outbox(&mut self) -> Result<bool, String> {
4049 let incompatible = self
4050 .outbox
4051 .iter()
4052 .filter(|commit| {
4053 first_incompatibility(&self.schema, &commit_audit_operations(commit)).is_some()
4054 })
4055 .cloned()
4056 .collect::<Vec<_>>();
4057 if incompatible.is_empty() {
4058 return Ok(false);
4059 }
4060 self.drop_outbox_commits(
4061 &incompatible,
4062 OUTBOX_INCOMPATIBLE_CODE,
4063 "the persisted commit cannot encode under the current schema",
4064 )?;
4065 Ok(true)
4066 }
4067
4068 fn drop_outbox_commits(
4072 &mut self,
4073 incompatible: &[Arc<OutboxCommit>],
4074 code: &str,
4075 message: &str,
4076 ) -> Result<(), String> {
4077 let rollback = self.capture();
4083 let owns_transaction = self.conn.is_autocommit();
4084 self.begin_observation("syncular_outbox_drop")?;
4085 let mut batch = ChangeAccumulator::default();
4086 let dropped = (|| -> Result<(), String> {
4087 let mut rejections = Vec::new();
4088 for commit in incompatible {
4089 let results = commit
4090 .ops
4091 .iter()
4092 .enumerate()
4093 .map(|(op_index, operation)| {
4094 let rejection = RejectionRecord {
4095 client_commit_id: commit.client_commit_id.clone(),
4096 op_index: op_index as i32,
4097 code: code.to_owned(),
4098 message: message.to_owned(),
4099 retryable: false,
4100 details: None,
4101 operation: Some(CommitOperation::from(operation)),
4102 };
4103 rejections.push(rejection.clone());
4104 CommitOperationOutcome::Error { rejection }
4105 })
4106 .collect::<Vec<_>>();
4107 self.persist_commit_outcome(
4108 &commit.client_commit_id,
4109 CommitOutcomeStatus::Rejected,
4110 &results,
4111 Some(&commit.ops),
4112 )?;
4113 self.delete_outbox_persisted(&commit.client_commit_id)?;
4114 for operation in &commit.ops {
4117 if self.schema.table(&operation.table).is_some() {
4118 batch.table(&operation.table);
4119 }
4120 }
4121 }
4122 self.prune_commit_outcomes()?;
4123 let incompatible_ids = incompatible
4124 .iter()
4125 .map(|commit| commit.client_commit_id.as_str())
4126 .collect::<BTreeSet<_>>();
4127 self.outbox
4128 .retain(|commit| !incompatible_ids.contains(commit.client_commit_id.as_str()));
4129 self.rejections.extend(rejections);
4130 self.overlay_dirty.set(true);
4133 self.rebuild_overlay()?;
4134 batch.status = true;
4135 batch.rejections = true;
4136 batch.outcomes = true;
4137 Ok(())
4138 })();
4139 let result = dropped.and_then(|()| self.finish_observation("syncular_outbox_drop", batch));
4140 if let Err(error) = result {
4141 if owns_transaction {
4145 if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
4146 let mut failure = self.storage_failure.borrow_mut();
4147 let failure =
4148 failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
4149 failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
4150 }
4151 } else {
4152 self.rollback_observation("syncular_outbox_drop");
4153 }
4154 self.restore(rollback);
4155 return Err(error);
4156 }
4157 Ok(())
4158 }
4159
4160 fn create_synced_tables(&self) -> Result<(), String> {
4163 for table in &self.schema.tables {
4164 for (full, index_prefix) in [
4168 (base_table(&table.name), "_syncular_base_"),
4169 (visible_table(&table.name), ""),
4170 ] {
4171 let mut cols: Vec<String> =
4172 table.columns.iter().map(|c| quote_ident(&c.name)).collect();
4173 cols.push("\"_syncular_version\" INTEGER NOT NULL".to_owned());
4174 cols.extend(
4175 table
4176 .sealed_columns()
4177 .iter()
4178 .map(|name| format!("{} TEXT", quote_ident(name))),
4179 );
4180 let sql = format!(
4181 "CREATE TABLE IF NOT EXISTS {full} ({} , PRIMARY KEY ({}))",
4182 cols.join(", "),
4183 quote_ident(&table.primary_key)
4184 );
4185 self.conn
4186 .execute(&sql, [])
4187 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4188 for name in table.sealed_columns() {
4192 let present: bool = self
4193 .conn
4194 .query_row(
4195 "SELECT EXISTS(SELECT 1 FROM pragma_table_info(?1) WHERE name = ?2)",
4196 rusqlite::params![format!("{index_prefix}{}", table.name), name],
4197 |row| row.get(0),
4198 )
4199 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4200 if !present {
4201 self.conn
4202 .execute(
4203 &format!(
4204 "ALTER TABLE {full} ADD COLUMN {} TEXT",
4205 quote_ident(name)
4206 ),
4207 [],
4208 )
4209 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4210 }
4211 }
4212 if table.has_encrypted_columns() && !index_prefix.is_empty() {
4215 self.conn
4216 .execute(
4217 &format!(
4218 "CREATE INDEX IF NOT EXISTS {} ON {full} (\"_sync_sealed_key\") WHERE \"_sync_sealed_key\" IS NOT NULL",
4219 quote_ident(&format!("_syncular_sealed_{}", table.name))
4220 ),
4221 [],
4222 )
4223 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4224 }
4225 for index in &table.indexes {
4229 let unique = if index.unique { "UNIQUE " } else { "" };
4230 let index_name = quote_ident(&format!("{index_prefix}{}", index.name));
4231 let cols_sql = index
4232 .columns
4233 .iter()
4234 .map(|c| quote_ident(c))
4235 .collect::<Vec<_>>()
4236 .join(", ");
4237 let index_sql = format!(
4238 "CREATE {unique}INDEX IF NOT EXISTS {index_name} ON {full} ({cols_sql})"
4239 );
4240 self.conn
4241 .execute(&index_sql, [])
4242 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4243 }
4244 }
4245 }
4246 for table in &self.schema.tables {
4249 for index in &table.fts_indexes {
4250 self.create_fts_projection(table, index)?;
4251 }
4252 }
4253 Ok(())
4254 }
4255
4256 fn fts_projection_exists(&self, index: &FtsIndexSchema) -> Result<bool, String> {
4257 let count: i64 = self
4258 .conn
4259 .query_row(
4260 "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?1",
4261 rusqlite::params![index.name],
4262 |row| row.get(0),
4263 )
4264 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4265 Ok(count > 0)
4266 }
4267
4268 fn drop_fts_triggers(&self, index: &FtsIndexSchema) -> Result<(), String> {
4269 for suffix in ["ai", "ad", "au"] {
4270 self.conn
4271 .execute(
4272 &format!(
4273 "DROP TRIGGER IF EXISTS {}",
4274 quote_ident(&format!("{}_{suffix}", index.name))
4275 ),
4276 [],
4277 )
4278 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4279 }
4280 Ok(())
4281 }
4282
4283 fn create_fts_triggers(
4284 &self,
4285 table: &TableSchema,
4286 index: &FtsIndexSchema,
4287 ) -> Result<(), String> {
4288 let fts = quote_ident(&index.name);
4289 let source = visible_table(&table.name);
4290 let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4291 let pk = quote_ident(&table.primary_key);
4292 let projection_columns = std::iter::once(source_id.clone())
4293 .chain(index.columns.iter().map(|column| quote_ident(column)))
4294 .collect::<Vec<_>>()
4295 .join(", ");
4296 let new_values = std::iter::once(format!("CAST(new.{pk} AS TEXT)"))
4297 .chain(
4298 index
4299 .columns
4300 .iter()
4301 .map(|column| format!("new.{}", quote_ident(column))),
4302 )
4303 .collect::<Vec<_>>()
4304 .join(", ");
4305 let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4306 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)");
4307 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)");
4308 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})");
4309 let bi = quote_ident(&format!("{}_bi", index.name));
4310 let ai = quote_ident(&format!("{}_ai", index.name));
4311 let ad = quote_ident(&format!("{}_ad", index.name));
4312 let au = quote_ident(&format!("{}_au", index.name));
4313 let replacement_exists = format!("EXISTS (SELECT 1 FROM {source} WHERE {pk} = new.{pk})");
4314 let sql = format!(
4315 "DROP TRIGGER IF EXISTS {bi};
4316 DROP TRIGGER IF EXISTS {ai};
4317 DROP TRIGGER IF EXISTS {ad};
4318 DROP TRIGGER IF EXISTS {au};
4319 CREATE TRIGGER {bi} BEFORE INSERT ON {source} WHEN {replacement_exists} BEGIN {delete_new}; END;
4320 CREATE TRIGGER {ai} AFTER INSERT ON {source} BEGIN {insert_new}; END;
4321 CREATE TRIGGER {ad} AFTER DELETE ON {source} BEGIN {delete_old}; END;
4322 CREATE TRIGGER {au} AFTER UPDATE ON {source} BEGIN {delete_old}; {delete_new}; {insert_new}; END;",
4323 );
4324 self.conn
4325 .execute_batch(&sql)
4326 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4327 }
4328
4329 fn rebuild_fts_projection(
4330 &self,
4331 table: &TableSchema,
4332 index: &FtsIndexSchema,
4333 ) -> Result<(), String> {
4334 let fts = quote_ident(&index.name);
4335 let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4336 let pk = quote_ident(&table.primary_key);
4337 let indexed_columns = index
4338 .columns
4339 .iter()
4340 .map(|column| quote_ident(column))
4341 .collect::<Vec<_>>();
4342 let projection_columns = std::iter::once(source_id.clone())
4343 .chain(indexed_columns.iter().cloned())
4344 .collect::<Vec<_>>()
4345 .join(", ");
4346 let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4347 let sql = format!(
4348 "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};",
4349 columns = indexed_columns.join(", "),
4350 source = visible_table(&table.name),
4351 );
4352 self.conn
4353 .execute_batch(&sql)
4354 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4355 }
4356
4357 fn create_fts_projection(
4358 &self,
4359 table: &TableSchema,
4360 index: &FtsIndexSchema,
4361 ) -> Result<(), String> {
4362 self.begin_observation("syncular_fts_schema")?;
4363 let result = (|| {
4364 let existed = self.fts_projection_exists(index)?;
4365 let tokenizer = index.tokenize.replace('\'', "''");
4366 let columns = index
4367 .columns
4368 .iter()
4369 .map(|column| quote_ident(column))
4370 .collect::<Vec<_>>()
4371 .join(", ");
4372 let sql = format!(
4373 "CREATE VIRTUAL TABLE IF NOT EXISTS {fts} USING fts5({source_id} UNINDEXED, {columns}, tokenize='{tokenizer}')",
4374 fts = quote_ident(&index.name),
4375 source_id = quote_ident(FTS_SOURCE_ID_COLUMN),
4376 );
4377 self.conn.execute(&sql, []).map_err(|error| {
4378 format!(
4379 "cannot create local FTS5 projection {:?}: {error}",
4380 index.name
4381 )
4382 })?;
4383 let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4384 let mapped: bool = self
4385 .conn
4386 .query_row(
4387 "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type='table' AND name=?1)",
4388 [format!("_syncular_fts_{}", index.name)],
4389 |row| row.get(0),
4390 )
4391 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4392 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))?;
4393 if !mapped && existed {
4394 self.conn
4395 .execute_batch(&format!(
4396 "INSERT INTO {mapping}(id, source_id) SELECT rowid, {} FROM {}",
4397 quote_ident(FTS_SOURCE_ID_COLUMN),
4398 quote_ident(&index.name)
4399 ))
4400 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4401 }
4402 self.create_fts_triggers(table, index)?;
4403 if !existed {
4404 self.rebuild_fts_projection(table, index)?;
4405 }
4406 Ok(())
4407 })();
4408 if let Err(error) = result {
4409 self.rollback_observation("syncular_fts_schema");
4410 return Err(error);
4411 }
4412 if let Err(error) = self.conn.execute_batch("RELEASE syncular_fts_schema") {
4413 self.rollback_observation("syncular_fts_schema");
4414 return Err(error.to_string());
4415 }
4416 Ok(())
4417 }
4418
4419 fn persist_outbox_insert(&self, commit: &OutboxCommit) -> Result<(), String> {
4422 let ops: Vec<Value> = commit
4423 .ops
4424 .iter()
4425 .map(|op| {
4426 let mut entry = serde_json::json!({
4427 "op": if op.upsert { "upsert" } else { "delete" },
4428 "table": op.table,
4429 "rowId": op.row_id,
4430 "baseVersion": op.base_version,
4431 "values": op.values.clone().map(Value::Object),
4432 });
4433 if op.insert {
4434 entry["insert"] = Value::Bool(true);
4435 }
4436 entry
4437 })
4438 .collect();
4439 self.conn
4440 .execute(
4441 "INSERT OR REPLACE INTO _syncular_outbox (commit_id, ops_json) VALUES (?1, ?2)",
4442 rusqlite::params![commit.client_commit_id, Value::Array(ops).to_string()],
4443 )
4444 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4445 for operation in &commit.ops {
4446 let Some(values) = &operation.values else {
4447 continue;
4448 };
4449 let Some(table) = self.schema.table(&operation.table) else {
4450 continue;
4451 };
4452 for column in table
4453 .columns
4454 .iter()
4455 .filter(|column| column.ty == ColumnType::BlobRef)
4456 {
4457 let Some(Value::String(raw)) = values.get(&column.name) else {
4458 continue;
4459 };
4460 let Ok(blob_ref) = serde_json::from_str::<Value>(raw) else {
4461 continue;
4462 };
4463 let Some(blob_id) = blob_ref.get("blobId").and_then(Value::as_str) else {
4464 continue;
4465 };
4466 self.conn
4467 .execute(
4468 "INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id, blob_id)
4469 SELECT ?1, ?2 WHERE EXISTS (SELECT 1 FROM _syncular_blobs WHERE blob_id = ?2)",
4470 rusqlite::params![commit.client_commit_id, blob_id],
4471 )
4472 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4473 }
4474 }
4475 Ok(())
4476 }
4477
4478 fn delete_outbox_persisted(&self, client_commit_id: &str) -> Result<(), String> {
4479 self.conn
4480 .execute(
4481 "DELETE FROM _syncular_blob_commit_refs WHERE commit_id = ?1",
4482 rusqlite::params![client_commit_id],
4483 )
4484 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4485 self.conn
4486 .execute(
4487 "DELETE FROM _syncular_outbox WHERE commit_id = ?1",
4488 rusqlite::params![client_commit_id],
4489 )
4490 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4491 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)", [])
4492 .map(|_| ())
4493 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4494 }
4495
4496 fn outcome_status_name(status: CommitOutcomeStatus) -> &'static str {
4497 match status {
4498 CommitOutcomeStatus::Applied => "applied",
4499 CommitOutcomeStatus::Cached => "cached",
4500 CommitOutcomeStatus::Conflict => "conflict",
4501 CommitOutcomeStatus::Rejected => "rejected",
4502 }
4503 }
4504
4505 fn outcome_resolution_name(resolution: CommitOutcomeResolution) -> &'static str {
4506 match resolution {
4507 CommitOutcomeResolution::Active => "active",
4508 CommitOutcomeResolution::ResolvedKeepServer => "resolved_keep_server",
4509 CommitOutcomeResolution::Superseded => "superseded",
4510 CommitOutcomeResolution::Dismissed => "dismissed",
4511 }
4512 }
4513
4514 fn parse_outcome_status(value: &str) -> Result<CommitOutcomeStatus, String> {
4515 match value {
4516 "applied" => Ok(CommitOutcomeStatus::Applied),
4517 "cached" => Ok(CommitOutcomeStatus::Cached),
4518 "conflict" => Ok(CommitOutcomeStatus::Conflict),
4519 "rejected" => Ok(CommitOutcomeStatus::Rejected),
4520 _ => Err(format!("invalid persisted commit outcome status {value:?}")),
4521 }
4522 }
4523
4524 fn parse_outcome_resolution(value: &str) -> Result<CommitOutcomeResolution, String> {
4525 match value {
4526 "active" => Ok(CommitOutcomeResolution::Active),
4527 "resolved_keep_server" => Ok(CommitOutcomeResolution::ResolvedKeepServer),
4528 "superseded" => Ok(CommitOutcomeResolution::Superseded),
4529 "dismissed" => Ok(CommitOutcomeResolution::Dismissed),
4530 _ => Err(format!(
4531 "invalid persisted commit outcome resolution {value:?}"
4532 )),
4533 }
4534 }
4535
4536 fn persist_commit_outcome(
4537 &self,
4538 client_commit_id: &str,
4539 status: CommitOutcomeStatus,
4540 results: &[CommitOperationOutcome],
4541 operations: Option<&[OutboxOp]>,
4542 ) -> Result<(), String> {
4543 let results_json = serde_json::to_string(results).map_err(|error| error.to_string())?;
4544 let operations_json = operations
4545 .map(|items| {
4546 serde_json::to_string(&items.iter().map(CommitOperation::from).collect::<Vec<_>>())
4547 })
4548 .transpose()
4549 .map_err(|error| error.to_string())?;
4550 self.conn
4551 .execute(
4552 "INSERT INTO _syncular_commit_outcomes (
4553 client_commit_id, status, recorded_at_ms, results_json,
4554 operations_json, resolution
4555 ) VALUES (?1, ?2, ?3, ?4, ?5, 'active')",
4556 rusqlite::params![
4557 client_commit_id,
4558 Self::outcome_status_name(status),
4559 self.clock_now_ms(),
4560 results_json,
4561 operations_json
4562 ],
4563 )
4564 .map(|_| ())
4565 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4566 }
4567
4568 fn stored_cell_is_representable(cell: &Value) -> bool {
4571 cell.is_null()
4572 || cell.is_string()
4573 || cell.is_boolean()
4574 || cell.is_number()
4575 || is_canonical_bytes_envelope(cell)
4576 }
4577
4578 fn stored_row_is_representable(value: &Value) -> bool {
4579 value
4580 .as_object()
4581 .is_some_and(|row| row.values().all(Self::stored_cell_is_representable))
4582 }
4583
4584 fn stored_operation_is_representable(value: &Value) -> bool {
4585 value.get("table").is_some_and(Value::is_string)
4586 && value.get("rowId").is_some_and(Value::is_string)
4587 && value.get("baseVersion").is_none_or(|v| {
4588 v.as_i64()
4589 .is_some_and(|n| n.unsigned_abs() <= MAX_JS_SAFE_INTEGER)
4590 })
4591 && match value.get("op").and_then(Value::as_str) {
4592 Some("upsert") => {
4593 value
4594 .get("values")
4595 .is_some_and(Self::stored_row_is_representable)
4596 && value
4597 .get("insert")
4598 .is_none_or(|insert| *insert == Value::Bool(true))
4599 }
4600 Some("delete") => value.get("values").is_none() && value.get("insert").is_none(),
4601 _ => false,
4602 }
4603 }
4604
4605 fn outbox_op_is_journalable(operation: &OutboxOp) -> bool {
4609 serde_json::to_value(CommitOperation::from(operation))
4610 .is_ok_and(|value| Self::stored_operation_is_representable(&value))
4611 }
4612
4613 fn outcome_from_row(row: StoredCommitOutcomeRow) -> Result<CommitOutcome, String> {
4614 let StoredCommitOutcomeRow {
4615 sequence,
4616 client_commit_id,
4617 status,
4618 recorded_at_ms,
4619 results_json,
4620 operations_json,
4621 resolution,
4622 resolved_at_ms,
4623 replacement_client_commit_id,
4624 } = row;
4625 if sequence.unsigned_abs() > MAX_JS_SAFE_INTEGER
4626 || recorded_at_ms.unsigned_abs() > MAX_JS_SAFE_INTEGER
4627 || resolved_at_ms.is_some_and(|value| value.unsigned_abs() > MAX_JS_SAFE_INTEGER)
4628 {
4629 return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned());
4630 }
4631 let invalid = || "sync.local_corrupt: persisted commit outcome is invalid".to_owned();
4632 let stored: Vec<Value> = serde_json::from_str(&results_json).map_err(|_| invalid())?;
4633 for result in &stored {
4634 let nested = match result.get("status").and_then(Value::as_str) {
4635 Some("conflict") => result.get("conflict"),
4636 Some("error") => result.get("rejection"),
4637 _ => None,
4638 };
4639 if nested
4640 .and_then(|record| record.get("operation"))
4641 .is_some_and(|op| !Self::stored_operation_is_representable(op))
4642 || (result.get("status").and_then(Value::as_str) == Some("conflict")
4643 && nested
4644 .and_then(|record| record.get("serverRow"))
4645 .is_some_and(|row| !Self::stored_row_is_representable(row)))
4646 {
4647 return Err(invalid());
4648 }
4649 }
4650 let results: Vec<CommitOperationOutcome> =
4651 serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())?;
4652 let has_conflict = results
4653 .iter()
4654 .any(|result| matches!(result, CommitOperationOutcome::Conflict { .. }));
4655 let has_error = results
4656 .iter()
4657 .any(|result| matches!(result, CommitOperationOutcome::Error { .. }));
4658 let status = Self::parse_outcome_status(&status).map_err(|_| invalid())?;
4659 let redacted = results.is_empty() && operations_json.is_none();
4660 if match status {
4661 CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => has_conflict || has_error,
4662 CommitOutcomeStatus::Conflict => !(has_conflict || redacted),
4663 CommitOutcomeStatus::Rejected => has_conflict || !(has_error || redacted),
4664 } {
4665 return Err(invalid());
4666 }
4667 let operations: Option<Vec<CommitOperation>> = operations_json
4668 .map(|raw| {
4669 let stored: Vec<Value> = serde_json::from_str(&raw).map_err(|_| invalid())?;
4670 if !stored.iter().all(Self::stored_operation_is_representable) {
4671 return Err(invalid());
4672 }
4673 serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())
4674 })
4675 .transpose()?;
4676 for result in &results {
4677 match result {
4678 CommitOperationOutcome::Conflict { conflict }
4679 if conflict.server_version.unsigned_abs() > MAX_JS_SAFE_INTEGER =>
4680 {
4681 return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned())
4682 }
4683 CommitOperationOutcome::Error { rejection } => {
4684 if let Some(details) = &rejection.details {
4685 let encoded = serde_json::to_string(details).map_err(|_| {
4686 "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4687 })?;
4688 RejectionDetails::parse(&encoded).map_err(|_| {
4689 "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4690 })?;
4691 }
4692 }
4693 _ => {}
4694 }
4695 }
4696 Ok(CommitOutcome {
4697 sequence,
4698 client_commit_id,
4699 status,
4700 recorded_at_ms,
4701 results,
4702 operations,
4703 retained_rows: None,
4704 resolution: Self::parse_outcome_resolution(&resolution)?,
4705 resolved_at_ms,
4706 replacement_client_commit_id,
4707 })
4708 }
4709
4710 fn unique_conflicts(
4712 &self,
4713 table: &TableSchema,
4714 values: &Map<String, Value>,
4715 base: bool,
4716 ) -> Result<Vec<RetainedUniqueConflict>, String> {
4717 let source = if base {
4718 base_table(&table.name)
4719 } else {
4720 visible_table(&table.name)
4721 };
4722 let mut conflicts = Vec::new();
4723 for index in table.indexes.iter().filter(|index| index.unique) {
4724 let mut params = vec![json_param_to_sql(
4725 values.get(&table.primary_key).ok_or("sync.local_corrupt")?,
4726 )?];
4727 for name in &index.columns {
4728 let column = table
4729 .columns
4730 .iter()
4731 .find(|column| column.name == *name)
4732 .ok_or("sync.local_corrupt")?;
4733 let cell = json_to_column_value(column, values.get(name))?;
4734 params.push(owned_sql_value(RowParam::Cell(&cell))?);
4735 }
4736 let sql = format!(
4737 "SELECT * FROM {source} WHERE {} != ? AND {}",
4738 quote_ident(&table.primary_key),
4739 index
4740 .columns
4741 .iter()
4742 .map(|column| format!("{} = ?", quote_ident(column)))
4743 .collect::<Vec<_>>()
4744 .join(" AND ")
4745 );
4746 let mut statement = self
4747 .conn
4748 .prepare_cached(&sql)
4749 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4750 let records = statement
4751 .query_map(rusqlite::params_from_iter(params), |record| {
4752 let values = table
4753 .columns
4754 .iter()
4755 .enumerate()
4756 .map(|(index, column)| {
4757 let value = sql_ref_to_json(column, record.get_ref(index)?);
4758 json_to_column_value(column, Some(&value)).map_err(|message| {
4759 rusqlite::Error::ToSqlConversionFailure(message.into())
4760 })
4761 })
4762 .collect::<Result<Row, _>>()?;
4763 Ok((values, record.get::<_, i64>(table.columns.len())?))
4764 })
4765 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4766 for record in records {
4767 let (row, version) =
4768 record.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4769 let row_id = render_row_id_json(Some(&column_value_to_json(&row[table.pk_index])))?;
4770 conflicts.push(RetainedUniqueConflict {
4771 index: index.name.clone(),
4772 columns: index.columns.clone(),
4773 row_id,
4774 server_row: table
4775 .columns
4776 .iter()
4777 .zip(&row)
4778 .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
4779 .collect(),
4780 server_version: version,
4781 });
4782 }
4783 }
4784 Ok(conflicts)
4785 }
4786
4787 fn attach_retained_rows(&self, mut outcome: CommitOutcome) -> Result<CommitOutcome, String> {
4788 if let Some((commit, initial)) = self
4789 .failed_commits
4790 .iter()
4791 .find(|(commit, _)| commit.client_commit_id == outcome.client_commit_id)
4792 {
4793 let mut rows = Vec::new();
4794 for operation in &commit.ops {
4795 let Some(table) = self.schema.table(&operation.table) else {
4797 continue;
4798 };
4799 let key =
4800 serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
4801 .map_err(|_| "sync.local_corrupt".to_owned())?;
4802 let base = self.stored_row(table, &operation.row_id, true)?;
4803 rows.push(RetainedCommitRow {
4804 table: operation.table.clone(),
4805 row_id: operation.row_id.clone(),
4806 unique_conflicts: if operation.upsert {
4807 self.unique_conflicts(
4808 table,
4809 initial
4810 .get(&key)
4811 .and_then(Value::as_object)
4812 .or(operation.values.as_ref())
4813 .ok_or("sync.local_corrupt")?,
4814 true,
4815 )?
4816 } else {
4817 Vec::new()
4818 },
4819 local_row: if operation.upsert {
4820 initial
4821 .get(&key)
4822 .and_then(Value::as_object)
4823 .cloned()
4824 .or_else(|| operation.values.clone())
4825 } else {
4826 None
4827 },
4828 server_row: base.as_ref().map(|(values, _)| {
4829 table
4830 .columns
4831 .iter()
4832 .zip(values)
4833 .map(|(column, value)| {
4834 (column.name.clone(), column_value_to_json(value))
4835 })
4836 .collect()
4837 }),
4838 server_version: base.map(|(_, version)| version),
4839 });
4840 }
4841 outcome.retained_rows = Some(rows);
4842 }
4843 Ok(outcome)
4844 }
4845
4846 pub fn commit_outcome(&self, client_commit_id: &str) -> Result<Option<CommitOutcome>, String> {
4847 let row = self
4848 .conn
4849 .query_row(
4850 "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
4851 resolution, resolved_at_ms, replacement_client_commit_id
4852 FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
4853 rusqlite::params![client_commit_id],
4854 |row| {
4855 Ok(StoredCommitOutcomeRow {
4856 sequence: row.get(0)?,
4857 client_commit_id: row.get(1)?,
4858 status: row.get(2)?,
4859 recorded_at_ms: row.get(3)?,
4860 results_json: row.get(4)?,
4861 operations_json: row.get(5)?,
4862 resolution: row.get(6)?,
4863 resolved_at_ms: row.get(7)?,
4864 replacement_client_commit_id: row.get(8)?,
4865 })
4866 },
4867 )
4868 .optional()
4869 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4870 row.map(|row| self.attach_retained_rows(Self::outcome_from_row(row)?))
4871 .transpose()
4872 }
4873
4874 #[doc(hidden)]
4876 pub fn prepare_current_base(
4877 &self,
4878 client_commit_id: &str,
4879 sequence: i64,
4880 ) -> Result<CurrentBasePreparation, CurrentBaseProof> {
4881 let outcome = self
4882 .commit_outcome(client_commit_id)
4883 .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?;
4884 let valid = outcome.as_ref().is_some_and(|outcome| {
4885 outcome.sequence == sequence
4886 && outcome.resolution == CommitOutcomeResolution::Active
4887 && matches!(
4888 outcome.status,
4889 CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
4890 )
4891 && outcome
4892 .operations
4893 .as_ref()
4894 .zip(outcome.retained_rows.as_ref())
4895 .is_some_and(|(operations, rows)| {
4896 !rows.is_empty() && operations.len() == rows.len()
4897 })
4898 });
4899 if !valid {
4900 return Err(CurrentBaseProof::failure(
4901 CurrentBaseProofReason::OutcomeUnavailable,
4902 ));
4903 }
4904 if !self.transport_enabled {
4905 return Err(CurrentBaseProof::failure(CurrentBaseProofReason::Offline));
4906 }
4907 Ok(CurrentBasePreparation {
4908 client_commit_id: client_commit_id.to_owned(),
4909 sequence,
4910 units: load_units(&self.conn)
4911 .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?,
4912 transport_epoch: self.transport_epoch,
4913 registration_epoch: self.registration_epoch,
4914 security_epoch: self.security_epoch,
4915 })
4916 }
4917
4918 #[doc(hidden)]
4920 pub fn finish_current_base(
4921 &mut self,
4922 prepared: CurrentBasePreparation,
4923 drive: SyncOutcome,
4924 ) -> CurrentBaseProof {
4925 if !self.transport_enabled || self.transport_epoch != prepared.transport_epoch {
4926 return CurrentBaseProof::failure(CurrentBaseProofReason::Offline);
4927 }
4928 if self.registration_epoch != prepared.registration_epoch {
4929 return CurrentBaseProof::failure(CurrentBaseProofReason::MissingCoverage);
4930 }
4931 if self.security_preflight || self.security_epoch != prepared.security_epoch {
4932 return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed);
4933 }
4934 let report = match drive {
4935 SyncOutcome::Ok(report) => report,
4936 SyncOutcome::BudgetExhausted(_) => {
4937 return CurrentBaseProof::failure(CurrentBaseProofReason::BudgetExhausted)
4938 }
4939 _ => return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed),
4940 };
4941 if report.schema_floor.is_some() {
4942 return CurrentBaseProof::failure(CurrentBaseProofReason::SchemaFloor);
4943 }
4944 if self
4945 .conn
4946 .execute_batch("SAVEPOINT syncular_base_proof")
4947 .is_err()
4948 {
4949 return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
4950 }
4951 let proof = (|| {
4952 let snapshot = snapshot_read_connection(
4953 &self.conn,
4954 &SnapshotReadRequest {
4955 units: prepared.units.iter().map(|unit| unit.id.clone()).collect(),
4956 commit_ids: vec![prepared.client_commit_id.clone()],
4957 ..Default::default()
4958 },
4959 )
4960 .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4961 let current = self
4962 .commit_outcome(&prepared.client_commit_id)
4963 .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4964 let unavailable = if report.revoked.is_empty() {
4965 CurrentBaseProofReason::OutcomeUnavailable
4966 } else {
4967 CurrentBaseProofReason::Revoked
4968 };
4969 let Some(outcome) = current else {
4970 return Err(unavailable);
4971 };
4972 if !matches!(
4973 snapshot.deliveries.first(),
4974 Some(CommitDelivery::Known { .. })
4975 ) || outcome.sequence != prepared.sequence
4976 || outcome.resolution != CommitOutcomeResolution::Active
4977 || !matches!(
4978 outcome.status,
4979 CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
4980 )
4981 {
4982 return Err(unavailable);
4983 }
4984 let (Some(operations), Some(rows)) = (outcome.operations, outcome.retained_rows) else {
4985 return Err(unavailable);
4986 };
4987 if rows.is_empty() || operations.len() != rows.len() {
4988 return Err(unavailable);
4989 }
4990 let after =
4991 load_units(&self.conn).map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4992 let complete: HashSet<&str> = snapshot
4993 .units
4994 .iter()
4995 .filter_map(|unit| match unit {
4996 UnitCatchup::Known {
4997 id,
4998 bootstrap_complete: true,
4999 ..
5000 } => Some(id.as_str()),
5001 _ => None,
5002 })
5003 .collect();
5004 let candidates: Vec<&UnitRecord> = after
5007 .iter()
5008 .filter(|unit| {
5009 complete.contains(unit.id.as_str())
5010 && prepared.units.iter().any(|before| before.id == unit.id)
5011 })
5012 .collect();
5013 let covered = |table_name: &str, row: &Map<String, Value>| {
5014 let Some(table) = self.schema.table(table_name) else {
5015 return false;
5016 };
5017 candidates.iter().any(|unit| {
5018 covers(table, &unit.scopes)
5019 && pair_scopes(&unit.scopes, table_name, unit.echo.as_deref()).is_some_and(
5020 |scopes| {
5021 scopes.iter().all(|(variable, allowed)| {
5022 table
5023 .scope_column(variable)
5024 .and_then(|column| match row.get(column) {
5025 Some(Value::String(value)) => Some(value.clone()),
5026 Some(Value::Bool(value)) => Some(value.to_string()),
5027 Some(Value::Number(value)) => {
5028 value.as_f64().map(|number| {
5029 ryu_js::Buffer::new()
5030 .format_finite(number)
5031 .to_owned()
5032 })
5033 }
5034 _ => None,
5035 })
5036 .is_some_and(|value| {
5037 !value.is_empty() && allowed.contains(&value)
5038 })
5039 })
5040 },
5041 )
5042 })
5043 };
5044 for row in &rows {
5045 let Some(base) = row.server_row.as_ref().or(row.local_row.as_ref()) else {
5046 return Err(if report.revoked.is_empty() {
5047 CurrentBaseProofReason::MissingCoverage
5048 } else {
5049 CurrentBaseProofReason::Revoked
5050 });
5051 };
5052 if !covered(&row.table, base)
5053 || row
5054 .unique_conflicts
5055 .iter()
5056 .any(|conflict| !covered(&row.table, &conflict.server_row))
5057 {
5058 return Err(if report.revoked.is_empty() {
5059 CurrentBaseProofReason::MissingCoverage
5060 } else {
5061 CurrentBaseProofReason::Revoked
5062 });
5063 }
5064 }
5065 Ok(rows)
5066 })();
5067 if self
5068 .conn
5069 .execute_batch("RELEASE syncular_base_proof")
5070 .is_err()
5071 {
5072 return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
5073 }
5074 match proof {
5075 Ok(rows) => CurrentBaseProof {
5076 proven: true,
5077 rows: Some(rows),
5078 reason: None,
5079 },
5080 Err(reason) => CurrentBaseProof::failure(reason),
5081 }
5082 }
5083
5084 pub fn prove_current_base(
5085 &mut self,
5086 transport: &mut dyn Transport,
5087 client_commit_id: &str,
5088 sequence: i64,
5089 max_rounds: Option<u32>,
5090 ) -> CurrentBaseProof {
5091 let prepared = match self.prepare_current_base(client_commit_id, sequence) {
5092 Ok(prepared) => prepared,
5093 Err(proof) => return proof,
5094 };
5095 let drive = self.sync_until_idle(transport, max_rounds);
5096 self.finish_current_base(prepared, drive)
5097 }
5098
5099 pub fn commit_outcomes(&self, query: CommitOutcomeQuery) -> Result<Vec<CommitOutcome>, String> {
5100 if query.limit == Some(0) {
5101 return Err("sync.invalid_request: commit outcome limit must be positive".to_owned());
5102 }
5103 let mut sql = String::from(
5104 "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
5105 resolution, resolved_at_ms, replacement_client_commit_id
5106 FROM _syncular_commit_outcomes",
5107 );
5108 if query.active_only {
5109 sql.push_str(" WHERE resolution = 'active' AND status IN ('conflict', 'rejected')");
5110 }
5111 sql.push_str(" ORDER BY seq DESC");
5112 if let Some(limit) = query.limit {
5113 sql.push_str(&format!(" LIMIT {limit}"));
5114 }
5115 let mut stmt = self
5116 .conn
5117 .prepare(&sql)
5118 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5119 let rows = stmt
5120 .query_map([], |row| {
5121 Ok(StoredCommitOutcomeRow {
5122 sequence: row.get(0)?,
5123 client_commit_id: row.get(1)?,
5124 status: row.get(2)?,
5125 recorded_at_ms: row.get(3)?,
5126 results_json: row.get(4)?,
5127 operations_json: row.get(5)?,
5128 resolution: row.get(6)?,
5129 resolved_at_ms: row.get(7)?,
5130 replacement_client_commit_id: row.get(8)?,
5131 })
5132 })
5133 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5134 let mut outcomes = Vec::new();
5135 for row in rows {
5136 outcomes.push(self.attach_retained_rows(Self::outcome_from_row(
5137 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
5138 )?)?);
5139 }
5140 Ok(outcomes)
5141 }
5142
5143 fn prune_commit_outcomes(&self) -> Result<(), String> {
5144 #[cfg(test)]
5145 self.outcome_prune_count
5146 .set(self.outcome_prune_count.get() + 1);
5147 let max_entries = self.limits.outcome_retention_max_entries.unwrap_or(1_000);
5148 let count = self
5149 .conn
5150 .query_row(
5151 "SELECT COUNT(*) FROM _syncular_commit_outcomes",
5152 [],
5153 |row| row.get::<_, i64>(0),
5154 )
5155 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5156 as usize;
5157 let excess = count.saturating_sub(max_entries);
5158 if excess == 0 {
5159 return Ok(());
5160 }
5161 let mut stmt = self
5162 .conn
5163 .prepare(
5164 "SELECT seq FROM _syncular_commit_outcomes
5165 WHERE status IN ('applied', 'cached') OR resolution != 'active'
5166 ORDER BY seq ASC LIMIT ?1",
5167 )
5168 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5169 let rows = stmt
5170 .query_map(rusqlite::params![excess as i64], |row| row.get::<_, i64>(0))
5171 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5172 let sequences = rows
5173 .collect::<Result<Vec<_>, _>>()
5174 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5175 drop(stmt);
5176 for sequence in sequences {
5177 self.conn
5178 .execute(
5179 "DELETE FROM _syncular_commit_outcomes WHERE seq = ?1",
5180 rusqlite::params![sequence],
5181 )
5182 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5183 }
5184 Ok(())
5185 }
5186
5187 pub fn units(&self) -> Result<Vec<UnitRecord>, String> {
5191 self.stored(load_units(&self.conn))
5192 }
5193
5194 pub fn unit(&self, id: &str) -> Result<Option<UnitRecord>, String> {
5195 self.stored(get_unit(&self.conn, id))
5196 }
5197
5198 pub fn subscribe(&mut self, scopes: UnitScopes) -> Result<String, String> {
5200 Ok(self.subscribe_many(vec![scopes])?.remove(0))
5201 }
5202
5203 pub fn subscribe_many(&mut self, units: Vec<UnitScopes>) -> Result<Vec<String>, String> {
5210 self.begin_observation("syncular_subscribe")?;
5211 let mut changed = false;
5212 let registered = (|| {
5213 let mut ids = Vec::with_capacity(units.len());
5214 for scopes in units {
5215 let (id, held) = self.hold_unit(scopes, true)?;
5216 changed |= held;
5217 ids.push(id);
5218 }
5219 self.conn
5220 .execute_batch("RELEASE syncular_subscribe")
5221 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5222 Ok(ids)
5223 })();
5224 let ids = match registered {
5225 Ok(ids) => ids,
5226 Err(error) => {
5227 self.rollback_observation("syncular_subscribe");
5228 return Err(error);
5229 }
5230 };
5231 if changed {
5232 self.registration_epoch = self.registration_epoch.wrapping_add(1);
5233 self.set_sync_needed(true, true);
5234 }
5235 Ok(ids)
5236 }
5237
5238 pub fn unsubscribe(&mut self, id: &str) -> Result<(), String> {
5241 let Some(unit) = self.stored(get_unit(&self.conn, id))? else {
5242 return Ok(());
5243 };
5244 if !unit.explicit {
5245 return Ok(());
5246 }
5247 if !self.stored(window_refs(&self.conn, id))?.is_empty() {
5248 return self.stored(save_unit(
5249 &self.conn,
5250 &UnitRecord {
5251 explicit: false,
5252 ..unit
5253 },
5254 ));
5255 }
5256 self.conn
5257 .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5258 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5259 self.registration_epoch = self.registration_epoch.wrapping_add(1);
5260 if unit.status == UnitStatus::Active {
5261 self.set_sync_needed(true, true);
5262 }
5263 Ok(())
5264 }
5265
5266 fn hold_unit(&mut self, scopes: UnitScopes, explicit: bool) -> Result<(String, bool), String> {
5270 if scopes.is_empty()
5271 || scopes.values().any(|value| value == "*")
5272 || !self
5273 .schema
5274 .tables
5275 .iter()
5276 .any(|table| covers(table, &scopes))
5277 {
5278 return Err("sync.invalid_subscription: a unit names one non-wildcard value per variable and covers a table".to_owned());
5279 }
5280 let id = ssp2::registration::unit_id(&scope_pairs(&scopes));
5281 let existing = self.stored(get_unit(&self.conn, &id))?;
5282 if let Some(existing) = existing
5283 .as_ref()
5284 .filter(|unit| unit.status != UnitStatus::Revoked)
5285 {
5286 if explicit && !existing.explicit {
5287 self.stored(save_unit(
5288 &self.conn,
5289 &UnitRecord {
5290 explicit,
5291 ..existing.clone()
5292 },
5293 ))?;
5294 }
5295 return Ok((id, false));
5296 }
5297 self.delete_pending_evict(&id)?;
5298 self.stored(save_unit(
5299 &self.conn,
5300 &UnitRecord {
5301 id: id.clone(),
5302 scopes,
5303 explicit: explicit || existing.is_some_and(|unit| unit.explicit),
5304 status: UnitStatus::Active,
5305 reason_code: None,
5306 cursor: Some(-1),
5307 bootstrap_state: None,
5308 seeded: Vec::new(),
5309 echo: None,
5310 },
5311 ))?;
5312 Ok((id, true))
5313 }
5314
5315 pub fn set_window(
5323 &mut self,
5324 base: &WindowBase,
5325 units: &[String],
5326 ) -> Result<CommandEffects, String> {
5327 let base_key = window_base_key(base);
5328 let live = self.load_window_units(&base_key)?;
5329 let mut changed = false;
5330 for value in units {
5331 if live.iter().any(|(held, _)| held == value) {
5332 continue;
5333 }
5334 let rollback = self.capture();
5335 self.begin_observation("syncular_window")?;
5336 let widened = (|| {
5337 let (id, registered) = self.hold_unit(window_unit_scopes(base, value), false)?;
5338 self.sync_needed |= registered;
5339 self.conn
5340 .execute(
5341 "INSERT OR REPLACE INTO _syncular_windows(base, unit, sub_id) VALUES (?1, ?2, ?3)",
5342 rusqlite::params![base_key, value, id],
5343 )
5344 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5345 let mut batch = ChangeAccumulator::default();
5346 batch.window(&base_key, value);
5347 batch.status = true;
5348 self.finish_observation("syncular_window", batch)
5349 })();
5350 if let Err(error) = widened {
5351 self.rollback_observation("syncular_window");
5352 self.restore(rollback);
5353 return Err(error);
5354 }
5355 changed = true;
5356 self.registration_epoch = self.registration_epoch.wrapping_add(1);
5357 }
5358 for (value, id) in live {
5359 if units.contains(&value) {
5360 continue;
5361 }
5362 self.rebuild_overlay_if_dirty()?;
5363 let rollback = self.capture();
5364 self.begin_observation("syncular_window")?;
5365 let remaining = self.release_window_unit(&base_key, &value, &id);
5366 let remaining = match remaining {
5367 Ok(remaining) => remaining,
5368 Err(error) => {
5369 self.rollback_observation("syncular_window");
5370 self.restore(rollback);
5371 return Err(error);
5372 }
5373 };
5374 changed = true;
5375 self.registration_epoch = self.registration_epoch.wrapping_add(1);
5376 if remaining {
5377 self.drain_pending_evictions()?;
5378 }
5379 }
5380 Ok(if changed && self.transport_enabled {
5381 CommandEffects::interactive()
5382 } else {
5383 CommandEffects::none()
5384 })
5385 }
5386
5387 pub fn window_state(&self, base: &WindowBase) -> Result<WindowState, String> {
5391 persisted_window_state(&self.conn, base).map_err(|failure| failure.message)
5392 }
5393
5394 fn load_window_units(&self, base_key: &str) -> Result<Vec<(String, String)>, String> {
5396 let mut statement = self
5397 .conn
5398 .prepare_cached(
5399 "SELECT unit, sub_id FROM _syncular_windows WHERE base = ?1 ORDER BY unit ASC",
5400 )
5401 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5402 let rows = statement
5403 .query_map([base_key], |row| Ok((row.get(0)?, row.get(1)?)))
5404 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5405 rows.collect::<Result<_, _>>()
5406 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5407 }
5408
5409 fn load_window_registry(&self) -> Result<Vec<(String, String)>, String> {
5411 let mut statement = self
5412 .conn
5413 .prepare_cached("SELECT base, unit FROM _syncular_windows ORDER BY base, unit")
5414 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5415 let rows = statement
5416 .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))
5417 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5418 rows.collect::<Result<_, _>>()
5419 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5420 }
5421
5422 fn release_window_unit(
5430 &mut self,
5431 base_key: &str,
5432 value: &str,
5433 id: &str,
5434 ) -> Result<bool, String> {
5435 self.conn
5436 .execute(
5437 "DELETE FROM _syncular_windows WHERE base = ?1 AND unit = ?2",
5438 rusqlite::params![base_key, value],
5439 )
5440 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5441 let mut batch = ChangeAccumulator::default();
5442 batch.window(base_key, value);
5443 batch.status = true;
5444 let unit = self.stored(get_unit(&self.conn, id))?;
5445 let mut remaining = false;
5446 if let Some(unit) = unit.filter(|unit| !unit.explicit) {
5447 if self.stored(window_refs(&self.conn, id))?.is_empty() {
5448 let units = self.stored(load_units(&self.conn))?;
5449 self.conn
5450 .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5451 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5452 self.sync_needed = true;
5453 for table in self.schema.tables.clone() {
5454 let Some(effective) = unit
5455 .echo
5456 .as_deref()
5457 .filter(|_| covers(&table, &unit.scopes))
5458 .and_then(|echo| pair_scopes(&unit.scopes, &table.name, Some(echo)))
5459 else {
5460 continue;
5461 };
5462 let pinned = self.pinned_row_ids(&table.name);
5463 let owners = unit_owners(&units, &table, id);
5464 let (more, deferred) =
5465 self.evict_scope_rows(&table.name, &effective, &owners, &pinned)?;
5466 remaining |= more;
5467 if deferred {
5468 self.save_pending_evict(id, &table.name, &effective)?;
5469 }
5470 self.record_scope_map(&mut batch, &table.name, &effective);
5471 }
5472 }
5473 }
5474 self.finish_observation("syncular_window", batch)?;
5475 Ok(remaining)
5476 }
5477
5478 fn evict_scope_rows(
5483 &self,
5484 table_name: &str,
5485 effective: &[(String, Vec<String>)],
5486 owners: &[Vec<(String, Vec<String>)>],
5487 pinned: &std::collections::HashSet<String>,
5488 ) -> Result<(bool, bool), String> {
5489 let table = self.schema.table(table_name).ok_or("sync.unknown_table")?;
5490 let Some((scope, mut params)) = local_scope_predicate(table, effective, owners)
5491 .map_err(|()| "sync.scope_revoked".to_owned())?
5492 else {
5493 return Ok((false, false));
5494 };
5495 let scope_params = params.len();
5496 let pk = quote_ident(&table.primary_key);
5497 let predicate = if pinned.is_empty() {
5499 scope.clone()
5500 } else {
5501 params.extend(pinned.iter().cloned().map(SqlValue::Text));
5502 let holes = vec!["?"; pinned.len()].join(", ");
5503 format!("{scope} AND CAST({pk} AS TEXT) NOT IN ({holes})")
5504 };
5505 let base = base_table(table_name);
5506 let visible = visible_table(table_name);
5507 let mut ids: Vec<SqlValue> = Vec::new();
5508 for source in [&base, &visible] {
5509 let mut stmt = self
5510 .conn
5511 .prepare_cached(&format!(
5512 "SELECT {pk} FROM {source} WHERE {predicate} LIMIT 1024"
5513 ))
5514 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5515 ids = stmt
5516 .query_map(rusqlite::params_from_iter(¶ms), |row| row.get(0))
5517 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5518 .collect::<Result<_, _>>()
5519 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5520 if !ids.is_empty() {
5521 break;
5522 }
5523 }
5524 if !ids.is_empty() {
5525 for id in &ids {
5526 self.conn
5527 .execute(
5528 "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2",
5529 rusqlite::params![table_name, id],
5530 )
5531 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5532 }
5533 let holes = vec!["?"; ids.len()].join(", ");
5534 for source in [&base, &visible] {
5535 self.conn
5536 .execute(
5537 &format!("DELETE FROM {source} WHERE {pk} IN ({holes})"),
5538 rusqlite::params_from_iter(&ids),
5539 )
5540 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5541 }
5542 }
5543 let mut remaining = false;
5544 let mut deferred = false;
5545 for source in [&base, &visible] {
5546 remaining |= self
5547 .conn
5548 .query_row(
5549 &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
5550 rusqlite::params_from_iter(¶ms),
5551 |row| row.get::<_, bool>(0),
5552 )
5553 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5554 deferred |= self
5555 .conn
5556 .query_row(
5557 &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {scope})"),
5558 rusqlite::params_from_iter(¶ms[..scope_params]),
5559 |row| row.get::<_, bool>(0),
5560 )
5561 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5562 }
5563 Ok((remaining, deferred))
5564 }
5565
5566 fn drain_pending_evictions(&mut self) -> Result<(), String> {
5570 let pending = self.load_pending_evictions()?;
5571 if pending.is_empty() {
5572 return Ok(());
5573 }
5574 self.rebuild_overlay_if_dirty()?;
5575 for (unit_id, table_name, effective) in pending {
5576 let Some(table) = self.schema.table(&table_name).cloned() else {
5577 self.delete_pending_evict_table(&unit_id, &table_name)?;
5578 continue;
5579 };
5580 loop {
5581 std::thread::yield_now();
5582 self.begin_observation("syncular_evict")?;
5583 let chunk = (|| {
5584 let pinned = self.pinned_row_ids(&table_name);
5585 let owners =
5586 unit_owners(&self.stored(load_units(&self.conn))?, &table, &unit_id);
5587 let (remaining, deferred) =
5588 self.evict_scope_rows(&table_name, &effective, &owners, &pinned)?;
5589 if !deferred {
5590 self.delete_pending_evict_table(&unit_id, &table_name)?;
5591 }
5592 let mut batch = ChangeAccumulator::default();
5593 self.record_scope_map(&mut batch, &table_name, &effective);
5594 self.finish_observation("syncular_evict", batch)?;
5595 Ok(remaining)
5596 })();
5597 match chunk {
5598 Ok(true) => {}
5599 Ok(false) => break,
5600 Err(error) => {
5601 self.rollback_observation("syncular_evict");
5602 return Err(error);
5603 }
5604 }
5605 }
5606 }
5607 Ok(())
5608 }
5609
5610 fn pinned_row_ids(&self, table: &str) -> std::collections::HashSet<String> {
5613 let mut pinned = std::collections::HashSet::new();
5614 for commit in self
5615 .outbox
5616 .iter()
5617 .map(|commit| &**commit)
5618 .chain(self.failed_commits.iter().map(|(commit, _)| commit))
5619 {
5620 for op in &commit.ops {
5621 if op.table == table {
5622 pinned.insert(op.row_id.clone());
5623 }
5624 }
5625 }
5626 pinned
5627 }
5628
5629 fn save_pending_evict(
5630 &self,
5631 unit_id: &str,
5632 table: &str,
5633 effective: &[(String, Vec<String>)],
5634 ) -> Result<(), String> {
5635 self.conn.execute(
5636 "INSERT OR REPLACE INTO _syncular_pending_evictions(unit_id, tbl, effective_scopes) VALUES (?1, ?2, ?3)",
5637 rusqlite::params![unit_id, table, scope_map_to_json(effective).to_string()],
5638 ).map(|_| ()).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5639 }
5640
5641 fn delete_pending_evict(&self, unit_id: &str) -> Result<(), String> {
5643 self.conn
5644 .execute(
5645 "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
5646 [unit_id],
5647 )
5648 .map(|_| ())
5649 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5650 }
5651
5652 fn delete_pending_evict_table(&self, unit_id: &str, table: &str) -> Result<(), String> {
5653 self.conn
5654 .execute(
5655 "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1 AND tbl = ?2",
5656 [unit_id, table],
5657 )
5658 .map(|_| ())
5659 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5660 }
5661
5662 fn load_pending_evictions(&self) -> Result<Vec<PendingEvict>, String> {
5663 let mut stmt = self
5664 .conn
5665 .prepare("SELECT unit_id, tbl, effective_scopes FROM _syncular_pending_evictions")
5666 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5667 let rows = stmt
5668 .query_map([], |row| {
5669 Ok((
5670 row.get::<_, String>(0)?,
5671 row.get::<_, String>(1)?,
5672 row.get::<_, String>(2)?,
5673 ))
5674 })
5675 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5676 rows.map(|row| {
5677 let (unit_id, table, json) =
5678 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5679 let value: Value = serde_json::from_str(&json)
5680 .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5681 let effective = json_to_scope_map(&value)
5682 .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5683 Ok((unit_id, table, effective))
5684 })
5685 .collect()
5686 }
5687
5688 pub fn set_retain_failed_commits(&mut self, enabled: bool) -> Result<(), String> {
5690 self.retain_failed_commits = enabled;
5691 for (commit, _) in self.failed_commits.iter() {
5692 for operation in &commit.ops {
5693 self.overlay_dirty.table(&operation.table);
5694 }
5695 }
5696 self.failed_commits = self.load_failed_commits()?.into();
5697 for (commit, _) in self.failed_commits.iter() {
5698 for operation in &commit.ops {
5699 self.overlay_dirty.table(&operation.table);
5700 }
5701 }
5702 Ok(())
5703 }
5704
5705 fn load_failed_commits(&self) -> Result<Vec<FailedCommit>, String> {
5706 let mut statement = self.conn.prepare("SELECT client_commit_id, operations_json, initial_json FROM _syncular_failed_commits ORDER BY seq")
5707 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5708 let rows = statement
5709 .query_map([], |row| {
5710 Ok((
5711 row.get::<_, String>(0)?,
5712 row.get::<_, String>(1)?,
5713 row.get::<_, String>(2)?,
5714 ))
5715 })
5716 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5717 rows.map(|row| {
5718 let (id, operations, initial) =
5719 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5720 let operations: Vec<CommitOperation> =
5721 serde_json::from_str(&operations).map_err(|_| "sync.local_corrupt".to_owned())?;
5722 let initial =
5723 serde_json::from_str(&initial).map_err(|_| "sync.local_corrupt".to_owned())?;
5724 Ok((
5725 OutboxCommit {
5726 client_commit_id: id,
5727 ops: operations
5728 .into_iter()
5729 .map(|op| OutboxOp {
5730 upsert: op.op == "upsert",
5731 table: op.table,
5732 row_id: op.row_id,
5733 base_version: op.base_version,
5734 values: op.values,
5735 insert: op.insert,
5736 })
5737 .collect(),
5738 },
5739 initial,
5740 ))
5741 })
5742 .collect()
5743 }
5744
5745 fn retain_failed_commit(&mut self, id: &str, operations: &[OutboxOp]) -> Result<(), String> {
5746 let mut initial = Map::new();
5747 for operation in operations {
5748 let Some(table) = self.schema.table(&operation.table) else {
5750 continue;
5751 };
5752 let initial_row = match self.stored_row(table, &operation.row_id, true)? {
5753 Some(row) => Some(row),
5754 None => self.visible_row(table, &operation.row_id)?,
5755 };
5756 if let Some((values, _)) = initial_row {
5757 let mut intended: Map<String, Value> = table
5758 .columns
5759 .iter()
5760 .zip(values.iter())
5761 .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
5762 .collect();
5763 if let Some(patch) = &operation.values {
5764 intended.extend(patch.clone());
5765 }
5766 initial.insert(
5767 serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
5768 .map_err(|_| "sync.local_corrupt".to_owned())?,
5769 Value::Object(intended),
5770 );
5771 }
5772 }
5773 self.conn.execute("INSERT INTO _syncular_failed_commits(client_commit_id, operations_json, initial_json) VALUES (?1, ?2, ?3)", rusqlite::params![id,
5774 serde_json::to_string(&operations.iter().map(CommitOperation::from).collect::<Vec<_>>()).map_err(|_| "sync.local_corrupt".to_owned())?,
5775 serde_json::to_string(&initial).map_err(|_| "sync.local_corrupt".to_owned())?])
5776 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5777 self.failed_commits.push((
5778 OutboxCommit {
5779 client_commit_id: id.to_owned(),
5780 ops: operations.to_vec(),
5781 },
5782 initial,
5783 ));
5784 Ok(())
5785 }
5786
5787 fn drop_failed_commits(
5788 &mut self,
5789 matches: impl Fn(&str, &Map<String, Value>) -> bool,
5790 ) -> Result<Vec<OutboxCommit>, String> {
5791 let mut doomed = self.drop_acknowledged_rows(&matches)?;
5792 for (commit, initial) in self.failed_commits.iter() {
5793 for operation in &commit.ops {
5794 let key =
5795 serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
5796 .map_err(|_| "sync.local_corrupt".to_owned())?;
5797 if initial
5798 .get(&key)
5799 .and_then(Value::as_object)
5800 .is_some_and(|values| matches(&operation.table, values))
5801 {
5802 doomed.push(commit.clone());
5803 break;
5804 }
5805 }
5806 }
5807 for commit in &doomed {
5808 self.conn
5809 .execute(
5810 "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
5811 rusqlite::params![commit.client_commit_id],
5812 )
5813 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5814 }
5815 for commit in &doomed {
5816 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))?;
5817 }
5818 self.conflicts.retain(|record| {
5819 !doomed
5820 .iter()
5821 .any(|commit| commit.client_commit_id == record.client_commit_id)
5822 });
5823 self.rejections.retain(|record| {
5824 !doomed
5825 .iter()
5826 .any(|commit| commit.client_commit_id == record.client_commit_id)
5827 });
5828 self.failed_commits.retain(|(commit, _)| {
5829 !doomed
5830 .iter()
5831 .any(|dropped| dropped.client_commit_id == commit.client_commit_id)
5832 });
5833 for commit in &doomed {
5834 for operation in &commit.ops {
5835 self.overlay_dirty.table(&operation.table);
5836 }
5837 }
5838 Ok(doomed)
5839 }
5840
5841 pub fn mutate(&mut self, mutations: Vec<Mutation>) -> Result<String, ClientError> {
5845 self.mutate_with_commit_id(mutations, None)
5846 }
5847
5848 pub fn mutate_with_commit_id(
5852 &mut self,
5853 mutations: Vec<Mutation>,
5854 client_commit_id: Option<String>,
5855 ) -> Result<String, ClientError> {
5856 let prior = self.storage_failure.borrow_mut().take();
5857 if let Some(id) = &client_commit_id {
5858 let held = if id.is_empty() {
5859 Err("sync.invalid_request: clientCommitId is empty".to_owned())
5860 } else {
5861 self.conn
5862 .query_row(
5863 "SELECT EXISTS(SELECT 1 FROM _syncular_outbox WHERE commit_id=?1 UNION ALL SELECT 1 FROM _syncular_commit_outcomes WHERE client_commit_id=?1)",
5864 [id],
5865 |row| row.get(0),
5866 )
5867 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5868 };
5869 match held {
5870 Ok(false) => {}
5871 Ok(true) => {
5872 return self.finish_authoring(
5873 prior,
5874 Err(ClientError {
5875 code: "client.commit_id_reused".to_owned(),
5876 message: "clientCommitId is held".to_owned(),
5877 details: Some(json!({ "clientCommitId": id })),
5878 retryable: false,
5879 }),
5880 )
5881 }
5882 Err(message) => return self.finish_authoring(prior, Err(message.into())),
5883 }
5884 }
5885 let outcome = (|| -> Result<String, ClientError> {
5886 if mutations.is_empty() {
5887 return Err(
5888 "sync.invalid_request: a commit must contain at least one operation (§6.1)"
5889 .to_owned()
5890 .into(),
5891 );
5892 }
5893 let mut ops = Vec::with_capacity(mutations.len());
5894 for mutation in mutations {
5895 match mutation {
5896 Mutation::Patch {
5897 table,
5898 values,
5899 base_version,
5900 } => {
5901 let schema_table = self
5902 .schema
5903 .table(&table)
5904 .ok_or_else(|| "sync.unknown_table".to_owned())?;
5905 let values = normalize_values_casing(schema_table, values)?;
5906 let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
5907 ops.push(self.prepare_patch(&table, &row_id, values, base_version)?);
5908 }
5909 Mutation::Upsert {
5910 table,
5911 values,
5912 base_version,
5913 } => {
5914 let schema_table = self.schema.table(&table).ok_or_else(|| {
5915 format!("sync.unknown_table: unknown table {table:?}")
5916 })?;
5917 let values = normalize_values_casing(schema_table, values)?;
5921 let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
5922 let values = full_row_values(schema_table, values)?;
5925 self.refuse_sealed_row(schema_table, &row_id)?;
5926 self.validate_author_encode(schema_table, &row_id, &values)?;
5932 let insert = !self.visible_row_exists(schema_table, &row_id)?;
5936 ops.push(OutboxOp {
5937 upsert: true,
5938 table,
5939 row_id,
5940 base_version,
5941 values: Some(values),
5942 insert,
5943 });
5944 }
5945 Mutation::Delete {
5946 table,
5947 row_id,
5948 base_version,
5949 } => {
5950 let schema_table = self.schema.table(&table).ok_or_else(|| {
5951 format!("sync.unknown_table: unknown table {table:?}")
5952 })?;
5953 self.refuse_sealed_row(schema_table, &row_id)?;
5954 if row_id.contains('\0') {
5956 return Err("sync.invalid_request: rowId holds U+0000 (§2.4)"
5957 .to_owned()
5958 .into());
5959 }
5960 ops.push(OutboxOp {
5961 upsert: false,
5962 table,
5963 row_id,
5964 base_version,
5965 values: None,
5966 insert: false,
5967 });
5968 }
5969 }
5970 }
5971 Ok(self.record_outbox_commit(ops, client_commit_id)?)
5972 })();
5973 self.finish_authoring(prior, outcome)
5974 }
5975
5976 fn finish_authoring(
5982 &self,
5983 prior: Option<QueryReadFailure>,
5984 outcome: Result<String, ClientError>,
5985 ) -> Result<String, ClientError> {
5986 let fresh = self.storage_failure.borrow_mut().take();
5987 *self.storage_failure.borrow_mut() = fresh.clone().or(prior);
5988 outcome.map_err(|error| fresh.map(ClientError::from).unwrap_or(error))
5989 }
5990
5991 fn record_outbox_commit(
5992 &mut self,
5993 ops: Vec<OutboxOp>,
5994 client_commit_id: Option<String>,
5995 ) -> Result<String, String> {
5996 let commit = OutboxCommit {
5997 client_commit_id: client_commit_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
5998 ops,
5999 };
6000 self.begin_observation("syncular_mutation")?;
6001 let mut batch = ChangeAccumulator::default();
6002 for op in &commit.ops {
6003 let mut precise = self.record_row_scopes(&mut batch, &op.table, &op.row_id, false);
6004 if let Some(values) = &op.values {
6005 if let Some(table) = self.schema.table(&op.table) {
6006 for scope in &table.scope_variables {
6007 if let Some(Value::String(value)) = values.get(&scope.column) {
6008 batch.scope(&op.table, format!("{}:{value}", scope.prefix));
6009 precise = true;
6010 }
6011 }
6012 }
6013 }
6014 if !precise {
6015 batch.table(&op.table);
6016 }
6017 }
6018 if let Err(error) = self.persist_outbox_insert(&commit) {
6019 self.rollback_observation("syncular_mutation");
6020 return Err(error);
6021 }
6022 let was_dirty = self.overlay_dirty.snapshot();
6028 let id = commit.client_commit_id.clone();
6029 let appended = self.rebuild_overlay_if_dirty().and_then(|()| {
6030 commit
6031 .ops
6032 .iter()
6033 .try_for_each(|op| self.apply_outbox_op(op))?;
6034 self.outbox.push(Arc::new(commit));
6035 batch.status = true;
6036 self.finish_observation("syncular_mutation", batch)
6037 .inspect_err(|_| drop(self.outbox.pop()))
6038 });
6039 if let Err(error) = appended {
6040 self.rollback_observation("syncular_mutation");
6041 self.overlay_dirty.restore(was_dirty);
6042 return Err(error);
6043 }
6044 Ok(id)
6045 }
6046
6047 pub fn patch(
6053 &mut self,
6054 table: &str,
6055 row_id: &str,
6056 partial: Map<String, Value>,
6057 base_version: Option<i64>,
6058 ) -> Result<String, ClientError> {
6059 let prior = self.storage_failure.borrow_mut().take();
6060 let outcome = self.perform_patch(table, row_id, partial, base_version);
6061 self.finish_authoring(prior, outcome)
6062 }
6063
6064 fn perform_patch(
6067 &mut self,
6068 table: &str,
6069 row_id: &str,
6070 partial: Map<String, Value>,
6071 base_version: Option<i64>,
6072 ) -> Result<String, ClientError> {
6073 let operation = self.prepare_patch(table, row_id, partial, base_version)?;
6074 Ok(self.record_outbox_commit(vec![operation], None)?)
6075 }
6076
6077 fn prepare_patch(
6078 &self,
6079 table: &str,
6080 row_id: &str,
6081 partial: Map<String, Value>,
6082 base_version: Option<i64>,
6083 ) -> Result<OutboxOp, ClientError> {
6084 let schema_table = self
6085 .schema
6086 .table(table)
6087 .ok_or_else(|| format!("sync.unknown_table: unknown table {table:?}"))?;
6088 let partial = normalize_values_casing(schema_table, partial)?;
6089 if let Some(pk) = partial.get(&schema_table.primary_key) {
6090 if render_row_id_json(Some(pk)).ok().as_deref() != Some(row_id) {
6091 return Err(invalid_authoring(
6092 "patch cannot change the primary key",
6093 json!({ "table": table }),
6094 ));
6095 }
6096 }
6097 if !self.visible_row_exists(schema_table, row_id)? {
6098 return Err("sync.row_missing: a sparse patch requires a local row"
6099 .to_owned()
6100 .into());
6101 }
6102 self.refuse_sealed_row(schema_table, row_id)?;
6103 for scope in &schema_table.scope_variables {
6113 if !partial.contains_key(&scope.column) || scope.column == schema_table.primary_key {
6114 continue;
6115 }
6116 let Some(column) = schema_table
6117 .columns
6118 .iter()
6119 .find(|column| column.name == scope.column)
6120 else {
6121 continue;
6122 };
6123 let stored = self
6124 .conn
6125 .query_row(
6126 &format!(
6127 "SELECT {} FROM {} WHERE {}",
6128 quote_ident(&scope.column),
6129 visible_table(&schema_table.name),
6130 row_id_predicate(schema_table)
6131 ),
6132 rusqlite::params![row_id],
6133 |row| Ok(sql_ref_to_json(column, row.get_ref(0)?)),
6134 )
6135 .optional()
6136 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6137 let incoming = json_to_column_value(column, partial.get(&scope.column))
6142 .ok()
6143 .map(|value| column_value_to_json(&value));
6144 let equal = stored.as_ref().is_some_and(|stored| {
6148 stored.get("$bytes").is_none() && incoming.as_ref() == Some(stored)
6149 });
6150 if !equal {
6151 return Err(invalid_authoring(
6152 "patch cannot write a scope column (§3.4)",
6153 json!({ "table": table, "column": scope.column }),
6154 ));
6155 }
6156 }
6157 let mut values = partial;
6158 for scope in &schema_table.scope_variables {
6161 values.remove(&scope.column);
6162 }
6163 let pk_value = match schema_table.columns[schema_table.pk_index].ty {
6164 ColumnType::Integer => match row_id.parse::<i64>() {
6166 Ok(v)
6167 if v.to_string() == row_id
6168 && (-ssp2::primitives::I64_SAFE_MAX..=ssp2::primitives::I64_SAFE_MAX)
6169 .contains(&v) =>
6170 {
6171 Value::from(v)
6172 }
6173 _ => {
6174 return Err(format!(
6175 "sync.invalid_request: table {table:?}: invalid integer primary key {row_id:?}"
6176 )
6177 .into())
6178 }
6179 },
6180 ColumnType::Boolean => match row_id {
6181 "true" => Value::Bool(true),
6182 "false" => Value::Bool(false),
6183 _ => {
6184 return Err(format!(
6185 "sync.invalid_request: table {table:?}: invalid boolean primary key {row_id:?}"
6186 )
6187 .into())
6188 }
6189 },
6190 _ => Value::from(row_id.to_owned()),
6191 };
6192 values.insert(schema_table.primary_key.clone(), pk_value);
6193 if let Some(column) = schema_table
6195 .columns
6196 .iter()
6197 .find(|column| !column.nullable && values.get(&column.name) == Some(&Value::Null))
6198 {
6199 return Err(invalid_authoring(
6200 "a non-nullable column is null (§6.1)",
6201 json!({ "table": table, "column": column.name }),
6202 ));
6203 }
6204 self.validate_author_encode(schema_table, row_id, &values)?;
6210 Ok(OutboxOp {
6211 upsert: true,
6212 table: table.to_owned(),
6213 row_id: row_id.to_owned(),
6214 base_version,
6215 values: Some(values),
6216 insert: false,
6217 })
6218 }
6219
6220 fn stored_key_fallback(
6225 &self,
6226 table: &TableSchema,
6227 row_id: &str,
6228 ) -> Result<Option<Row>, String> {
6229 let Some(selector) = self.encryption.key_id_columns.get(&table.name) else {
6230 return Ok(None);
6231 };
6232 let Some(index) = table
6233 .columns
6234 .iter()
6235 .position(|column| &column.name == selector)
6236 else {
6237 return Ok(None);
6238 };
6239 let sql = format!(
6240 "SELECT {} FROM {} WHERE {}",
6241 quote_ident(selector),
6242 visible_table(&table.name),
6243 row_id_predicate(table)
6244 );
6245 let key = self
6246 .conn
6247 .query_row(&sql, rusqlite::params![row_id], |row| {
6248 row.get::<_, Option<String>>(0)
6249 })
6250 .optional()
6251 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6252 .flatten()
6253 .filter(|key| !key.is_empty());
6254 let Some(key) = key else {
6255 return Ok(None);
6256 };
6257 let mut fallback: Row = vec![None; table.columns.len()];
6258 fallback[index] = Some(ColumnValue::String(key));
6259 Ok(Some(fallback))
6260 }
6261
6262 fn validate_author_encode(
6267 &self,
6268 table: &TableSchema,
6269 row_id: &str,
6270 values: &Map<String, Value>,
6271 ) -> Result<(), String> {
6272 match encode_sparse_row_json(table, row_id, values, &self.encryption, None) {
6273 Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => Ok(()),
6274 result => result.map(|_| ()),
6275 }
6276 }
6277
6278 fn drop_unencodable_outbox(
6292 &mut self,
6293 with_encryption: bool,
6294 batch: Option<&mut ChangeAccumulator>,
6295 ) -> Result<bool, String> {
6296 let mut failures = Vec::new();
6297 for commit in self.outbox.iter() {
6298 for op in &commit.ops {
6299 let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6300 continue;
6301 };
6302 let Some(values) = op.presented_values(table) else {
6305 continue;
6306 };
6307 let fallback = self.stored_key_fallback(table, &op.row_id)?;
6308 let failure = match encode_sparse_row_json(
6309 table,
6310 &op.row_id,
6311 &values,
6312 &self.encryption,
6313 fallback.as_ref(),
6314 ) {
6315 Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => {
6316 with_encryption.then_some((error, ENCRYPT_FAILED_CODE))
6317 }
6318 Err(error) if error.starts_with(INVALID_REQUEST_CODE) => Some((
6323 LEGACY_VALUE_REFUSAL_MESSAGE.to_owned(),
6324 OUTBOX_INCOMPATIBLE_CODE,
6325 )),
6326 _ => None,
6327 };
6328 if let Some((error, code)) = failure {
6329 failures.push((commit.clone(), error, code));
6330 break;
6331 }
6332 }
6333 }
6334 if failures.is_empty() {
6335 return Ok(false);
6336 }
6337 let rollback = self.capture();
6343 let owns_observation = batch.is_none();
6344 let owns_transaction = self.conn.is_autocommit();
6345 let mut domains = ChangeAccumulator::default();
6346 if owns_observation {
6347 self.begin_observation("syncular_value_recovery")?;
6348 }
6349 let dropped = (|| -> Result<(), String> {
6350 for (commit, message, code) in failures {
6351 if self.retain_failed_commits && code == ENCRYPT_FAILED_CODE {
6352 self.retain_failed_commit(&commit.client_commit_id, &commit.ops)?;
6353 }
6354 let representable = commit.ops.iter().all(Self::outbox_op_is_journalable);
6355 let rejection = RejectionRecord {
6356 client_commit_id: commit.client_commit_id.clone(),
6357 op_index: 0,
6358 code: code.to_owned(),
6359 message,
6360 retryable: false,
6361 details: (code == OUTBOX_INCOMPATIBLE_CODE).then(|| RejectionDetails {
6362 field_paths: None,
6363 reason: Some(INVALID_STORED_VALUES_REASON.to_owned()),
6364 required_action: None,
6365 references: None,
6366 }),
6367 operation: representable
6368 .then(|| commit.ops.first())
6369 .flatten()
6370 .map(CommitOperation::from),
6371 };
6372 self.persist_commit_outcome(
6373 &commit.client_commit_id,
6374 CommitOutcomeStatus::Rejected,
6375 &[CommitOperationOutcome::Error {
6376 rejection: rejection.clone(),
6377 }],
6378 representable.then_some(commit.ops.as_slice()),
6379 )?;
6380 self.delete_outbox_persisted(&commit.client_commit_id)?;
6381 self.outbox
6382 .retain(|candidate| candidate.client_commit_id != commit.client_commit_id);
6383 self.rejections.push(rejection);
6384 for operation in &commit.ops {
6385 domains.table(operation.table.as_str());
6386 }
6387 }
6388 domains.status = true;
6389 domains.rejections = true;
6390 domains.outcomes = true;
6391 self.prune_commit_outcomes()?;
6392 self.overlay_dirty.set(true);
6394 self.rebuild_overlay()?;
6395 Ok(())
6396 })();
6397 let result = match batch {
6398 Some(batch) => {
6399 if dropped.is_ok() {
6400 for table in domains.tables.keys() {
6401 batch.table(table.as_str());
6402 }
6403 batch.status |= domains.status;
6404 batch.rejections |= domains.rejections;
6405 batch.outcomes |= domains.outcomes;
6406 }
6407 dropped
6408 }
6409 None => {
6410 dropped.and_then(|()| self.finish_observation("syncular_value_recovery", domains))
6411 }
6412 };
6413 if let Err(error) = result {
6414 if owns_observation {
6415 if owns_transaction {
6416 if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
6417 let mut failure = self.storage_failure.borrow_mut();
6418 let failure =
6419 failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
6420 failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
6421 }
6422 } else {
6423 self.rollback_observation("syncular_value_recovery");
6424 }
6425 }
6426 self.restore(rollback);
6427 return Err(error);
6428 }
6429 Ok(true)
6430 }
6431
6432 pub fn pending_commit_ids(&self) -> Vec<String> {
6433 self.outbox
6434 .iter()
6435 .map(|c| c.client_commit_id.clone())
6436 .collect()
6437 }
6438
6439 pub fn pending_payloads(&self) -> Result<Vec<Vec<u8>>, String> {
6443 let mut payloads = Vec::new();
6444 for commit in self.outbox.iter() {
6445 for op in &commit.ops {
6446 let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6447 continue;
6448 };
6449 let Some(values) = op.presented_values(table) else {
6450 continue;
6451 };
6452 let fallback = self.stored_key_fallback(table, &op.row_id)?;
6453 if let Ok(payload) = encode_sparse_row_json(
6454 table,
6455 &op.row_id,
6456 &values,
6457 &self.encryption,
6458 fallback.as_ref(),
6459 ) {
6460 payloads.push(payload);
6461 }
6462 }
6463 }
6464 Ok(payloads)
6465 }
6466
6467 pub fn conflicts(&self) -> &[ConflictRecord] {
6468 &self.conflicts
6469 }
6470
6471 pub fn rejections(&self) -> &[RejectionRecord] {
6472 &self.rejections
6473 }
6474
6475 pub fn resolve_commit_outcome(
6476 &mut self,
6477 input: ResolveCommitOutcomeInput,
6478 ) -> Result<CommitOutcome, String> {
6479 let current = self
6480 .commit_outcome(&input.client_commit_id)?
6481 .ok_or_else(|| {
6482 format!(
6483 "sync.outcome_not_found: no durable outcome exists for {:?}",
6484 input.client_commit_id
6485 )
6486 })?;
6487 if current.resolution != CommitOutcomeResolution::Active {
6488 return Ok(current);
6489 }
6490 if input.resolution == CommitOutcomeResolution::Active {
6491 return Err("sync.invalid_request: resolution must leave active state".to_owned());
6492 }
6493 match input.resolution {
6494 CommitOutcomeResolution::Superseded => {
6495 let replacement = input
6496 .replacement_client_commit_id
6497 .as_deref()
6498 .filter(|value| !value.is_empty() && *value != input.client_commit_id)
6499 .ok_or_else(|| {
6500 "sync.invalid_request: superseded outcomes require a distinct replacementClientCommitId"
6501 .to_owned()
6502 })?;
6503 let _ = replacement;
6504 }
6505 _ if input.replacement_client_commit_id.is_some() => {
6506 return Err(
6507 "sync.invalid_request: replacementClientCommitId is valid only for superseded outcomes"
6508 .to_owned(),
6509 );
6510 }
6511 _ => {}
6512 }
6513 let allowed = match current.status {
6514 CommitOutcomeStatus::Conflict => matches!(
6515 input.resolution,
6516 CommitOutcomeResolution::ResolvedKeepServer | CommitOutcomeResolution::Superseded
6517 ),
6518 CommitOutcomeStatus::Rejected => {
6519 matches!(
6520 input.resolution,
6521 CommitOutcomeResolution::Superseded
6522 | CommitOutcomeResolution::ResolvedKeepServer
6523 )
6524 }
6525 CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => {
6526 input.resolution == CommitOutcomeResolution::Dismissed
6527 }
6528 };
6529 if !allowed {
6530 return Err(format!(
6531 "sync.invalid_request: resolution {:?} is invalid for {:?} outcome",
6532 input.resolution, current.status
6533 ));
6534 }
6535
6536 let rollback = self.capture();
6537 self.begin_observation("syncular_outcome_resolution")?;
6538 let result = (|| {
6539 self.conn
6540 .execute(
6541 "UPDATE _syncular_commit_outcomes
6542 SET resolution = ?1, resolved_at_ms = ?2,
6543 replacement_client_commit_id = ?3
6544 WHERE client_commit_id = ?4 AND resolution = 'active'",
6545 rusqlite::params![
6546 Self::outcome_resolution_name(input.resolution),
6547 self.clock_now_ms(),
6548 input.replacement_client_commit_id,
6549 input.client_commit_id
6550 ],
6551 )
6552 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6553 let resolved = self
6554 .commit_outcome(¤t.client_commit_id)?
6555 .ok_or_else(|| "sync.outcome_not_found: outcome disappeared".to_owned())?;
6556 self.conn
6557 .execute(
6558 "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
6559 rusqlite::params![input.client_commit_id],
6560 )
6561 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6562 for (commit, _) in self.failed_commits.iter() {
6563 if commit.client_commit_id == input.client_commit_id {
6564 for operation in &commit.ops {
6565 self.overlay_dirty.table(&operation.table);
6566 }
6567 }
6568 }
6569 self.failed_commits
6570 .retain(|(commit, _)| commit.client_commit_id != input.client_commit_id);
6571 self.prune_commit_outcomes()?;
6572 Ok(resolved)
6573 })();
6574 let resolved = match result {
6575 Ok(outcome) => outcome,
6576 Err(error) => {
6577 self.rollback_observation("syncular_outcome_resolution");
6578 self.restore(rollback);
6579 return Err(error);
6580 }
6581 };
6582 self.conflicts
6583 .retain(|record| record.client_commit_id != current.client_commit_id);
6584 self.rejections
6585 .retain(|record| record.client_commit_id != current.client_commit_id);
6586 let mut batch = ChangeAccumulator {
6587 conflicts: current.status == CommitOutcomeStatus::Conflict,
6588 rejections: current.status == CommitOutcomeStatus::Rejected,
6589 outcomes: true,
6590 ..ChangeAccumulator::default()
6591 };
6592 if let Some(operations) = ¤t.operations {
6593 for operation in operations {
6594 batch.table(&operation.table);
6595 }
6596 }
6597 if let Err(error) = self
6598 .rebuild_overlay_if_dirty()
6599 .and_then(|()| self.finish_observation("syncular_outcome_resolution", batch))
6600 {
6601 self.rollback_observation("syncular_outcome_resolution");
6602 self.restore(rollback);
6603 return Err(error);
6604 }
6605 Ok(resolved)
6606 }
6607
6608 pub fn schema_floor(&self) -> Option<&SchemaFloor> {
6609 self.schema_floor.as_ref()
6610 }
6611
6612 pub fn lease_state(&self) -> Option<&LeaseState> {
6614 self.lease_state.as_ref()
6615 }
6616
6617 fn record_lease_error(&mut self, code: &str) -> Result<(), String> {
6620 if code != "sync.auth_lease_required" && code != "sync.auth_lease_revoked" {
6621 return Ok(());
6622 }
6623 let mut next = self.lease_state.clone().unwrap_or_default();
6624 next.error_code = Some(code.to_owned());
6625 self.set_lease_state(Some(next))
6626 }
6627
6628 fn set_lease_state(&mut self, next: Option<LeaseState>) -> Result<(), String> {
6629 if self.lease_state == next {
6630 return Ok(());
6631 }
6632 self.begin_observation("syncular_lease")?;
6633 let rollback = self.capture();
6634 self.lease_state = next;
6635 let persisted = match &self.lease_state {
6636 Some(lease) => serde_json::to_string(lease)
6637 .map_err(|error| error.to_string())
6638 .and_then(|json| self.set_meta(LEASE_STATE_KEY, &json)),
6639 None => self.delete_meta(LEASE_STATE_KEY),
6640 };
6641 let batch = ChangeAccumulator {
6642 status: true,
6643 ..ChangeAccumulator::default()
6644 };
6645 if let Err(error) =
6646 persisted.and_then(|()| self.finish_observation("syncular_lease", batch))
6647 {
6648 self.rollback_observation("syncular_lease");
6649 self.restore(rollback);
6650 return Err(error);
6651 }
6652 Ok(())
6653 }
6654
6655 fn set_schema_floor(&mut self, next: Option<SchemaFloor>) -> Result<(), String> {
6656 if self.schema_floor == next {
6657 return Ok(());
6658 }
6659 self.begin_observation("syncular_schema_floor")?;
6660 let rollback = self.capture();
6661 self.stopped = next.is_some();
6662 self.schema_floor = next;
6663 let persisted = match &self.schema_floor {
6664 Some(floor) => serde_json::to_string(floor)
6665 .map_err(|error| error.to_string())
6666 .and_then(|json| self.set_meta(SCHEMA_FLOOR_KEY, &json)),
6667 None => self.delete_meta(SCHEMA_FLOOR_KEY),
6668 };
6669 let batch = ChangeAccumulator {
6670 status: true,
6671 ..ChangeAccumulator::default()
6672 };
6673 if let Err(error) =
6674 persisted.and_then(|()| self.finish_observation("syncular_schema_floor", batch))
6675 {
6676 self.rollback_observation("syncular_schema_floor");
6677 self.restore(rollback);
6678 return Err(error);
6679 }
6680 Ok(())
6681 }
6682
6683 fn set_upgrading(&mut self, value: bool) {
6684 if self.upgrading == value {
6685 return;
6686 }
6687 if self.begin_observation("syncular_upgrading").is_err() {
6688 return;
6689 }
6690 self.upgrading = value;
6691 let batch = ChangeAccumulator {
6692 status: true,
6693 ..ChangeAccumulator::default()
6694 };
6695 if self
6696 .finish_observation("syncular_upgrading", batch)
6697 .is_err()
6698 {
6699 self.rollback_observation("syncular_upgrading");
6700 }
6701 }
6702
6703 pub fn sync_needed(&self) -> bool {
6704 self.sync_needed
6705 }
6706
6707 pub fn read_rows(&self, table: &str) -> Result<Vec<RowState>, String> {
6708 let schema_table = self
6709 .schema
6710 .table(table)
6711 .ok_or_else(|| format!("unknown table {table:?}"))?;
6712 let sql = format!(
6713 "SELECT * FROM {} ORDER BY {} ASC",
6714 visible_table(table),
6715 quote_ident(&schema_table.primary_key)
6716 );
6717 let mut stmt = self
6718 .conn
6719 .prepare(&sql)
6720 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6721 let mut rows = stmt
6722 .query([])
6723 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6724 let mut out = Vec::new();
6725 while let Some(row) = rows
6726 .next()
6727 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6728 {
6729 let mut values = Map::new();
6730 for (i, column) in schema_table.columns.iter().enumerate() {
6731 let value = row
6732 .get_ref(i)
6733 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6734 values.insert(column.name.clone(), sql_ref_to_json(column, value));
6735 }
6736 let version: i64 = row
6737 .get(schema_table.columns.len())
6738 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6739 let row_id = match values.get(&schema_table.primary_key) {
6740 Some(Value::String(s)) => s.clone(),
6741 Some(Value::Number(n)) => n.to_string(),
6742 Some(Value::Bool(b)) => b.to_string(),
6743 other => format!("{}", other.cloned().unwrap_or(Value::Null)),
6744 };
6745 let sealed_key = if schema_table.has_encrypted_columns() {
6746 row.get(schema_table.columns.len() + 1)
6747 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6748 } else {
6749 None
6750 };
6751 out.push(RowState {
6752 row_id,
6753 version,
6754 values,
6755 sealed_key,
6756 });
6757 }
6758 Ok(out)
6759 }
6760
6761 #[cfg(feature = "crdt-yjs")]
6777 fn crdt_column_bytes(
6778 &self,
6779 table: &str,
6780 row_id: &str,
6781 column: &str,
6782 ) -> Result<Option<Vec<u8>>, String> {
6783 let schema_table = self
6784 .schema
6785 .table(table)
6786 .ok_or_else(|| format!("unknown table {table:?}"))?;
6787 let col = schema_table
6788 .columns
6789 .iter()
6790 .find(|c| c.name == column)
6791 .ok_or_else(|| format!("table {table:?} has no column {column:?}"))?;
6792 if col.ty != ColumnType::Crdt {
6793 return Err(format!("column {column:?} is not a crdt column (§5.10.1)"));
6794 }
6795 let sql = format!(
6796 "SELECT {} FROM {} WHERE {}",
6797 quote_ident(column),
6798 visible_table(table),
6799 row_id_predicate(schema_table)
6800 );
6801 let bytes: Option<Vec<u8>> = self
6802 .conn
6803 .prepare_cached(&sql)
6804 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6805 .query_row(rusqlite::params![row_id], |row| {
6806 row.get::<_, Option<Vec<u8>>>(0)
6807 })
6808 .map_err(|e| match e {
6809 rusqlite::Error::QueryReturnedNoRows => "no such row".to_owned(),
6810 other => Self::sqlite_failure(&self.storage_failure, other),
6811 })?;
6812 Ok(bytes)
6813 }
6814
6815 #[cfg(feature = "crdt-yjs")]
6819 pub fn crdt_text(
6820 &self,
6821 table: &str,
6822 row_id: &str,
6823 column: &str,
6824 name: &str,
6825 ) -> Result<String, String> {
6826 let bytes = self
6827 .crdt_column_bytes(table, row_id, column)?
6828 .unwrap_or_default();
6829 crate::crdt::text(&bytes, name)
6830 }
6831
6832 #[cfg(feature = "crdt-yjs")]
6836 pub fn crdt_insert_text(
6837 &mut self,
6838 table: &str,
6839 row_id: &str,
6840 column: &str,
6841 name: &str,
6842 index: u32,
6843 value: &str,
6844 ) -> Result<String, ClientError> {
6845 let prior = self.storage_failure.borrow_mut().take();
6846 let outcome = (|| -> Result<String, ClientError> {
6847 let current = self
6848 .crdt_column_bytes(table, row_id, column)?
6849 .unwrap_or_default();
6850 let update = crate::crdt::insert_text(¤t, name, index, value)?;
6851 self.perform_crdt_push_update(table, row_id, column, &update)
6852 })();
6853 self.finish_authoring(prior, outcome)
6854 }
6855
6856 #[cfg(feature = "crdt-yjs")]
6860 pub fn crdt_delete_text(
6861 &mut self,
6862 table: &str,
6863 row_id: &str,
6864 column: &str,
6865 name: &str,
6866 index: u32,
6867 len: u32,
6868 ) -> Result<String, ClientError> {
6869 let prior = self.storage_failure.borrow_mut().take();
6870 let outcome = (|| -> Result<String, ClientError> {
6871 let current = self
6872 .crdt_column_bytes(table, row_id, column)?
6873 .unwrap_or_default();
6874 let update = crate::crdt::delete_text(¤t, name, index, len)?;
6875 self.perform_crdt_push_update(table, row_id, column, &update)
6876 })();
6877 self.finish_authoring(prior, outcome)
6878 }
6879
6880 #[cfg(feature = "crdt-yjs")]
6885 pub fn crdt_apply_update(
6886 &mut self,
6887 table: &str,
6888 row_id: &str,
6889 column: &str,
6890 update: &[u8],
6891 ) -> Result<String, ClientError> {
6892 let prior = self.storage_failure.borrow_mut().take();
6893 let outcome = (|| -> Result<String, ClientError> {
6894 let current = self
6895 .crdt_column_bytes(table, row_id, column)?
6896 .unwrap_or_default();
6897 let next = crate::crdt::apply_update(¤t, update)?;
6898 self.perform_crdt_push_update(table, row_id, column, &next)
6899 })();
6900 self.finish_authoring(prior, outcome)
6901 }
6902
6903 #[cfg(feature = "crdt-yjs")]
6910 fn perform_crdt_push_update(
6911 &mut self,
6912 table: &str,
6913 row_id: &str,
6914 column: &str,
6915 crdt_bytes: &[u8],
6916 ) -> Result<String, ClientError> {
6917 let mut bytes_obj = Map::new();
6918 bytes_obj.insert("$bytes".to_owned(), Value::from(bytes_to_hex(crdt_bytes)));
6919 let mut partial = Map::new();
6920 partial.insert(column.to_owned(), Value::Object(bytes_obj));
6921 self.perform_patch(table, row_id, partial, None)
6922 }
6923
6924 pub fn query(&self, sql: &str, params: &[QueryValue]) -> Result<Vec<QueryRow>, String> {
6939 query_connection(&self.conn, sql, params).map_err(|failure| failure.to_string())
6940 }
6941
6942 #[cfg(feature = "bench-internals")]
6944 #[doc(hidden)]
6945 pub fn benchmark_connection(&mut self) -> &mut Connection {
6946 &mut self.conn
6947 }
6948
6949 #[cfg(feature = "bench-internals")]
6951 #[doc(hidden)]
6952 pub fn benchmark_phases(
6953 &self,
6954 enabled: Option<bool>,
6955 reset: bool,
6956 ) -> Result<Option<Value>, String> {
6957 self.benchmark_phases.configure(enabled, reset)?;
6958 Ok(self.benchmark_phases.snapshot())
6959 }
6960
6961 pub fn authority_snapshot(&self) -> Result<Value, String> {
6963 validate_authority_reads(&self.schema, &self.limits.authority_reads)?;
6964 if self.limits.authority_reads.is_empty() {
6965 return Err("client.authority_read_forbidden: no authority reads were declared at client creation".into());
6966 }
6967 self.conn
6968 .execute_batch("SAVEPOINT authority_snapshot")
6969 .map_err(|e| e.to_string())?;
6970 let result = (|| {
6971 let revision = self
6972 .get_meta(LOCAL_REVISION_KEY)?
6973 .ok_or("sync.local_corrupt: authority revision is missing")?;
6974 let parsed_revision = revision
6975 .parse::<u64>()
6976 .map_err(|_| "sync.local_corrupt: authority revision is invalid")?;
6977 if parsed_revision.to_string() != revision {
6978 return Err("sync.local_corrupt: authority revision is invalid".into());
6979 }
6980 let mut tables = Vec::new();
6981 for read in &self.limits.authority_reads {
6982 let table = self
6983 .schema
6984 .table(&read.table)
6985 .ok_or("client.authority_read_forbidden: authority table is not declared")?;
6986 let scalar = |column: &str, value: &Value| -> Result<String, String> {
6987 let ty = table
6988 .columns
6989 .iter()
6990 .find(|c| c.name == column)
6991 .expect("validated authority column")
6992 .ty;
6993 if ty == ColumnType::Boolean {
6994 if let Some(value) = value.as_bool() {
6995 return Ok(value.to_string());
6996 }
6997 return match value.as_i64() {
6998 Some(0) => Ok("false".into()),
6999 Some(1) => Ok("true".into()),
7000 _ => Err("sync.local_corrupt: authority boolean is invalid".into()),
7001 };
7002 }
7003 match value {
7004 Value::String(s) => Ok(s.clone()),
7005 Value::Number(n) => Ok(n.to_string()),
7006 Value::Object(o) if ty == ColumnType::Integer && o.len() == 1 => o
7007 .get("$bigint")
7008 .and_then(Value::as_str)
7009 .map(str::to_owned)
7010 .ok_or("sync.local_corrupt: authority integer is invalid".into()),
7011 _ => {
7012 Err("sync.local_corrupt: authority scalar is missing or invalid".into())
7013 }
7014 }
7015 };
7016 let matches = |row: &QueryRow| -> Result<bool, String> {
7017 for (variable, values) in &read.scopes {
7018 let column = table
7019 .scope_column(variable)
7020 .expect("validated authority scope");
7021 let value = row
7022 .get(column)
7023 .ok_or("sync.local_corrupt: authority scope column is missing")?;
7024 if value.is_null() || !values.contains(&scalar(column, value)?) {
7025 return Ok(false);
7026 }
7027 }
7028 Ok(true)
7029 };
7030 let selected = read
7031 .columns
7032 .iter()
7033 .map(|c| quote_ident(c))
7034 .collect::<Vec<_>>()
7035 .join(",");
7036 let mut intent = BTreeSet::new();
7037 let mut relevant = BTreeSet::new();
7038 for row in query_connection(&self.conn,
7039 "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=?",
7040 &[Value::String(read.table.clone())]).map_err(|e| e.to_string())? {
7041 let id = row.get("id").and_then(Value::as_str).ok_or("sync.local_corrupt: authority intent id is invalid")?.to_owned();
7042 intent.insert(id.clone());
7043 if let Some(raw) = row.get("values_json").and_then(Value::as_str) {
7044 let values: QueryRow = serde_json::from_str(raw).map_err(|_| "sync.local_corrupt: authority intent values are invalid")?;
7045 if read.scopes.keys().all(|v| values.contains_key(table.scope_column(v).expect("validated scope"))) && matches(&values)? {relevant.insert(id);}
7046 }
7047 }
7048 let mut rows = BTreeMap::new();
7049 for full in [base_table(&read.table), visible_table(&read.table)] {
7050 for mut values in query_connection(
7051 &self.conn,
7052 &format!(
7053 "SELECT {selected},_syncular_version AS authority_version FROM {full}"
7054 ),
7055 &[],
7056 )
7057 .map_err(|e| e.to_string())?
7058 {
7059 if !matches(&values)? {
7060 continue;
7061 }
7062 let id = scalar(
7063 &table.primary_key,
7064 values
7065 .get(&table.primary_key)
7066 .expect("selected primary key"),
7067 )?;
7068 relevant.insert(id.clone());
7069 if full == base_table(&read.table) {
7070 let version = values
7071 .remove("authority_version")
7072 .expect("selected version");
7073 let version = version
7074 .as_i64()
7075 .ok_or("sync.local_corrupt: authority server version is invalid")?;
7076 if version >= 0 {
7077 rows.insert(id.clone(), json!({"values": values, "version": version, "hasLocalIntent": intent.contains(&id)}));
7078 }
7079 }
7080 }
7081 }
7082 intent.retain(|id| relevant.contains(id));
7083 let rows = rows.into_values().collect::<Vec<_>>();
7084 let replica = self.stored(replica_cursor(&self.conn))?;
7086 let persisted = self
7087 .stored(load_units(&self.conn))?
7088 .into_iter()
7089 .filter(|unit| covers(table, &unit.scopes))
7090 .map(|unit| {
7091 let effective = unit.echo.as_deref().and_then(|echo| {
7092 pair_scopes(&unit.scopes, &read.table, Some(echo))
7093 });
7094 let requested = read
7095 .scopes
7096 .keys()
7097 .map(|v| (v.clone(), json!(unit.scopes.get(v).into_iter().collect::<Vec<_>>())))
7098 .collect::<Map<_, _>>();
7099 let complete = effective
7100 .as_ref()
7101 .is_some_and(|scopes| scopes.len() == read.scopes.len())
7102 && unit.status == UnitStatus::Active
7103 && !unit.bootstrapping();
7104 let exposed = effective.map(|scopes| {
7105 read.scopes
7106 .keys()
7107 .map(|v| {
7108 let held = scopes.iter().find(|(variable, _)| variable == v);
7109 (v.clone(), json!(held.map_or(&Vec::new(), |(_, values)| values)))
7110 })
7111 .collect::<Map<_, _>>()
7112 });
7113 json!({"requestedScopes": requested, "status": unit.status, "cursor": unit.cursor.unwrap_or(replica), "effectiveScopes": exposed, "complete": complete})
7114 })
7115 .collect::<Vec<_>>();
7116 fn covered(selectors: &[(&String, &Vec<String>)], candidates: &[&Value]) -> bool {
7117 match selectors.split_first() {
7118 None => !candidates.is_empty(),
7119 Some(((variable, values), rest)) => values.iter().all(|value| {
7120 covered(
7121 rest,
7122 &candidates
7123 .iter()
7124 .copied()
7125 .filter(|p| {
7126 p["effectiveScopes"][variable.as_str()]
7127 .as_array()
7128 .is_some_and(|held| {
7129 held.contains(&Value::String(value.clone()))
7130 || held.contains(&Value::String("*".into()))
7131 })
7132 })
7133 .collect::<Vec<_>>(),
7134 )
7135 }),
7136 }
7137 }
7138 let coverage = if covered(
7139 &read.scopes.iter().collect::<Vec<_>>(),
7140 &persisted
7141 .iter()
7142 .filter(|p| p["complete"] == true)
7143 .collect::<Vec<_>>(),
7144 ) {
7145 "complete"
7146 } else if persisted.iter().any(|p| {
7147 p["status"] == "active"
7148 && read.scopes.iter().all(|(v, values)| {
7149 values.iter().any(|value| {
7150 p["requestedScopes"][v].as_array().is_some_and(|held| {
7151 held.contains(&Value::String(value.clone()))
7152 })
7153 })
7154 })
7155 }) {
7156 "pending"
7157 } else {
7158 "missing"
7159 };
7160 tables.push(json!({"table": read.table, "rows": rows, "localIntentRowIds": intent, "scopes": read.scopes, "coverage": coverage, "persisted": persisted}));
7161 }
7162 Ok(
7163 json!({"revision": revision, "complete": tables.iter().all(|t| t["coverage"] == "complete"), "tables": tables}),
7164 )
7165 })();
7166 match result {
7167 Ok(snapshot) => {
7168 self.conn
7169 .execute_batch("RELEASE authority_snapshot")
7170 .map_err(|e| e.to_string())?;
7171 Ok(snapshot)
7172 }
7173 Err(error) => {
7174 self.conn
7175 .execute_batch("ROLLBACK TO authority_snapshot; RELEASE authority_snapshot")
7176 .map_err(|e| format!("{error}; rollback failed: {e}"))?;
7177 Err(error)
7178 }
7179 }
7180 }
7181
7182 pub fn query_snapshot(
7186 &mut self,
7187 sql: &str,
7188 params: &[QueryValue],
7189 coverage: &[WindowCoverage],
7190 owner: Option<QueryOwner<'_>>,
7191 ) -> Result<QuerySnapshot, String> {
7192 let result = snapshot_connection(&self.conn, sql, params, coverage);
7193 if let Some(owner) = owner {
7194 self.record_query_read(owner, result.as_ref().err());
7195 }
7196 result.map_err(|failure| failure.to_string())
7197 }
7198
7199 pub fn record_query_read(&mut self, owner: QueryOwner<'_>, failure: Option<&QueryReadFailure>) {
7203 let position = self
7204 .query_failures
7205 .iter()
7206 .position(|entry| entry.id == owner.id);
7207 let Some(failure) = failure else {
7208 if let Some(index) = position {
7209 self.query_failures.remove(index);
7210 }
7211 return;
7212 };
7213 let tables: Vec<String> = BTreeSet::from_iter(owner.tables.iter().copied())
7214 .into_iter()
7215 .map(str::to_owned)
7216 .collect();
7217 let code = failure.code.unwrap_or("client.query_failed").to_owned();
7218 if position.is_some_and(|index| {
7219 let entry = &self.query_failures[index];
7220 entry.tables == tables && entry.code == code && entry.sqlite_code == failure.sqlite_code
7221 }) {
7222 return;
7223 }
7224 if let Some(index) = position {
7225 self.query_failures.remove(index);
7226 }
7227 self.query_failures.push(DiagnosticQueryFailure {
7228 id: owner.id.to_owned(),
7229 tables,
7230 code,
7231 sqlite_code: failure.sqlite_code,
7232 at_ms: self.clock_now_ms(),
7233 });
7234 if self.query_failures.len() > MAX_DIAGNOSTIC_QUERY_FAILURES {
7235 self.query_failures.remove(0);
7236 }
7237 }
7238
7239 fn build_request(&self, url_capable: bool) -> Result<(Message, RequestMeta), Box<SyncOutcome>> {
7242 #[cfg(feature = "bench-internals")]
7243 let _phase = self.benchmark_phases.start(Phase::RequestPrepare);
7244 let log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7245 Box::new(SyncOutcome::Failed {
7246 error_code: "storage.failed".into(),
7247 message,
7248 details: None,
7249 recommended_action: None,
7250 })
7251 })?;
7252 let max_commits = self.limits.max_push_commits_per_request;
7253 let max_ops = self
7254 .limits
7255 .max_push_operations_per_request
7256 .unwrap_or(PUSH_OPS_PER_REQUEST);
7257 let byte_cap = self.limits.max_push_request_bytes;
7258 let accept = self.limits.accept.unwrap_or(if url_capable {
7261 DEFAULT_ACCEPT | ACCEPT_SIGNED_URLS
7262 } else {
7263 DEFAULT_ACCEPT
7264 });
7265 let storage_failed = |message: String| {
7266 Box::new(SyncOutcome::Failed {
7267 error_code: "storage.failed".into(),
7268 message,
7269 details: None,
7270 recommended_action: None,
7271 })
7272 };
7273 let header = Frame::ReqHeader {
7274 client_id: self.client_id.clone(),
7275 schema_version: self.schema.version,
7276 log_epoch: log_epoch.clone(),
7277 outbox_id: self.get_meta(OUTBOX_ID_KEY).map_err(storage_failed)?,
7278 };
7279 let mut lead = vec![header];
7283 lead.extend(
7284 self.round_failure
7285 .iter()
7286 .map(|code| Frame::RoundFailure { code: code.clone() }),
7287 );
7288 let registered: Vec<UnitRecord> = self
7289 .stored(load_units(&self.conn))
7290 .map_err(storage_failed)?
7291 .into_iter()
7292 .filter(|unit| unit.status == UnitStatus::Active)
7293 .collect();
7294 let registration_digest = ssp2::registration::registration_digest(
7295 registered
7296 .iter()
7297 .map(|unit| scope_pairs(&unit.scopes))
7298 .collect::<Vec<_>>()
7299 .iter()
7300 .map(Vec::as_slice),
7301 );
7302 let echo_digest = self
7303 .get_meta(ECHO_DIGEST_KEY)
7304 .map_err(storage_failed)?
7305 .filter(|hex| !hex.is_empty())
7306 .map(|hex| {
7307 crate::values::hex_to_bytes(&hex)
7308 .ok()
7309 .and_then(|bytes| <[u8; 32]>::try_from(bytes).ok())
7310 .ok_or_else(|| {
7311 "sync.local_corrupt: persisted echo digest is invalid".to_owned()
7312 })
7313 })
7314 .transpose()
7315 .map_err(storage_failed)?;
7316 let pull = Frame::PullHeader {
7317 limit_commits: self.limits.limit_commits.unwrap_or(0),
7318 limit_snapshot_rows: self.limits.limit_snapshot_rows.unwrap_or(0),
7319 max_snapshot_pages: self.limits.max_snapshot_pages.unwrap_or(0),
7320 accept,
7321 cursor: self
7322 .stored(replica_cursor(&self.conn))
7323 .map_err(storage_failed)?,
7324 registration_digest,
7325 echo_digest,
7326 };
7327 let registration_digest = bytes_to_hex(®istration_digest);
7328 let travels = self
7331 .get_meta(REGISTERED_DIGEST_KEY)
7332 .map_err(storage_failed)?
7333 .as_deref()
7334 != Some(registration_digest.as_str());
7335 let mut sub_frames: Vec<Frame> = Vec::new();
7336 if travels {
7337 sub_frames.extend(registered.iter().map(|unit| Frame::Unit {
7338 scopes: scope_pairs(&unit.scopes),
7339 }));
7340 }
7341 sub_frames.extend(registered.iter().filter_map(|unit| {
7343 Some(Frame::Progress {
7344 id: unit.id.clone(),
7345 cursor: unit.cursor?,
7346 bootstrap_state: unit.bootstrap_state.clone().map(RawJson),
7347 })
7348 }));
7349 let fixed_bytes = match byte_cap {
7352 Some(_) => {
7353 let mut frames = lead.clone();
7354 frames.push(pull.clone());
7355 frames.extend(sub_frames.iter().cloned());
7356 encode_message(&Message {
7357 wire_version: WIRE_VERSION,
7358 msg_kind: MsgKind::Request,
7359 frames,
7360 })
7361 .len()
7362 }
7363 None => 0,
7364 };
7365 if let Some(cap) = byte_cap {
7366 if fixed_bytes > cap {
7367 return Err(Self::push_capacity_outcome("bytes", cap, fixed_bytes, None));
7368 }
7369 }
7370 let base_bytes = match byte_cap {
7371 Some(_) => {
7372 let mut frames = lead.clone();
7373 frames.push(pull.clone());
7374 encode_message(&Message {
7375 wire_version: WIRE_VERSION,
7376 msg_kind: MsgKind::Request,
7377 frames,
7378 })
7379 .len()
7380 }
7381 None => 0,
7382 };
7383 let total_outbox = if log_epoch.is_some() {
7384 self.outbox.len()
7385 } else {
7386 0
7387 };
7388 let mut push_frames: Vec<Frame> = Vec::new();
7389 let mut pushed_ids = Vec::new();
7390 let mut ops_in_request = 0usize;
7391 let mut bytes_in_request = 0usize;
7392 let mut deferred_commits = 0usize;
7393 #[cfg(feature = "bench-internals")]
7394 let outbox_phase = self.benchmark_phases.start(Phase::OutboxEncode);
7395 for (index, commit) in self.outbox.iter().take(total_outbox).enumerate() {
7396 if max_commits.is_some_and(|cap| push_frames.len() >= cap) {
7400 deferred_commits = total_outbox - index;
7401 break;
7402 }
7403 if ops_in_request + commit.ops.len() > max_ops {
7404 if push_frames.is_empty() {
7405 return Err(Self::push_capacity_outcome(
7406 "operations",
7407 max_ops,
7408 commit.ops.len(),
7409 Some(commit.client_commit_id.as_str()),
7410 ));
7411 }
7412 deferred_commits = total_outbox - index;
7413 break;
7414 }
7415 if self.outbox[..index]
7418 .iter()
7419 .flat_map(|earlier| &earlier.ops)
7420 .any(|earlier| commit.ops.iter().any(|op| chains_on(earlier, op)))
7421 {
7422 deferred_commits = total_outbox - index;
7423 break;
7424 }
7425 let operations = commit
7426 .ops
7427 .iter()
7428 .map(|op| {
7429 let payload = match self
7430 .schema
7431 .table(&op.table)
7432 .and_then(|table| Some((table, op.presented_values(table)?)))
7433 {
7434 Some((table, values)) => {
7435 let fallback =
7445 self.stored_key_fallback(table, &op.row_id)
7446 .map_err(|message| {
7447 Box::new(SyncOutcome::Failed {
7448 error_code: "storage.failed".into(),
7449 message,
7450 details: None,
7451 recommended_action: None,
7452 })
7453 })?;
7454 encode_sparse_row_json(
7455 table,
7456 &op.row_id,
7457 &values,
7458 &self.encryption,
7459 fallback.as_ref(),
7460 )
7461 .ok()
7462 }
7463 None => None,
7464 };
7465 Ok(ssp2::model::Operation {
7466 table: op.table.clone(),
7467 row_id: op.row_id.clone(),
7468 op: if op.upsert { Op::Upsert } else { Op::Delete },
7469 base_version: op.base_version,
7470 payload,
7471 })
7472 })
7473 .collect::<Result<Vec<_>, Box<SyncOutcome>>>()?;
7474 let client_seq = self
7476 .conn
7477 .prepare_cached("SELECT seq FROM _syncular_outbox WHERE commit_id = ?1")
7478 .and_then(|mut statement| {
7479 statement.query_row([&commit.client_commit_id], |row| row.get(0))
7480 })
7481 .map_err(|error| {
7482 storage_failed(Self::sqlite_failure(&self.storage_failure, error))
7483 })?;
7484 let frame = Frame::PushCommit {
7485 client_commit_id: commit.client_commit_id.clone(),
7486 client_seq,
7487 operations,
7488 };
7489 let frame_bytes = match byte_cap {
7490 Some(_) => {
7491 let mut frames = lead.clone();
7492 frames.push(frame.clone());
7493 frames.push(pull.clone());
7494 encode_message(&Message {
7495 wire_version: WIRE_VERSION,
7496 msg_kind: MsgKind::Request,
7497 frames,
7498 })
7499 .len()
7500 - base_bytes
7501 }
7502 None => 0,
7503 };
7504 if let Some(cap) = byte_cap {
7508 if !push_frames.is_empty() && fixed_bytes + bytes_in_request + frame_bytes > cap {
7509 deferred_commits = total_outbox - index;
7510 break;
7511 }
7512 }
7513 push_frames.push(frame);
7514 pushed_ids.push(commit.client_commit_id.clone());
7515 ops_in_request += commit.ops.len();
7516 bytes_in_request += frame_bytes;
7517 }
7518 #[cfg(feature = "bench-internals")]
7519 drop(outbox_phase);
7520 if let Some(cap) = byte_cap {
7521 if fixed_bytes + bytes_in_request > cap {
7522 let blocked = if push_frames.is_empty() {
7525 None
7526 } else {
7527 self.outbox.first().map(|c| c.client_commit_id.as_str())
7528 };
7529 return Err(Self::push_capacity_outcome(
7530 "bytes",
7531 cap,
7532 fixed_bytes + bytes_in_request,
7533 blocked,
7534 ));
7535 }
7536 }
7537 let mut frames = lead;
7538 frames.extend(push_frames);
7539 frames.push(pull);
7540 frames.extend(sub_frames);
7541 let message = Message {
7542 wire_version: WIRE_VERSION,
7543 msg_kind: MsgKind::Request,
7544 frames,
7545 };
7546 Ok((
7547 message,
7548 RequestMeta {
7549 pushed_ids,
7550 registration_digest,
7551 accept,
7552 deferred_commits,
7553 applied: BTreeMap::new(),
7554 deferred: BTreeSet::new(),
7555 },
7556 ))
7557 }
7558
7559 fn push_capacity_outcome(
7561 kind: &str,
7562 limit: usize,
7563 size: usize,
7564 client_commit_id: Option<&str>,
7565 ) -> Box<SyncOutcome> {
7566 let mut details = Map::new();
7567 details.insert("kind".to_owned(), Value::from(kind));
7568 details.insert("limit".to_owned(), Value::from(limit as u64));
7569 details.insert("size".to_owned(), Value::from(size as u64));
7570 if let Some(id) = client_commit_id {
7571 details.insert("clientCommitId".to_owned(), Value::from(id));
7572 }
7573 Box::new(SyncOutcome::Failed {
7574 error_code: "client.push_request_too_large".into(),
7575 message: "the push request exceeds a configured capacity limit".into(),
7576 details: Some(Value::Object(details)),
7577 recommended_action: None,
7578 })
7579 }
7580
7581 pub fn progress(&self) -> ProgressObserver {
7585 self.progress.clone()
7586 }
7587
7588 pub fn sync(&mut self, transport: &mut dyn Transport) -> SyncOutcome {
7589 let prepared = match self.prepare_sync_round(transport.supports_url_fetch()) {
7590 Ok(prepared) => prepared,
7591 Err(outcome) => return *outcome,
7592 };
7593 let mut next = prepared;
7598 loop {
7599 match self.apply_sync_round(next.exchange(transport)) {
7600 crate::AppliedSyncRound::Continue(prepared) => next = prepared,
7601 crate::AppliedSyncRound::Complete {
7602 outcome, controls, ..
7603 } => {
7604 if self.transport_enabled {
7605 for text in controls {
7606 let _ = transport.realtime_send(&text);
7607 }
7608 } else {
7609 self.disconnect_realtime(transport);
7610 }
7611 return outcome;
7612 }
7613 }
7614 }
7615 }
7616
7617 fn finish_sync_round(&mut self, started_at_ms: i64, mut outcome: SyncOutcome) -> SyncOutcome {
7618 if let SyncOutcome::Failed {
7619 error_code,
7620 message,
7621 details,
7622 ..
7623 } = &mut outcome
7624 {
7625 if let Some((failure, code)) = self
7626 .storage_failure
7627 .borrow()
7628 .as_ref()
7629 .and_then(|failure| failure.code.map(|code| (failure, code)))
7630 {
7631 *error_code = code.to_owned();
7632 *message = match code {
7633 "client.storage_busy" => "local SQLite storage is busy",
7634 "client.storage_full" => "local SQLite storage is full",
7635 "client.storage_io" => "local SQLite storage I/O failed",
7636 "client.storage_corrupt" => "local SQLite storage is corrupt",
7637 _ => unreachable!("unrecognized classified storage failure"),
7638 }
7639 .to_owned();
7640 *details = failure.details();
7641 }
7642 }
7643 let details = match &outcome {
7644 SyncOutcome::Failed { details, .. } => details.as_ref(),
7645 _ => None,
7646 };
7647 let cause_kind = details
7648 .and_then(|details| details.get("causeKind"))
7649 .and_then(Value::as_str)
7650 .and_then(|cause| match cause {
7651 "network" => Some(crate::TransportCauseKind::Network),
7652 "connect" => Some(crate::TransportCauseKind::Connect),
7653 "tls" => Some(crate::TransportCauseKind::Tls),
7654 "io" => Some(crate::TransportCauseKind::Io),
7655 "request" => Some(crate::TransportCauseKind::Request),
7656 "protocol" => Some(crate::TransportCauseKind::Protocol),
7657 "timeout" => Some(crate::TransportCauseKind::Timeout),
7658 "round_deadline" => Some(crate::TransportCauseKind::RoundDeadline),
7659 "aborted" => Some(crate::TransportCauseKind::Aborted),
7660 "body" => Some(crate::TransportCauseKind::Body),
7661 "status" => Some(crate::TransportCauseKind::Status),
7662 "redirect" => Some(crate::TransportCauseKind::Redirect),
7663 "unknown" => Some(crate::TransportCauseKind::Unknown),
7664 _ => None,
7665 });
7666 let http_status = if matches!(
7667 cause_kind,
7668 Some(
7669 crate::TransportCauseKind::Status
7670 | crate::TransportCauseKind::Body
7671 | crate::TransportCauseKind::Redirect
7672 )
7673 ) {
7674 details
7675 .and_then(|details| details.get("httpStatus"))
7676 .and_then(Value::as_f64)
7677 .filter(|status| status.fract() == 0.0 && (100.0..=599.0).contains(status))
7678 .map(|status| status as u16)
7679 } else {
7680 None
7681 };
7682 let retry_delay_ms = self.round_retry_delay_ms;
7683 self.progress.update(|p| match &outcome {
7684 SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report)
7685 if report.failed.is_empty() =>
7686 {
7687 p.state = ProgressState::Complete
7688 }
7689 SyncOutcome::Ok(_) | SyncOutcome::BudgetExhausted(_) => {
7690 p.state = ProgressState::Failed;
7691 p.error_code = Some("sync.scope_revoked".into());
7692 }
7693 SyncOutcome::Failed { error_code, .. } => {
7694 p.state = ProgressState::Failed;
7695 p.error_code = Some(Self::diagnostic_code(error_code));
7696 p.cause_kind = cause_kind;
7697 p.http_status = http_status;
7698 p.retry_delay_ms = retry_delay_ms;
7699 }
7700 SyncOutcome::RealtimeUnavailable { .. } => {
7701 p.state = ProgressState::Failed;
7702 p.error_code = Some(REALTIME_UNAVAILABLE_CODE.to_owned());
7703 p.retry_delay_ms = retry_delay_ms;
7704 }
7705 });
7706 let completed_at_ms = self.clock_now_ms();
7707 self.last_round = Some(match &outcome {
7708 SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report) => DiagnosticLastRound {
7709 status: "succeeded".to_owned(),
7710 started_at_ms,
7711 completed_at_ms,
7712 duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7713 counters: Some(DiagnosticRoundCounters {
7714 pushed: report.pushed,
7715 applied: report.applied.len(),
7716 rejected: report.rejected.len(),
7717 retryable: report.retryable.len(),
7718 conflicts: report.conflicts,
7719 commits_applied: report.commits_applied,
7720 segment_rows_applied: report.segment_rows_applied,
7721 bootstrapping: report.bootstrapping.len(),
7722 resets: report.resets.len(),
7723 revoked: report.revoked.len(),
7724 failed: report.failed.len(),
7725 deferred_commits: report.deferred_commits,
7726 }),
7727 error_code: None,
7728 cause_kind: None,
7729 http_status: None,
7730 },
7731 SyncOutcome::Failed { error_code, .. } => DiagnosticLastRound {
7732 status: "failed".to_owned(),
7733 started_at_ms,
7734 completed_at_ms,
7735 duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7736 counters: None,
7737 error_code: Some(Self::diagnostic_code(error_code)),
7738 cause_kind,
7739 http_status,
7740 },
7741 SyncOutcome::RealtimeUnavailable { .. } => DiagnosticLastRound {
7742 status: "failed".to_owned(),
7743 started_at_ms,
7744 completed_at_ms,
7745 duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7746 counters: None,
7747 error_code: Some(REALTIME_UNAVAILABLE_CODE.to_owned()),
7748 cause_kind: None,
7749 http_status: None,
7750 },
7751 });
7752 outcome
7753 }
7754
7755 pub fn prepare_sync_round(
7758 &mut self,
7759 url_capable: bool,
7760 ) -> Result<crate::PreparedSyncRound, Box<SyncOutcome>> {
7761 if !self.transport_enabled {
7762 return Err(Box::new(SyncOutcome::Failed {
7763 error_code: "sync.offline".into(),
7764 message: "transport gate is closed".into(),
7765 details: None,
7766 recommended_action: None,
7767 }));
7768 }
7769 if self.active_round.is_some() {
7770 return Err(Box::new(SyncOutcome::Failed {
7771 error_code: "client.round_in_progress".into(),
7772 message: "a sync round is already in flight".into(),
7773 details: None,
7774 recommended_action: None,
7775 }));
7776 }
7777 self.storage_failure.borrow_mut().take();
7778 self.progress.start();
7779 self.round_retry_delay_ms = None;
7780 let started_at_ms = self.clock_now_ms();
7781 let prepared = (|| {
7782 if self.stopped {
7783 return Err(Box::new(SyncOutcome::Ok(SyncReport {
7784 schema_floor: self.schema_floor.clone(),
7785 ..SyncReport::default()
7786 })));
7787 }
7788 if self.security_preflight {
7789 return Err(Box::new(SyncOutcome::Failed {
7790 error_code: SECURITY_PREFLIGHT_REQUIRED_CODE.into(),
7791 message: "security preflight must complete before syncing".into(),
7792 details: None,
7793 recommended_action: None,
7794 }));
7795 }
7796 self.set_sync_needed(false, false);
7797 self.drain_pending_evictions()
7798 .and_then(|_| self.drop_incompatible_outbox())
7799 .and_then(|_| self.drop_unencodable_outbox(true, None))
7800 .map_err(|message| {
7801 Box::new(SyncOutcome::Failed {
7802 error_code: "storage.failed".into(),
7803 message,
7804 details: None,
7805 recommended_action: None,
7806 })
7807 })?;
7808 self.reveal_sealed_rows().map_err(|error| {
7810 Box::new(SyncOutcome::Failed {
7811 error_code: error.code,
7812 message: error.message,
7813 details: error.details,
7814 recommended_action: None,
7815 })
7816 })?;
7817 let has_log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7818 Box::new(SyncOutcome::Failed {
7819 error_code: "storage.failed".into(),
7820 message,
7821 details: None,
7822 recommended_action: None,
7823 })
7824 })?;
7825 let uploads = if has_log_epoch.is_some() && self.schema_has_blobs() {
7826 self.pending_blob_uploads().map_err(|e| {
7827 Box::new(SyncOutcome::Failed {
7828 error_code: e.code,
7829 message: e.message,
7830 details: e.details,
7831 recommended_action: None,
7832 })
7833 })?
7834 } else {
7835 Vec::new()
7836 };
7837 if self.realtime_state != RealtimeState::Connected
7838 && self.realtime_policy == RealtimePolicy::Required
7839 {
7840 let retry_delay_ms = self.schedule_background_retry();
7841 self.realtime_retry_delay_ms = Some(retry_delay_ms);
7842 return Err(Box::new(SyncOutcome::RealtimeUnavailable {
7843 state: self.realtime_state,
7844 reason_code: self.realtime_reason_code.clone(),
7845 retry_delay_ms,
7846 }));
7847 }
7848 let (message, mut meta) = self.build_request(url_capable)?;
7849 let units = self.stored(load_units(&self.conn)).map_err(|message| {
7850 Box::new(SyncOutcome::Failed {
7851 error_code: "storage.failed".into(),
7852 message,
7853 details: None,
7854 recommended_action: None,
7855 })
7856 })?;
7857 meta.applied = units
7858 .iter()
7859 .filter_map(|unit| {
7860 let (cursor, token, ids) = self.applied_segments.get(&unit.id)?;
7861 (*cursor == unit.cursor && *token == unit.bootstrap_state)
7862 .then(|| (unit.id.clone(), ids.clone()))
7863 })
7864 .collect();
7865 let id = uuid::Uuid::new_v4();
7866 self.active_round = Some(id);
7867 let phase = if uploads.is_empty() {
7868 crate::round::RoundPhase::Sync
7869 } else {
7870 crate::round::RoundPhase::UploadGrant
7871 };
7872 Ok(crate::PreparedSyncRound {
7873 id,
7874 started_at_ms,
7875 message,
7876 meta,
7877 uploads: uploads.into(),
7878 phase,
7879 encoded: None,
7880 continuation: None,
7881 completed: None,
7882 realtime: self.realtime_state == RealtimeState::Connected,
7883 scopes: units
7885 .into_iter()
7886 .map(|unit| {
7887 (
7888 unit.id,
7889 canonical_scope_json(&unit_scope_lists(&unit.scopes)),
7890 )
7891 })
7892 .collect(),
7893 #[cfg(feature = "bench-internals")]
7894 benchmark_phases: self.benchmark_phases.clone(),
7895 progress: self.progress.clone(),
7896 fixed_now: self.now_ms,
7897 round_deadline_at: None,
7898 })
7899 })();
7900 prepared.map_err(|outcome| Box::new(self.finish_sync_round(started_at_ms, *outcome)))
7901 }
7902
7903 pub fn cancel_sync_round(&mut self) {
7906 self.active_round = None;
7907 }
7908
7909 pub fn apply_sync_round(
7912 &mut self,
7913 completed: crate::CompletedSyncRound,
7914 ) -> crate::AppliedSyncRound {
7915 let mut prepared = completed.prepared;
7916 if self.active_round != Some(prepared.id) || self.security_preflight {
7917 return crate::AppliedSyncRound::Complete {
7918 outcome: SyncOutcome::Failed {
7919 error_code: "client.round_cancelled".into(),
7920 message: "sync round belongs to a released client context".into(),
7921 details: None,
7922 recommended_action: None,
7923 },
7924 controls: Vec::new(),
7925 more: false,
7926 bootstrap_advanced: false,
7927 };
7928 }
7929 self.storage_failure.borrow_mut().take();
7930 let (response, mut downloads, transport_failed) = match completed.exchange {
7931 crate::round::ExchangeResult::Upload { id, result } => {
7932 let result = match result {
7933 Err(error)
7938 if error
7939 .details
7940 .as_ref()
7941 .and_then(|details| details.get("retryable"))
7942 == Some(&Value::Bool(false)) =>
7943 {
7944 self.conn
7945 .prepare(
7946 "SELECT commit_id FROM _syncular_blob_commit_refs WHERE blob_id = ?",
7947 )
7948 .and_then(|mut statement| {
7949 statement
7950 .query_map(rusqlite::params![id], |row| row.get::<_, String>(0))?
7951 .collect::<Result<HashSet<_>, _>>()
7952 })
7953 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
7954 .and_then(|refused| {
7955 let commits = self
7956 .outbox
7957 .iter()
7958 .filter(|commit| refused.contains(&commit.client_commit_id))
7959 .cloned()
7960 .collect::<Vec<_>>();
7961 if !commits.is_empty() {
7962 self.drop_outbox_commits(&commits, &error.code, &error.message)?;
7963 }
7964 prepared.message.frames.retain(|frame| {
7965 !matches!(frame, Frame::PushCommit { client_commit_id, .. }
7966 if refused.contains(client_commit_id))
7967 });
7968 prepared.meta.pushed_ids.retain(|id| !refused.contains(id));
7969 prepared.continuation = Some(crate::round::RoundPhase::UploadGrant);
7970 Ok(())
7971 })
7972 .map_err(|message| TransportError::new("client.failed", message))
7973 }
7974 result => result,
7975 };
7976 let result = result.and_then(|()| {
7977 self.conn
7978 .execute(
7979 "DELETE FROM _syncular_blob_uploads WHERE blob_id = ?",
7980 rusqlite::params![id],
7981 )
7982 .map(|_| ())
7983 .map_err(|error| {
7984 TransportError::new(
7985 "client.failed",
7986 Self::sqlite_failure(&self.storage_failure, error),
7987 )
7988 })
7989 });
7990 match result {
7991 Ok(()) => return crate::AppliedSyncRound::Continue(prepared),
7992 Err(TransportError {
7993 code,
7994 message,
7995 details,
7996 }) => {
7997 self.active_round = None;
7998 if Self::unreachable_transport(&details) {
7999 self.set_sync_needed(true, false);
8002 } else if Self::retryable_failure_code(&code) {
8003 self.schedule_background_retry();
8004 }
8005 let recommended_action = recommended_action_of(&details);
8006 let outcome = self.finish_sync_round(
8007 prepared.started_at_ms,
8008 SyncOutcome::Failed {
8009 error_code: code,
8010 message,
8011 details,
8012 recommended_action,
8013 },
8014 );
8015 return crate::AppliedSyncRound::Complete {
8016 outcome,
8017 controls: Vec::new(),
8018 more: false,
8019 bootstrap_advanced: false,
8020 };
8021 }
8022 }
8023 }
8024 crate::round::ExchangeResult::Reply {
8025 response,
8026 downloads,
8027 transport_failed,
8028 } => (response, downloads, transport_failed),
8029 };
8030 self.active_round = None;
8031 let before = self.resume_tokens();
8032 let outcome = (|| {
8033 let response = match response {
8034 Ok(response) => {
8035 self.round_failure = None;
8038 response
8039 }
8040 Err(TransportError {
8041 code,
8042 message,
8043 details,
8044 }) => {
8045 if ssp2::model::valid_round_failure_code(&code) {
8050 self.round_failure = Some(code.clone());
8051 }
8052 if transport_failed {
8053 if prepared.realtime {
8054 self.set_realtime_state(RealtimeState::Lost, Some(&code));
8055 }
8056 if let Err(message) = self.record_lease_error(&code) {
8057 return SyncOutcome::Failed {
8058 error_code: "storage.failed".to_owned(),
8059 message,
8060 details: None,
8061 recommended_action: None,
8062 };
8063 }
8064 }
8065 if Self::retryable_failure_code(&code) && !Self::unreachable_transport(&details)
8066 {
8067 let delay = self.schedule_background_retry();
8068 if prepared.realtime && transport_failed {
8069 self.realtime_retry_delay_ms = Some(delay);
8070 }
8071 }
8072 let recommended_action = recommended_action_of(&details);
8073 return SyncOutcome::Failed {
8074 error_code: code,
8075 message,
8076 details,
8077 recommended_action,
8078 };
8079 }
8080 };
8081 let mut outcome = self.process_response(&mut downloads, response, &prepared.meta);
8082 if let SyncOutcome::Ok(report) = &mut outcome {
8083 report.deferred_commits = prepared.meta.deferred_commits;
8084 }
8085 match &outcome {
8086 SyncOutcome::Ok(_) => self.reset_background_retry(),
8087 SyncOutcome::Failed {
8088 error_code,
8089 details,
8090 ..
8091 } if Self::retryable_failure_code(error_code)
8092 && !Self::unreachable_transport(details) =>
8093 {
8094 self.schedule_background_retry();
8095 }
8096 _ => {}
8097 }
8098 if prepared.meta.deferred_commits > 0 {
8099 self.set_sync_needed(true, true);
8100 }
8101 self.previous_version_lifetime_check();
8102 outcome
8103 })();
8104 match &outcome {
8105 SyncOutcome::Ok(report) if !report.bootstrapping.is_empty() => {
8108 self.set_sync_needed(true, false)
8109 }
8110 SyncOutcome::Failed { details, .. } if Self::unreachable_transport(details) => {
8113 self.set_sync_needed(true, false)
8114 }
8115 _ => {}
8116 }
8117 let more = self.transport_enabled
8118 && matches!(&outcome, SyncOutcome::Ok(report)
8119 if report.schema_floor.is_none()
8120 && (!report.bootstrapping.is_empty()
8121 || report.commits_applied > 0
8122 || report.segment_rows_applied > 0
8123 || !report.resets.is_empty()
8124 || report.deferred_commits > 0
8125 || self.sync_needed));
8126 let bootstrap_advanced = matches!(&outcome, SyncOutcome::Ok(report) if report.segment_rows_applied > 0 && !report.bootstrapping.is_empty())
8127 && before != self.resume_tokens();
8128 crate::AppliedSyncRound::Complete {
8129 outcome: self.finish_sync_round(prepared.started_at_ms, outcome),
8130 controls: if self.transport_enabled {
8131 downloads.controls
8132 } else {
8133 Vec::new()
8134 },
8135 more,
8136 bootstrap_advanced,
8137 }
8138 }
8139
8140 fn resume_tokens(&self) -> Option<Vec<(String, Option<String>, usize)>> {
8144 load_units(&self.conn).ok().map(|units| {
8145 units
8146 .into_iter()
8147 .map(|unit| {
8148 let applied = self
8149 .applied_segments
8150 .get(&unit.id)
8151 .map_or(0, |(_, _, ids)| ids.len());
8152 (unit.id, unit.bootstrap_state, applied)
8153 })
8154 .collect()
8155 })
8156 }
8157
8158 pub const SYNC_IDLE_TIMEOUT_MS: u64 = 60_000;
8160
8161 pub fn sync_until_idle(
8162 &mut self,
8163 transport: &mut dyn Transport,
8164 max_rounds: Option<u32>,
8165 ) -> SyncOutcome {
8166 self.sync_until_idle_with_deadline(transport, max_rounds, Some(Self::SYNC_IDLE_TIMEOUT_MS))
8167 }
8168
8169 pub fn sync_until_idle_with_deadline(
8174 &mut self,
8175 transport: &mut dyn Transport,
8176 max_rounds: Option<u32>,
8177 timeout_ms: Option<u64>,
8178 ) -> SyncOutcome {
8179 if max_rounds == Some(0) {
8182 return SyncOutcome::Failed {
8183 details: None,
8184 error_code: "sync.invalid_request".into(),
8185 message: "maxRounds must be a positive integer".into(),
8186 recommended_action: None,
8187 };
8188 }
8189 if timeout_ms.is_some_and(|ms| ms == 0 || i64::try_from(ms).is_err()) {
8190 return SyncOutcome::Failed {
8191 details: None,
8192 error_code: "sync.invalid_request".into(),
8193 message: "timeoutMs must be a positive integer".into(),
8194 recommended_action: None,
8195 };
8196 }
8197 let started_at_ms = self.clock_now_ms();
8198 let deadline_ms = timeout_ms.map(|ms| started_at_ms.saturating_add(ms as i64));
8199 self.sync_until_idle_bounded(transport, max_rounds, started_at_ms, deadline_ms)
8200 }
8201
8202 fn sync_until_idle_bounded(
8203 &mut self,
8204 transport: &mut dyn Transport,
8205 max_rounds: Option<u32>,
8206 started_at_ms: i64,
8207 deadline_ms: Option<i64>,
8208 ) -> SyncOutcome {
8209 let rounds = max_rounds.unwrap_or(20);
8210 let mut aggregate = SyncReport::default();
8211 let mut spent = 0;
8212 while spent < rounds {
8213 if let Some(deadline_ms) = deadline_ms {
8214 if self.clock_now_ms() >= deadline_ms {
8215 return SyncOutcome::Failed {
8216 error_code: "sync.idle_timeout".into(),
8217 message: "sync_until_idle exceeded its deadline".into(),
8218 details: Some(serde_json::json!({
8219 "timeoutMs": deadline_ms
8220 .saturating_sub(started_at_ms) as u64,
8221 "rounds": spent,
8222 })),
8223 recommended_action: Some("retryLater".into()),
8224 };
8225 }
8226 }
8227 spent += 1;
8228 let before = self.resume_tokens();
8229 match self.sync(transport) {
8230 SyncOutcome::Failed {
8231 error_code,
8232 message,
8233 details,
8234 recommended_action,
8235 } => {
8236 return SyncOutcome::Failed {
8237 details,
8238 error_code,
8239 message,
8240 recommended_action,
8241 };
8242 }
8243 outcome @ SyncOutcome::RealtimeUnavailable { .. } => return outcome,
8244 SyncOutcome::BudgetExhausted(_) => {
8245 unreachable!("sync() never exhausts a round budget")
8246 }
8247 SyncOutcome::Ok(report) => {
8248 if max_rounds.is_none()
8249 && report.segment_rows_applied > 0
8250 && !report.bootstrapping.is_empty()
8251 && before != self.resume_tokens()
8252 {
8253 spent = 0;
8254 }
8255 let stop = !self.transport_enabled() || report.schema_floor.is_some();
8258 aggregate.merge(&report);
8259 if stop {
8260 return SyncOutcome::Ok(aggregate);
8261 }
8262 let more = !report.bootstrapping.is_empty()
8268 || report.commits_applied > 0
8269 || report.segment_rows_applied > 0
8270 || !report.resets.is_empty()
8271 || report.deferred_commits > 0
8272 || self.sync_needed;
8273 if !more {
8274 return SyncOutcome::Ok(aggregate);
8275 }
8276 }
8277 }
8278 }
8279 SyncOutcome::BudgetExhausted(aggregate)
8282 }
8283
8284 fn process_response(
8285 &mut self,
8286 transport: &mut dyn Transport,
8287 response: Message,
8288 meta: &RequestMeta,
8289 ) -> SyncOutcome {
8290 #[cfg(feature = "bench-internals")]
8291 let _phase = self.benchmark_phases.start(Phase::ResponseApply);
8292 let mut report = SyncReport {
8293 pushed: meta.pushed_ids.len() as u32,
8294 ..SyncReport::default()
8295 };
8296 let mut rejection_details_by_commit: HashMap<String, BTreeMap<i32, RejectionDetails>> =
8297 HashMap::new();
8298 let pushed_ids = meta
8299 .pushed_ids
8300 .iter()
8301 .map(String::as_str)
8302 .collect::<HashSet<_>>();
8303 let mut last_final_push_result_id: Option<String> = None;
8304 for frame in &response.frames {
8305 match frame {
8306 Frame::PushResultDetails {
8307 client_commit_id,
8308 entries,
8309 } => {
8310 let details = rejection_details_by_commit
8311 .entry(client_commit_id.clone())
8312 .or_default();
8313 for entry in entries {
8314 let parsed = match RejectionDetails::parse(&entry.details.0) {
8315 Ok(value) => value,
8316 Err(message) => {
8317 return SyncOutcome::Failed {
8318 details: None,
8319 error_code: "sync.invalid_request".to_owned(),
8320 message,
8321 recommended_action: None,
8322 };
8323 }
8324 };
8325 details.insert(entry.op_index, parsed);
8326 }
8327 }
8328 Frame::PushResult {
8329 client_commit_id,
8330 status,
8331 results,
8332 ..
8333 } if pushed_ids.contains(client_commit_id.as_str())
8334 && Self::push_result_is_final(*status, results) =>
8335 {
8336 last_final_push_result_id = Some(client_commit_id.clone());
8337 }
8338 _ => {}
8339 }
8340 }
8341 let mut frames = response.frames.into_iter().peekable();
8342 match frames.next() {
8343 Some(Frame::RespHeader {
8344 required_schema_version,
8345 latest_schema_version,
8346 log_epoch,
8347 reset_required,
8348 }) => {
8349 if let Some(required) = required_schema_version {
8350 let floor = SchemaFloor {
8353 required_schema_version: Some(required),
8354 latest_schema_version,
8355 };
8356 if let Err(message) = self.set_schema_floor(Some(floor.clone())) {
8357 return SyncOutcome::Failed {
8358 details: None,
8359 error_code: "storage.failed".to_owned(),
8360 message,
8361 recommended_action: None,
8362 };
8363 }
8364 report.schema_floor = Some(floor);
8365 return SyncOutcome::Ok(report);
8366 }
8367 if reset_required {
8368 if frames.next().is_some() {
8369 return SyncOutcome::Failed {
8370 details: None,
8371 error_code: "client.invalid_host_response".to_owned(),
8372 message: "log-epoch reset response contains body frames".to_owned(),
8373 recommended_action: None,
8374 };
8375 }
8376 match self.run_log_epoch_reset(&log_epoch) {
8377 Ok(resets) => {
8378 report.resets = resets;
8379 return SyncOutcome::Ok(report);
8380 }
8381 Err(message) => {
8382 return SyncOutcome::Failed {
8383 details: None,
8384 error_code: "sync.local_corrupt".to_owned(),
8385 message,
8386 recommended_action: None,
8387 };
8388 }
8389 }
8390 }
8391 let stored_epoch = match self.get_meta(LOG_EPOCH_KEY) {
8392 Ok(stored) => stored,
8393 Err(message) => {
8394 return SyncOutcome::Failed {
8395 details: None,
8396 error_code: "storage.failed".to_owned(),
8397 message,
8398 recommended_action: None,
8399 };
8400 }
8401 };
8402 if stored_epoch.as_deref() != Some(log_epoch.as_str()) {
8403 return SyncOutcome::Failed {
8404 details: None,
8405 error_code: "client.invalid_host_response".to_owned(),
8406 message: "server changed logEpoch without requiring a reset".to_owned(),
8407 recommended_action: None,
8408 };
8409 }
8410 }
8411 _ => {
8412 return SyncOutcome::Failed {
8413 details: None,
8414 error_code: "sync.invalid_request".to_owned(),
8415 message: "response does not start with RESP_HEADER".to_owned(),
8416 recommended_action: None,
8417 };
8418 }
8419 }
8420
8421 if let Err(message) = self.begin_coalesced_apply() {
8422 return SyncOutcome::Failed {
8423 details: None,
8424 error_code: "storage.failed".into(),
8425 message,
8426 recommended_action: None,
8427 };
8428 }
8429 let mut failure: Option<(String, String, Option<String>, Option<Value>)> = None;
8430 let mut live: Option<(LiveStatus, String, Vec<UnitRecord>)> = None;
8433 let mut live_ended = false;
8434 while let Some(frame) = frames.next() {
8435 match frame {
8436 frame @ Frame::PushResult { .. } => {
8437 let successful = matches!(
8438 &frame,
8439 Frame::PushResult {
8440 status: PushStatus::Applied | PushStatus::Cached,
8441 ..
8442 }
8443 );
8444 let mut results = vec![frame];
8445 if successful {
8446 while matches!(
8447 frames.peek(),
8448 Some(Frame::PushResult {
8449 status: PushStatus::Applied | PushStatus::Cached,
8450 ..
8451 })
8452 ) {
8453 if let Some(next) = frames.next() {
8454 results.push(next);
8455 }
8456 }
8457 }
8458 if self
8459 .handle_push_results(
8460 &results,
8461 &pushed_ids,
8462 &rejection_details_by_commit,
8463 &mut report,
8464 last_final_push_result_id.as_deref(),
8465 )
8466 .is_err()
8467 {
8468 failure = Some((
8469 "client.outcome_persistence_failed".to_owned(),
8470 "local commit outcome could not be persisted".to_owned(),
8471 None,
8472 None,
8473 ));
8474 break;
8475 }
8476 }
8477 Frame::PushResultDetails { .. } => {}
8478 Frame::SubStart {
8479 id,
8480 status,
8481 reason_code,
8482 bootstrap,
8483 fenced,
8484 } => {
8485 let mut body = Vec::new();
8488 let mut sub_end: Option<(i64, Option<String>)> = None;
8489 let mut error: Option<Frame> = None;
8490 for inner in frames.by_ref() {
8491 match inner {
8492 Frame::SubEnd {
8493 next_cursor,
8494 bootstrap_state,
8495 } => {
8496 sub_end = Some((next_cursor, bootstrap_state.map(|r| r.0)));
8497 break;
8498 }
8499 inner @ Frame::Error { .. } => {
8500 error = Some(inner);
8501 break;
8502 }
8503 Frame::Unknown { .. } => {}
8504 other => body.push(other),
8505 }
8506 }
8507 let ended = sub_end.is_some();
8508 let section = SectionStart {
8509 id,
8510 status,
8511 reason_code,
8512 bootstrap,
8513 fenced,
8514 };
8515 match self.process_section(
8516 transport,
8517 §ion,
8518 body,
8519 sub_end,
8520 meta,
8521 &mut report,
8522 ) {
8523 Err(SectionError::Abort(code, message)) => {
8524 failure = Some((code, message, None, None));
8525 break;
8526 }
8527 Err(SectionError::Transport(error)) => {
8528 failure = Some((error.code, error.message, None, error.details));
8529 break;
8530 }
8531 _ => {}
8532 }
8533 if ended {
8534 self.progress.update(|p| {
8536 p.unit_id = None;
8537 p.table = None;
8538 p.segment_id = None;
8539 });
8540 }
8541 match error {
8542 Some(Frame::Error {
8543 code,
8544 message,
8545 recommended_action,
8546 details,
8547 ..
8548 }) => {
8549 failure = Some(Self::error_frame_failure(
8550 code,
8551 message,
8552 recommended_action,
8553 details,
8554 ));
8555 break;
8556 }
8557 Some(_) => unreachable!("only an ERROR closes a section early"),
8558 None if !ended => {
8559 failure = Some((
8560 "sync.invalid_request".to_owned(),
8561 "unit section without SUB_END".to_owned(),
8562 None,
8563 None,
8564 ));
8565 break;
8566 }
8567 None => {}
8568 }
8569 }
8570 Frame::LiveStart {
8571 status,
8572 reason_code,
8573 } => {
8574 let receivers = match self.stored(load_units(&self.conn)) {
8575 Ok(units) => units
8576 .into_iter()
8577 .filter(|unit| {
8578 unit.status == UnitStatus::Active
8579 && unit.echo.is_some()
8580 && !unit.bootstrapping()
8581 })
8582 .collect(),
8583 Err(message) => {
8584 failure = Some(("storage.failed".to_owned(), message, None, None));
8585 break;
8586 }
8587 };
8588 live = Some((status, reason_code, receivers));
8589 }
8590 Frame::Commit {
8591 commit_seq,
8592 tables,
8593 changes,
8594 ..
8595 } => {
8596 let Some((LiveStatus::Active, _, receivers)) = &live else {
8597 continue;
8598 };
8599 let receivers = receivers.clone();
8600 match self.apply_live_commit(
8601 &receivers,
8602 &tables,
8603 changes,
8604 commit_seq,
8605 AppliedServerCommitSource::Pull,
8606 ) {
8607 Ok(applied) => report.commits_applied += u32::from(applied),
8608 Err(error) => {
8609 failure = Some((error.code, error.message, None, error.details));
8610 break;
8611 }
8612 }
8613 }
8614 Frame::LiveEnd {
8615 through_seq,
8616 echo_digest,
8617 } => {
8618 let Some((status, reason_code, _)) = live.take() else {
8619 continue;
8620 };
8621 live_ended = true;
8622 live = Some((status, String::new(), Vec::new()));
8623 if let Err(message) = self.finish_live_section(
8624 status,
8625 &reason_code,
8626 through_seq,
8627 echo_digest,
8628 &meta.registration_digest,
8629 &mut report,
8630 ) {
8631 failure = Some(("storage.failed".to_owned(), message, None, None));
8632 break;
8633 }
8634 }
8635 Frame::Lease {
8636 lease_id,
8637 expires_at_ms,
8638 } => {
8639 if let Err(message) = self.set_lease_state(Some(LeaseState {
8642 lease_id: Some(lease_id),
8643 expires_at_ms: Some(expires_at_ms),
8644 error_code: None,
8645 })) {
8646 failure = Some(("storage.failed".to_owned(), message, None, None));
8647 break;
8648 }
8649 }
8650 Frame::Error {
8651 code,
8652 message,
8653 recommended_action,
8654 details,
8655 ..
8656 } => {
8657 failure = Some(Self::error_frame_failure(
8660 code,
8661 message,
8662 recommended_action,
8663 details,
8664 ));
8665 break;
8666 }
8667 Frame::Unknown { .. } => {}
8668 _ => {
8669 failure = Some((
8670 "sync.invalid_request".to_owned(),
8671 "unexpected frame in response".to_owned(),
8672 None,
8673 None,
8674 ));
8675 break;
8676 }
8677 }
8678 }
8679
8680 let applied = match failure {
8681 Some(failure) => Err(failure),
8682 None => self
8687 .rebuild_overlay_if_dirty()
8688 .and_then(|()| self.drain_pending_evictions())
8689 .map_err(|message| ("storage.failed".to_owned(), message, None, None)),
8690 };
8691 if let Err(message) = self.finish_coalesced_apply() {
8694 return SyncOutcome::Failed {
8695 details: None,
8696 error_code: "storage.failed".into(),
8697 message,
8698 recommended_action: None,
8699 };
8700 }
8701 if let Err((error_code, message, recommended_action, details)) = applied {
8702 return SyncOutcome::Failed {
8703 details,
8704 error_code,
8705 message,
8706 recommended_action,
8707 };
8708 }
8709 let catching_up = match self.stored(load_units(&self.conn)) {
8710 Ok(units) => units
8711 .into_iter()
8712 .filter(|unit| unit.status == UnitStatus::Active && unit.cursor.is_some())
8713 .map(|unit| unit.id)
8714 .collect::<Vec<_>>(),
8715 Err(message) => {
8716 return SyncOutcome::Failed {
8717 details: None,
8718 error_code: "storage.failed".into(),
8719 message,
8720 recommended_action: None,
8721 }
8722 }
8723 };
8724 let status = live.map(|(status, _, _)| status);
8728 if !live_ended || status != Some(LiveStatus::Active) || !catching_up.is_empty() {
8729 self.set_sync_needed(true, status == Some(LiveStatus::Unregistered));
8730 }
8731 self.ack_after_pull(transport);
8732 if self.upgrading && catching_up.is_empty() {
8735 self.set_upgrading(false);
8736 }
8737 report.bootstrapping = catching_up;
8738 SyncOutcome::Ok(report)
8739 }
8740
8741 fn error_frame_failure(
8743 code: String,
8744 message: String,
8745 recommended_action: String,
8746 details: Option<RawJson>,
8747 ) -> (String, String, Option<String>, Option<Value>) {
8748 let recommended_action = (!recommended_action.is_empty()).then_some(recommended_action);
8749 let details = details
8750 .and_then(|details| serde_json::from_str::<Value>(&details.0).ok())
8751 .filter(Value::is_object);
8752 (code, message, recommended_action, details)
8753 }
8754
8755 fn finish_live_section(
8760 &mut self,
8761 status: LiveStatus,
8762 reason_code: &str,
8763 through_seq: i64,
8764 echo_digest: Option<[u8; 32]>,
8765 registration_digest: &str,
8766 report: &mut SyncReport,
8767 ) -> Result<(), String> {
8768 let rollback = self.capture();
8769 let resets = report.resets.len();
8770 self.begin_observation("syncular_live_end")?;
8771 let finished = (|| {
8772 let mut batch = ChangeAccumulator::default();
8773 let before = self.stored(replica_cursor(&self.conn))?;
8774 let mut cursor = if status == LiveStatus::Unregistered {
8775 before
8776 } else {
8777 -1
8778 };
8779 let joined = before.max(through_seq);
8780 for unit in self.stored(load_units(&self.conn))? {
8781 if unit.status != UnitStatus::Active || unit.bootstrapping() {
8782 continue;
8783 }
8784 match status {
8785 LiveStatus::Reset if unit.cursor.is_none() => {
8788 for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
8789 batch.window(&base_key, &value);
8790 }
8791 report.resets.push(unit.id.clone());
8792 self.stored(save_unit(
8793 &self.conn,
8794 &UnitRecord {
8795 reason_code: Some(reason_code.to_owned()),
8796 cursor: Some(-1),
8797 seeded: Vec::new(),
8798 ..unit
8799 },
8800 ))?;
8801 }
8802 LiveStatus::Active => {
8804 let next = unit.cursor.unwrap_or(joined).max(through_seq);
8805 if next >= joined {
8806 cursor = joined;
8807 }
8808 if unit.cursor.is_some() {
8809 self.stored(save_unit(
8810 &self.conn,
8811 &UnitRecord {
8812 cursor: (next < joined).then_some(next),
8813 ..unit
8814 },
8815 ))?;
8816 }
8817 }
8818 _ => {}
8819 }
8820 }
8821 self.set_meta(REPLICA_CURSOR_KEY, &cursor.to_string())?;
8822 self.set_meta(
8823 ECHO_DIGEST_KEY,
8824 &echo_digest
8825 .map(|digest| bytes_to_hex(&digest))
8826 .unwrap_or_default(),
8827 )?;
8828 if status == LiveStatus::Unregistered {
8829 self.delete_meta(REGISTERED_DIGEST_KEY)?;
8830 } else {
8831 self.set_meta(REGISTERED_DIGEST_KEY, registration_digest)?;
8832 }
8833 self.finish_observation("syncular_live_end", batch)
8834 })();
8835 if finished.is_err() {
8836 self.rollback_observation("syncular_live_end");
8837 self.restore(rollback);
8838 report.resets.truncate(resets);
8839 }
8840 finished
8841 }
8842
8843 fn handle_push_results(
8846 &mut self,
8847 frames: &[Frame],
8848 pushed_ids: &HashSet<&str>,
8849 rejection_details_by_commit: &HashMap<String, BTreeMap<i32, RejectionDetails>>,
8850 report: &mut SyncReport,
8851 last_final_push_result_id: Option<&str>,
8852 ) -> Result<(), String> {
8853 self.begin_observation("syncular_push_results")?;
8854 let rollback = self.capture();
8855 let conflict_count = self.conflicts.len();
8856 let applied_count = report.applied.len();
8857 let rejected_count = report.rejected.len();
8858 let retryable_count = report.retryable.len();
8859 let mut drained = Vec::new();
8860 let mut batch = ChangeAccumulator::default();
8861 let persisted = (|| {
8862 for frame in frames {
8863 let Frame::PushResult {
8864 client_commit_id,
8865 status,
8866 results,
8867 commit_seq,
8868 } = frame
8869 else {
8870 return Err("unexpected acknowledgement frame".to_owned());
8871 };
8872 if !pushed_ids.contains(client_commit_id.as_str()) {
8873 continue;
8874 }
8875 let Some(index) = self
8876 .outbox
8877 .iter()
8878 .position(|commit| commit.client_commit_id == *client_commit_id)
8879 else {
8880 continue;
8881 };
8882 let status = *status;
8883 let rejection_details = rejection_details_by_commit.get(client_commit_id);
8884 let operations = self.outbox[index].ops.clone();
8885 match status {
8886 PushStatus::Applied | PushStatus::Cached => {
8887 let sequence =
8890 commit_seq.ok_or_else(|| "ACK lacks a commit sequence".to_owned())?;
8891 let affected: HashSet<_> = operations
8892 .iter()
8893 .map(|op| (op.table.as_str(), op.row_id.as_str()))
8894 .collect();
8895 let prior = self.acknowledged_operations(Some(&affected), None)?;
8896 for (op_index, operation) in operations.iter().enumerate() {
8897 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))
8898 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
8899 if delivered {
8900 continue;
8901 }
8902 let table = self
8903 .schema
8904 .table(&operation.table)
8905 .ok_or_else(|| "sync.unknown_table".to_owned())?;
8906 let mut intended: Map<String, Value> = self
8907 .stored_row(table, &operation.row_id, true)?
8908 .map(|(row, _)| {
8909 table
8910 .columns
8911 .iter()
8912 .zip(&row)
8913 .map(|(column, value)| {
8914 (column.name.clone(), column_value_to_json(value))
8915 })
8916 .collect()
8917 })
8918 .unwrap_or_default();
8919 let mut scope_image = intended.clone();
8920 for op in prior
8921 .iter()
8922 .chain(
8923 self.failed_commits
8924 .iter()
8925 .flat_map(|(commit, _)| &commit.ops),
8926 )
8927 .chain(
8928 self.outbox
8929 .iter()
8930 .take(index)
8931 .flat_map(|commit| &commit.ops),
8932 )
8933 .chain(operations.iter().take(op_index + 1))
8934 {
8935 if op.table != operation.table || op.row_id != operation.row_id {
8936 continue;
8937 }
8938 if let Some(values) = &op.values {
8939 intended.extend(values.clone());
8940 } else {
8941 scope_image = intended.clone();
8942 intended.clear();
8943 }
8944 }
8945 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)",
8946 rusqlite::params![client_commit_id, op_index as i64, operation.table, operation.row_id, sequence,
8947 serde_json::to_string(&CommitOperation::from(operation)).map_err(|_| "sync.local_corrupt".to_owned())?,
8948 serde_json::to_string(if operation.upsert { &intended } else { &scope_image }).map_err(|_| "sync.local_corrupt".to_owned())?])
8949 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
8950 }
8951 let journal_results = results
8952 .iter()
8953 .map(|result| {
8954 let op_index = match result {
8955 OpResult::Applied { op_index }
8956 | OpResult::Conflict { op_index, .. }
8957 | OpResult::Error { op_index, .. } => *op_index,
8958 };
8959 CommitOperationOutcome::Applied { op_index }
8960 })
8961 .collect::<Vec<_>>();
8962 let outcome_status = if status == PushStatus::Applied {
8963 CommitOutcomeStatus::Applied
8964 } else {
8965 CommitOutcomeStatus::Cached
8966 };
8967 let persisted = self
8968 .persist_commit_outcome(
8969 client_commit_id,
8970 outcome_status,
8971 &journal_results,
8972 None,
8973 )
8974 .and_then(|()| self.delete_outbox_persisted(client_commit_id));
8975 persisted?;
8976 self.sync_needed = true;
8977 batch.status = true;
8978 batch.outcomes = true;
8979 }
8980 PushStatus::Rejected => {
8981 if results.iter().any(|result| {
8982 matches!(
8983 result,
8984 OpResult::Error {
8985 code,
8986 retryable: true,
8987 ..
8988 } if code == "sync.idempotency_cache_miss"
8989 )
8990 }) {
8991 report.retryable.push(client_commit_id.to_owned());
8994 continue;
8995 }
8996
8997 let mut journal_results = Vec::with_capacity(results.len());
8998 let mut conflicts = Vec::new();
8999 let mut rejections = Vec::new();
9000 for result in results {
9001 match result {
9002 OpResult::Applied { op_index } => {
9003 journal_results.push(CommitOperationOutcome::Applied {
9004 op_index: *op_index,
9005 });
9006 }
9007 OpResult::Conflict {
9008 op_index,
9009 code,
9010 message,
9011 server_version,
9012 server_row,
9013 conflict_columns: conflict_columns_bitmap,
9014 } => {
9015 let operation = operations
9016 .get(*op_index as usize)
9017 .map(CommitOperation::from);
9018 let (table, row_id) = operation
9019 .as_ref()
9020 .map(|op| (op.table.clone(), op.row_id.clone()))
9021 .unwrap_or_default();
9022 let server_row_json = self
9023 .schema
9024 .table(&table)
9025 .and_then(|t| {
9026 decode_row_bytes(t, server_row, &self.encryption)
9027 .ok()
9028 .map(|(row, _)| (t, row))
9029 })
9030 .map(|(t, row)| {
9031 let mut map = Map::new();
9032 for (i, column) in t.columns.iter().enumerate() {
9033 map.insert(
9034 column.name.clone(),
9035 column_value_to_json(
9036 row.get(i).unwrap_or(&None),
9037 ),
9038 );
9039 }
9040 map
9041 })
9042 .unwrap_or_default();
9043 let conflict_columns = self
9046 .schema
9047 .table(&table)
9048 .map(|t| {
9049 t.columns
9050 .iter()
9051 .enumerate()
9052 .filter(|(index, _)| {
9053 conflict_columns_bitmap
9054 .get(index / 8)
9055 .is_some_and(|byte| {
9056 byte & (1 << (index % 8)) != 0
9057 })
9058 })
9059 .map(|(_, column)| column.name.clone())
9060 .collect::<Vec<_>>()
9061 })
9062 .unwrap_or_default();
9063 let conflict = ConflictRecord {
9064 client_commit_id: client_commit_id.to_owned(),
9065 op_index: *op_index,
9066 table,
9067 row_id,
9068 code: code.clone(),
9069 message: message.clone(),
9070 server_version: *server_version,
9071 server_row: server_row_json,
9072 conflict_columns,
9073 operation,
9074 };
9075 journal_results.push(CommitOperationOutcome::Conflict {
9076 conflict: conflict.clone(),
9077 });
9078 conflicts.push(conflict);
9079 }
9080 OpResult::Error {
9081 op_index,
9082 code,
9083 message,
9084 retryable,
9085 } => {
9086 let rejection = RejectionRecord {
9087 client_commit_id: client_commit_id.to_owned(),
9088 op_index: *op_index,
9089 code: code.clone(),
9090 message: message.clone(),
9091 retryable: *retryable,
9092 details: rejection_details
9093 .and_then(|details| details.get(op_index))
9094 .cloned(),
9095 operation: operations
9096 .get(*op_index as usize)
9097 .map(CommitOperation::from),
9098 };
9099 journal_results.push(CommitOperationOutcome::Error {
9100 rejection: rejection.clone(),
9101 });
9102 rejections.push(rejection);
9103 }
9104 }
9105 }
9106 if self.retain_failed_commits {
9107 self.retain_failed_commit(client_commit_id, &operations)?;
9108 }
9109 let outcome_status = if conflicts.is_empty() {
9110 CommitOutcomeStatus::Rejected
9111 } else {
9112 CommitOutcomeStatus::Conflict
9113 };
9114 let persisted = self
9115 .persist_commit_outcome(
9116 client_commit_id,
9117 outcome_status,
9118 &journal_results,
9119 Some(&operations),
9120 )
9121 .and_then(|()| self.delete_outbox_persisted(client_commit_id));
9122 persisted?;
9123 batch.conflicts = !conflicts.is_empty();
9124 batch.rejections = !rejections.is_empty();
9125 batch.status = true;
9126 batch.outcomes = true;
9127 self.conflicts.extend(conflicts);
9128 self.rejections.extend(rejections);
9129 }
9130 }
9131 drained.push(self.outbox.remove(index));
9132 if batch.status {
9133 for operation in &operations {
9134 if !self.record_row_scopes(
9135 &mut batch,
9136 &operation.table,
9137 &operation.row_id,
9138 false,
9139 ) {
9140 batch.table(&operation.table);
9141 }
9142 }
9143 }
9144 match status {
9145 PushStatus::Applied | PushStatus::Cached => {
9146 report.applied.push(client_commit_id.to_owned())
9147 }
9148 PushStatus::Rejected => report.rejected.push(client_commit_id.to_owned()),
9149 }
9150 }
9151 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)) {
9152 self.prune_commit_outcomes()?;
9153 }
9154 self.reconcile_rows(&drained)?;
9155 self.rebuild_overlay_if_dirty()?;
9156 self.finish_observation("syncular_push_results", batch)
9157 })();
9158 if let Err(error) = persisted {
9159 self.rollback_observation("syncular_push_results");
9160 self.restore(rollback);
9161 report.applied.truncate(applied_count);
9162 report.rejected.truncate(rejected_count);
9163 report.retryable.truncate(retryable_count);
9164 return Err(error);
9165 }
9166 if !rollback.sync_needed && self.sync_needed {
9167 self.sync_intent_queue.push_back(SyncIntent::Interactive);
9168 }
9169 report.conflicts += (self.conflicts.len() - conflict_count) as u32;
9170 Ok(())
9171 }
9172
9173 fn push_result_is_final(status: PushStatus, results: &[OpResult]) -> bool {
9174 status != PushStatus::Rejected
9175 || !results.iter().any(|result| {
9176 matches!(
9177 result,
9178 OpResult::Error {
9179 code,
9180 retryable: true,
9181 ..
9182 } if code == "sync.idempotency_cache_miss"
9183 )
9184 })
9185 }
9186
9187 fn process_section(
9195 &mut self,
9196 transport: &mut dyn Transport,
9197 start: &SectionStart,
9198 body: Vec<Frame>,
9199 sub_end: Option<(i64, Option<String>)>,
9200 meta: &RequestMeta,
9201 report: &mut SyncReport,
9202 ) -> Result<(), SectionError> {
9203 let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
9204 let unit = self
9205 .stored(get_unit(&self.conn, &start.id))
9206 .map_err(storage)?
9207 .filter(|unit| unit.status == UnitStatus::Active);
9208 self.progress.update(|p| {
9210 p.phase = ProgressPhase::Import;
9211 p.unit_id = unit.as_ref().map(|unit| unit.id.clone());
9212 p.table = None;
9213 p.segment_id = None;
9214 p.bytes_received = 0;
9215 p.bytes_total = None;
9216 p.rows_processed = 0;
9217 p.rows_total = None;
9218 p.import_write_ms = None;
9219 p.import_commit_ms = None;
9220 });
9221 let Some(unit) = unit else {
9222 return Ok(());
9223 };
9224 let echo: Vec<EchoRecord> = start
9225 .fenced
9226 .iter()
9227 .map(|record| EchoRecord {
9228 table: record.table.clone(),
9229 status: record.status.name().to_owned(),
9230 scopes: record.scopes.iter().cloned().collect(),
9231 })
9232 .collect();
9233 if self
9236 .applied_segments
9237 .get(&unit.id)
9238 .is_some_and(|(cursor, token, _)| {
9239 (*cursor, token) != (unit.cursor, &unit.bootstrap_state)
9240 })
9241 {
9242 self.applied_segments.remove(&unit.id);
9243 }
9244 let mut seeded: BTreeSet<String> = if unit.bootstrap_state.is_none() {
9246 BTreeSet::new()
9247 } else {
9248 unit.seeded.iter().cloned().collect()
9249 };
9250 let applied = (|| {
9251 for frame in body {
9252 match frame {
9253 Frame::SegmentInline { payload } => {
9254 let segment = decode_rows_segment(&payload).map_err(|e| {
9255 SectionError::Abort(e.code.as_str().to_owned(), e.detail)
9256 })?;
9257 self.progress.update(|p| {
9258 p.phase = ProgressPhase::Import;
9259 p.unit_id = Some(unit.id.clone());
9260 p.table = Some(segment.table.clone());
9261 p.segment_id = None;
9262 p.bytes_received = payload.len() as u64;
9263 p.bytes_total = Some(payload.len() as u64);
9264 p.rows_processed = 0;
9265 p.rows_total =
9266 Some(segment.blocks.iter().map(|block| block.len() as u64).sum());
9267 p.import_write_ms = None;
9268 p.import_commit_ms = None;
9269 });
9270 let (pair, clear, effective) =
9271 self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
9272 report.segment_rows_applied +=
9273 self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
9274 seeded.insert(segment.table);
9275 }
9276 Frame::SegmentRef {
9277 segment_id,
9278 byte_length,
9279 media_type,
9280 table,
9281 row_count,
9282 as_of_commit_seq,
9283 scope_digest,
9284 row_cursor,
9285 next_row_cursor,
9286 url,
9287 url_expires_at_ms,
9288 ..
9289 } => {
9290 let advertised = match media_type {
9293 MediaType::Rows => {
9294 meta.accept & ACCEPT_EXTERNAL_ROWS != 0
9295 || meta.accept & ACCEPT_INLINE_ROWS != 0
9296 }
9297 MediaType::Sqlite => meta.accept & ACCEPT_SQLITE != 0,
9298 };
9299 if !advertised {
9300 return Err(SectionError::Abort(
9301 "sync.invalid_request".to_owned(),
9302 format!(
9303 "SEGMENT_REF mediaType {} was not advertised in accept (§4.2)",
9304 media_type.name()
9305 ),
9306 ));
9307 }
9308 if meta
9310 .applied
9311 .get(&unit.id)
9312 .is_some_and(|ids| ids.contains(&segment_id))
9313 {
9314 seeded.insert(table);
9315 continue;
9316 }
9317 if meta
9318 .deferred
9319 .contains(&(unit.id.clone(), segment_id.clone()))
9320 {
9321 return Err(SectionError::Deferred);
9322 }
9323 self.progress.update(|p| {
9324 p.phase = ProgressPhase::Download;
9325 p.unit_id = Some(unit.id.clone());
9326 p.table = Some(table.clone());
9327 p.segment_id = Some(segment_id.clone());
9328 p.bytes_received = 0;
9329 p.bytes_total = u64::try_from(byte_length).ok();
9330 p.rows_processed = 0;
9331 p.rows_total = u64::try_from(row_count).ok();
9332 p.import_write_ms = None;
9333 p.import_commit_ms = None;
9334 });
9335 let observer = self.progress.clone();
9336 let mut on_progress = |bytes| observer.update(|p| p.bytes_received = bytes);
9337 let bytes = if let Some(url) = url {
9338 if meta.accept & ACCEPT_SIGNED_URLS == 0 {
9343 return Err(SectionError::Abort(
9344 "sync.invalid_request".to_owned(),
9345 "SEGMENT_REF carries a url but accept bit 3 was not advertised (§5.4)"
9346 .to_owned(),
9347 ));
9348 }
9349 if url_expires_at_ms.is_some_and(|exp| {
9351 exp <= transport
9352 .segment_fetch_started_at(&url)
9353 .unwrap_or_else(|| self.clock_now_ms())
9354 }) {
9355 return Err(SectionError::Abort(
9356 "sync.segment_expired".to_owned(),
9357 format!(
9358 "signed URL for segment {segment_id} expired before fetch — re-pull mints fresh descriptors (§5.4)"
9359 ),
9360 ));
9361 }
9362 transport
9363 .fetch_url(
9364 &url,
9365 u64::try_from(byte_length).unwrap_or(0),
9366 &mut on_progress,
9367 )
9368 .map_err(|e| self.segment_fetch_failed(e))?
9369 } else {
9370 let requested_scopes_json =
9372 canonical_scope_json(&unit_scope_lists(&unit.scopes));
9373 transport
9374 .download_segment(
9375 &SegmentRequest {
9376 segment_id: segment_id.clone(),
9377 table: table.clone(),
9378 requested_scopes_json,
9379 byte_length: u64::try_from(byte_length).unwrap_or(0),
9380 },
9381 &mut on_progress,
9382 )
9383 .map_err(|e| {
9384 if e.code == "sync.forbidden" {
9387 SectionError::Refused
9388 } else {
9389 self.segment_fetch_failed(e)
9390 }
9391 })?
9392 };
9393 if bytes.len() as i64 > byte_length {
9397 self.schedule_background_retry();
9398 return Err(SectionError::Abort(
9399 "sync.invalid_request".to_owned(),
9400 "segment exceeds its byteLength".to_owned(),
9401 ));
9402 }
9403 on_progress(bytes.len() as u64);
9404 let digest = Sha256::digest(&bytes);
9405 let expected = segment_id
9406 .strip_prefix("sha256:")
9407 .unwrap_or(segment_id.as_str());
9408 if bytes_to_hex(&digest) != expected {
9409 self.schedule_background_retry();
9411 return Err(SectionError::Abort(
9412 "sync.invalid_request".to_owned(),
9413 "segment bytes do not match the content address (§5.1)".to_owned(),
9414 ));
9415 }
9416 self.progress.update(|p| p.phase = ProgressPhase::Import);
9417 if media_type == MediaType::Sqlite {
9418 if row_cursor.is_some() || next_row_cursor.is_some() {
9421 return Err(SectionError::Abort(
9422 "sync.invalid_request".to_owned(),
9423 "sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)"
9424 .to_owned(),
9425 ));
9426 }
9427 let (pair, clear, effective) =
9428 self.segment_pair(&unit, &echo, &seeded, &table)?;
9429 report.segment_rows_applied += self.apply_sqlite_segment(
9430 &pair,
9431 &bytes,
9432 clear,
9433 &effective,
9434 &unit.id,
9435 row_count,
9436 as_of_commit_seq,
9437 &scope_digest,
9438 )?;
9439 seeded.insert(table);
9440 } else {
9441 let segment = decode_rows_segment(&bytes).map_err(|e| {
9442 SectionError::Abort(e.code.as_str().to_owned(), e.detail)
9443 })?;
9444 let (pair, clear, effective) =
9445 self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
9446 report.segment_rows_applied +=
9447 self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
9448 seeded.insert(segment.table);
9449 }
9450 self.applied_segments
9451 .entry(unit.id.clone())
9452 .or_insert_with(|| {
9453 (unit.cursor, unit.bootstrap_state.clone(), BTreeSet::new())
9454 })
9455 .2
9456 .insert(segment_id);
9457 }
9458 _ => {
9459 return Err(SectionError::Abort(
9460 "sync.invalid_request".to_owned(),
9461 "unexpected frame inside a unit section".to_owned(),
9462 ));
9463 }
9464 }
9465 }
9466 Ok(())
9467 })();
9468 match applied {
9469 Ok(()) => {}
9470 Err(SectionError::Refused | SectionError::Deferred) => return Ok(()),
9472 Err(SectionError::FailClosed) => {
9473 self.begin_observation("syncular_section_failure")
9476 .map_err(storage)?;
9477 let failed = (|| {
9478 let mut batch = ChangeAccumulator::default();
9479 for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9480 batch.window(&base_key, &value);
9481 }
9482 batch.status = true;
9483 self.stored(save_unit(
9484 &self.conn,
9485 &UnitRecord {
9486 status: UnitStatus::Failed,
9487 reason_code: Some("sync.scope_revoked".to_owned()),
9488 ..unit.clone()
9489 },
9490 ))?;
9491 self.finish_observation("syncular_section_failure", batch)
9492 })();
9493 if let Err(message) = failed {
9494 self.rollback_observation("syncular_section_failure");
9495 return Err(storage(message));
9496 }
9497 report.failed.push(unit.id);
9498 return Ok(());
9499 }
9500 Err(error) => return Err(error),
9501 }
9502 let Some((next_cursor, bootstrap_state)) = sub_end else {
9503 return Ok(());
9504 };
9505 let rollback = self.capture();
9506 let counts = (
9507 report.resets.len(),
9508 report.revoked.len(),
9509 report.failed.len(),
9510 );
9511 self.begin_observation("syncular_sub_end")
9512 .map_err(storage)?;
9513 let finished = self
9514 .finish_section(start, echo, next_cursor, bootstrap_state, seeded, report)
9515 .and_then(|batch| {
9516 self.rebuild_overlay_if_dirty()?;
9517 self.finish_observation("syncular_sub_end", batch)
9518 });
9519 if let Err(message) = finished {
9520 self.rollback_observation("syncular_sub_end");
9521 self.restore(rollback);
9522 report.resets.truncate(counts.0);
9523 report.revoked.truncate(counts.1);
9524 report.failed.truncate(counts.2);
9525 return Err(storage(message));
9526 }
9527 self.applied_segments.remove(&unit.id);
9528 Ok(())
9529 }
9530
9531 #[allow(clippy::type_complexity)]
9534 fn segment_pair(
9535 &self,
9536 unit: &UnitRecord,
9537 echo: &[EchoRecord],
9538 seeded: &BTreeSet<String>,
9539 name: &str,
9540 ) -> Result<(TableSchema, bool, Vec<(String, Vec<String>)>), SectionError> {
9541 let table = self.schema.table(name).cloned().ok_or_else(|| {
9542 SectionError::Abort(
9543 "sync.schema_mismatch".to_owned(),
9544 format!("segment table {name:?} is not in the client schema"),
9545 )
9546 })?;
9547 let effective = covers(&table, &unit.scopes)
9548 .then(|| pair_scopes(&unit.scopes, name, Some(echo)))
9549 .flatten()
9550 .ok_or_else(|| {
9551 SectionError::Abort(
9552 "sync.invalid_request".to_owned(),
9553 "a segment names no active pair of its unit".to_owned(),
9554 )
9555 })?;
9556 Ok((table, !seeded.contains(name), effective))
9557 }
9558
9559 fn finish_section(
9566 &mut self,
9567 start: &SectionStart,
9568 echo: Vec<EchoRecord>,
9569 next_cursor: i64,
9570 bootstrap_state: Option<String>,
9571 seeded: BTreeSet<String>,
9572 report: &mut SyncReport,
9573 ) -> Result<ChangeAccumulator, String> {
9574 #[cfg(feature = "bench-internals")]
9575 let _phase = self.benchmark_phases.start(Phase::CursorPersist);
9576 let mut batch = ChangeAccumulator::default();
9577 let Some(unit) = self
9579 .stored(get_unit(&self.conn, &start.id))?
9580 .filter(|unit| unit.status == UnitStatus::Active)
9581 else {
9582 return Ok(batch);
9583 };
9584 for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9585 batch.window(&base_key, &value);
9586 }
9587 if start.status == SubStatus::Reset {
9588 report.resets.push(unit.id.clone());
9591 self.stored(save_unit(
9592 &self.conn,
9593 &UnitRecord {
9594 reason_code: Some(start.reason_code.clone()),
9595 cursor: Some(-1),
9596 bootstrap_state: None,
9597 seeded: Vec::new(),
9598 ..unit
9599 },
9600 ))?;
9601 return Ok(batch);
9602 }
9603 let revoked = start.status == SubStatus::Revoked;
9604 let mut units = None;
9605 let mut failed = false;
9606 let mut rearmed = false;
9607 for table in self.schema.tables.clone() {
9608 if !covers(&table, &unit.scopes) {
9609 continue;
9610 }
9611 let last = unit
9612 .echo
9613 .as_deref()
9614 .and_then(|last| pair_scopes(&unit.scopes, &table.name, Some(last)));
9615 let next = (!revoked)
9616 .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
9617 .flatten();
9618 rearmed |= unit.echo.is_some() && last.is_none() && next.is_some();
9620 if let (Some(last), None) = (&last, &next) {
9623 let units = match units {
9624 Some(ref units) => units,
9625 None => units.insert(self.stored(load_units(&self.conn))?),
9626 };
9627 let owners = unit_owners(units, &table, &unit.id);
9628 failed |= !self.purge_pair(&mut batch, &table, last, &owners)?;
9629 }
9630 }
9631 if revoked || failed {
9632 if revoked {
9633 report.revoked.push(unit.id.clone());
9634 }
9635 if failed {
9636 report.failed.push(unit.id.clone());
9637 }
9638 batch.status = true;
9639 self.stored(save_unit(
9640 &self.conn,
9641 &UnitRecord {
9642 status: if failed {
9643 UnitStatus::Failed
9644 } else {
9645 UnitStatus::Revoked
9646 },
9647 reason_code: Some(if failed {
9648 "sync.scope_revoked".to_owned()
9649 } else {
9650 start.reason_code.clone()
9651 }),
9652 cursor: Some(-1),
9653 bootstrap_state: None,
9654 seeded: Vec::new(),
9655 echo: None,
9656 ..unit
9657 },
9658 ))?;
9659 return Ok(batch);
9660 }
9661 let completed = start.bootstrap && !rearmed && bootstrap_state.is_none();
9662 let (cursor, bootstrap_state, seeded) = if rearmed {
9663 (Some(-1), None, Vec::new())
9664 } else if start.bootstrap {
9665 let seeded = if bootstrap_state.is_none() {
9666 Vec::new()
9667 } else {
9668 seeded.into_iter().collect()
9669 };
9670 (Some(next_cursor), bootstrap_state, seeded)
9671 } else {
9672 (
9673 unit.cursor,
9674 unit.bootstrap_state.clone(),
9675 unit.seeded.clone(),
9676 )
9677 };
9678 self.stored(save_unit(
9679 &self.conn,
9680 &UnitRecord {
9681 reason_code: None,
9682 echo: Some(echo.clone()),
9683 cursor,
9684 bootstrap_state,
9685 seeded,
9686 ..unit.clone()
9687 },
9688 ))?;
9689 if !completed {
9690 return Ok(batch);
9691 }
9692 for table in self.schema.tables.clone() {
9695 let Some(effective) = covers(&table, &unit.scopes)
9696 .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
9697 .flatten()
9698 else {
9699 continue;
9700 };
9701 let mut statement = self
9702 .conn
9703 .prepare("SELECT id,intent_json FROM _syncular_acked_rows WHERE tbl=?1 AND commit_seq<=?2")
9704 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9705 let rows = statement
9706 .query_map(rusqlite::params![table.name, next_cursor], |row| {
9707 Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
9708 })
9709 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9710 let mut covered = HashSet::new();
9711 for row in rows {
9712 let (id, intent) =
9713 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9714 let values: Map<String, Value> =
9715 serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
9716 if owns_local_row(&table, &effective, &[], &values) {
9717 covered.insert(id);
9718 }
9719 }
9720 drop(statement);
9721 for id in covered {
9722 self.conn
9723 .execute(
9724 "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3",
9725 rusqlite::params![table.name, id, next_cursor],
9726 )
9727 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9728 self.overlay_dirty.table(&table.name);
9729 batch.table(&table.name);
9730 }
9731 }
9732 Ok(batch)
9733 }
9734
9735 fn purge_pair(
9741 &mut self,
9742 batch: &mut ChangeAccumulator,
9743 table: &TableSchema,
9744 last: &[(String, Vec<String>)],
9745 owners: &[Vec<(String, Vec<String>)>],
9746 ) -> Result<bool, String> {
9747 if local_scope_predicate(table, last, owners).is_err() {
9748 return Ok(false);
9749 }
9750 for commit in self.drop_failed_commits(|name, values| {
9751 name == table.name && owns_local_row(table, last, owners, values)
9752 })? {
9753 batch.conflicts = true;
9754 batch.rejections = true;
9755 batch.outcomes = true;
9756 for operation in commit.ops {
9757 batch.table(&operation.table);
9758 }
9759 }
9760 if !self.purge_scope_rows(&table.name, last, owners)? {
9761 return Err("storage.failed: the revoked scope purge failed".to_owned());
9762 }
9763 self.record_scope_map(batch, &table.name, last);
9764 if self.drop_doomed_outbox(table, last, owners)? {
9765 batch.status = true;
9766 batch.rejections = true;
9767 batch.outcomes = true;
9768 }
9769 self.delete_unreferenced_cached_blobs()?;
9771 Ok(true)
9772 }
9773
9774 fn apply_live_commit(
9779 &mut self,
9780 receivers: &[UnitRecord],
9781 tables: &[String],
9782 changes: Vec<ssp2::model::Change>,
9783 commit_seq: i64,
9784 source: AppliedServerCommitSource,
9785 ) -> Result<bool, TransportError> {
9786 let changes: Vec<ssp2::model::Change> = changes
9787 .into_iter()
9788 .filter(|change| {
9789 let Some(table) = tables
9791 .get(change.table_index as usize)
9792 .and_then(|name| self.schema.table(name))
9793 else {
9794 return true;
9795 };
9796 receivers.iter().any(|unit| {
9797 covers(table, &unit.scopes)
9798 && pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()).is_some_and(
9799 |scopes| {
9800 scopes.iter().all(|(variable, values)| {
9801 change
9802 .scopes
9803 .iter()
9804 .find(|(key, _)| key == variable)
9805 .is_some_and(|(_, value)| values.contains(value))
9806 })
9807 },
9808 )
9809 })
9810 })
9811 .collect();
9812 if changes.is_empty() {
9813 return Ok(false);
9814 }
9815 let affected_tables = changes
9816 .iter()
9817 .filter_map(|change| tables.get(change.table_index as usize))
9818 .cloned()
9819 .collect::<BTreeSet<_>>();
9820 let previous_batches = self.change_queue.len();
9821 self.apply_commit_frame(tables, &changes, commit_seq)?;
9822 if self.change_queue.len() > previous_batches {
9823 if let Some(batch) = self.change_queue.back_mut() {
9824 batch
9825 .applied_commits
9826 .extend(
9827 affected_tables
9828 .into_iter()
9829 .map(|table| AppliedServerCommit {
9830 table,
9831 commit_seq,
9832 source,
9833 }),
9834 );
9835 }
9836 }
9837 Ok(true)
9838 }
9839
9840 fn apply_commit_frame(
9842 &mut self,
9843 tables: &[String],
9844 changes: &[ssp2::model::Change],
9845 sequence: i64,
9846 ) -> Result<(), TransportError> {
9847 #[cfg(feature = "bench-internals")]
9848 let _phase = self.benchmark_phases.start(Phase::CommitApply);
9849 let rollback = self.capture();
9850 self.coalesce_unit(changes.len())
9851 .and_then(|()| self.begin_observation("syncular_commit"))
9852 .map_err(|message| TransportError::new("storage.failed", message))?;
9853 let applied = (|| {
9854 let mut batch = ChangeAccumulator::default();
9855 self.record_commit_changes(&mut batch, tables, changes);
9856 for change in changes {
9859 let Some(table) = tables.get(change.table_index as usize) else {
9860 continue;
9861 };
9862 let acknowledged = self
9863 .conn
9864 .prepare_cached("SELECT op_json FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq=?3")
9865 .and_then(|mut statement| {
9866 statement
9867 .query_map(rusqlite::params![table, change.row_id, sequence], |row| row.get::<_, String>(0))?
9868 .collect::<Result<Vec<_>, _>>()
9869 })
9870 .map_err(|error| TransportError::new("storage.failed", Self::sqlite_failure(&self.storage_failure, error)))?
9871 .iter()
9872 .map(|op| serde_json::from_str::<CommitOperation>(op).map(OutboxOp::from))
9873 .collect::<Result<Vec<_>, _>>()
9874 .map_err(|_| TransportError::new("storage.failed", "sync.local_corrupt: invalid acknowledged operation".to_owned()))?;
9875 for index in 0..self.outbox.len() {
9876 if !self.outbox[index]
9877 .ops
9878 .iter()
9879 .any(|op| acknowledged.iter().any(|earlier| chains_on(earlier, op)))
9880 {
9881 continue;
9882 }
9883 let commit = Arc::make_mut(&mut self.outbox[index]);
9884 for op in &mut commit.ops {
9885 if acknowledged.iter().any(|earlier| chains_on(earlier, op)) {
9886 op.base_version = Some(change.row_version);
9887 }
9888 }
9889 let ops = serde_json::to_string(
9890 &commit
9891 .ops
9892 .iter()
9893 .map(CommitOperation::from)
9894 .collect::<Vec<_>>(),
9895 )
9896 .map_err(|_| {
9897 TransportError::new(
9898 "storage.failed",
9899 "sync.local_corrupt: unencodable outbox".to_owned(),
9900 )
9901 })?;
9902 let id = commit.client_commit_id.clone();
9903 self.conn
9904 .execute(
9905 "UPDATE _syncular_outbox SET ops_json=?1 WHERE commit_id=?2",
9906 rusqlite::params![ops, id],
9907 )
9908 .map_err(|error| {
9909 TransportError::new(
9910 "storage.failed",
9911 Self::sqlite_failure(&self.storage_failure, error),
9912 )
9913 })?;
9914 }
9915 }
9916 {
9917 let storage_failed = |error| {
9918 TransportError::new(
9919 "storage.failed",
9920 Self::sqlite_failure(&self.storage_failure, error),
9921 )
9922 };
9923 let pinned: HashSet<(&str, &str)> = self
9924 .outbox
9925 .iter()
9926 .flat_map(|commit| &commit.ops)
9927 .map(|op| (op.table.as_str(), op.row_id.as_str()))
9928 .collect();
9929 for change in changes {
9930 let table = tables.get(change.table_index as usize).ok_or_else(|| {
9931 TransportError::new(
9932 "sync.invalid_request",
9933 "change tableIndex out of range".to_owned(),
9934 )
9935 })?;
9936 if pinned.contains(&(table.as_str(), change.row_id.as_str())) {
9937 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)")
9938 .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
9939 .map_err(storage_failed)?;
9940 }
9941 self.conn.prepare_cached("DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3")
9942 .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
9943 .map_err(storage_failed)?;
9944 }
9945 }
9946 self.apply_commit_changes(tables, changes)?;
9947 self.rebuild_overlay_if_dirty()
9948 .map_err(|message| TransportError::new("storage.failed", message))?;
9949 self.finish_observation("syncular_commit", batch)
9950 .map_err(|message| TransportError::new("storage.failed", message))
9951 })();
9952 if applied.is_err() {
9953 self.rollback_observation("syncular_commit");
9954 self.restore(rollback);
9955 }
9956 applied
9957 }
9958
9959 fn apply_commit_changes(
9960 &mut self,
9961 tables: &[String],
9962 changes: &[ssp2::model::Change],
9963 ) -> Result<(), TransportError> {
9964 let changed_tables: BTreeSet<&str> = changes
9969 .iter()
9970 .filter_map(|change| tables.get(change.table_index as usize))
9971 .map(String::as_str)
9972 .collect();
9973 let mut mirror_visible = !self.overlay_dirty.get();
9974 for name in &changed_tables {
9975 if mirror_visible
9976 && self
9977 .schema
9978 .table(name)
9979 .is_some_and(|table| table.indexes.iter().any(|index| index.unique))
9980 {
9981 let (pending, protected) = self
9982 .table_intent(name)
9983 .map_err(|message| TransportError::new("storage.failed", message))?;
9984 mirror_visible = !pending && !protected;
9985 }
9986 }
9987 for change in changes {
9988 let table_name = tables.get(change.table_index as usize).ok_or_else(|| {
9989 TransportError::new(
9990 "sync.invalid_request",
9991 "change tableIndex out of range".to_owned(),
9992 )
9993 })?;
9994 let table = self.schema.table(table_name).ok_or_else(|| {
9995 TransportError::new(
9996 "sync.schema_mismatch",
9997 format!("change targets unknown table {table_name:?}"),
9998 )
9999 })?;
10000 let landed = match change.op {
10001 Op::Upsert => {
10002 let payload = change.row.as_ref().ok_or_else(|| {
10003 TransportError::new(
10004 "sync.invalid_request",
10005 "upsert change without row payload".to_owned(),
10006 )
10007 })?;
10008 let (row, sealed) = {
10010 #[cfg(feature = "bench-internals")]
10011 let _phase = self.benchmark_phases.start(Phase::RowDecode);
10012 decode_row_bytes(table, payload, &self.encryption)?
10014 };
10015 let table_name = table.name.clone();
10016 let landed = self
10018 .write_base_row(&table_name, &row, change.row_version, sealed.as_ref())
10019 .map_err(|m| TransportError::new("sync.invalid_request", m))?;
10020 if mirror_visible && landed {
10021 self.write_row(
10022 &visible_table(&table_name),
10023 &table_name,
10024 &row,
10025 change.row_version,
10026 sealed.as_ref(),
10027 )
10028 .map_err(|m| TransportError::new("sync.invalid_request", m))?;
10029 }
10030 landed
10031 }
10032 Op::Delete => self
10035 .delete_base_row(table_name, &change.row_id, change.row_version)
10036 .map_err(|m| TransportError::new("sync.invalid_request", m))?,
10037 };
10038 self.overlay_dirty.table(table_name);
10042 if mirror_visible && !(landed && change.op == Op::Upsert) {
10043 let predicate = row_id_predicate(table);
10044 let visible = visible_table(table_name);
10045 let mut statements = vec![format!("DELETE FROM {visible} WHERE {predicate}")];
10046 if !landed {
10047 statements.push(format!(
10048 "INSERT INTO {visible} SELECT * FROM {} WHERE {predicate}",
10049 base_table(table_name)
10050 ));
10051 }
10052 for statement in &statements {
10053 self.conn
10054 .prepare_cached(statement)
10055 .and_then(|mut statement| {
10056 statement.execute(rusqlite::params![change.row_id])
10057 })
10058 .map_err(|error| {
10059 TransportError::new("sync.invalid_request", error.to_string())
10060 })?;
10061 }
10062 }
10063 }
10064 if mirror_visible {
10065 let changed_rows: HashSet<(&str, &str)> = changes
10066 .iter()
10067 .map(|change| {
10068 (
10069 tables[change.table_index as usize].as_str(),
10070 change.row_id.as_str(),
10071 )
10072 })
10073 .collect();
10074 self.replay_overlay(&changed_tables, Some(&changed_rows))
10075 .map_err(|message| TransportError::new("storage.failed", message))?;
10076 self.overlay_dirty.set(false);
10077 }
10078 Ok(())
10079 }
10080
10081 fn apply_segment(
10086 &mut self,
10087 table: &TableSchema,
10088 segment: &RowsSegment,
10089 first_page: bool,
10090 effective: &[(String, Vec<String>)],
10091 unit_id: &str,
10092 ) -> Result<u32, SectionError> {
10093 let column = if segment.columns.len() != table.wire_columns.len() {
10098 Some(Value::from("count"))
10099 } else {
10100 segment
10101 .columns
10102 .iter()
10103 .zip(table.wire_columns.iter())
10104 .position(|(a, b)| a.name != b.name || a.ty != b.ty || a.nullable != b.nullable)
10105 .map(Value::from)
10106 };
10107 if segment.table != table.name
10108 || segment.schema_version != self.schema.version
10109 || column.is_some()
10110 {
10111 let mut details = Map::new();
10112 details.insert("table".to_owned(), Value::from(table.name.as_str()));
10113 if let Some(column) = column {
10114 details.insert("column".to_owned(), column);
10115 }
10116 return Err(SectionError::Transport(TransportError {
10117 code: "sync.schema_mismatch".to_owned(),
10118 message: "rows segment columns do not match the generated schema (§5.2)".to_owned(),
10119 details: Some(Value::Object(details)),
10120 }));
10121 }
10122 let mut applied = 0u32;
10123 let empty = Vec::new();
10124 let blocks = if segment.blocks.is_empty() {
10125 std::slice::from_ref(&empty)
10126 } else {
10127 &segment.blocks
10128 };
10129 for (index, block) in blocks.iter().enumerate() {
10130 let clear = first_page && index == 0;
10131 if !clear && block.is_empty() {
10132 continue;
10133 }
10134 let rollback = self.capture();
10135 let (pending, protected) = self
10136 .table_intent(&table.name)
10137 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10138 let reconcile_pending =
10139 !protected && pending && table.indexes.iter().any(|index| index.unique);
10140 let mirror_visible = !protected && !reconcile_pending;
10141 self.coalesce_unit(block.len())
10142 .and_then(|()| self.begin_observation("syncular_segment_block"))
10143 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10144 let outcome = (|| {
10145 self.rebuild_overlay_if_dirty()
10146 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10147 let mut changed_keys = Vec::new();
10148 let mut batch = ChangeAccumulator::default();
10149 if clear && self.clear_scope(table, effective, unit_id)? || !block.is_empty() {
10150 batch.table(&table.name);
10151 }
10152 for (row_index, row) in block.iter().enumerate() {
10153 let decrypted;
10154 let mut sealed = None;
10155 let values = if table.has_encrypted_columns() {
10156 let mut values = row.values.clone();
10157 sealed = crate::values::decrypt_segment_row(
10158 table,
10159 &mut values,
10160 &self.encryption,
10161 )
10162 .map_err(SectionError::Transport)?;
10163 decrypted = values;
10164 &decrypted
10165 } else {
10166 &row.values
10167 };
10168 if !self
10169 .write_base_row(&table.name, values, row.server_version, sealed.as_ref())
10170 .map_err(|message| {
10171 SectionError::Abort("sync.invalid_request".into(), message)
10172 })?
10173 {
10174 continue;
10175 }
10176 if reconcile_pending {
10177 changed_keys.push(
10178 owned_sql_value(RowParam::Cell(&values[table.pk_index])).map_err(
10179 |message| SectionError::Abort("storage.failed".into(), message),
10180 )?,
10181 );
10182 }
10183 if mirror_visible {
10184 self.write_row(
10185 &visible_table(&table.name),
10186 &table.name,
10187 values,
10188 row.server_version,
10189 sealed.as_ref(),
10190 )
10191 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10192 }
10193 let processed = u64::from(applied) + row_index as u64 + 1;
10194 if processed.is_multiple_of(1024) {
10195 self.progress.update(|p| p.rows_processed = processed);
10196 }
10197 }
10198 self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
10199 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10200 self.finish_observation("syncular_segment_block", batch)
10201 .map_err(|message| SectionError::Abort("storage.failed".into(), message))
10202 })();
10203 if let Err(error) = outcome {
10204 self.rollback_observation("syncular_segment_block");
10205 self.restore(rollback);
10206 return Err(error);
10207 }
10208 applied += block.len() as u32;
10209 self.progress
10210 .update(|p| p.rows_processed = u64::from(applied));
10211 std::thread::yield_now();
10212 }
10213 self.progress
10214 .update(|p| p.rows_processed = u64::from(applied));
10215 Ok(applied)
10216 }
10217
10218 #[allow(clippy::too_many_arguments)]
10226 fn apply_sqlite_segment(
10227 &mut self,
10228 table: &TableSchema,
10229 bytes: &[u8],
10230 first_page: bool,
10231 effective: &[(String, Vec<String>)],
10232 unit_id: &str,
10233 row_count: i64,
10234 as_of_commit_seq: i64,
10235 scope_digest: &str,
10236 ) -> Result<u32, SectionError> {
10237 let invalid = |detail: &str| {
10238 SectionError::Abort(
10239 "sync.invalid_request".to_owned(),
10240 format!("sqlite segment rejected: {detail} (§5.3)"),
10241 )
10242 };
10243 if table.has_encrypted_columns() {
10246 return Err(invalid("table has encrypted columns"));
10247 }
10248
10249 let directory = self
10253 .previous_version_replica_path()
10254 .and_then(|replica| std::path::Path::new(&replica).parent().map(Into::into))
10255 .unwrap_or_else(std::env::temp_dir);
10256 let path = directory.join(format!(".syncular-image-{}.tmp", uuid::Uuid::new_v4()));
10257 let outcome = (|| {
10258 let mut options = std::fs::OpenOptions::new();
10259 options.write(true).create_new(true);
10260 #[cfg(unix)]
10261 std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600);
10262 std::io::Write::write_all(
10263 &mut options
10264 .open(&path)
10265 .map_err(|_| invalid("image temp file write failed"))?,
10266 bytes,
10267 )
10268 .map_err(|_| invalid("image temp file write failed"))?;
10269 let img = rusqlite::Connection::open_with_flags(
10270 &path,
10271 rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY,
10272 )
10273 .map_err(|_| invalid("bytes do not open as a SQLite database"))?;
10274 self.apply_sqlite_image(
10275 &img,
10276 table,
10277 first_page,
10278 effective,
10279 unit_id,
10280 row_count,
10281 as_of_commit_seq,
10282 scope_digest,
10283 )
10284 })();
10285 let _ = std::fs::remove_file(&path);
10286 outcome
10287 }
10288
10289 #[allow(clippy::too_many_arguments)]
10290 fn apply_sqlite_image(
10291 &mut self,
10292 img: &rusqlite::Connection,
10293 table: &crate::schema::TableSchema,
10294 first_fresh_page: bool,
10295 effective: &[(String, Vec<String>)],
10296 unit_id: &str,
10297 row_count: i64,
10298 as_of_commit_seq: i64,
10299 scope_digest: &str,
10300 ) -> Result<u32, SectionError> {
10301 let invalid = |detail: String| {
10302 SectionError::Abort(
10303 "sync.invalid_request".to_owned(),
10304 format!("sqlite segment rejected: {detail} (§5.3)"),
10305 )
10306 };
10307
10308 type MetaRow = (i64, String, i64, i64, String, i64, i64);
10311 let meta: MetaRow = img
10312 .query_row(
10313 "SELECT format, \"table\", \"schemaVersion\", \"asOfCommitSeq\",
10314 \"scopeDigest\", \"rowCount\",
10315 (SELECT count(*) FROM _syncular_segment)
10316 FROM _syncular_segment",
10317 [],
10318 |row| {
10319 Ok((
10320 row.get(0)?,
10321 row.get(1)?,
10322 row.get(2)?,
10323 row.get(3)?,
10324 row.get(4)?,
10325 row.get(5)?,
10326 row.get(6)?,
10327 ))
10328 },
10329 )
10330 .map_err(|_| invalid("missing or unreadable _syncular_segment metadata".to_owned()))?;
10331 let (format, meta_table, schema_version, pin, digest, meta_rows, meta_count) = meta;
10332 if meta_count != 1 {
10333 return Err(invalid(format!(
10334 "_syncular_segment must contain exactly one row, found {meta_count}"
10335 )));
10336 }
10337 if format != 1 {
10338 return Err(invalid(format!("format {format}")));
10339 }
10340 if meta_table != table.name {
10341 return Err(invalid(format!("image table {meta_table:?}")));
10342 }
10343 if schema_version != i64::from(self.schema.version) {
10344 return Err(invalid(format!("schemaVersion {schema_version}")));
10345 }
10346 if pin != as_of_commit_seq {
10347 return Err(invalid(format!("asOfCommitSeq {pin}")));
10348 }
10349 if digest != scope_digest {
10350 return Err(invalid("scopeDigest mismatch".to_owned()));
10351 }
10352 if meta_rows != row_count {
10353 return Err(invalid(format!("rowCount {meta_rows}")));
10354 }
10355
10356 let mut names: Vec<String> = Vec::new();
10358 let mut primary_keys: Vec<String> = Vec::new();
10359 {
10360 let mut stmt = img
10361 .prepare(&format!("PRAGMA table_info({})", quote_ident(&table.name)))
10362 .map_err(|_| invalid("image data table missing".to_owned()))?;
10363 let mut rows = stmt
10364 .query([])
10365 .map_err(|_| invalid("image data table unreadable".to_owned()))?;
10366 while let Some(row) = rows
10367 .next()
10368 .map_err(|_| invalid("image data table unreadable".to_owned()))?
10369 {
10370 if row
10371 .get::<_, i64>(5)
10372 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?
10373 > 0
10374 {
10375 primary_keys.push(row.get(1).map_err(|error| {
10376 invalid(Self::sqlite_failure(&self.storage_failure, error))
10377 })?);
10378 }
10379 names.push(
10380 row.get::<_, String>(1)
10381 .map_err(|_| invalid("image data table unreadable".to_owned()))?,
10382 );
10383 }
10384 }
10385 let mut expected: Vec<&str> = table.columns.iter().map(|c| c.name.as_str()).collect();
10386 expected.push("_syncular_version");
10387 if names.len() != expected.len() || names.iter().zip(expected.iter()).any(|(a, b)| a != b) {
10388 return Err(SectionError::Transport(TransportError {
10389 code: "sync.schema_mismatch".to_owned(),
10390 message: "sqlite segment columns do not match the generated schema (§5.3)"
10391 .to_owned(),
10392 details: Some(serde_json::json!({ "table": table.name })),
10393 }));
10394 }
10395
10396 if primary_keys != vec![table.primary_key.clone()] {
10397 return Err(invalid(
10398 "image primary key does not match generated schema".into(),
10399 ));
10400 }
10401 let actual_count: i64 = img
10402 .query_row(
10403 &format!("SELECT count(*) FROM {}", quote_ident(&table.name)),
10404 [],
10405 |row| row.get(0),
10406 )
10407 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10408 if actual_count != row_count {
10409 return Err(invalid("image row count does not match descriptor".into()));
10410 }
10411 let insert = self.insert_row_sql(&base_table(&table.name), table);
10412 let visible_insert = self.insert_row_sql(&visible_table(&table.name), table);
10413 let column_list = names
10414 .iter()
10415 .map(|n| quote_ident(n))
10416 .collect::<Vec<_>>()
10417 .join(", ");
10418 let mut stmt = img
10419 .prepare(&format!(
10420 "SELECT {column_list} FROM {} ORDER BY {}",
10421 quote_ident(&table.name),
10422 quote_ident(&table.primary_key)
10423 ))
10424 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10425 let mut rows = stmt
10426 .query([])
10427 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10428 let mut applied = 0u32;
10429 let mut limit = if first_fresh_page {
10430 1024
10431 } else {
10432 self.image_chunk_rows
10433 .get(&table.name)
10434 .copied()
10435 .unwrap_or(1024)
10436 };
10437 let (mut write, mut commit) = (std::time::Duration::ZERO, std::time::Duration::ZERO);
10438 loop {
10439 let clear = applied == 0 && first_fresh_page;
10440 let rollback = self.capture();
10441 let (pending, protected) = self
10442 .table_intent(&table.name)
10443 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10444 let reconcile_pending =
10445 !protected && pending && table.indexes.iter().any(|index| index.unique);
10446 let mirror_visible = !protected && !reconcile_pending;
10447 let chunk = if pending || protected {
10454 limit.min(1024)
10455 } else {
10456 limit
10457 };
10458 self.coalesce_unit(chunk as usize)
10459 .and_then(|()| self.begin_observation("syncular_image_chunk"))
10460 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10461 let started = std::time::Instant::now();
10462 let result = (|| {
10463 self.rebuild_overlay_if_dirty()
10464 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10465 let mut changed_keys = Vec::new();
10466 let mut batch = ChangeAccumulator::default();
10467 if clear && self.clear_scope(table, effective, unit_id)? {
10468 batch.table(&table.name);
10469 }
10470 let mut processed = 0u32;
10471 {
10472 let mut ins = self.conn.prepare_cached(&insert).map_err(|error| {
10473 invalid(Self::sqlite_failure(&self.storage_failure, error))
10474 })?;
10475 let mut mirror = if mirror_visible {
10476 Some(self.conn.prepare_cached(&visible_insert).map_err(|error| {
10477 invalid(Self::sqlite_failure(&self.storage_failure, error))
10478 })?)
10479 } else {
10480 None
10481 };
10482 for _ in 0..chunk {
10483 let Some(row) = rows.next().map_err(|error| {
10484 invalid(Self::sqlite_failure(&self.storage_failure, error))
10485 })?
10486 else {
10487 break;
10488 };
10489 for (i, column) in table.columns.iter().enumerate() {
10490 let cell = row.get_ref(i).map_err(|error| {
10491 invalid(Self::sqlite_failure(&self.storage_failure, error))
10492 })?;
10493 let param = image_cell_param(column, cell).map_err(invalid)?;
10494 ins.raw_bind_parameter(i + 1, ¶m).map_err(|error| {
10495 invalid(Self::sqlite_failure(&self.storage_failure, error))
10496 })?;
10497 if let Some(mirror) = &mut mirror {
10498 mirror.raw_bind_parameter(i + 1, ¶m).map_err(|error| {
10499 invalid(Self::sqlite_failure(&self.storage_failure, error))
10500 })?;
10501 }
10502 }
10503 let version_index = table.columns.len();
10504 let version: i64 = row.get(version_index).map_err(|error| {
10505 invalid(Self::sqlite_failure(&self.storage_failure, error))
10506 })?;
10507 if version < 1 {
10508 return Err(invalid("image row version must be positive".into()));
10509 }
10510 ins.raw_bind_parameter(version_index + 1, version)
10511 .map_err(|error| {
10512 invalid(Self::sqlite_failure(&self.storage_failure, error))
10513 })?;
10514 let landed = ins.raw_execute().map_err(|error| {
10516 invalid(Self::sqlite_failure(&self.storage_failure, error))
10517 })? > 0;
10518 processed += 1;
10519 if processed.is_multiple_of(1024) && processed < chunk {
10520 self.progress
10521 .update(|p| p.rows_processed = u64::from(applied + processed));
10522 }
10523 if !landed {
10524 continue;
10525 }
10526 if let Some(mirror) = &mut mirror {
10527 mirror
10528 .raw_bind_parameter(version_index + 1, version)
10529 .map_err(|error| {
10530 invalid(Self::sqlite_failure(&self.storage_failure, error))
10531 })?;
10532 mirror.raw_execute().map_err(|error| {
10533 invalid(Self::sqlite_failure(&self.storage_failure, error))
10534 })?;
10535 }
10536 if reconcile_pending {
10537 changed_keys.push(row.get::<_, SqlValue>(table.pk_index).map_err(
10538 |error| invalid(Self::sqlite_failure(&self.storage_failure, error)),
10539 )?);
10540 }
10541 }
10542 }
10543 if processed > 0 {
10544 batch.table(&table.name);
10545 self.overlay_dirty.table(&table.name);
10546 }
10547 self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
10548 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10549 let written = std::time::Instant::now();
10550 self.finish_observation("syncular_image_chunk", batch)
10551 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10552 Ok((processed, written))
10553 })();
10554 let (processed, written) = match result {
10555 Ok(done) => done,
10556 Err(error) => {
10557 self.rollback_observation("syncular_image_chunk");
10558 self.restore(rollback);
10559 return Err(error);
10560 }
10561 };
10562 let coalesced = self.coalesced.is_some();
10564 if coalesced {
10565 self.commit_coalesced_apply()
10566 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10567 }
10568 write += written - started;
10569 commit += written.elapsed();
10570 applied += processed;
10571 let last = processed < chunk || i64::from(applied) == actual_count;
10572 if last && self.conn.is_autocommit() {
10574 self.conn
10575 .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
10576 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10577 }
10578 if coalesced {
10579 self.begin_coalesced_apply()
10580 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10581 }
10582 self.progress.update(|p| {
10583 p.rows_processed = u64::from(applied);
10584 p.import_write_ms = u64::try_from(write.as_millis()).ok();
10585 p.import_commit_ms = u64::try_from(commit.as_millis()).ok();
10586 });
10587 let duration = started.elapsed().as_secs_f64() * 1000.0;
10588 #[cfg(test)]
10589 let duration = self.image_chunk_ms.get().unwrap_or(duration);
10590 std::thread::yield_now();
10591 if last {
10592 break;
10593 }
10594 limit = (processed * 2)
10596 .min(65_536)
10597 .min((f64::from(processed) * 250.0 / duration) as u32)
10598 .max(1024);
10599 self.image_chunk_rows.insert(table.name.clone(), limit);
10600 }
10601 if i64::from(applied) != actual_count {
10602 return Err(invalid(format!(
10603 "image yielded {applied} rows, expected {actual_count}"
10604 )));
10605 }
10606 Ok(applied)
10607 }
10608
10609 fn reconcile_rows(&self, drained: &[Arc<OutboxCommit>]) -> Result<(), String> {
10614 let names: BTreeSet<&str> = drained
10615 .iter()
10616 .flat_map(|commit| &commit.ops)
10617 .map(|op| op.table.as_str())
10618 .collect();
10619 for name in names {
10620 let Some(table) = self.schema.table(name) else {
10621 continue;
10622 };
10623 let ops = drained.iter().flat_map(|commit| &commit.ops);
10624 let tables = BTreeSet::from([name]);
10625 let rows: HashSet<_> = ops
10626 .clone()
10627 .map(|op| (op.table.as_str(), op.row_id.as_str()))
10628 .collect();
10629 let unique = table.indexes.iter().any(|index| index.unique);
10630 let acknowledged = if unique {
10631 self.acknowledged_operations(None, Some(&tables))?
10632 } else {
10633 Vec::new()
10634 };
10635 let peers = acknowledged
10636 .iter()
10637 .chain(
10638 self.failed_commits
10639 .iter()
10640 .flat_map(|(commit, _)| &commit.ops),
10641 )
10642 .chain(self.outbox.iter().flat_map(|commit| &commit.ops))
10643 .filter(|_| unique);
10644 self.restore_base_rows(table, &mut Vec::new(), peers.chain(ops.clone()))?;
10645 self.replay_overlay(&tables, (!unique).then_some(&rows))?;
10646 }
10647 Ok(())
10648 }
10649
10650 fn table_intent(&self, table: &str) -> Result<(bool, bool), String> {
10653 let touches = |op: &OutboxOp| op.table == table;
10654 Ok((
10655 self.outbox
10656 .iter()
10657 .flat_map(|commit| &commit.ops)
10658 .any(touches),
10659 self.failed_commits
10660 .iter()
10661 .flat_map(|(commit, _)| &commit.ops)
10662 .any(touches)
10663 || self
10664 .conn
10665 .query_row(
10666 "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows WHERE tbl=?1)",
10667 [table],
10668 |row| row.get(0),
10669 )
10670 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10671 ))
10672 }
10673
10674 fn reconcile_import(
10678 &mut self,
10679 table: &TableSchema,
10680 keys: &mut Vec<SqlValue>,
10681 protected: bool,
10682 restore: bool,
10683 ) -> Result<(), String> {
10684 if protected {
10685 return self.rebuild_overlay_if_dirty();
10686 }
10687 let pending = self.outbox.iter().flat_map(|commit| &commit.ops);
10688 if restore {
10689 self.restore_base_rows(table, keys, pending.clone())?;
10690 }
10691 self.apply_outbox_ops(pending.filter(|op| op.table == table.name))?;
10692 self.overlay_dirty.set(false);
10693 Ok(())
10694 }
10695
10696 fn restore_base_rows<'a>(
10700 &self,
10701 table: &TableSchema,
10702 keys: &mut Vec<SqlValue>,
10703 ops: impl IntoIterator<Item = &'a OutboxOp>,
10704 ) -> Result<(), String> {
10705 let visible = visible_table(&table.name);
10706 let base = base_table(&table.name);
10707 let pk = quote_ident(&table.primary_key);
10708 let predicate = row_id_predicate(table);
10709 let mut lookup = self.conn.prepare_cached(&format!(
10710 "SELECT {pk} FROM {base} WHERE {predicate} UNION SELECT {pk} FROM {visible} WHERE {predicate}"
10711 )).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10712 let mut deleted = HashSet::new();
10713 for op in ops.into_iter().filter(|op| op.table == table.name) {
10714 if op.upsert {
10715 if let Some(values) = &op.values {
10716 let key = json_to_column_value(
10717 &table.columns[table.pk_index],
10718 values.get(&table.primary_key),
10719 )?;
10720 keys.push(owned_sql_value(RowParam::Cell(&key))?);
10721 }
10722 } else if deleted.insert(&op.row_id) {
10723 keys.extend(
10724 lookup
10725 .query_map([&op.row_id], |row| row.get::<_, SqlValue>(0))
10726 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
10727 .collect::<Result<Vec<_>, _>>()
10728 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10729 );
10730 }
10731 }
10732 for chunk in keys.chunks(400) {
10735 let holes = vec!["?"; chunk.len()].join(",");
10736 self.conn
10737 .prepare_cached(&format!("DELETE FROM {visible} WHERE {pk} IN ({holes})"))
10738 .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
10739 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10740 }
10741 let updates = table
10742 .columns
10743 .iter()
10744 .map(|column| column.name.as_str())
10745 .chain(std::iter::once("_syncular_version"))
10746 .chain(table.sealed_columns().iter().copied())
10747 .filter(|name| *name != table.primary_key)
10748 .map(|name| {
10749 let name = quote_ident(name);
10750 format!("{name}=excluded.{name}")
10751 })
10752 .collect::<Vec<_>>()
10753 .join(",");
10754 for chunk in keys.chunks(400) {
10755 let holes = vec!["?"; chunk.len()].join(",");
10756 self.conn.prepare_cached(&format!("INSERT INTO {visible} SELECT * FROM {base} WHERE {pk} IN ({holes}) ON CONFLICT ({pk}) DO UPDATE SET {updates}"))
10757 .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
10758 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10759 }
10760 Ok(())
10761 }
10762
10763 fn compile_local_data_purge(
10766 &self,
10767 input: &LocalDataPurgeInput,
10768 ) -> Result<(Vec<CompiledLocalDataPurgeTarget>, String), String> {
10769 let invalid = |message: String| format!("sync.invalid_request: {message}");
10770 if input.purge_id.is_empty()
10771 || input.purge_id.len() > 128
10772 || !is_local_operation_code_like(&input.purge_id)
10773 {
10774 return Err(invalid(
10775 "local purge purgeId must be a 1–128 character code-like identifier".to_owned(),
10776 ));
10777 }
10778 if input.targets.is_empty() || input.targets.len() > MAX_LOCAL_PURGE_TARGETS {
10779 return Err(invalid(format!(
10780 "local purge needs between 1 and {MAX_LOCAL_PURGE_TARGETS} targets"
10781 )));
10782 }
10783
10784 let mut deduplicated: BTreeMap<
10785 String,
10786 (CompiledLocalDataPurgeTarget, LocalDataPurgeTarget),
10787 > = BTreeMap::new();
10788 for target in &input.targets {
10789 let table = self.schema.table(&target.table).ok_or_else(|| {
10790 invalid(format!(
10791 "local purge names unknown table {:?}",
10792 target.table
10793 ))
10794 })?;
10795 if target.selectors.is_empty() || target.selectors.len() > MAX_LOCAL_PURGE_SELECTORS {
10796 return Err(invalid(format!(
10797 "local purge target {:?} needs between 1 and {MAX_LOCAL_PURGE_SELECTORS} selectors",
10798 target.table
10799 )));
10800 }
10801 let mut selectors = Vec::with_capacity(target.selectors.len());
10802 let mut canonical_selectors = BTreeMap::new();
10803 for (column_name, raw_values) in &target.selectors {
10804 let Some((column_index, column)) = table
10805 .columns
10806 .iter()
10807 .enumerate()
10808 .find(|(_, column)| column.name == *column_name)
10809 else {
10810 return Err(invalid(format!(
10811 "local purge target {:?} names unknown column {:?}",
10812 target.table, column_name
10813 )));
10814 };
10815 let encrypted = table
10816 .encrypted_columns
10817 .iter()
10818 .any(|candidate| candidate.index == column_index);
10819 if column.ty != ColumnType::String || encrypted {
10820 return Err(invalid(format!(
10821 "local purge selector {:?}.{:?} must be a plaintext string column",
10822 target.table, column_name
10823 )));
10824 }
10825 if raw_values.is_empty() || raw_values.len() > MAX_LOCAL_PURGE_VALUES {
10826 return Err(invalid(format!(
10827 "local purge selector {:?}.{:?} needs between 1 and {MAX_LOCAL_PURGE_VALUES} values",
10828 target.table, column_name
10829 )));
10830 }
10831 let mut values = raw_values.clone();
10832 values.sort();
10833 values.dedup();
10834 if values.iter().any(|value| {
10835 value.is_empty()
10836 || value.len() > MAX_LOCAL_PURGE_VALUE_LENGTH
10837 || !is_local_operation_code_like(value)
10838 }) {
10839 return Err(invalid(format!(
10840 "local purge selector values must be 1–{MAX_LOCAL_PURGE_VALUE_LENGTH} character code-like identifiers"
10841 )));
10842 }
10843 selectors.push((column_name.clone(), values.clone()));
10844 canonical_selectors.insert(column_name.clone(), values);
10845 }
10846 let canonical = LocalDataPurgeTarget {
10847 table: target.table.clone(),
10848 selectors: canonical_selectors,
10849 };
10850 let key = serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
10851 deduplicated.insert(
10852 key,
10853 (
10854 CompiledLocalDataPurgeTarget {
10855 table: target.table.clone(),
10856 selectors,
10857 },
10858 canonical,
10859 ),
10860 );
10861 }
10862 let targets = deduplicated
10863 .values()
10864 .map(|(compiled, _)| compiled.clone())
10865 .collect::<Vec<_>>();
10866 let canonical = deduplicated
10867 .values()
10868 .map(|(_, target)| target.clone())
10869 .collect::<Vec<_>>();
10870 let canonical_plan =
10871 serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
10872 Ok((targets, canonical_plan))
10873 }
10874
10875 fn local_purge_base_row_ids(
10876 &self,
10877 targets: &[CompiledLocalDataPurgeTarget],
10878 ) -> Result<BTreeMap<String, BTreeSet<String>>, String> {
10879 let mut by_table: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
10880 for target in targets {
10881 let table = self
10882 .schema
10883 .table(&target.table)
10884 .ok_or_else(|| format!("sync.invalid_request: unknown table {:?}", target.table))?;
10885 let mut clauses = Vec::with_capacity(target.selectors.len());
10886 let mut params = Vec::new();
10887 for (column, values) in &target.selectors {
10888 clauses.push(format!(
10889 "{} IN ({})",
10890 quote_ident(column),
10891 values.iter().map(|_| "?").collect::<Vec<_>>().join(", ")
10892 ));
10893 params.extend(values.iter().cloned().map(SqlValue::Text));
10894 }
10895 let sql = format!(
10896 "SELECT CAST({} AS TEXT) FROM {} WHERE {}",
10897 quote_ident(&table.primary_key),
10898 base_table(&target.table),
10899 clauses.join(" AND ")
10900 );
10901 let mut statement = self
10902 .conn
10903 .prepare(&sql)
10904 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10905 let rows = statement
10906 .query_map(rusqlite::params_from_iter(params), |row| {
10907 let value = sql_ref_to_json(&table.columns[table.pk_index], row.get_ref(0)?);
10908 render_row_id_json(Some(&value))
10909 .map_err(|message| rusqlite::Error::ToSqlConversionFailure(message.into()))
10910 })
10911 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10912 let ids = by_table.entry(target.table.clone()).or_default();
10913 for row in rows {
10914 ids.insert(
10915 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10916 );
10917 }
10918 }
10919 Ok(by_table)
10920 }
10921
10922 fn local_purge_values_match(
10923 target: &CompiledLocalDataPurgeTarget,
10924 values: &Map<String, Value>,
10925 ) -> bool {
10926 target.selectors.iter().all(|(column, allowed)| {
10927 values
10928 .get(column)
10929 .and_then(Value::as_str)
10930 .is_some_and(|value| allowed.iter().any(|candidate| candidate == value))
10931 })
10932 }
10933
10934 pub fn purge_local_data(
10938 &mut self,
10939 input: &LocalDataPurgeInput,
10940 ) -> Result<LocalDataPurgeResult, String> {
10941 let (targets, canonical_plan) = self.compile_local_data_purge(input)?;
10942 let meta_key = format!("localPurge:{}", input.purge_id);
10943 let applied_plan = self
10944 .conn
10945 .query_row(
10946 "SELECT value FROM _syncular_meta WHERE key = ?1",
10947 rusqlite::params![meta_key],
10948 |row| row.get::<_, String>(0),
10949 )
10950 .optional()
10951 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10952 if let Some(applied_plan) = applied_plan {
10953 if applied_plan != canonical_plan {
10954 return Err(format!(
10955 "sync.invalid_request: local purge id {:?} was already used with a different plan",
10956 input.purge_id
10957 ));
10958 }
10959 self.erase_purged_pages()?;
10961 return Ok(LocalDataPurgeResult {
10962 already_applied: true,
10963 purged_rows: 0,
10964 dropped_commits: 0,
10965 });
10966 }
10967
10968 let _ = self.drop_previous_version();
10972
10973 let rollback = self.capture();
10974 self.begin_observation("syncular_local_purge")?;
10975 let applied = (|| -> Result<(ChangeAccumulator, LocalDataPurgeResult), String> {
10976 let row_ids = self.local_purge_base_row_ids(&targets)?;
10977 let retained_dropped = self.drop_failed_commits(|table, values| {
10978 targets.iter().any(|target| {
10979 target.table == table && Self::local_purge_values_match(target, values)
10980 })
10981 })?;
10982 let doomed = self
10983 .outbox
10984 .iter()
10985 .filter(|commit| {
10986 commit.ops.iter().any(|operation| {
10987 let matching_targets = targets
10988 .iter()
10989 .filter(|target| target.table == operation.table)
10990 .collect::<Vec<_>>();
10991 if matching_targets.is_empty() {
10992 return false;
10993 }
10994 if row_ids
10995 .get(&operation.table)
10996 .is_some_and(|ids| ids.contains(&operation.row_id))
10997 {
10998 return true;
10999 }
11000 operation.values.as_ref().is_some_and(|values| {
11001 matching_targets
11002 .iter()
11003 .any(|target| Self::local_purge_values_match(target, values))
11004 })
11005 })
11006 })
11007 .cloned()
11008 .collect::<Vec<_>>();
11009 let doomed_ids = doomed
11010 .iter()
11011 .map(|commit| commit.client_commit_id.clone())
11012 .collect::<BTreeSet<_>>();
11013 let mut batch = ChangeAccumulator::default();
11014 for commit in &retained_dropped {
11015 batch.conflicts = true;
11016 batch.rejections = true;
11017 batch.outcomes = true;
11018 for operation in &commit.ops {
11019 batch.table(&operation.table);
11020 }
11021 }
11022 let mut rejections = Vec::new();
11023 for commit in &doomed {
11026 for operation in &commit.ops {
11027 batch.table(&operation.table);
11028 self.overlay_dirty.table(&operation.table);
11029 }
11030 let results = (0..commit.ops.len())
11031 .map(|op_index| {
11032 let rejection = RejectionRecord {
11033 client_commit_id: commit.client_commit_id.clone(),
11034 op_index: op_index as i32,
11035 code: "client.local_data_purged".to_owned(),
11036 message: "the commit was dropped by an application-authorized local data purge".to_owned(),
11037 retryable: false,
11038 details: None,
11039 operation: None,
11040 };
11041 rejections.push(rejection.clone());
11042 CommitOperationOutcome::Error { rejection }
11043 })
11044 .collect::<Vec<_>>();
11045 self.persist_commit_outcome(
11046 &commit.client_commit_id,
11047 CommitOutcomeStatus::Rejected,
11048 &results,
11049 None,
11050 )?;
11051 self.delete_outbox_persisted(&commit.client_commit_id)?;
11052 }
11053 if !doomed.is_empty() {
11054 self.outbox
11055 .retain(|commit| !doomed_ids.contains(&commit.client_commit_id));
11056 self.rejections.extend(rejections);
11057 self.prune_commit_outcomes()?;
11058 batch.status = true;
11059 batch.rejections = true;
11060 batch.outcomes = true;
11061 }
11062
11063 let mut purged_rows = 0usize;
11064 for (table, ids) in &row_ids {
11065 if ids.is_empty() {
11066 continue;
11067 }
11068 batch.table(table);
11069 self.overlay_dirty.table(table);
11070 for row_id in ids {
11071 self.delete_base_row(table, row_id, i64::MAX)?;
11072 purged_rows += 1;
11073 }
11074 }
11075 let touches = |table: &str, row_id: &str, values: Option<&Map<String, Value>>| {
11079 targets.iter().any(|target| {
11080 target.table == table
11081 && (row_ids.get(table).is_some_and(|ids| ids.contains(row_id))
11082 || values.is_some_and(|values| {
11083 Self::local_purge_values_match(target, values)
11084 }))
11085 })
11086 };
11087 let entries = self
11088 .conn
11089 .prepare("SELECT client_commit_id, results_json, operations_json FROM _syncular_commit_outcomes")
11090 .and_then(|mut statement| {
11091 statement
11092 .query_map([], |row| {
11093 Ok((
11094 row.get::<_, String>(0)?,
11095 row.get::<_, String>(1)?,
11096 row.get::<_, Option<String>>(2)?,
11097 ))
11098 })?
11099 .collect::<Result<Vec<_>, _>>()
11100 })
11101 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11102 for (client_commit_id, results_json, operations_json) in entries {
11103 let corrupt = |_| "sync.local_corrupt: persisted commit outcome is invalid".to_owned();
11104 let mut results: Vec<CommitOperationOutcome> =
11105 serde_json::from_str(&results_json).map_err(corrupt)?;
11106 let operations: Vec<CommitOperation> = operations_json
11107 .map(|json| serde_json::from_str(&json))
11108 .transpose()
11109 .map_err(corrupt)?
11110 .unwrap_or_default();
11111 let named = operations
11112 .iter()
11113 .chain(results.iter().filter_map(|result| match result {
11114 CommitOperationOutcome::Conflict { conflict } => conflict.operation.as_ref(),
11115 CommitOperationOutcome::Error { rejection } => rejection.operation.as_ref(),
11116 CommitOperationOutcome::Applied { .. } => None,
11117 }))
11118 .any(|operation| touches(&operation.table, &operation.row_id, operation.values.as_ref()))
11119 || results.iter().any(|result| {
11120 matches!(result, CommitOperationOutcome::Conflict { conflict }
11121 if touches(&conflict.table, &conflict.row_id, Some(&conflict.server_row)))
11122 });
11123 if !named {
11124 continue;
11125 }
11126 for result in &mut results {
11127 match result {
11128 CommitOperationOutcome::Conflict { conflict } => {
11129 conflict.server_row = Map::new();
11130 conflict.conflict_columns.clear();
11131 conflict.operation = None;
11132 }
11133 CommitOperationOutcome::Error { rejection } => {
11134 rejection.details = None;
11135 rejection.operation = None;
11136 }
11137 CommitOperationOutcome::Applied { .. } => {}
11138 }
11139 }
11140 let results_json = serde_json::to_string(&results).map_err(|error| error.to_string())?;
11141 self.conn
11142 .execute(
11143 "UPDATE _syncular_commit_outcomes SET results_json = ?1, operations_json = NULL WHERE client_commit_id = ?2",
11144 rusqlite::params![results_json, client_commit_id],
11145 )
11146 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11147 batch.outcomes = true;
11148 }
11149 self.rebuild_overlay_if_dirty()?;
11150 self.delete_unreferenced_cached_blobs()?;
11151 self.conn
11152 .execute(
11153 "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
11154 rusqlite::params![meta_key, canonical_plan],
11155 )
11156 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11157 Ok((
11158 batch,
11159 LocalDataPurgeResult {
11160 already_applied: false,
11161 purged_rows,
11162 dropped_commits: doomed.len(),
11163 },
11164 ))
11165 })()
11166 .and_then(|(batch, result)| {
11167 self.finish_observation("syncular_local_purge", batch)
11168 .map(|()| result)
11169 });
11170 let result = match applied {
11171 Ok(result) => result,
11172 Err(error) => {
11173 self.rollback_observation("syncular_local_purge");
11174 self.restore(rollback);
11175 return Err(error);
11176 }
11177 };
11178 self.cancel_sync_round();
11179 self.erase_purged_pages()?;
11180 Ok(result)
11181 }
11182
11183 fn erase_purged_pages(&self) -> Result<(), String> {
11188 let erased = self
11189 .conn
11190 .execute_batch("PRAGMA secure_delete = ON; VACUUM;")
11191 .and_then(|()| {
11192 self.conn
11193 .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
11194 });
11195 let reset = self.conn.execute_batch("PRAGMA secure_delete = OFF");
11196 erased
11197 .and(reset)
11198 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11199 }
11200
11201 pub fn rebootstrap_local_data(
11207 &mut self,
11208 input: &LocalDataRebootstrapInput,
11209 ) -> Result<LocalDataRebootstrapResult, String> {
11210 if input.rebootstrap_id.is_empty()
11211 || input.rebootstrap_id.len() > 128
11212 || !is_local_operation_code_like(&input.rebootstrap_id)
11213 {
11214 return Err(
11215 "sync.invalid_request: local rebootstrap rebootstrapId must be a 1–128 character code-like identifier"
11216 .to_owned(),
11217 );
11218 }
11219 let meta_key = format!("localRebootstrap:{}", input.rebootstrap_id);
11220 if let Some(persisted) = meta_get(&self.conn, &meta_key).map_err(|_| {
11221 "sync.local_corrupt: persisted local rebootstrap receipt is unreadable".to_owned()
11222 })? {
11223 let (retained_commits, reset_subscriptions) =
11224 decode_local_rebootstrap_receipt(&persisted)?;
11225 return Ok(LocalDataRebootstrapResult {
11226 already_applied: true,
11227 retained_commits,
11228 reset_subscriptions,
11229 });
11230 }
11231 if self.stopped || self.schema_floor.is_some() {
11232 return Err(
11233 "sync.invalid_request: local rebootstrap cannot bypass an active schema-floor stop; update the application first"
11234 .to_owned(),
11235 );
11236 }
11237
11238 let retained_commits = self.outbox.len();
11239 let reset_subscriptions = self.stored(load_units(&self.conn))?.len();
11240 let receipt = encode_local_rebootstrap_receipt(retained_commits, reset_subscriptions)?;
11241 let rollback = self.capture();
11242 self.begin_observation("syncular_local_rebootstrap")?;
11243 let mut batch = ChangeAccumulator::default();
11244 let applied = (|| -> Result<(), String> {
11245 self.run_schema_reset_observed(&mut batch, false)?;
11246 self.conn
11247 .execute(
11248 "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
11249 rusqlite::params![meta_key, receipt],
11250 )
11251 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11252 self.sync_needed = true;
11253 self.sync_intent_queue.push_back(SyncIntent::Interactive);
11254 batch.status = true;
11255 Ok(())
11256 })()
11257 .and_then(|()| self.finish_observation("syncular_local_rebootstrap", batch));
11258 if let Err(error) = applied {
11259 self.rollback_observation("syncular_local_rebootstrap");
11260 self.restore(rollback);
11261 return Err(error);
11262 }
11263
11264 Ok(LocalDataRebootstrapResult {
11265 already_applied: false,
11266 retained_commits,
11267 reset_subscriptions,
11268 })
11269 }
11270
11271 fn purge_scope_rows(
11277 &mut self,
11278 table_name: &str,
11279 effective: &[(String, Vec<String>)],
11280 owners: &[Vec<(String, Vec<String>)>],
11281 ) -> Result<bool, String> {
11282 let Some(table) = self.schema.table(table_name) else {
11283 return Ok(false);
11284 };
11285 let Ok(predicate) = local_scope_predicate(table, effective, owners) else {
11286 return Ok(false);
11287 };
11288 let Some((predicate, params)) = predicate else {
11289 return Ok(true);
11290 };
11291 self.overlay_dirty.table(table_name);
11292 for source in [base_table(table_name), visible_table(table_name)] {
11293 self.conn
11294 .execute(
11295 &format!("DELETE FROM {source} WHERE {predicate}"),
11296 rusqlite::params_from_iter(¶ms),
11297 )
11298 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11299 }
11300 Ok(true)
11301 }
11302
11303 fn drop_doomed_outbox(
11307 &mut self,
11308 table: &TableSchema,
11309 effective: &[(String, Vec<String>)],
11310 owners: &[Vec<(String, Vec<String>)>],
11311 ) -> Result<bool, String> {
11312 let doomed: Vec<_> =
11313 self.outbox
11314 .iter()
11315 .filter(|commit| {
11316 commit.ops.iter().any(|op| {
11317 op.upsert
11318 && op.table == table.name
11319 && op.values.as_ref().is_some_and(|values| {
11320 owns_local_row(table, effective, owners, values)
11321 })
11322 })
11323 })
11324 .cloned()
11325 .collect();
11326 if doomed.is_empty() {
11327 return Ok(false);
11328 }
11329 let mut rejections = Vec::new();
11330 for commit in &doomed {
11331 let results = commit
11332 .ops
11333 .iter()
11334 .enumerate()
11335 .map(|(op_index, operation)| {
11336 self.overlay_dirty.table(&operation.table);
11337 let rejection = RejectionRecord {
11338 client_commit_id: commit.client_commit_id.clone(),
11339 op_index: op_index as i32,
11340 code: "sync.scope_revoked".to_owned(),
11341 message: "the commit was dropped because its effective scope was revoked"
11342 .to_owned(),
11343 retryable: false,
11344 details: None,
11345 operation: Some(CommitOperation::from(operation)),
11346 };
11347 rejections.push(rejection.clone());
11348 CommitOperationOutcome::Error { rejection }
11349 })
11350 .collect::<Vec<_>>();
11351 self.persist_commit_outcome(
11352 &commit.client_commit_id,
11353 CommitOutcomeStatus::Rejected,
11354 &results,
11355 Some(&commit.ops),
11356 )?;
11357 self.delete_outbox_persisted(&commit.client_commit_id)?;
11358 }
11359 self.prune_commit_outcomes()?;
11360 let doomed_ids = doomed
11361 .iter()
11362 .map(|commit| commit.client_commit_id.as_str())
11363 .collect::<BTreeSet<_>>();
11364 self.outbox
11365 .retain(|commit| !doomed_ids.contains(commit.client_commit_id.as_str()));
11366 self.rejections.extend(rejections);
11367 Ok(true)
11368 }
11369
11370 pub fn upload_blob(
11377 &mut self,
11378 bytes: &[u8],
11379 media_type: Option<String>,
11380 name: Option<String>,
11381 ) -> Result<Value, String> {
11382 let blob_id = blob_id_for(bytes);
11383 let now = self.clock_now_ms();
11384 let tx = self
11385 .conn
11386 .transaction()
11387 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11388 tx.execute(
11389 "INSERT INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,?,?)
11390 ON CONFLICT(blob_id) DO NOTHING",
11391 rusqlite::params![blob_id, bytes, bytes.len() as i64, media_type, now],
11392 )
11393 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11394 tx.execute(
11395 "INSERT OR IGNORE INTO _syncular_blob_uploads(blob_id, media_type, created_at_ms) VALUES (?,?,?)",
11396 rusqlite::params![blob_id, media_type, now],
11397 )
11398 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11399 tx.commit()
11400 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11401 self.enforce_blob_cache_cap();
11402 let mut obj = Map::new();
11403 obj.insert("blobId".to_owned(), Value::from(blob_id));
11404 obj.insert("byteLength".to_owned(), Value::from(bytes.len() as i64));
11405 if let Some(mt) = media_type {
11406 obj.insert("mediaType".to_owned(), Value::from(mt));
11407 }
11408 if let Some(n) = name {
11409 obj.insert("name".to_owned(), Value::from(n));
11410 }
11411 Ok(Value::Object(obj))
11412 }
11413
11414 pub fn fetch_blob_bytes(
11418 &mut self,
11419 transport: &mut dyn Transport,
11420 blob_id_or_ref: &str,
11421 ) -> Result<FetchedBlob, (String, String)> {
11422 let simple = |m: String| ("client.failed".to_owned(), m);
11423 let (blob_id, byte_length) = if blob_id_or_ref.starts_with("sha256:") {
11426 (blob_id_or_ref.to_owned(), None)
11427 } else {
11428 let value: Value = serde_json::from_str(blob_id_or_ref)
11429 .map_err(|_| simple("blob ref is not JSON".to_owned()))?;
11430 (
11431 value
11432 .get("blobId")
11433 .and_then(Value::as_str)
11434 .ok_or_else(|| simple("blob ref has no blobId".to_owned()))?
11435 .to_owned(),
11436 value.get("byteLength").and_then(Value::as_u64),
11437 )
11438 };
11439 if let Some(cached) = self.get_cached_blob_bytes(&blob_id).map_err(simple)? {
11440 return Ok(cached);
11441 }
11442 if !self.transport_enabled {
11443 return Err(("sync.offline".into(), "transport gate is closed".into()));
11444 }
11445 #[cfg(feature = "bench-internals")]
11451 let download_phase = self.benchmark_phases.start(Phase::BlobDownload);
11452 let bytes = match transport
11453 .blob_download(&blob_id, byte_length)
11454 .map_err(|e| (e.code, e.message))?
11455 {
11456 BlobDownload::Bytes(bytes) => bytes,
11457 BlobDownload::Url {
11458 url,
11459 url_expires_at_ms,
11460 } => {
11461 if url_expires_at_ms.is_some_and(|exp| exp <= self.clock_now_ms()) {
11463 return Err((
11464 "sync.segment_expired".to_owned(),
11465 format!(
11466 "blob url for {blob_id} expired before fetch — re-request mints a fresh url (§5.9.5)"
11467 ),
11468 ));
11469 }
11470 transport
11471 .fetch_blob_url(&url, byte_length)
11472 .map_err(|e| (e.code, e.message))?
11473 }
11474 };
11475 #[cfg(feature = "bench-internals")]
11476 drop(download_phase);
11477 #[cfg(feature = "bench-internals")]
11478 let validate_phase = self.benchmark_phases.start(Phase::BlobValidate);
11479 if byte_length.is_some_and(|cap| bytes.len() as u64 > cap) {
11482 return Err((
11483 "sync.invalid_request".to_owned(),
11484 "blob exceeds its byteLength".to_owned(),
11485 ));
11486 }
11487 if blob_id_for(&bytes) != blob_id {
11488 return Err(simple(format!(
11489 "blob content address mismatch for {blob_id}"
11490 )));
11491 }
11492 #[cfg(feature = "bench-internals")]
11493 drop(validate_phase);
11494 #[cfg(feature = "bench-internals")]
11495 let insert_phase = self.benchmark_phases.start(Phase::BlobCacheInsert);
11496 let now = self.clock_now_ms();
11497 self.conn
11498 .execute(
11499 "INSERT OR IGNORE INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,NULL,?)",
11500 rusqlite::params![blob_id, bytes, bytes.len() as i64, now],
11501 )
11502 .map_err(|e| simple(e.to_string()))?;
11503 self.conn
11504 .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
11505 .map_err(|e| simple(e.to_string()))?;
11506 self.enforce_blob_cache_cap();
11507 #[cfg(feature = "bench-internals")]
11508 drop(insert_phase);
11509 self.get_cached_blob_bytes(&blob_id)
11510 .map_err(simple)?
11511 .ok_or_else(|| simple("blob cache write failed".to_owned()))
11512 }
11513
11514 fn get_cached_blob_bytes(&self, blob_id: &str) -> Result<Option<FetchedBlob>, String> {
11515 #[cfg(feature = "bench-internals")]
11516 let _phase = self.benchmark_phases.start(Phase::BlobCacheRead);
11517 let mut stmt = self
11518 .conn
11519 .prepare("SELECT bytes, byte_length, media_type FROM _syncular_blobs WHERE blob_id = ?")
11520 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11521 let mut rows = stmt
11522 .query(rusqlite::params![blob_id])
11523 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11524 if let Some(row) = rows
11525 .next()
11526 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11527 {
11528 let bytes: Vec<u8> = row
11529 .get(0)
11530 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11531 let byte_length: i64 = row
11532 .get(1)
11533 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11534 let media_type: Option<String> = row
11535 .get(2)
11536 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11537 return Ok(Some(FetchedBlob {
11538 blob_id: blob_id.to_owned(),
11539 byte_length,
11540 bytes,
11541 media_type,
11542 }));
11543 }
11544 Ok(None)
11545 }
11546
11547 fn pending_blob_uploads(&self) -> Result<Vec<crate::round::PendingUpload>, TransportError> {
11549 let pending: Vec<(String, Option<String>)> = {
11550 let mut stmt = self
11551 .conn
11552 .prepare(
11553 "SELECT blob_id, media_type FROM (
11554 SELECT blob_id, media_type, created_at_ms FROM _syncular_blob_uploads
11555 UNION ALL
11556 SELECT DISTINCT r.blob_id, b.media_type, 9223372036854775807 AS created_at_ms
11557 FROM _syncular_blob_commit_refs r LEFT JOIN _syncular_blobs b ON b.blob_id = r.blob_id
11558 WHERE NOT EXISTS (SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id = r.blob_id)
11559 ) ORDER BY created_at_ms, blob_id",
11560 )
11561 .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11562 let rows = stmt
11563 .query_map([], |row| {
11564 Ok((row.get::<_, String>(0)?, row.get::<_, Option<String>>(1)?))
11565 })
11566 .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11567 rows.collect::<Result<_, _>>()
11568 .map_err(|error| match error {
11569 rusqlite::Error::InvalidColumnType(..)
11570 | rusqlite::Error::FromSqlConversionFailure(..) => TransportError::new(
11571 "sync.local_corrupt",
11572 "Pending blob upload metadata is invalid",
11573 ),
11574 _ => TransportError::new("client.failed", error.to_string()),
11575 })?
11576 };
11577 let mut uploads = Vec::new();
11578 for (blob_id, media_type) in pending {
11579 let bytes = (|| {
11580 let stored: Option<(SqlValue, SqlValue)> = self
11581 .conn
11582 .query_row(
11583 "SELECT bytes, byte_length FROM _syncular_blobs WHERE blob_id = ?",
11584 rusqlite::params![blob_id],
11585 |row| Ok((row.get(0)?, row.get(1)?)),
11586 )
11587 .optional()
11588 .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11589 let Some((SqlValue::Blob(bytes), SqlValue::Integer(byte_length))) = stored else {
11590 return Err(TransportError::new(
11591 "sync.local_corrupt",
11592 "Pending blob upload body is missing or corrupt",
11593 ));
11594 };
11595 if byte_length != bytes.len() as i64 || blob_id_for(&bytes) != blob_id {
11596 return Err(TransportError::new(
11597 "sync.local_corrupt",
11598 "Pending blob upload body is missing or corrupt",
11599 ));
11600 }
11601 Ok(bytes)
11602 })();
11603 let failed = bytes.is_err();
11604 uploads.push(crate::round::PendingUpload {
11605 id: blob_id,
11606 bytes,
11607 media_type,
11608 });
11609 if failed {
11610 break;
11611 }
11612 }
11613 Ok(uploads)
11614 }
11615
11616 fn visible_blob_ids_sql(&self) -> String {
11617 let mut selects = Vec::new();
11618 for table in &self.schema.tables {
11619 for column in table
11620 .columns
11621 .iter()
11622 .filter(|column| column.ty == ColumnType::BlobRef)
11623 {
11624 let identifier = quote_ident(&column.name);
11625 selects.push(format!(
11626 "SELECT json_extract({identifier}, '$.blobId') AS blob_id FROM {} \
11627 WHERE typeof({identifier}) = 'text' AND json_valid({identifier}) \
11628 AND json_type({identifier}, '$.blobId') = 'text'",
11629 quote_ident(&table.name),
11630 ));
11631 }
11632 }
11633 if selects.is_empty() {
11634 "SELECT NULL AS blob_id WHERE 0".to_owned()
11635 } else {
11636 selects.join(" UNION ")
11637 }
11638 }
11639
11640 fn enforce_blob_cache_cap(&self) {
11643 let Some(max_bytes) = self.limits.blob_cache_max_bytes else {
11644 return;
11645 };
11646 let mut total: i64 = self
11647 .conn
11648 .query_row(
11649 "SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs",
11650 [],
11651 |row| row.get(0),
11652 )
11653 .unwrap_or(0);
11654 if total <= max_bytes {
11655 return;
11656 }
11657 let query = format!(
11658 "SELECT blob_id, byte_length FROM _syncular_blobs
11659 WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
11660 AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
11661 AND blob_id NOT IN ({})
11662 ORDER BY created_at_ms ASC, blob_id ASC",
11663 self.visible_blob_ids_sql(),
11664 );
11665 let candidates: Vec<(String, i64)> = {
11666 let Ok(mut stmt) = self.conn.prepare(&query) else {
11667 return;
11668 };
11669 let Ok(rows) = stmt.query_map([], |row| {
11670 Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
11671 }) else {
11672 return;
11673 };
11674 rows.filter_map(Result::ok).collect()
11675 };
11676 for (blob_id, byte_length) in candidates {
11677 if total <= max_bytes {
11678 break;
11679 }
11680 let _ = self.conn.execute(
11681 "DELETE FROM _syncular_blobs WHERE blob_id = ?",
11682 rusqlite::params![blob_id],
11683 );
11684 total -= byte_length;
11685 }
11686 }
11687
11688 fn delete_unreferenced_cached_blobs(&mut self) -> Result<(), String> {
11689 #[cfg(feature = "bench-internals")]
11690 let _phase = self.benchmark_phases.start(Phase::BlobRetention);
11691 if !self.schema_has_blobs() {
11692 return Ok(());
11693 }
11694 self.rebuild_overlay_if_dirty()?;
11695 self.conn
11696 .execute(
11697 &format!(
11698 "DELETE FROM _syncular_blobs
11699 WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
11700 AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
11701 AND blob_id NOT IN ({})",
11702 self.visible_blob_ids_sql(),
11703 ),
11704 [],
11705 )
11706 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11707 Ok(())
11708 }
11709
11710 fn insert_row_sql(&self, full_table: &str, table: &crate::schema::TableSchema) -> String {
11715 if let Some(sql) = self.insert_sql.borrow().get(full_table) {
11716 return sql.clone();
11717 }
11718 let mut columns: Vec<String> = table.columns.iter().map(|c| quote_ident(&c.name)).collect();
11719 columns.push(quote_ident("_syncular_version"));
11720 columns.extend(table.sealed_columns().iter().map(|name| quote_ident(name)));
11721 let placeholders: Vec<&str> = columns.iter().map(|_| "?").collect();
11722 let primary_key = quote_ident(&table.primary_key);
11723 let updates = columns
11724 .iter()
11725 .filter(|column| **column != primary_key)
11726 .map(|column| format!("{column}=excluded.{column}"))
11727 .collect::<Vec<_>>()
11728 .join(", ");
11729 let guard = if full_table == base_table(&table.name) {
11732 format!(" WHERE excluded._syncular_version > {full_table}._syncular_version")
11733 } else {
11734 String::new()
11735 };
11736 let sql = format!(
11737 "INSERT INTO {full_table} ({}) VALUES ({}) ON CONFLICT ({primary_key}) DO UPDATE SET {updates}{guard}",
11738 columns.join(", "),
11739 placeholders.join(", ")
11740 );
11741 self.insert_sql
11742 .borrow_mut()
11743 .insert(full_table.to_owned(), sql.clone());
11744 sql
11745 }
11746
11747 fn write_base_row(
11750 &self,
11751 table_name: &str,
11752 row: &Row,
11753 version: i64,
11754 sealed: Option<&SealedRow>,
11755 ) -> Result<bool, String> {
11756 let landed = self.write_row(&base_table(table_name), table_name, row, version, sealed)?;
11757 if landed {
11758 self.overlay_dirty.table(table_name);
11759 }
11760 Ok(landed)
11761 }
11762
11763 fn write_row(
11764 &self,
11765 full_table: &str,
11766 table_name: &str,
11767 row: &Row,
11768 version: i64,
11769 sealed: Option<&SealedRow>,
11770 ) -> Result<bool, String> {
11771 #[cfg(feature = "bench-internals")]
11772 let _phase = self.benchmark_phases.start(Phase::RowWrite);
11773 let table = self
11774 .schema
11775 .table(table_name)
11776 .ok_or_else(|| format!("unknown table {table_name:?}"))?;
11777 let sql = self.insert_row_sql(full_table, table);
11778 let mut stmt = self
11779 .conn
11780 .prepare_cached(&sql)
11781 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11782 let params = row
11783 .iter()
11784 .map(RowParam::Cell)
11785 .chain(std::iter::once(RowParam::Version(version)))
11786 .chain(
11787 [
11788 sealed.map(|sealed| sealed.key_id.as_str()),
11789 sealed.map(|sealed| sealed.envelopes.as_str()),
11790 ]
11791 .into_iter()
11792 .take(table.sealed_columns().len())
11793 .map(RowParam::Text),
11794 );
11795 stmt.execute(rusqlite::params_from_iter(params))
11796 .map(|changed| changed > 0)
11797 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11798 }
11799
11800 fn delete_base_row(
11803 &self,
11804 table_name: &str,
11805 row_id: &str,
11806 version: i64,
11807 ) -> Result<bool, String> {
11808 let table = self
11809 .schema
11810 .table(table_name)
11811 .ok_or_else(|| format!("unknown table {table_name:?}"))?;
11812 let sql = format!(
11813 "DELETE FROM {} WHERE {} AND _syncular_version < ?2",
11814 base_table(table_name),
11815 row_id_predicate(table)
11816 );
11817 let mut stmt = self
11818 .conn
11819 .prepare_cached(&sql)
11820 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11821 let landed = stmt
11822 .execute(rusqlite::params![row_id, version])
11823 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11824 > 0;
11825 if landed {
11826 self.overlay_dirty.table(table_name);
11827 }
11828 Ok(landed)
11829 }
11830
11831 fn has_acknowledged_rows(&self) -> Result<bool, String> {
11832 self.conn
11833 .query_row(
11834 "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows)",
11835 [],
11836 |row| row.get(0),
11837 )
11838 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11839 }
11840
11841 fn acknowledged_operations(
11842 &self,
11843 rows: Option<&HashSet<(&str, &str)>>,
11844 tables: Option<&BTreeSet<&str>>,
11845 ) -> Result<Vec<OutboxOp>, String> {
11846 let keys = rows.map(|rows| serde_json::to_string(&rows).expect("row keys"));
11847 let mut statement = self
11848 .conn
11849 .prepare_cached(if keys.is_some() {
11850 ACKED_ROWS_BY_ROW
11851 } else {
11852 "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"
11853 })
11854 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11855 let rows = statement
11856 .query_map(
11857 rusqlite::params![
11858 keys,
11859 tables.map(|tables| serde_json::to_string(tables).expect("table keys"))
11860 ],
11861 |row| {
11862 #[cfg(test)]
11863 self.acknowledged_replay_count
11864 .set(self.acknowledged_replay_count.get() + 1);
11865 Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
11866 },
11867 )
11868 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11869 rows.map(|row| {
11870 let (op, intent) =
11871 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11872 let op: CommitOperation =
11873 serde_json::from_str(&op).map_err(|_| "sync.local_corrupt".to_owned())?;
11874 let table = self
11875 .schema
11876 .table(&op.table)
11877 .ok_or_else(|| "sync.unknown_table".to_owned())?;
11878 let values = if op.op == "upsert" && self.visible_row(table, &op.row_id)?.is_none() {
11879 Some(serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?)
11880 } else {
11881 op.values.clone()
11882 };
11883 Ok(OutboxOp {
11884 values,
11885 ..op.into()
11886 })
11887 })
11888 .collect()
11889 }
11890
11891 fn drop_acknowledged_rows(
11892 &self,
11893 matches: impl Fn(&str, &Map<String, Value>) -> bool,
11894 ) -> Result<Vec<OutboxCommit>, String> {
11895 let mut statement = self
11896 .conn
11897 .prepare("SELECT commit_id,tbl,intent_json,id FROM _syncular_acked_rows")
11898 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11899 let rows = statement
11900 .query_map([], |row| {
11901 Ok((
11902 row.get::<_, String>(0)?,
11903 row.get::<_, String>(1)?,
11904 row.get::<_, String>(2)?,
11905 row.get::<_, String>(3)?,
11906 ))
11907 })
11908 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11909 let mut doomed = HashSet::new();
11910 for row in rows {
11911 let (id, table, intent, row_id) =
11912 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11913 let values =
11914 serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
11915 let base_matches = self
11916 .schema
11917 .table(&table)
11918 .map(|schema| self.stored_row(schema, &row_id, true))
11919 .transpose()?
11920 .flatten()
11921 .is_some_and(|(base, _)| {
11922 let schema = self.schema.table(&table).expect("acknowledged table");
11923 let values = schema
11924 .columns
11925 .iter()
11926 .zip(base.iter())
11927 .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
11928 .collect();
11929 matches(&table, &values)
11930 });
11931 if matches(&table, &values) || base_matches {
11932 doomed.insert(id);
11933 }
11934 }
11935 let mut dropped = Vec::new();
11936 for id in doomed {
11937 let mut statement = self
11938 .conn
11939 .prepare("SELECT op_json FROM _syncular_acked_rows WHERE commit_id=?1 ORDER BY idx")
11940 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11941 let operations = statement
11942 .query_map([&id], |row| row.get::<_, String>(0))
11943 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11944 let mut ops = Vec::new();
11945 for operation in operations {
11946 let json = operation
11947 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11948 let op: CommitOperation =
11949 serde_json::from_str(&json).map_err(|_| "sync.local_corrupt".to_owned())?;
11950 self.overlay_dirty.table(&op.table);
11951 ops.push(OutboxOp {
11952 table: op.table,
11953 row_id: op.row_id,
11954 upsert: op.op == "upsert",
11955 base_version: op.base_version,
11956 values: op.values,
11957 insert: op.insert,
11958 });
11959 }
11960 dropped.push(OutboxCommit {
11961 client_commit_id: id.clone(),
11962 ops,
11963 });
11964 self.conn
11965 .execute("DELETE FROM _syncular_acked_rows WHERE commit_id=?1", [id])
11966 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11967 }
11968 Ok(dropped)
11969 }
11970
11971 fn rebuild_overlay_if_dirty(&mut self) -> Result<(), String> {
11974 if self.overlay_dirty.get() {
11975 self.rebuild_overlay()?;
11976 }
11977 Ok(())
11978 }
11979
11980 fn rebuild_overlay(&mut self) -> Result<(), String> {
11984 #[cfg(feature = "bench-internals")]
11985 let _phase = self.benchmark_phases.start(Phase::OverlayRebuild);
11986 #[cfg(test)]
11987 self.overlay_rebuild_count
11988 .set(self.overlay_rebuild_count.get() + 1);
11989 let dirty = self.overlay_dirty.snapshot();
11990 let tables: Vec<_> = self
11991 .schema
11992 .tables
11993 .iter()
11994 .filter(|table| {
11995 dirty
11996 .as_ref()
11997 .is_none_or(|names| names.is_empty() || names.contains(&table.name))
11998 })
11999 .cloned()
12000 .collect();
12001 let names: BTreeSet<_> = tables.iter().map(|table| table.name.as_str()).collect();
12002 self.begin_observation("syncular_overlay")?;
12003 let rebuilt = (|| {
12004 for table in &tables {
12005 for index in &table.fts_indexes {
12006 self.drop_fts_triggers(index)?;
12007 }
12008 let visible = visible_table(&table.name);
12009 let base = base_table(&table.name);
12010 self.conn
12011 .execute_batch(&format!(
12012 "DELETE FROM {visible}; INSERT INTO {visible} SELECT * FROM {base}"
12013 ))
12014 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12015 }
12016 self.replay_overlay(&names, None)?;
12017 for table in &tables {
12018 for index in &table.fts_indexes {
12019 self.rebuild_fts_projection(table, index)?;
12020 self.create_fts_triggers(table, index)?;
12021 }
12022 }
12023 self.conn
12024 .execute_batch("RELEASE syncular_overlay")
12025 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12026 Ok(())
12027 })();
12028 if rebuilt.is_err() {
12029 self.conn
12030 .execute_batch("ROLLBACK TO syncular_overlay; RELEASE syncular_overlay")
12031 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12032 } else {
12033 self.overlay_dirty.set(false);
12034 }
12035 rebuilt
12036 }
12037
12038 fn replay_overlay(
12042 &self,
12043 tables: &BTreeSet<&str>,
12044 rows: Option<&HashSet<(&str, &str)>>,
12045 ) -> Result<(), String> {
12046 let replays = |op: &&OutboxOp| {
12047 tables.contains(op.table.as_str())
12048 && rows.is_none_or(|rows| rows.contains(&(op.table.as_str(), op.row_id.as_str())))
12049 };
12050 self.apply_outbox_ops(&self.acknowledged_operations(rows, Some(tables))?)?;
12051 for (commit, initial) in self.failed_commits.iter() {
12052 for operation in commit.ops.iter().filter(replays) {
12053 let Some(table) = self.schema.table(&operation.table) else {
12054 continue;
12055 };
12056 if operation.upsert
12057 && self.visible_row(table, &operation.row_id)?.is_none()
12058 && operation.presented_values(table).is_some_and(|values| {
12059 table
12060 .columns
12061 .iter()
12062 .all(|column| values.contains_key(&column.name))
12063 })
12064 {
12065 let key = serde_json::to_string(&(&operation.table, &operation.row_id))
12066 .expect("row key serialization");
12067 if let Some(Value::Object(values)) = initial.get(&key) {
12068 self.apply_outbox_ops(&[OutboxOp {
12069 values: Some(values.clone()),
12070 ..operation.clone()
12071 }])?;
12072 }
12073 }
12074 }
12075 self.apply_outbox_ops(commit.ops.iter().filter(replays))?;
12076 }
12077 self.apply_outbox_ops(
12078 self.outbox
12079 .iter()
12080 .flat_map(|commit| &commit.ops)
12081 .filter(replays),
12082 )
12083 }
12084
12085 fn apply_outbox_ops<'a>(
12090 &self,
12091 ops: impl IntoIterator<Item = &'a OutboxOp>,
12092 ) -> Result<(), String> {
12093 #[cfg(feature = "bench-internals")]
12094 let mut phase = self.benchmark_phases.start(Phase::PendingReplay);
12095 for op in ops {
12096 #[cfg(feature = "bench-internals")]
12097 if let Some(phase) = &mut phase {
12098 phase.unit();
12099 }
12100 if op.upsert {
12101 if let Some((table, values)) = self
12102 .schema
12103 .table(&op.table)
12104 .filter(|table| table.indexes.iter().any(|index| index.unique))
12105 .and_then(|table| Some((table, op.presented_values(table)?)))
12106 {
12107 let mut intended: Map<String, Value> = self
12108 .visible_row(table, &op.row_id)?
12109 .map(|(row, _)| {
12110 table
12111 .columns
12112 .iter()
12113 .zip(&row)
12114 .map(|(column, value)| {
12115 (column.name.clone(), column_value_to_json(value))
12116 })
12117 .collect()
12118 })
12119 .unwrap_or_default();
12120 intended.extend(values.into_owned());
12121 if !self.unique_conflicts(table, &intended, false)?.is_empty() {
12122 continue;
12123 }
12124 }
12125 }
12126 self.apply_outbox_op(op)?;
12127 }
12128 Ok(())
12129 }
12130
12131 fn apply_outbox_op(&self, op: &OutboxOp) -> Result<(), String> {
12132 let Some(table) = self.schema.table(&op.table) else {
12133 return Ok(());
12134 };
12135 let visible = visible_table(&table.name);
12136 if !op.upsert {
12137 let sql = format!("DELETE FROM {visible} WHERE {}", row_id_predicate(table));
12138 self.conn
12139 .prepare_cached(&sql)
12140 .and_then(|mut statement| statement.execute(rusqlite::params![op.row_id]))
12141 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12142 return Ok(());
12143 }
12144 let Some(values) = op.presented_values(table) else {
12148 return Ok(());
12149 };
12150 let full = table
12156 .columns
12157 .iter()
12158 .all(|column| values.contains_key(&column.name));
12159 let local = self.visible_row(table, &op.row_id)?;
12160 if local.is_none() && !full {
12161 return Ok(());
12162 }
12163 let mut row: Row = Vec::with_capacity(table.columns.len());
12164 for (index, column) in table.columns.iter().enumerate() {
12165 let incoming = match values.get(&column.name) {
12166 Some(raw) => json_to_column_value(
12167 if raw.get("$bytes").is_some()
12168 && table
12169 .encrypted_columns
12170 .iter()
12171 .any(|encrypted| encrypted.index == index)
12172 {
12173 &table.wire_columns[index]
12174 } else {
12175 column
12176 },
12177 Some(raw),
12178 ),
12179 None => Ok(local
12180 .as_ref()
12181 .and_then(|(values, _)| values.get(index).cloned())
12182 .flatten()),
12183 };
12184 row.push(incoming.map_err(|_| {
12185 "sync.local_corrupt: persisted optimistic row value is invalid".to_owned()
12186 })?);
12187 }
12188 let version = local.as_ref().map_or(-1, |(_, version)| *version);
12189 self.write_row(&visible, &table.name, &row, version, None)
12190 .map(|_| ())
12191 .map_err(|error| {
12192 if error.starts_with("UNIQUE constraint failed:") {
12193 "sync.constraint_violation: local write violates a unique constraint".to_owned()
12194 } else {
12195 error
12196 }
12197 })
12198 }
12199
12200 fn visible_row_exists(&self, table: &TableSchema, row_id: &str) -> Result<bool, String> {
12204 self.conn
12205 .query_row(
12206 &format!(
12207 "SELECT EXISTS(SELECT 1 FROM {} WHERE {})",
12208 visible_table(&table.name),
12209 row_id_predicate(table)
12210 ),
12211 rusqlite::params![row_id],
12212 |row| row.get(0),
12213 )
12214 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
12215 }
12216
12217 fn refuse_sealed_row(&self, table: &TableSchema, row_id: &str) -> Result<(), ClientError> {
12220 if !table.has_encrypted_columns() {
12221 return Ok(());
12222 }
12223 let key_id: Option<String> = self
12224 .conn
12225 .query_row(
12226 &format!(
12227 "SELECT \"_sync_sealed_key\" FROM {} WHERE {}",
12228 visible_table(&table.name),
12229 row_id_predicate(table)
12230 ),
12231 rusqlite::params![row_id],
12232 |row| row.get(0),
12233 )
12234 .optional()
12235 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
12236 .flatten();
12237 match key_id {
12238 None => Ok(()),
12239 Some(key_id) => Err(ClientError {
12240 code: "client.encryption_key_missing".to_owned(),
12241 message: "the row is sealed under a key this device does not hold".to_owned(),
12242 details: Some(json!({ "table": table.name, "keyId": key_id })),
12243 retryable: false,
12244 }),
12245 }
12246 }
12247
12248 fn reveal_sealed_rows(&mut self) -> Result<(), TransportError> {
12252 let storage = |message: String| TransportError::new("storage.failed", message);
12253 let tables: Vec<TableSchema> = self
12254 .schema
12255 .tables
12256 .iter()
12257 .filter(|table| table.has_encrypted_columns())
12258 .cloned()
12259 .collect();
12260 for table in &tables {
12261 let base = base_table(&table.name);
12262 let pk = quote_ident(&table.primary_key);
12263 let sealed: Vec<(SqlValue, i64, String)> = self
12264 .conn
12265 .prepare_cached(&format!(
12266 "SELECT {pk}, \"_syncular_version\", \"_sync_sealed\" FROM {base} WHERE \"_sync_sealed_key\" IS NOT NULL"
12267 ))
12268 .and_then(|mut statement| {
12269 statement
12270 .query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?
12271 .collect()
12272 })
12273 .map_err(|error| storage(Self::sqlite_failure(&self.storage_failure, error)))?;
12274 let mut revealed = Vec::new();
12275 for (key, version, envelopes) in sealed {
12276 if let Some(row) =
12277 crate::values::reveal_sealed_row(table, &envelopes, &self.encryption)?
12278 {
12279 revealed.push((key, version, row));
12280 }
12281 }
12282 if revealed.is_empty() {
12283 continue;
12284 }
12285 self.begin_observation("syncular_reveal").map_err(storage)?;
12286 let outcome = (|| {
12287 let assignments = table
12288 .encrypted_columns
12289 .iter()
12290 .map(|enc| format!("{}=?", quote_ident(&table.columns[enc.index].name)))
12291 .collect::<Vec<_>>()
12292 .join(",");
12293 let mut statement = self
12294 .conn
12295 .prepare_cached(&format!(
12296 "UPDATE {base} SET {assignments},\"_sync_sealed_key\"=NULL,\"_sync_sealed\"=NULL WHERE {pk}=? AND \"_syncular_version\"=?"
12297 ))
12298 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12299 for (key, version, row) in &revealed {
12300 let mut params = table
12301 .encrypted_columns
12302 .iter()
12303 .map(|enc| owned_sql_value(RowParam::Cell(&row[enc.index])))
12304 .collect::<Result<Vec<_>, _>>()?;
12305 params.push(key.clone());
12306 params.push(SqlValue::Integer(*version));
12307 statement
12308 .execute(rusqlite::params_from_iter(params))
12309 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12310 }
12311 drop(statement);
12312 self.overlay_dirty.table(&table.name);
12313 self.rebuild_overlay()?;
12314 let mut batch = ChangeAccumulator::default();
12315 batch.table(&table.name);
12316 self.finish_observation("syncular_reveal", batch)
12317 })();
12318 if outcome.is_err() {
12319 self.rollback_observation("syncular_reveal");
12320 }
12321 outcome.map_err(storage)?;
12322 }
12323 Ok(())
12324 }
12325
12326 fn visible_row(&self, table: &TableSchema, row_id: &str) -> Result<Option<(Row, i64)>, String> {
12329 self.stored_row(table, row_id, false)
12330 }
12331
12332 fn stored_row(
12333 &self,
12334 table: &TableSchema,
12335 row_id: &str,
12336 base: bool,
12337 ) -> Result<Option<(Row, i64)>, String> {
12338 let sql = format!(
12339 "SELECT * FROM {} WHERE {}",
12340 if base {
12341 base_table(&table.name)
12342 } else {
12343 visible_table(&table.name)
12344 },
12345 row_id_predicate(table)
12346 );
12347 let mut stmt = self
12348 .conn
12349 .prepare_cached(&sql)
12350 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12351 let mut rows = stmt
12352 .query(rusqlite::params![row_id])
12353 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12354 let Some(row) = rows
12355 .next()
12356 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
12357 else {
12358 return Ok(None);
12359 };
12360 let mut values = Vec::with_capacity(table.columns.len());
12361 for (index, column) in table.columns.iter().enumerate() {
12362 let raw = row
12363 .get_ref(index)
12364 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12365 if let rusqlite::types::ValueRef::Blob(bytes) = raw {
12366 if table
12367 .encrypted_columns
12368 .iter()
12369 .any(|encrypted| encrypted.index == index)
12370 {
12371 values.push(Some(ColumnValue::Bytes(bytes.to_vec())));
12372 continue;
12373 }
12374 }
12375 let json = sql_ref_to_json(column, raw);
12376 values.push(json_to_column_value(column, Some(&json)).map_err(|_| {
12377 "sync.local_corrupt: persisted local row value is invalid".to_owned()
12378 })?);
12379 }
12380 let version: i64 = row
12381 .get(table.columns.len())
12382 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
12383 Ok(Some((values, version)))
12384 }
12385
12386 #[must_use]
12390 pub fn realtime_policy(&self) -> RealtimePolicy {
12391 self.realtime_policy
12392 }
12393
12394 #[must_use]
12396 pub fn realtime_state(&self) -> RealtimeState {
12397 self.realtime_state
12398 }
12399
12400 pub fn set_realtime_policy(&mut self, policy: RealtimePolicy) -> Result<(), String> {
12403 if self.realtime_state == RealtimeState::Connected && policy != self.realtime_policy {
12404 return Err(
12405 "sync.invalid_request: disconnect realtime before changing the realtime policy"
12406 .to_owned(),
12407 );
12408 }
12409 self.realtime_policy = policy;
12410 match policy {
12411 RealtimePolicy::Off => self.set_realtime_state(RealtimeState::Disabled, None),
12412 RealtimePolicy::Required | RealtimePolicy::Optional
12413 if self.realtime_state == RealtimeState::Disabled =>
12414 {
12415 self.set_realtime_state(RealtimeState::Disconnected, None);
12416 }
12417 RealtimePolicy::Required | RealtimePolicy::Optional => {}
12418 }
12419 Ok(())
12420 }
12421
12422 fn set_realtime_state(&mut self, state: RealtimeState, reason_code: Option<&str>) {
12425 self.realtime_state = state;
12426 self.realtime_reason_code = reason_code.map(Self::diagnostic_code);
12427 if matches!(state, RealtimeState::Connected | RealtimeState::Disabled) {
12428 self.realtime_reason_code = None;
12429 self.realtime_retry_delay_ms = None;
12430 }
12431 }
12432
12433 #[must_use]
12434 fn realtime_connected(&self) -> bool {
12435 self.realtime_state == RealtimeState::Connected
12436 }
12437
12438 pub fn connect_realtime(&mut self, transport: &mut dyn Transport) -> Result<(), String> {
12439 if !self.transport_enabled {
12440 return Err("sync.offline: transport gate is closed".into());
12441 }
12442 if self.realtime_policy == RealtimePolicy::Off {
12443 return Err(
12444 "sync.invalid_request: realtime is off; realtime connect is refused".to_owned(),
12445 );
12446 }
12447 if self.realtime_connected() {
12448 return Ok(());
12449 }
12450 self.realtime_state = RealtimeState::Connecting;
12451 match transport.realtime_connect_for_client(&self.client_id) {
12452 Ok(()) => {
12453 self.set_realtime_state(RealtimeState::Connected, None);
12454 Ok(())
12455 }
12456 Err(error) => {
12457 self.set_realtime_state(RealtimeState::Refused, Some(&error.code));
12458 Err(format!("{}: {}", error.code, error.message))
12459 }
12460 }
12461 }
12462
12463 pub fn disconnect_realtime(&mut self, transport: &mut dyn Transport) {
12464 self.cancel_sync_round();
12465 if self.realtime_state == RealtimeState::Disconnected
12468 || self.realtime_state == RealtimeState::Disabled
12469 {
12470 return;
12471 }
12472 let _ = transport.realtime_close();
12473 self.set_realtime_state(
12474 if self.realtime_policy == RealtimePolicy::Off {
12475 RealtimeState::Disabled
12476 } else {
12477 RealtimeState::Disconnected
12478 },
12479 None,
12480 );
12481 self.presence.clear(); }
12483
12484 pub fn realtime_lost(&mut self, transport: &mut dyn Transport, error: &TransportError) {
12490 if self.realtime_state != RealtimeState::Connected {
12491 return;
12492 }
12493 self.cancel_sync_round();
12494 let _ = transport.realtime_close();
12495 self.set_realtime_state(RealtimeState::Lost, Some(&error.code));
12496 self.realtime_retry_delay_ms = Some(self.schedule_background_retry());
12497 self.presence.clear();
12498 }
12499
12500 pub fn set_presence(
12506 &mut self,
12507 transport: &mut dyn Transport,
12508 scope_key: &str,
12509 doc: Option<&Value>,
12510 ) -> Result<(), String> {
12511 if !self.transport_enabled {
12512 return Err("sync.offline: transport gate is closed".into());
12513 }
12514 if !self.realtime_connected() {
12515 return Err("setPresence requires a connected realtime socket (§8.6)".to_string());
12516 }
12517 let text = encode_presence_publish(scope_key, doc);
12518 transport
12519 .realtime_send(&text)
12520 .map_err(|e| format!("{}: {}", e.code, e.message))
12521 }
12522
12523 pub fn presence(&self, scope_key: &str) -> Vec<PresencePeer> {
12525 self.presence
12526 .get(scope_key)
12527 .map(|peers| peers.values().cloned().collect())
12528 .unwrap_or_default()
12529 }
12530
12531 fn apply_presence(
12533 &mut self,
12534 scope_key: String,
12535 kind: Option<PresenceKind>,
12536 actor_id: Option<String>,
12537 client_id: Option<String>,
12538 doc: Option<Value>,
12539 error: Option<String>,
12540 ) {
12541 if error.is_some() {
12544 return;
12545 }
12546 let (Some(kind), Some(actor_id), Some(client_id)) = (kind, actor_id, client_id) else {
12547 return;
12548 };
12549 let peer_key = format!("{actor_id} {client_id}");
12550 match kind {
12551 PresenceKind::Leave => {
12552 if let Some(peers) = self.presence.get_mut(&scope_key) {
12553 peers.remove(&peer_key);
12554 if peers.is_empty() {
12555 self.presence.remove(&scope_key);
12556 }
12557 }
12558 }
12559 _ => {
12560 let doc = match doc {
12561 Some(Value::Object(_)) => doc.unwrap(),
12562 _ => return,
12563 };
12564 self.presence.entry(scope_key).or_default().insert(
12565 peer_key,
12566 PresencePeer {
12567 actor_id,
12568 client_id,
12569 doc,
12570 },
12571 );
12572 }
12573 }
12574 }
12575
12576 pub fn on_realtime_text(&mut self, text: &str) {
12578 if self.stopped || !self.transport_enabled || self.security_preflight {
12579 return;
12580 }
12581 match parse_control(text) {
12582 Ok(ControlMessage::Hello { requires_sync, .. }) => {
12583 if requires_sync {
12584 self.set_sync_needed(true, true);
12586 }
12587 }
12588 Ok(ControlMessage::Presence {
12589 scope_key,
12590 kind,
12591 actor_id,
12592 client_id,
12593 doc,
12594 error,
12595 ..
12596 }) => {
12597 self.apply_presence(scope_key, kind, actor_id, client_id, doc, error);
12598 }
12599 Ok(ControlMessage::Wake { .. }) => {
12600 self.set_sync_needed(true, true);
12602 }
12603 _ => {}
12604 }
12605 }
12606
12607 pub fn on_realtime_binary_queued(&mut self, bytes: &[u8]) -> Vec<String> {
12611 let mut transport = crate::round::DownloadResults::default();
12612 self.on_realtime_binary(&mut transport, bytes);
12613 transport.controls
12614 }
12615
12616 pub fn on_realtime_binary(&mut self, transport: &mut dyn Transport, bytes: &[u8]) {
12622 if self.stopped || !self.transport_enabled || self.security_preflight {
12623 return;
12624 }
12625 #[cfg(feature = "bench-internals")]
12626 let decode_phase = self.benchmark_phases.start(Phase::ResponseDecode);
12627 let message = match decode_message(bytes) {
12628 Ok(m) if m.msg_kind == MsgKind::Response => m,
12629 _ => {
12630 self.set_sync_needed(true, true);
12631 return;
12632 }
12633 };
12634 #[cfg(feature = "bench-internals")]
12635 drop(decode_phase);
12636 if let Some(Frame::RespHeader {
12639 required_schema_version: Some(required),
12640 latest_schema_version,
12641 ..
12642 }) = message.frames.first()
12643 {
12644 let floor = SchemaFloor {
12645 required_schema_version: Some(*required),
12646 latest_schema_version: *latest_schema_version,
12647 };
12648 if self.set_schema_floor(Some(floor)).is_err() {
12649 self.set_sync_needed(true, true);
12650 }
12651 return;
12652 }
12653 let through = message.frames.iter().find_map(|frame| match frame {
12654 Frame::LiveEnd { through_seq, .. } => Some(*through_seq),
12655 _ => None,
12656 });
12657 let epoch = self.get_meta(LOG_EPOCH_KEY).ok().flatten();
12658 let mut dropped = !matches!(message.frames.first(), Some(Frame::RespHeader {
12659 reset_required: false,
12660 log_epoch,
12661 ..
12662 }) if Some(log_epoch) == epoch.as_ref());
12663 let mut applied: Option<i64> = None;
12664 dropped |= self.begin_coalesced_apply().is_err();
12665 let mut receivers: Option<Vec<UnitRecord>> = None;
12666 for frame in message.frames {
12667 if dropped {
12668 break;
12669 }
12670 match frame {
12671 Frame::LiveStart { status, .. } => {
12672 let Ok(cursor) = self.stored(replica_cursor(&self.conn)) else {
12673 dropped = true;
12674 break;
12675 };
12676 if status != LiveStatus::Active || cursor < 0 {
12677 dropped = true;
12678 } else if !through.is_some_and(|through| through <= cursor) {
12679 receivers = self.stored(load_units(&self.conn)).ok().map(|units| {
12681 units
12682 .into_iter()
12683 .filter(|unit| {
12684 unit.status == UnitStatus::Active
12685 && unit.echo.is_some()
12686 && unit.cursor.is_none()
12687 })
12688 .collect()
12689 });
12690 dropped = receivers.is_none();
12691 }
12692 }
12693 Frame::Commit {
12694 commit_seq,
12695 tables,
12696 changes,
12697 ..
12698 } => {
12699 let Some(receivers) = receivers.clone() else {
12700 continue;
12701 };
12702 dropped = self
12703 .apply_live_commit(
12704 &receivers,
12705 &tables,
12706 changes,
12707 commit_seq,
12708 AppliedServerCommitSource::Delta,
12709 )
12710 .is_err();
12711 }
12712 Frame::LiveEnd { through_seq, .. } if receivers.is_some() => {
12713 dropped = self
12714 .set_meta(REPLICA_CURSOR_KEY, &through_seq.to_string())
12715 .is_err();
12716 applied = Some(through_seq);
12717 }
12718 Frame::Error { .. } => dropped = true,
12719 _ => {}
12720 }
12721 }
12722 if self.finish_coalesced_apply().is_err() || dropped {
12725 applied = None;
12726 dropped = true;
12727 }
12728 if let Some(cursor) = applied {
12729 let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
12731 let _ = transport.realtime_send(&ack);
12732 }
12733 if dropped {
12734 self.set_sync_needed(true, true);
12735 }
12736 }
12737
12738 fn ack_after_pull(&mut self, transport: &mut dyn Transport) {
12741 if !self.realtime_connected() {
12742 return;
12743 }
12744 if let Ok(cursor @ 0..) = self.stored(replica_cursor(&self.conn)) {
12745 let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
12746 let _ = transport.realtime_send(&ack);
12747 }
12748 }
12749}
12750
12751#[cfg(test)]
12752mod previous_version_wiring_tests;
12753
12754#[cfg(test)]
12755mod identity_tests;
12756
12757#[cfg(test)]
12758mod insert_intent_tests;
12759
12760#[cfg(test)]
12761mod robustness_tests;
12762
12763#[cfg(test)]
12764mod range_image_tests;