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