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(()) => Ok(client),
2077 Err(error) => {
2078 let failure = Self::sqlite_failure(&client.storage_failure, error);
2079 if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2080 let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2082 }
2083 Err(failure)
2084 }
2085 },
2086 Err(error) => {
2087 if let Err(rollback) = client.conn.execute_batch("ROLLBACK") {
2088 let _ = Self::sqlite_failure(&client.storage_failure, rollback);
2090 }
2091 Err(error)
2092 }
2093 }
2094 }
2095
2096 pub fn set_now_ms(&mut self, now_ms: i64) {
2099 self.now_ms = Some(now_ms);
2100 }
2101
2102 pub fn set_encryption(&mut self, encryption: crate::values::EncryptionConfig) {
2106 self.encryption = encryption;
2107 }
2108
2109 #[must_use]
2110 pub fn security_lifecycle(&self) -> &'static str {
2111 if self.security_preflight {
2112 "preflight"
2113 } else {
2114 "active"
2115 }
2116 }
2117
2118 #[must_use]
2119 pub fn security_preflight(&self) -> bool {
2120 self.security_preflight
2121 }
2122
2123 pub fn set_transport_enabled(&mut self, transport: &mut dyn Transport, enabled: bool) {
2125 if self.transport_enabled != enabled {
2126 self.transport_enabled = enabled;
2127 self.transport_epoch = self.transport_epoch.wrapping_add(1);
2128 self.sync_intent_queue.clear();
2129 self.sync_intent_queue
2130 .push_back(if enabled && !self.security_preflight {
2131 SyncIntent::Interactive
2132 } else {
2133 SyncIntent::None
2134 });
2135 }
2136 if !enabled && self.active_round.is_none() {
2138 self.disconnect_realtime(transport);
2139 }
2140 }
2141
2142 pub fn transport_enabled(&self) -> bool {
2143 self.transport_enabled
2144 }
2145
2146 pub fn begin_security_preflight(&mut self) -> Result<(), String> {
2153 self.seal_security_on_teardown();
2154 self.set_meta(SECURITY_PREFLIGHT_PENDING_KEY, "1")
2157 }
2158
2159 pub fn seal_security_on_teardown(&mut self) {
2169 self.cancel_sync_round();
2170 self.security_preflight = true;
2171 self.security_epoch = self.security_epoch.wrapping_add(1);
2172 self.encryption = crate::values::EncryptionConfig::default();
2173 self.sync_intent_queue.clear();
2174 }
2175
2176 pub fn activate_security(
2178 &mut self,
2179 encryption: crate::values::EncryptionConfig,
2180 ) -> Result<(), String> {
2181 if !self.security_preflight {
2182 return Err(
2183 "sync.invalid_request: activateSecurity requires security preflight".to_owned(),
2184 );
2185 }
2186 self.enqueue_startup_sync_if_needed()?;
2187 self.delete_meta(SECURITY_PREFLIGHT_PENDING_KEY)?;
2188 self.encryption = encryption;
2189 self.security_preflight = false;
2190 Ok(())
2191 }
2192
2193 fn clock_now_ms(&self) -> i64 {
2194 self.now_ms.unwrap_or_else(crate::wall_clock_ms)
2195 }
2196
2197 fn create_bookkeeping_tables(&self) -> Result<(), String> {
2198 let exists = |name: &str| {
2199 self.conn
2200 .query_row(
2201 "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?1)",
2202 [name],
2203 |row| row.get::<_, bool>(0),
2204 )
2205 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2206 };
2207 let outbox_existed = exists("_syncular_outbox")?;
2208 self.conn
2210 .execute_batch(
2211 "CREATE TABLE IF NOT EXISTS _syncular_outbox (
2212 seq INTEGER PRIMARY KEY AUTOINCREMENT,
2213 commit_id TEXT NOT NULL UNIQUE, ops_json TEXT NOT NULL);
2214 CREATE TABLE IF NOT EXISTS _syncular_row_deliveries (
2215 tbl TEXT NOT NULL, id TEXT NOT NULL, commit_seq INTEGER NOT NULL, PRIMARY KEY(tbl,id));
2216 CREATE TABLE IF NOT EXISTS _syncular_acked_rows (
2217 commit_id TEXT NOT NULL, idx INTEGER NOT NULL, tbl TEXT NOT NULL, id TEXT NOT NULL,
2218 commit_seq INTEGER NOT NULL, op_json TEXT NOT NULL, intent_json TEXT,
2219 PRIMARY KEY(commit_id, idx));
2220 CREATE INDEX IF NOT EXISTS _syncular_acked_rows_row
2221 ON _syncular_acked_rows(tbl, id);
2222 CREATE TABLE IF NOT EXISTS _syncular_failed_commits (
2223 seq INTEGER PRIMARY KEY AUTOINCREMENT, client_commit_id TEXT NOT NULL UNIQUE,
2224 operations_json TEXT NOT NULL, initial_json TEXT NOT NULL);
2225 CREATE TABLE IF NOT EXISTS _syncular_commit_outcomes (
2226 seq INTEGER PRIMARY KEY AUTOINCREMENT,
2227 client_commit_id TEXT NOT NULL UNIQUE,
2228 status TEXT NOT NULL CHECK(status IN ('applied', 'cached', 'conflict', 'rejected')),
2229 recorded_at_ms INTEGER NOT NULL,
2230 results_json TEXT NOT NULL,
2231 operations_json TEXT,
2232 resolution TEXT NOT NULL DEFAULT 'active'
2233 CHECK(resolution IN ('active', 'resolved_keep_server', 'superseded', 'dismissed')),
2234 resolved_at_ms INTEGER,
2235 replacement_client_commit_id TEXT);
2236 CREATE INDEX IF NOT EXISTS _syncular_commit_outcomes_resolution_seq
2237 ON _syncular_commit_outcomes(resolution, seq);
2238 CREATE TABLE IF NOT EXISTS _syncular_units (
2239 id TEXT PRIMARY KEY, scopes TEXT NOT NULL,
2240 explicit INTEGER NOT NULL DEFAULT 0,
2241 status TEXT NOT NULL DEFAULT 'active', reason_code TEXT,
2242 cursor INTEGER DEFAULT -1, bootstrap_state TEXT,
2243 seeded TEXT NOT NULL DEFAULT '[]', echo TEXT);
2244 CREATE TABLE IF NOT EXISTS _syncular_meta (
2245 key TEXT PRIMARY KEY, value TEXT NOT NULL);
2246 CREATE TABLE IF NOT EXISTS _syncular_windows (
2247 base TEXT NOT NULL, unit TEXT NOT NULL, sub_id TEXT NOT NULL,
2248 PRIMARY KEY (base, unit));
2249 CREATE INDEX IF NOT EXISTS _syncular_windows_unit ON _syncular_windows(sub_id);
2250 CREATE TABLE IF NOT EXISTS _syncular_pending_evictions (
2251 unit_id TEXT NOT NULL, tbl TEXT NOT NULL,
2252 effective_scopes TEXT NOT NULL, PRIMARY KEY (unit_id, tbl));
2253 CREATE TABLE IF NOT EXISTS _syncular_blob_commit_refs(
2254 commit_id TEXT NOT NULL, blob_id TEXT NOT NULL,
2255 PRIMARY KEY(commit_id, blob_id));
2256 CREATE INDEX IF NOT EXISTS _syncular_blob_commit_refs_body
2257 ON _syncular_blob_commit_refs(blob_id);",
2258 )
2259 .map_err(|e| e.to_string())?;
2260 let _ = self
2263 .conn
2264 .execute_batch("ALTER TABLE _syncular_commit_outcomes ADD COLUMN operations_json TEXT");
2265 if self.get_meta(LOCAL_REVISION_KEY)?.is_none() {
2266 self.set_meta(LOCAL_REVISION_KEY, "0")?;
2267 }
2268 if !outbox_existed || self.get_meta(OUTBOX_ID_KEY)?.is_none() {
2271 self.set_meta(OUTBOX_ID_KEY, &uuid::Uuid::new_v4().to_string())?;
2272 }
2273 if exists("_syncular_window_pending_evict")? {
2278 let invalid: bool = self
2279 .conn
2280 .query_row(
2281 "SELECT EXISTS(SELECT 1 FROM _syncular_window_pending_evict
2282 WHERE NOT json_valid(effective_scopes)
2283 OR json_type(effective_scopes) <> 'object'
2284 OR EXISTS(SELECT 1 FROM json_each(effective_scopes)
2285 WHERE type <> 'array'
2286 OR EXISTS(SELECT 1 FROM json_each(value) AS v
2287 WHERE v.type <> 'text')))",
2288 [],
2289 |row| row.get(0),
2290 )
2291 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2292 if invalid {
2293 return Err(
2294 "sync.local_corrupt: a version 3 pending eviction cannot be upgraded"
2295 .to_owned(),
2296 );
2297 }
2298 self.conn
2299 .execute_batch(
2300 "INSERT OR REPLACE INTO _syncular_pending_evictions
2301 SELECT sub_id, tbl, effective_scopes FROM _syncular_window_pending_evict;
2302 DROP TABLE _syncular_window_pending_evict;
2303 DROP TABLE IF EXISTS _syncular_subscriptions;
2304 DELETE FROM _syncular_windows;",
2305 )
2306 .and_then(|()| reset_units(&self.conn))
2307 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2308 }
2309 if self.schema_has_blobs() {
2312 if exists("_syncular_blobs")? {
2313 let mut statement = self
2314 .conn
2315 .prepare("PRAGMA table_info(_syncular_blobs)")
2316 .map_err(|e| e.to_string())?;
2317 let mut columns = statement
2318 .query_map([], |row| row.get::<_, String>(1))
2319 .map_err(|e| e.to_string())?
2320 .collect::<Result<Vec<_>, _>>()
2321 .map_err(|e| e.to_string())?;
2322 columns.sort();
2323 let mut expected = vec![
2324 "blob_id",
2325 "byte_length",
2326 "bytes",
2327 "created_at_ms",
2328 "media_type",
2329 ];
2330 expected.sort_unstable();
2331 if columns != expected {
2332 return Err(
2333 "sync.schema_mismatch: Local blob schema is incompatible".to_owned()
2334 );
2335 }
2336 } else {
2337 self.conn
2338 .execute_batch(
2339 "CREATE TABLE _syncular_blobs(
2340 blob_id TEXT PRIMARY KEY,
2341 bytes BLOB NOT NULL,
2342 byte_length INTEGER NOT NULL,
2343 media_type TEXT,
2344 created_at_ms INTEGER NOT NULL);",
2345 )
2346 .map_err(|e| e.to_string())?;
2347 }
2348 self.conn
2349 .execute_batch(
2350 "CREATE TABLE IF NOT EXISTS _syncular_blob_uploads(
2351 blob_id TEXT PRIMARY KEY,
2352 media_type TEXT,
2353 created_at_ms INTEGER NOT NULL);",
2354 )
2355 .map_err(|e| e.to_string())?;
2356 }
2357 Ok(())
2358 }
2359
2360 fn schema_has_blobs(&self) -> bool {
2362 self.schema
2363 .tables
2364 .iter()
2365 .any(|t| t.columns.iter().any(|c| c.ty == ColumnType::BlobRef))
2366 }
2367
2368 fn get_meta(&self, key: &str) -> Result<Option<String>, String> {
2371 meta_get(&self.conn, key)
2372 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2373 }
2374
2375 fn persist_schema_version(&self) -> Result<(), String> {
2378 self.conn
2379 .execute(
2380 "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
2381 rusqlite::params![LOCAL_SCHEMA_VERSION_KEY, self.schema.version.to_string()],
2382 )
2383 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2384 set_local_schema_descriptor(&self.conn, &self.schema)
2385 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2386 }
2387
2388 pub(crate) fn set_meta(&self, key: &str, value: &str) -> Result<(), String> {
2389 meta_set(&self.conn, key, value)
2390 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2391 }
2392
2393 fn delete_meta(&self, key: &str) -> Result<(), String> {
2394 meta_delete(&self.conn, key)
2395 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2396 }
2397
2398 fn load_outbox(&self) -> Result<Vec<Arc<OutboxCommit>>, String> {
2400 let mut stmt = self
2401 .conn
2402 .prepare("SELECT commit_id, ops_json FROM _syncular_outbox ORDER BY seq ASC")
2403 .map_err(|error| error.to_string())?;
2404 let rows = stmt
2405 .query_map([], |row| {
2406 Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
2407 })
2408 .map_err(|error| error.to_string())?;
2409 let mut commits = Vec::new();
2410 for row in rows {
2411 let (client_commit_id, raw) = row.map_err(|error| error.to_string())?;
2412 let entries: Vec<Value> = serde_json::from_str(&raw).map_err(|error| {
2413 format!("invalid persisted outbox {client_commit_id:?}: {error}")
2414 })?;
2415 let mut ops = Vec::with_capacity(entries.len());
2416 for entry in entries {
2417 let op = entry.get("op").and_then(Value::as_str).unwrap_or("delete");
2418 ops.push(OutboxOp {
2419 upsert: op == "upsert",
2420 table: entry
2421 .get("table")
2422 .and_then(Value::as_str)
2423 .ok_or_else(|| "persisted outbox operation missing table".to_owned())?
2424 .to_owned(),
2425 row_id: entry
2426 .get("rowId")
2427 .and_then(Value::as_str)
2428 .ok_or_else(|| "persisted outbox operation missing rowId".to_owned())?
2429 .to_owned(),
2430 base_version: entry.get("baseVersion").and_then(Value::as_i64),
2431 values: entry.get("values").and_then(Value::as_object).cloned(),
2434 insert: entry.get("insert") == Some(&Value::Bool(true)),
2435 });
2436 }
2437 commits.push(Arc::new(OutboxCommit {
2438 client_commit_id,
2439 ops,
2440 }));
2441 }
2442 Ok(commits)
2443 }
2444
2445 fn restore_persisted_state(&mut self) -> Result<(), String> {
2446 self.outbox = self.load_outbox()?.into();
2447
2448 self.prune_commit_outcomes()?;
2449 let active = self.commit_outcomes(CommitOutcomeQuery {
2450 active_only: true,
2451 ..CommitOutcomeQuery::default()
2452 })?;
2453 self.conflicts = active
2454 .iter()
2455 .flat_map(|outcome| outcome.results.iter())
2456 .filter_map(|result| match result {
2457 CommitOperationOutcome::Conflict { conflict } => Some(conflict.clone()),
2458 _ => None,
2459 })
2460 .collect::<Vec<_>>()
2461 .into();
2462 self.rejections = active
2463 .iter()
2464 .flat_map(|outcome| outcome.results.iter())
2465 .filter_map(|result| match result {
2466 CommitOperationOutcome::Error { rejection } => Some(rejection.clone()),
2467 _ => None,
2468 })
2469 .collect::<Vec<_>>()
2470 .into();
2471
2472 self.lease_state = self
2473 .get_meta(LEASE_STATE_KEY)?
2474 .map(|raw| serde_json::from_str(&raw))
2475 .transpose()
2476 .map_err(|error| format!("invalid persisted lease state: {error}"))?;
2477 self.schema_floor = self
2478 .get_meta(SCHEMA_FLOOR_KEY)?
2479 .map(|raw| serde_json::from_str(&raw))
2480 .transpose()
2481 .map_err(|error| format!("invalid persisted schema floor: {error}"))?;
2482 self.stopped = self.schema_floor.is_some();
2483 if self.get_meta(SECURITY_PREFLIGHT_PENDING_KEY)?.as_deref() == Some("1") {
2486 self.security_preflight = true;
2487 }
2488 Ok(())
2489 }
2490
2491 fn save_unit_scope_schema(&self) -> Result<(), String> {
2492 let declarations: BTreeMap<_, BTreeMap<_, _>> = self
2493 .schema
2494 .tables
2495 .iter()
2496 .map(|table| {
2497 (
2498 table.name.clone(),
2499 table
2500 .scope_variables
2501 .iter()
2502 .map(|scope| {
2503 (
2504 scope.variable.clone(),
2505 [scope.prefix.clone(), scope.column.clone()],
2506 )
2507 })
2508 .collect(),
2509 )
2510 })
2511 .collect();
2512 self.set_meta(
2513 "subscriptionScopeSchema",
2514 &serde_json::to_string(&declarations).expect("scope schema serialization"),
2515 )
2516 }
2517
2518 fn prune_unknown_units(&mut self, bump: bool) -> Result<(), String> {
2523 let previous: Option<BTreeMap<String, BTreeMap<String, [String; 2]>>> = if bump {
2524 self.get_meta("subscriptionScopeSchema")?
2525 .map(|raw| serde_json::from_str(&raw))
2526 .transpose()
2527 .map_err(|_| "sync.local_corrupt: invalid persisted scope schema".to_owned())?
2528 } else {
2529 None
2530 };
2531 let unchanged = |name: &str, variables: &[&String]| {
2536 let (Some(old), Some(table)) = (
2537 previous.as_ref().and_then(|previous| previous.get(name)),
2538 self.schema.table(name),
2539 ) else {
2540 return false;
2541 };
2542 variables.iter().all(|variable| {
2543 table
2544 .scope_variables
2545 .iter()
2546 .find(|scope| &scope.variable == *variable)
2547 .is_some_and(|scope| {
2548 old.get(*variable) == Some(&[scope.prefix.clone(), scope.column.clone()])
2549 })
2550 })
2551 };
2552 let compatible = |scopes: &UnitScopes| {
2553 if !self.schema.tables.iter().any(|table| covers(table, scopes)) {
2554 return false;
2555 }
2556 if !bump {
2557 return true;
2558 }
2559 let Some(previous) = &previous else {
2560 return false;
2561 };
2562 previous.iter().all(|(name, old)| {
2563 !scopes.keys().all(|variable| old.contains_key(variable))
2564 || unchanged(name, &scopes.keys().collect::<Vec<_>>())
2565 })
2566 };
2567 let mut stale: BTreeSet<String> = self
2568 .stored(load_units(&self.conn))?
2569 .into_iter()
2570 .filter(|unit| !compatible(&unit.scopes))
2571 .map(|unit| unit.id)
2572 .collect();
2573 for (id, table, effective) in self.load_pending_evictions()? {
2578 if self.schema.table(&table).is_none()
2579 || (bump
2580 && !unchanged(
2581 &table,
2582 &effective
2583 .iter()
2584 .map(|(variable, _)| variable)
2585 .collect::<Vec<_>>(),
2586 ))
2587 {
2588 stale.insert(id);
2589 }
2590 }
2591 for id in &stale {
2592 for sql in [
2593 "DELETE FROM _syncular_windows WHERE sub_id = ?1",
2594 "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
2595 "DELETE FROM _syncular_units WHERE id = ?1",
2596 ] {
2597 self.conn
2598 .execute(sql, rusqlite::params![id])
2599 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
2600 }
2601 }
2602 Ok(())
2603 }
2604
2605 pub fn local_revision(&self) -> Result<u64, String> {
2606 Ok(self
2607 .get_meta(LOCAL_REVISION_KEY)?
2608 .and_then(|value| value.parse().ok())
2609 .unwrap_or(0))
2610 }
2611
2612 pub fn snapshot_read(
2618 &mut self,
2619 request: &SnapshotReadRequest<'_>,
2620 owner: Option<QueryOwner<'_>>,
2621 ) -> Result<SnapshotRead, QueryReadFailure> {
2622 let result = snapshot_read_connection(&self.conn, request);
2623 if let Some(owner) = owner {
2624 self.record_query_read(owner, result.as_ref().err());
2625 }
2626 result
2627 }
2628
2629 #[must_use]
2630 pub fn status_snapshot(&self) -> SyncStatusSnapshot {
2631 SyncStatusSnapshot {
2632 current_schema_version: self.schema.version,
2633 outbox: self.outbox.len(),
2634 upgrading: self.upgrading,
2635 lease_state: self.lease_state.clone(),
2636 schema_floor: self.schema_floor.clone(),
2637 sync_needed: self.sync_needed,
2638 previous_version_context: self.previous_version_status(),
2639 }
2640 }
2641
2642 fn previous_version_status(&self) -> PreviousVersionStatus {
2645 let Some(replica_path) = self.previous_version_replica_path() else {
2646 return PreviousVersionStatus {
2647 present: false,
2648 created_at_ms: None,
2649 };
2650 };
2651 match crate::previous_version::read_previous_version_record(&replica_path) {
2652 Ok(Some(record)) => PreviousVersionStatus {
2653 present: true,
2654 created_at_ms: Some(record.created_at_ms),
2655 },
2656 _ => PreviousVersionStatus {
2657 present: std::path::Path::new(
2658 &crate::previous_version::previous_version_container_path(&replica_path),
2659 )
2660 .exists(),
2661 created_at_ms: None,
2662 },
2663 }
2664 }
2665
2666 pub fn previous_version_snapshot(
2672 &self,
2673 spec: &PreviousVersionReadSpec,
2674 ) -> Result<PreviousVersionSnapshot, String> {
2675 let now_ms = self.clock_now_ms();
2676 crate::previous_version::previous_version_snapshot(
2677 &self.conn,
2678 self.previous_version_replica_path().as_deref(),
2679 self.previous_version.as_ref(),
2680 PreviousVersionLifecycle {
2681 lease_inactive: self.previous_version_lease_inactive(now_ms),
2682 scope_revoked: self
2683 .stored(load_units(&self.conn))?
2684 .iter()
2685 .any(|unit| unit.status == UnitStatus::Revoked),
2686 coverage_complete: self.previous_version_coverage_complete()?,
2687 },
2688 now_ms,
2689 self.schema.version,
2690 spec,
2691 )
2692 }
2693
2694 pub fn previous_version_audit(
2696 &self,
2697 ) -> Result<Option<crate::previous_version::PreviousVersionAudit>, String> {
2698 crate::previous_version::stored_previous_version_audit(&self.conn)
2699 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
2700 }
2701
2702 pub fn previous_version_discard(
2706 &self,
2707 ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2708 self.drop_previous_version()
2709 }
2710
2711 fn drop_previous_version(
2712 &self,
2713 ) -> Result<crate::previous_version::PreviousVersionDiscardOutcome, String> {
2714 let Some(replica_path) = self.previous_version_replica_path() else {
2715 return Ok(crate::previous_version::PreviousVersionDiscardOutcome {
2716 present: false,
2717 discarded: false,
2718 });
2719 };
2720 crate::previous_version::discard_previous_version(&self.conn, &replica_path)
2721 }
2722
2723 fn previous_version_lease_inactive(&self, now_ms: i64) -> bool {
2725 let Some(lease) = &self.lease_state else {
2726 return false;
2727 };
2728 if lease.error_code.is_some() {
2729 return true;
2730 }
2731 lease.expires_at_ms.is_some_and(|expires| expires <= now_ms)
2732 }
2733
2734 fn previous_version_coverage_complete(&self) -> Result<bool, String> {
2738 let units = self.stored(load_units(&self.conn))?;
2739 let mut active = units
2740 .iter()
2741 .filter(|unit| unit.status == UnitStatus::Active)
2742 .peekable();
2743 Ok(active.peek().is_some() && !active.any(UnitRecord::bootstrapping))
2744 }
2745
2746 fn previous_version_lifetime_check(&self) {
2750 let Some(config) = self.previous_version.filter(|config| config.enabled) else {
2751 return;
2752 };
2753 let now_ms = self.clock_now_ms();
2754 if self.previous_version_lease_inactive(now_ms) {
2755 let _ = self.drop_previous_version();
2756 return;
2757 }
2758 let Some(replica_path) = self.previous_version_replica_path() else {
2759 return;
2760 };
2761 let Ok(Some(record)) = crate::previous_version::read_previous_version_record(&replica_path)
2762 else {
2763 return;
2764 };
2765 let Ok(units) = load_units(&self.conn) else {
2766 return;
2767 };
2768 if units.iter().any(|unit| unit.status == UnitStatus::Revoked) {
2769 let _ = self.drop_previous_version();
2770 return;
2771 }
2772 if now_ms - record.created_at_ms > config.max_age_ms {
2773 let _ = self.drop_previous_version();
2774 return;
2775 }
2776 if self.previous_version_coverage_complete() == Ok(true) {
2777 let _ = self.drop_previous_version();
2778 }
2779 }
2780
2781 pub fn diagnostics_snapshot(&self) -> Result<ClientDiagnosticsSnapshot, String> {
2782 let registered = self.stored(load_units(&self.conn))?;
2783 let (local_revision, replica_cursor): (Option<String>, Option<String>) = self.stored(
2786 self.conn
2787 .prepare_cached(
2788 "SELECT (SELECT value FROM _syncular_meta WHERE key = ?1),
2789 (SELECT value FROM _syncular_meta WHERE key = ?2)",
2790 )
2791 .and_then(|mut statement| {
2792 statement.query_row([LOCAL_REVISION_KEY, REPLICA_CURSOR_KEY], |row| {
2793 Ok((row.get(0)?, row.get(1)?))
2794 })
2795 }),
2796 )?;
2797 let mut units = DiagnosticUnits::default();
2798 for unit in ®istered {
2799 *match unit.status {
2800 UnitStatus::Revoked => &mut units.revoked,
2801 UnitStatus::Failed => &mut units.failed,
2802 UnitStatus::Active if !unit.bootstrapping() => &mut units.complete,
2803 UnitStatus::Active
2804 if unit.reason_code.as_deref() == Some("sync.cursor_expired") =>
2805 {
2806 &mut units.reset
2807 }
2808 UnitStatus::Active => &mut units.bootstrapping,
2809 } += 1;
2810 }
2811 units.reason_codes = registered
2812 .iter()
2813 .filter_map(|unit| unit.reason_code.as_deref().map(Self::diagnostic_code))
2814 .collect::<BTreeSet<_>>()
2815 .into_iter()
2816 .collect();
2817 let captured_at_ms = self.clock_now_ms();
2818 let lease = if let Some(error_code) = self
2819 .lease_state
2820 .as_ref()
2821 .and_then(|state| state.error_code.clone())
2822 {
2823 ClientDiagnosticsLease {
2824 state: "stopped".to_owned(),
2825 expires_at_ms: self
2826 .lease_state
2827 .as_ref()
2828 .and_then(|state| state.expires_at_ms),
2829 error_code: Some(Self::diagnostic_code(&error_code)),
2830 }
2831 } else if let Some(expires_at_ms) = self
2832 .lease_state
2833 .as_ref()
2834 .and_then(|state| state.expires_at_ms)
2835 {
2836 ClientDiagnosticsLease {
2837 state: if expires_at_ms <= captured_at_ms {
2838 "expired".to_owned()
2839 } else {
2840 "active".to_owned()
2841 },
2842 expires_at_ms: Some(expires_at_ms),
2843 error_code: None,
2844 }
2845 } else {
2846 ClientDiagnosticsLease {
2847 state: "none".to_owned(),
2848 expires_at_ms: None,
2849 error_code: None,
2850 }
2851 };
2852 let connectivity = match self.last_round.as_ref() {
2853 _ if !self.transport_enabled && self.active_round.is_none() => "offline",
2854 Some(round) if round.status == "succeeded" => "online",
2855 Some(round)
2856 if round.status == "failed"
2857 && matches!(
2858 round.cause_kind,
2859 Some(
2860 crate::TransportCauseKind::Network | crate::TransportCauseKind::Connect
2861 )
2862 ) =>
2863 {
2864 "offline"
2865 }
2866 Some(round) if round.status == "failed" && round.http_status.is_some() => "online",
2867 _ => "unknown",
2868 };
2869 Ok(ClientDiagnosticsSnapshot {
2870 version: CLIENT_DIAGNOSTICS_VERSION,
2871 captured_at_ms,
2872 host: ClientDiagnosticsHost {
2873 kind: "direct".to_owned(),
2874 role: "single".to_owned(),
2875 connectivity: connectivity.to_owned(),
2876 realtime: self.realtime_state,
2877 realtime_policy: self.realtime_policy,
2878 realtime_reason_code: self.realtime_reason_code.clone(),
2879 realtime_retry_delay_ms: self.realtime_retry_delay_ms,
2880 },
2881 security_lifecycle: self.security_lifecycle().to_owned(),
2882 schema: ClientDiagnosticsSchema {
2883 current_version: self.schema.version,
2884 upgrading: self.upgrading,
2885 required_version: self
2886 .schema_floor
2887 .as_ref()
2888 .and_then(|floor| floor.required_schema_version),
2889 latest_version: self
2890 .schema_floor
2891 .as_ref()
2892 .and_then(|floor| floor.latest_schema_version),
2893 },
2894 replica: ClientDiagnosticsReplica {
2895 local_revision: local_revision
2896 .and_then(|value| value.parse::<u64>().ok())
2897 .unwrap_or(0)
2898 .to_string(),
2899 sync_needed: self.sync_needed,
2900 pending_outbox: self.outbox.len(),
2901 },
2902 lease,
2903 active_units: registered
2904 .iter()
2905 .filter(|unit| unit.status == UnitStatus::Active)
2906 .count(),
2907 units,
2908 replica_cursor: replica_cursor.map_or(Ok(-1), |raw| {
2909 raw.parse()
2910 .map_err(|_| "sync.local_corrupt: persisted unit state is invalid".to_owned())
2911 })?,
2912 last_round: self.last_round.clone(),
2913 last_change: self.last_change.clone(),
2914 storage: self.diagnostics_storage(),
2915 query_failures: self.query_failures.clone(),
2916 })
2917 }
2918
2919 fn diagnostics_storage(&self) -> ClientDiagnosticsStorage {
2920 let read = || -> Result<ClientDiagnosticsStorage, rusqlite::Error> {
2921 let page_count: i64 = self
2922 .conn
2923 .query_row("PRAGMA page_count", [], |row| row.get(0))?;
2924 let page_size: i64 = self
2925 .conn
2926 .query_row("PRAGMA page_size", [], |row| row.get(0))?;
2927 let (outbox_bytes, outcome_entries, outcome_bytes): (i64, i64, i64) = self
2930 .conn
2931 .prepare_cached(
2932 "SELECT (SELECT COALESCE(SUM(LENGTH(ops_json)), 0) FROM _syncular_outbox),
2933 COUNT(*), COALESCE(SUM(LENGTH(results_json) + COALESCE(LENGTH(operations_json), 0)), 0)
2934 FROM _syncular_commit_outcomes",
2935 )?
2936 .query_row([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?;
2937 let blob_bytes = if self.schema_has_blobs() {
2938 self.conn
2939 .prepare_cached("SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs")?
2940 .query_row([], |row| row.get(0))?
2941 } else {
2942 0
2943 };
2944 let pressure = self
2945 .limits
2946 .blob_cache_max_bytes
2947 .is_some_and(|limit| blob_bytes > limit);
2948 Ok(ClientDiagnosticsStorage {
2949 status: if pressure { "pressure" } else { "healthy" }.to_owned(),
2950 database_bytes_approx: Some(page_count.saturating_mul(page_size).max(0)),
2951 pending_outbox_bytes_approx: Some(outbox_bytes.max(0)),
2952 retained_outcome_bytes_approx: Some(outcome_bytes.max(0)),
2953 retained_outcome_entries: Some(outcome_entries.max(0)),
2954 blob_cache_bytes_approx: Some(blob_bytes.max(0)),
2955 pressure_reason_code: pressure.then(|| "client.blob_cache_over_limit".to_owned()),
2956 })
2957 };
2958 read().unwrap_or_else(|_| ClientDiagnosticsStorage {
2959 status: "unreadable".to_owned(),
2960 database_bytes_approx: None,
2961 pending_outbox_bytes_approx: None,
2962 retained_outcome_bytes_approx: None,
2963 retained_outcome_entries: None,
2964 blob_cache_bytes_approx: None,
2965 pressure_reason_code: None,
2966 })
2967 }
2968
2969 pub fn drain_change_batches(&mut self) -> Vec<ClientChangeBatch> {
2970 self.change_queue.drain(..).collect()
2971 }
2972
2973 pub fn drain_sync_intents(&mut self) -> Vec<SyncIntent> {
2974 let intents = self.sync_intent_queue.drain(..).collect();
2975 if self.transport_enabled {
2976 intents
2977 } else {
2978 vec![SyncIntent::None]
2979 }
2980 }
2981
2982 fn schedule_background_retry(&mut self) -> u64 {
2983 let delay_ms = self.retry_delay_ms;
2984 self.sync_intent_queue
2985 .push_back(SyncIntent::Background { delay_ms });
2986 self.retry_delay_ms = (self.retry_delay_ms * 2).min(30_000);
2987 self.round_retry_delay_ms = Some(delay_ms);
2988 delay_ms
2989 }
2990
2991 fn reset_background_retry(&mut self) {
2992 self.retry_delay_ms = 250;
2993 }
2994
2995 fn retryable_transport_code(code: &str) -> bool {
2996 code == "transport.failed"
2997 || code == "transport.timeout"
2998 || code == "transport.unavailable"
2999 || code == "sync.transport_failed"
3000 }
3001
3002 fn unreachable_transport(details: &Option<serde_json::Value>) -> bool {
3007 matches!(
3008 details
3009 .as_ref()
3010 .and_then(|details| details.get("causeKind"))
3011 .and_then(serde_json::Value::as_str),
3012 Some("connect" | "network")
3013 )
3014 }
3015
3016 fn segment_fetch_failed(&mut self, error: TransportError) -> SectionError {
3021 if ssp2::model::valid_round_failure_code(&error.code) {
3022 self.round_failure = Some(error.code.clone());
3023 }
3024 SectionError::Transport(error)
3025 }
3026
3027 fn retryable_failure_code(code: &str) -> bool {
3032 Self::retryable_transport_code(code)
3033 || matches!(
3034 code,
3035 "sync.auth_required"
3036 | "sync.auth_lease_required"
3037 | "sync.auth_lease_revoked"
3038 | "sync.internal_error"
3039 | "sync.idempotency_cache_miss"
3040 | "sync.schema_not_ready"
3041 | "sync.segment_expired"
3042 | "sync.rate_limited"
3043 | "sync.websocket_connection_limit"
3044 )
3045 }
3046
3047 fn diagnostic_code(code: &str) -> String {
3048 let valid = !code.is_empty()
3049 && code.len() <= 96
3050 && code.contains('.')
3051 && code
3052 .bytes()
3053 .next()
3054 .is_some_and(|byte| byte.is_ascii_lowercase())
3055 && code.bytes().all(|byte| {
3056 byte.is_ascii_lowercase()
3057 || byte.is_ascii_digit()
3058 || matches!(byte, b'.' | b'_' | b'-')
3059 });
3060 if valid {
3061 code.to_owned()
3062 } else {
3063 "client.unknown_failure".to_owned()
3064 }
3065 }
3066
3067 fn set_sync_needed(&mut self, value: bool, interactive: bool) {
3068 if self.sync_needed != value {
3069 if self.begin_observation("syncular_status").is_ok() {
3070 self.sync_needed = value;
3071 let batch = ChangeAccumulator {
3072 status: true,
3073 ..ChangeAccumulator::default()
3074 };
3075 if self.finish_observation("syncular_status", batch).is_err() {
3076 self.rollback_observation("syncular_status");
3077 }
3078 } else {
3079 self.sync_needed = value;
3080 }
3081 }
3082 if value && interactive {
3083 self.sync_intent_queue.push_back(SyncIntent::Interactive);
3084 }
3085 }
3086
3087 fn stored<T>(&self, result: rusqlite::Result<T>) -> Result<T, String> {
3090 result.map_err(|error| match error {
3091 rusqlite::Error::FromSqlConversionFailure(..) => {
3092 "sync.local_corrupt: persisted unit state is invalid".to_owned()
3093 }
3094 error => Self::sqlite_failure(&self.storage_failure, error),
3095 })
3096 }
3097
3098 fn sqlite_failure(
3099 storage_failure: &RefCell<Option<QueryReadFailure>>,
3100 error: rusqlite::Error,
3101 ) -> String {
3102 let message = error.to_string();
3103 let failure = QueryReadFailure::from(error);
3104 let code = failure.code;
3105 if code.is_some() && storage_failure.borrow().is_none() {
3106 *storage_failure.borrow_mut() = Some(failure);
3107 }
3108 match code {
3109 Some(code) => format!("{code}: {message}"),
3110 None => message,
3111 }
3112 }
3113
3114 fn begin_observation(&self, name: &str) -> Result<(), String> {
3115 if let Some(failure) = &self.coalesced_failure {
3116 return Err(failure.clone());
3117 }
3118 if self.coalesced.is_some() && self.conn.is_autocommit() {
3121 return Err("the coalesced apply transaction was rolled back".to_owned());
3122 }
3123 self.conn
3124 .execute_batch(&format!("SAVEPOINT {name}"))
3125 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3126 }
3127
3128 fn begin_coalesced_apply(&mut self) -> Result<(), String> {
3131 if self.coalesced.is_some() || !self.conn.is_autocommit() {
3132 return Ok(());
3133 }
3134 self.conn
3135 .execute_batch("BEGIN")
3136 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3137 self.coalesced = Some(CoalescedApply {
3138 rows: 0,
3139 rollback: self.capture(),
3140 });
3141 Ok(())
3142 }
3143
3144 fn capture(&self) -> Rollback {
3145 Rollback {
3146 outbox: self.outbox.clone(),
3147 failed_commits: self.failed_commits.clone(),
3148 conflicts: self.conflicts.clone(),
3149 rejections: self.rejections.clone(),
3150 schema_floor: self.schema_floor.clone(),
3151 lease_state: self.lease_state.clone(),
3152 stopped: self.stopped,
3153 upgrading: self.upgrading,
3154 sync_needed: self.sync_needed,
3155 active_round: self.active_round,
3156 overlay_dirty: self.overlay_dirty.snapshot(),
3157 change_queue: self.change_queue.len(),
3158 sync_intent_queue: self.sync_intent_queue.len(),
3159 last_change: self.last_change.clone(),
3160 }
3161 }
3162
3163 fn restore(&mut self, rollback: Rollback) {
3164 self.outbox = rollback.outbox;
3165 self.failed_commits = rollback.failed_commits;
3166 self.conflicts = rollback.conflicts;
3167 self.rejections = rollback.rejections;
3168 self.schema_floor = rollback.schema_floor;
3169 self.lease_state = rollback.lease_state;
3170 self.stopped = rollback.stopped;
3171 self.upgrading = rollback.upgrading;
3172 self.sync_needed = rollback.sync_needed;
3173 self.active_round = rollback.active_round;
3174 self.overlay_dirty.restore(rollback.overlay_dirty);
3175 self.change_queue.truncate(rollback.change_queue);
3176 self.sync_intent_queue.truncate(rollback.sync_intent_queue);
3177 self.last_change = rollback.last_change;
3178 }
3179
3180 fn coalesce_unit(&mut self, rows: usize) -> Result<(), String> {
3183 let Some(open) = &self.coalesced else {
3184 return Ok(());
3185 };
3186 if open.rows > 0 && open.rows + rows > COALESCED_APPLY_ROWS {
3187 self.commit_coalesced_apply()?;
3188 self.begin_coalesced_apply()?;
3189 }
3190 if let Some(open) = &mut self.coalesced {
3191 open.rows += rows;
3192 }
3193 Ok(())
3194 }
3195
3196 fn commit_coalesced_apply(&mut self) -> Result<(), String> {
3201 let Some(open) = self.coalesced.take() else {
3202 return Ok(());
3203 };
3204 let committed = if self.conn.is_autocommit() {
3205 Err("the coalesced apply transaction was rolled back".to_owned())
3206 } else {
3207 self.conn
3208 .execute_batch("COMMIT")
3209 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
3210 };
3211 let Err(error) = committed else {
3212 return Ok(());
3213 };
3214 if !self.conn.is_autocommit() {
3215 if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3216 let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3217 }
3218 }
3219 self.restore(open.rollback);
3220 self.coalesced_failure = Some(error.clone());
3221 Err(error)
3222 }
3223
3224 fn finish_coalesced_apply(&mut self) -> Result<(), String> {
3226 let committed = self.commit_coalesced_apply();
3227 match self.coalesced_failure.take() {
3228 Some(failure) => Err(failure),
3229 None => committed,
3230 }
3231 }
3232
3233 fn rollback_observation(&self, name: &str) {
3234 if let Err(error) = self
3235 .conn
3236 .execute_batch(&format!("ROLLBACK TO {name}; RELEASE {name}"))
3237 {
3238 if let Some(failure) = self.storage_failure.borrow_mut().as_mut() {
3239 if failure.rollback_failure.is_none() {
3240 failure.rollback_failure = Some(Box::new(QueryReadFailure::from(error)));
3241 }
3242 }
3243 }
3244 }
3245
3246 fn finish_observation(
3247 &mut self,
3248 name: &str,
3249 mut batch: ChangeAccumulator,
3250 ) -> Result<(), String> {
3251 #[cfg(feature = "bench-internals")]
3252 let _phase = self.benchmark_phases.start(Phase::ObservationCommit);
3253 if self.failed_commits.iter().any(|(commit, _)| {
3254 commit
3255 .ops
3256 .iter()
3257 .any(|operation| batch.tables.contains_key(&operation.table))
3258 }) {
3259 batch.outcomes = true;
3260 }
3261 if !batch.touched() {
3262 self.conn
3263 .execute_batch(&format!("RELEASE {name}"))
3264 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3265 return Ok(());
3266 }
3267 let revision = self
3268 .local_revision()?
3269 .checked_add(1)
3270 .ok_or_else(|| "local revision exhausted u64".to_owned())?;
3271 self.conn
3272 .execute(
3273 "INSERT OR REPLACE INTO _syncular_meta(key, value) VALUES (?1, ?2)",
3274 rusqlite::params![LOCAL_REVISION_KEY, revision.to_string()],
3275 )
3276 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3277 let status = batch.status.then(|| self.status_snapshot());
3278 let event = ClientChangeBatch {
3279 revision: revision.to_string(),
3280 tables: batch
3281 .tables
3282 .into_iter()
3283 .map(|(table, scope_keys)| TableChange {
3284 table,
3285 scope_keys: scope_keys.map(|keys| keys.into_iter().collect()),
3286 })
3287 .collect(),
3288 windows: batch
3289 .windows
3290 .into_iter()
3291 .map(|(base_key, units)| WindowChange {
3292 base_key,
3293 units: units.into_iter().collect(),
3294 })
3295 .collect(),
3296 status,
3297 conflicts_changed: batch.conflicts,
3298 rejections_changed: batch.rejections,
3299 outcomes_changed: batch.outcomes,
3300 applied_commits: Vec::new(),
3301 };
3302 self.conn
3303 .execute_batch(&format!("RELEASE {name}"))
3304 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3305 let mut diagnostic_tables = event
3306 .tables
3307 .iter()
3308 .map(|entry| entry.table.clone())
3309 .collect::<BTreeSet<_>>()
3310 .into_iter()
3311 .collect::<Vec<_>>();
3312 let mut diagnostic_windows = event
3314 .windows
3315 .iter()
3316 .map(|entry| {
3317 entry
3318 .base_key
3319 .split('\0')
3320 .next()
3321 .unwrap_or_default()
3322 .to_owned()
3323 })
3324 .collect::<BTreeSet<_>>()
3325 .into_iter()
3326 .collect::<Vec<_>>();
3327 let domains_truncated = diagnostic_tables.len() > MAX_DIAGNOSTIC_DOMAINS
3328 || diagnostic_windows.len() > MAX_DIAGNOSTIC_DOMAINS;
3329 diagnostic_tables.truncate(MAX_DIAGNOSTIC_DOMAINS);
3330 diagnostic_windows.truncate(MAX_DIAGNOSTIC_DOMAINS);
3331 self.last_change = Some(DiagnosticLastChange {
3332 revision: event.revision.clone(),
3333 recorded_at_ms: self.clock_now_ms(),
3334 tables: diagnostic_tables,
3335 windows: diagnostic_windows,
3336 domains_truncated,
3337 status_changed: event.status.is_some(),
3338 conflicts_changed: event.conflicts_changed,
3339 rejections_changed: event.rejections_changed,
3340 outcomes_changed: event.outcomes_changed,
3341 });
3342 self.change_queue.push_back(event);
3343 Ok(())
3344 }
3345
3346 fn record_scope_map(
3347 &self,
3348 batch: &mut ChangeAccumulator,
3349 table_name: &str,
3350 scopes: &[(String, Vec<String>)],
3351 ) {
3352 let Some(table) = self.schema.table(table_name) else {
3353 return;
3354 };
3355 if table.scope_variables.iter().any(|scope| {
3358 !scopes
3359 .iter()
3360 .any(|(variable, _)| *variable == scope.variable)
3361 }) {
3362 batch.table(table_name);
3363 return;
3364 }
3365 for (variable, values) in scopes {
3366 let Some(scope) = table
3367 .scope_variables
3368 .iter()
3369 .find(|scope| &scope.variable == variable)
3370 else {
3371 continue;
3372 };
3373 for value in values {
3374 batch.scope(table_name, format!("{}:{value}", scope.prefix));
3375 }
3376 }
3377 }
3378
3379 fn record_row_scopes(
3381 &self,
3382 batch: &mut ChangeAccumulator,
3383 table_name: &str,
3384 row_id: &str,
3385 base: bool,
3386 ) -> bool {
3387 let Some(table) = self.schema.table(table_name) else {
3388 return false;
3389 };
3390 if table.scope_variables.is_empty() {
3391 return false;
3392 }
3393 let columns = table
3394 .scope_variables
3395 .iter()
3396 .map(|scope| quote_ident(&scope.column))
3397 .collect::<Vec<_>>()
3398 .join(", ");
3399 let full_table = if base {
3400 base_table(table_name)
3401 } else {
3402 visible_table(table_name)
3403 };
3404 let sql = format!(
3405 "SELECT {columns} FROM {full_table} WHERE {} LIMIT 1",
3406 row_id_predicate(table)
3407 );
3408 let Ok(mut stmt) = self.conn.prepare_cached(&sql) else {
3409 return false;
3410 };
3411 let values = stmt.query_row(rusqlite::params![row_id], |row| {
3412 let mut values = Vec::with_capacity(table.scope_variables.len());
3413 for index in 0..table.scope_variables.len() {
3414 values.push(row.get::<_, Option<String>>(index)?);
3415 }
3416 Ok(values)
3417 });
3418 let Ok(values) = values else {
3419 return false;
3420 };
3421 let mut recorded = false;
3422 for (scope, value) in table.scope_variables.iter().zip(values) {
3423 if let Some(value) = value {
3424 batch.scope(table_name, format!("{}:{value}", scope.prefix));
3425 recorded = true;
3426 }
3427 }
3428 recorded
3429 }
3430
3431 fn record_commit_changes(
3432 &self,
3433 batch: &mut ChangeAccumulator,
3434 tables: &[String],
3435 changes: &[ssp2::model::Change],
3436 ) {
3437 #[cfg(feature = "bench-internals")]
3438 let _phase = self.benchmark_phases.start(Phase::ObservationPrepare);
3439 for change in changes {
3440 let Some(table_name) = tables.get(change.table_index as usize) else {
3441 continue;
3442 };
3443 let mut precise = self.record_row_scopes(batch, table_name, &change.row_id, true);
3444 if let Some(table) = self.schema.table(table_name) {
3445 for (variable, value) in &change.scopes {
3446 if let Some(scope) = table
3447 .scope_variables
3448 .iter()
3449 .find(|scope| &scope.variable == variable)
3450 {
3451 batch.scope(table_name, format!("{}:{value}", scope.prefix));
3452 precise = true;
3453 }
3454 }
3455 }
3456 if !precise {
3457 batch.table(table_name);
3458 }
3459 }
3460 }
3461
3462 fn scoped_rows_exist(
3465 &self,
3466 table_name: &str,
3467 effective: &[(String, Vec<String>)],
3468 owners: &[Vec<(String, Vec<String>)>],
3469 ) -> Result<bool, String> {
3470 let Some(table) = self.schema.table(table_name) else {
3471 return Ok(false);
3472 };
3473 let Ok(Some((predicate, params))) = local_scope_predicate(table, effective, owners) else {
3474 return Ok(false);
3475 };
3476 for source in [base_table(table_name), visible_table(table_name)] {
3477 if self
3478 .conn
3479 .query_row(
3480 &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
3481 rusqlite::params_from_iter(¶ms),
3482 |row| row.get::<_, bool>(0),
3483 )
3484 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
3485 {
3486 return Ok(true);
3487 }
3488 }
3489 Ok(false)
3490 }
3491
3492 fn clear_scope(
3497 &mut self,
3498 table: &TableSchema,
3499 effective: &[(String, Vec<String>)],
3500 unit_id: &str,
3501 ) -> Result<bool, SectionError> {
3502 let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
3503 let matched = self
3504 .scoped_rows_exist(&table.name, effective, &[])
3505 .map_err(storage)?;
3506 let owners = if matched {
3507 unit_owners(
3508 &self.stored(load_units(&self.conn)).map_err(storage)?,
3509 table,
3510 unit_id,
3511 )
3512 } else {
3513 Vec::new()
3514 };
3515 let changed = matched
3516 && (owners.is_empty()
3517 || self
3518 .scoped_rows_exist(&table.name, effective, &owners)
3519 .map_err(storage)?);
3520 if !self
3521 .purge_scope_rows(&table.name, effective, &owners)
3522 .map_err(storage)?
3523 {
3524 return Err(SectionError::FailClosed);
3525 }
3526 Ok(changed)
3527 }
3528
3529 pub fn upgrading(&self) -> bool {
3531 self.upgrading
3532 }
3533
3534 pub fn recreate_with_schema(&mut self, schema_json: &Value) -> Result<(), String> {
3542 let new_schema = parse_schema_json(schema_json)?;
3543 validate_authority_reads(&new_schema, &self.limits.authority_reads)?;
3544 self.conn
3545 .execute_batch("BEGIN IMMEDIATE")
3546 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3547 let prior_schema = std::mem::replace(&mut self.schema, new_schema);
3548 let rollback = self.capture();
3554 let guarded = (|| -> Result<(), String> {
3555 let marker = read_local_schema_version(&self.conn, self.schema.version)?;
3560 self.create_bookkeeping_tables()?;
3561 match marker {
3562 Some(version) if version < self.schema.version => self.run_schema_reset()?,
3563 None => {
3564 self.create_synced_tables()?;
3565 self.persist_schema_version()?;
3566 }
3567 _ => {}
3568 }
3569 self.outbox = self.load_outbox()?.into();
3574 self.drop_unencodable_outbox(false, None)?;
3579 if marker == Some(self.schema.version)
3580 && (!self.outbox.is_empty()
3581 || !self.failed_commits.is_empty()
3582 || self.has_acknowledged_rows()?)
3583 {
3584 self.overlay_dirty.set(true);
3585 self.rebuild_overlay()?;
3586 }
3587 self.prune_unknown_units(false)?;
3588 self.save_unit_scope_schema()?;
3589 self.enqueue_startup_sync_if_needed()?;
3593 Ok(())
3594 })();
3595 let outcome = match guarded {
3596 Ok(()) => self
3597 .conn
3598 .execute_batch("COMMIT")
3599 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error)),
3600 Err(error) => Err(error),
3601 };
3602 if let Err(error) = outcome {
3603 if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
3604 let _ = Self::sqlite_failure(&self.storage_failure, rollback);
3606 }
3607 self.schema = prior_schema;
3608 self.restore(rollback);
3609 self.insert_sql.borrow_mut().clear();
3611 return Err(error);
3612 }
3613 Ok(())
3614 }
3615
3616 fn enqueue_startup_sync_if_needed(&mut self) -> Result<(), String> {
3617 let startup_work = !self.stopped
3618 && (!self.outbox.is_empty()
3619 || self.has_acknowledged_rows()?
3620 || !self.load_pending_evictions()?.is_empty()
3621 || self
3622 .stored(load_units(&self.conn))?
3623 .iter()
3624 .any(|unit| unit.status == UnitStatus::Active));
3625 if startup_work {
3626 self.sync_needed = true;
3627 self.sync_intent_queue.push_back(SyncIntent::Interactive);
3628 }
3629 Ok(())
3630 }
3631
3632 fn clear_satisfied_persisted_schema_floor(&mut self) -> Result<(), String> {
3639 let satisfied = self
3640 .schema_floor
3641 .as_ref()
3642 .and_then(|floor| floor.required_schema_version)
3643 .is_some_and(|required| self.schema.version >= required);
3644 if !satisfied {
3645 return Ok(());
3646 }
3647 self.delete_meta(SCHEMA_FLOOR_KEY)?;
3648 self.schema_floor = None;
3649 self.stopped = false;
3650 Ok(())
3651 }
3652
3653 fn reconcile_previous_version_at_boot(&self) -> Result<(), String> {
3658 let Some(replica_path) = self.previous_version_replica_path() else {
3659 return Ok(());
3660 };
3661 let max_age_ms = self
3662 .previous_version
3663 .filter(|config| config.enabled)
3664 .map(|config| config.max_age_ms);
3665 reconcile_previous_version_at_boot(
3666 &self.conn,
3667 &replica_path,
3668 self.schema.version,
3669 max_age_ms,
3670 self.clock_now_ms(),
3671 )
3672 }
3673
3674 fn previous_version_replica_path(&self) -> Option<String> {
3678 let path = self.conn.path()?;
3679 if path.is_empty() || path.starts_with("file:") {
3680 return None;
3681 }
3682 Some(path.to_owned())
3683 }
3684
3685 fn run_schema_reset(&mut self) -> Result<(), String> {
3691 self.begin_observation("syncular_schema_reset")?;
3692 let rollback = self.capture();
3693 let mut batch = ChangeAccumulator::default();
3694 let result = self
3695 .run_schema_reset_observed(&mut batch, true)
3696 .and_then(|()| self.finish_observation("syncular_schema_reset", batch));
3697 if let Err(error) = result {
3698 self.rollback_observation("syncular_schema_reset");
3699 self.restore(rollback);
3700 return Err(error);
3701 }
3702 Ok(())
3703 }
3704
3705 fn run_log_epoch_reset(&mut self, log_epoch: &str) -> Result<Vec<String>, String> {
3706 if self.get_meta(LOG_EPOCH_KEY)?.is_none() {
3707 self.begin_observation("syncular_epoch_acquisition")?;
3708 let rollback = self.capture();
3709 if let Err(error) = self.conn.execute(
3710 "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
3711 rusqlite::params![LOG_EPOCH_KEY, log_epoch],
3712 ) {
3713 self.rollback_observation("syncular_epoch_acquisition");
3714 return Err(Self::sqlite_failure(&self.storage_failure, error));
3715 }
3716 self.sync_needed = true;
3717 let batch = ChangeAccumulator {
3718 status: true,
3719 ..ChangeAccumulator::default()
3720 };
3721 if let Err(error) = self.finish_observation("syncular_epoch_acquisition", batch) {
3722 self.rollback_observation("syncular_epoch_acquisition");
3723 self.restore(rollback);
3724 return Err(error);
3725 }
3726 self.sync_intent_queue.push_back(SyncIntent::Interactive);
3727 return Ok(Vec::new());
3728 }
3729 let resets = self
3730 .stored(load_units(&self.conn))?
3731 .into_iter()
3732 .map(|unit| unit.id)
3733 .collect();
3734 self.begin_observation("syncular_log_epoch_reset")?;
3735 let rollback = self.capture();
3736 let mut batch = ChangeAccumulator::default();
3737 let result = self
3738 .run_schema_reset_observed(&mut batch, false)
3739 .and_then(|()| {
3740 self.conn
3741 .execute(
3742 "INSERT OR REPLACE INTO _syncular_meta(key,value) VALUES (?1,?2)",
3743 rusqlite::params![LOG_EPOCH_KEY, log_epoch],
3744 )
3745 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3746 self.sync_needed = true;
3747 batch.status = true;
3748 self.finish_observation("syncular_log_epoch_reset", batch)
3749 });
3750 if let Err(error) = result {
3751 self.rollback_observation("syncular_log_epoch_reset");
3752 self.restore(rollback);
3753 return Err(error);
3754 }
3755 self.sync_intent_queue.push_back(SyncIntent::Interactive);
3756 Ok(resets)
3757 }
3758
3759 fn run_schema_reset_observed(
3760 &mut self,
3761 batch: &mut ChangeAccumulator,
3762 capture: bool,
3763 ) -> Result<(), String> {
3764 read_local_schema_version(&self.conn, self.schema.version)?;
3770 self.conn
3771 .execute_batch(
3772 "DELETE FROM _syncular_acked_rows; DELETE FROM _syncular_row_deliveries;",
3773 )
3774 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3775 self.cancel_sync_round();
3776 self.upgrading = true;
3777 batch.status = true;
3778 if self.previous_version.is_some_and(|config| config.enabled) {
3786 let previous_version = self
3787 .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
3788 .and_then(|value| value.parse::<i32>().ok())
3789 .unwrap_or(self.schema.version);
3790 let pending = self
3791 .outbox
3792 .iter()
3793 .map(|commit| PendingCommitAudit {
3794 commit_id: &commit.client_commit_id,
3795 operations: commit_audit_operations(commit),
3796 })
3797 .collect::<Vec<_>>();
3798 crate::previous_version::write_previous_version_audit(
3799 &self.conn,
3800 &crate::previous_version::build_previous_version_audit(
3801 &self.schema,
3802 &pending,
3803 previous_version,
3804 self.schema.version,
3805 self.clock_now_ms(),
3806 ),
3807 )?;
3808 }
3809 if let Some(replica_path) = self.previous_version_replica_path() {
3814 sweep_previous_version_container(&self.conn, &replica_path)?;
3815 if capture {
3816 if let Some(config) = self.previous_version.filter(|config| config.enabled) {
3817 let previous_version = self
3818 .get_meta(LOCAL_SCHEMA_VERSION_KEY)?
3819 .and_then(|value| value.parse::<i32>().ok())
3820 .unwrap_or(self.schema.version);
3821 capture_previous_version_from_replica(
3822 &self.conn,
3823 &replica_path,
3824 previous_version,
3825 self.schema.version,
3826 &config,
3827 self.clock_now_ms(),
3828 )?;
3829 }
3830 }
3831 }
3832 for table in &self.schema.tables {
3833 batch.table(&table.name);
3834 }
3835 for (base_key, value) in self.load_window_registry()? {
3836 batch.window(&base_key, &value);
3837 }
3838 if capture {
3839 self.prune_unknown_units(true)?;
3840 }
3841 self.insert_sql.borrow_mut().clear();
3843 self.overlay_dirty.set(true);
3844 let virtual_tables: Vec<String> = {
3852 let mut stmt = self
3853 .conn
3854 .prepare(
3855 "SELECT name FROM sqlite_master WHERE type = 'table' AND sql LIKE 'CREATE VIRTUAL TABLE%'",
3856 )
3857 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3858 let rows = stmt
3859 .query_map([], |row| row.get::<_, String>(0))
3860 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3861 rows.filter_map(Result::ok)
3862 .filter(|name| is_synced_table_name(name))
3863 .collect()
3864 };
3865 for name in virtual_tables {
3866 self.conn
3867 .execute_batch(&format!(
3868 "DROP TABLE IF EXISTS {}",
3869 quote_ident(&format!("_syncular_fts_{name}"))
3870 ))
3871 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3872 self.conn
3873 .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
3874 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3875 }
3876 let existing: Vec<String> = {
3877 let mut stmt = self
3878 .conn
3879 .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
3880 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3881 let rows = stmt
3882 .query_map([], |row| row.get::<_, String>(0))
3883 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3884 rows.filter_map(Result::ok)
3885 .filter(|name| is_synced_table_name(name))
3886 .collect()
3887 };
3888 for name in &existing {
3889 if let Some(table) = name.strip_prefix("_syncular_base_") {
3890 batch.table(table);
3891 } else if !name.starts_with("_syncular_") {
3892 batch.table(name);
3893 }
3894 }
3895 for name in existing {
3896 self.conn
3897 .execute(&format!("DROP TABLE IF EXISTS {}", quote_ident(&name)), [])
3898 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3899 }
3900 self.create_synced_tables()?;
3902 reset_units(&self.conn)
3904 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
3905 self.stopped = false;
3907 self.schema_floor = None;
3908 self.delete_meta(SCHEMA_FLOOR_KEY)?;
3909 self.persist_schema_version()?;
3911 self.save_unit_scope_schema()?;
3912 self.drop_unencodable_outbox(false, Some(batch))?;
3923 self.rebuild_overlay()?;
3925 Ok(())
3926 }
3927
3928 fn drop_incompatible_outbox(&mut self) -> Result<bool, String> {
3937 let incompatible = self
3938 .outbox
3939 .iter()
3940 .filter(|commit| {
3941 first_incompatibility(&self.schema, &commit_audit_operations(commit)).is_some()
3942 })
3943 .cloned()
3944 .collect::<Vec<_>>();
3945 if incompatible.is_empty() {
3946 return Ok(false);
3947 }
3948 self.drop_outbox_commits(
3949 &incompatible,
3950 OUTBOX_INCOMPATIBLE_CODE,
3951 "the persisted commit cannot encode under the current schema",
3952 )?;
3953 Ok(true)
3954 }
3955
3956 fn drop_outbox_commits(
3960 &mut self,
3961 incompatible: &[Arc<OutboxCommit>],
3962 code: &str,
3963 message: &str,
3964 ) -> Result<(), String> {
3965 let rollback = self.capture();
3971 let owns_transaction = self.conn.is_autocommit();
3972 self.begin_observation("syncular_outbox_drop")?;
3973 let mut batch = ChangeAccumulator::default();
3974 let dropped = (|| -> Result<(), String> {
3975 let mut rejections = Vec::new();
3976 for commit in incompatible {
3977 let results = commit
3978 .ops
3979 .iter()
3980 .enumerate()
3981 .map(|(op_index, operation)| {
3982 let rejection = RejectionRecord {
3983 client_commit_id: commit.client_commit_id.clone(),
3984 op_index: op_index as i32,
3985 code: code.to_owned(),
3986 message: message.to_owned(),
3987 retryable: false,
3988 details: None,
3989 operation: Some(CommitOperation::from(operation)),
3990 };
3991 rejections.push(rejection.clone());
3992 CommitOperationOutcome::Error { rejection }
3993 })
3994 .collect::<Vec<_>>();
3995 self.persist_commit_outcome(
3996 &commit.client_commit_id,
3997 CommitOutcomeStatus::Rejected,
3998 &results,
3999 Some(&commit.ops),
4000 )?;
4001 self.delete_outbox_persisted(&commit.client_commit_id)?;
4002 for operation in &commit.ops {
4005 if self.schema.table(&operation.table).is_some() {
4006 batch.table(&operation.table);
4007 }
4008 }
4009 }
4010 self.prune_commit_outcomes()?;
4011 let incompatible_ids = incompatible
4012 .iter()
4013 .map(|commit| commit.client_commit_id.as_str())
4014 .collect::<BTreeSet<_>>();
4015 self.outbox
4016 .retain(|commit| !incompatible_ids.contains(commit.client_commit_id.as_str()));
4017 self.rejections.extend(rejections);
4018 self.overlay_dirty.set(true);
4021 self.rebuild_overlay()?;
4022 batch.status = true;
4023 batch.rejections = true;
4024 batch.outcomes = true;
4025 Ok(())
4026 })();
4027 let result = dropped.and_then(|()| self.finish_observation("syncular_outbox_drop", batch));
4028 if let Err(error) = result {
4029 if owns_transaction {
4033 if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
4034 let mut failure = self.storage_failure.borrow_mut();
4035 let failure =
4036 failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
4037 failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
4038 }
4039 } else {
4040 self.rollback_observation("syncular_outbox_drop");
4041 }
4042 self.restore(rollback);
4043 return Err(error);
4044 }
4045 Ok(())
4046 }
4047
4048 fn create_synced_tables(&self) -> Result<(), String> {
4051 for table in &self.schema.tables {
4052 for (full, index_prefix) in [
4056 (base_table(&table.name), "_syncular_base_"),
4057 (visible_table(&table.name), ""),
4058 ] {
4059 let mut cols: Vec<String> =
4060 table.columns.iter().map(|c| quote_ident(&c.name)).collect();
4061 cols.push("\"_syncular_version\" INTEGER NOT NULL".to_owned());
4062 let sql = format!(
4063 "CREATE TABLE IF NOT EXISTS {full} ({} , PRIMARY KEY ({}))",
4064 cols.join(", "),
4065 quote_ident(&table.primary_key)
4066 );
4067 self.conn
4068 .execute(&sql, [])
4069 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4070 for index in &table.indexes {
4074 let unique = if index.unique { "UNIQUE " } else { "" };
4075 let index_name = quote_ident(&format!("{index_prefix}{}", index.name));
4076 let cols_sql = index
4077 .columns
4078 .iter()
4079 .map(|c| quote_ident(c))
4080 .collect::<Vec<_>>()
4081 .join(", ");
4082 let index_sql = format!(
4083 "CREATE {unique}INDEX IF NOT EXISTS {index_name} ON {full} ({cols_sql})"
4084 );
4085 self.conn
4086 .execute(&index_sql, [])
4087 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4088 }
4089 }
4090 }
4091 for table in &self.schema.tables {
4094 for index in &table.fts_indexes {
4095 self.create_fts_projection(table, index)?;
4096 }
4097 }
4098 Ok(())
4099 }
4100
4101 fn fts_projection_exists(&self, index: &FtsIndexSchema) -> Result<bool, String> {
4102 let count: i64 = self
4103 .conn
4104 .query_row(
4105 "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?1",
4106 rusqlite::params![index.name],
4107 |row| row.get(0),
4108 )
4109 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4110 Ok(count > 0)
4111 }
4112
4113 fn drop_fts_triggers(&self, index: &FtsIndexSchema) -> Result<(), String> {
4114 for suffix in ["ai", "ad", "au"] {
4115 self.conn
4116 .execute(
4117 &format!(
4118 "DROP TRIGGER IF EXISTS {}",
4119 quote_ident(&format!("{}_{suffix}", index.name))
4120 ),
4121 [],
4122 )
4123 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4124 }
4125 Ok(())
4126 }
4127
4128 fn create_fts_triggers(
4129 &self,
4130 table: &TableSchema,
4131 index: &FtsIndexSchema,
4132 ) -> Result<(), String> {
4133 let fts = quote_ident(&index.name);
4134 let source = visible_table(&table.name);
4135 let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4136 let pk = quote_ident(&table.primary_key);
4137 let projection_columns = std::iter::once(source_id.clone())
4138 .chain(index.columns.iter().map(|column| quote_ident(column)))
4139 .collect::<Vec<_>>()
4140 .join(", ");
4141 let new_values = std::iter::once(format!("CAST(new.{pk} AS TEXT)"))
4142 .chain(
4143 index
4144 .columns
4145 .iter()
4146 .map(|column| format!("new.{}", quote_ident(column))),
4147 )
4148 .collect::<Vec<_>>()
4149 .join(", ");
4150 let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4151 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)");
4152 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)");
4153 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})");
4154 let bi = quote_ident(&format!("{}_bi", index.name));
4155 let ai = quote_ident(&format!("{}_ai", index.name));
4156 let ad = quote_ident(&format!("{}_ad", index.name));
4157 let au = quote_ident(&format!("{}_au", index.name));
4158 let replacement_exists = format!("EXISTS (SELECT 1 FROM {source} WHERE {pk} = new.{pk})");
4159 let sql = format!(
4160 "DROP TRIGGER IF EXISTS {bi};
4161 DROP TRIGGER IF EXISTS {ai};
4162 DROP TRIGGER IF EXISTS {ad};
4163 DROP TRIGGER IF EXISTS {au};
4164 CREATE TRIGGER {bi} BEFORE INSERT ON {source} WHEN {replacement_exists} BEGIN {delete_new}; END;
4165 CREATE TRIGGER {ai} AFTER INSERT ON {source} BEGIN {insert_new}; END;
4166 CREATE TRIGGER {ad} AFTER DELETE ON {source} BEGIN {delete_old}; END;
4167 CREATE TRIGGER {au} AFTER UPDATE ON {source} BEGIN {delete_old}; {delete_new}; {insert_new}; END;",
4168 );
4169 self.conn
4170 .execute_batch(&sql)
4171 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4172 }
4173
4174 fn rebuild_fts_projection(
4175 &self,
4176 table: &TableSchema,
4177 index: &FtsIndexSchema,
4178 ) -> Result<(), String> {
4179 let fts = quote_ident(&index.name);
4180 let source_id = quote_ident(FTS_SOURCE_ID_COLUMN);
4181 let pk = quote_ident(&table.primary_key);
4182 let indexed_columns = index
4183 .columns
4184 .iter()
4185 .map(|column| quote_ident(column))
4186 .collect::<Vec<_>>();
4187 let projection_columns = std::iter::once(source_id.clone())
4188 .chain(indexed_columns.iter().cloned())
4189 .collect::<Vec<_>>()
4190 .join(", ");
4191 let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4192 let sql = format!(
4193 "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};",
4194 columns = indexed_columns.join(", "),
4195 source = visible_table(&table.name),
4196 );
4197 self.conn
4198 .execute_batch(&sql)
4199 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4200 }
4201
4202 fn create_fts_projection(
4203 &self,
4204 table: &TableSchema,
4205 index: &FtsIndexSchema,
4206 ) -> Result<(), String> {
4207 self.begin_observation("syncular_fts_schema")?;
4208 let result = (|| {
4209 let existed = self.fts_projection_exists(index)?;
4210 let tokenizer = index.tokenize.replace('\'', "''");
4211 let columns = index
4212 .columns
4213 .iter()
4214 .map(|column| quote_ident(column))
4215 .collect::<Vec<_>>()
4216 .join(", ");
4217 let sql = format!(
4218 "CREATE VIRTUAL TABLE IF NOT EXISTS {fts} USING fts5({source_id} UNINDEXED, {columns}, tokenize='{tokenizer}')",
4219 fts = quote_ident(&index.name),
4220 source_id = quote_ident(FTS_SOURCE_ID_COLUMN),
4221 );
4222 self.conn.execute(&sql, []).map_err(|error| {
4223 format!(
4224 "cannot create local FTS5 projection {:?}: {error}",
4225 index.name
4226 )
4227 })?;
4228 let mapping = quote_ident(&format!("_syncular_fts_{}", index.name));
4229 let mapped: bool = self
4230 .conn
4231 .query_row(
4232 "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type='table' AND name=?1)",
4233 [format!("_syncular_fts_{}", index.name)],
4234 |row| row.get(0),
4235 )
4236 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4237 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))?;
4238 if !mapped && existed {
4239 self.conn
4240 .execute_batch(&format!(
4241 "INSERT INTO {mapping}(id, source_id) SELECT rowid, {} FROM {}",
4242 quote_ident(FTS_SOURCE_ID_COLUMN),
4243 quote_ident(&index.name)
4244 ))
4245 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4246 }
4247 self.create_fts_triggers(table, index)?;
4248 if !existed {
4249 self.rebuild_fts_projection(table, index)?;
4250 }
4251 Ok(())
4252 })();
4253 if let Err(error) = result {
4254 self.rollback_observation("syncular_fts_schema");
4255 return Err(error);
4256 }
4257 if let Err(error) = self.conn.execute_batch("RELEASE syncular_fts_schema") {
4258 self.rollback_observation("syncular_fts_schema");
4259 return Err(error.to_string());
4260 }
4261 Ok(())
4262 }
4263
4264 fn persist_outbox_insert(&self, commit: &OutboxCommit) -> Result<(), String> {
4267 let ops: Vec<Value> = commit
4268 .ops
4269 .iter()
4270 .map(|op| {
4271 let mut entry = serde_json::json!({
4272 "op": if op.upsert { "upsert" } else { "delete" },
4273 "table": op.table,
4274 "rowId": op.row_id,
4275 "baseVersion": op.base_version,
4276 "values": op.values.clone().map(Value::Object),
4277 });
4278 if op.insert {
4279 entry["insert"] = Value::Bool(true);
4280 }
4281 entry
4282 })
4283 .collect();
4284 self.conn
4285 .execute(
4286 "INSERT OR REPLACE INTO _syncular_outbox (commit_id, ops_json) VALUES (?1, ?2)",
4287 rusqlite::params![commit.client_commit_id, Value::Array(ops).to_string()],
4288 )
4289 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4290 for operation in &commit.ops {
4291 let Some(values) = &operation.values else {
4292 continue;
4293 };
4294 let Some(table) = self.schema.table(&operation.table) else {
4295 continue;
4296 };
4297 for column in table
4298 .columns
4299 .iter()
4300 .filter(|column| column.ty == ColumnType::BlobRef)
4301 {
4302 let Some(Value::String(raw)) = values.get(&column.name) else {
4303 continue;
4304 };
4305 let Ok(blob_ref) = serde_json::from_str::<Value>(raw) else {
4306 continue;
4307 };
4308 let Some(blob_id) = blob_ref.get("blobId").and_then(Value::as_str) else {
4309 continue;
4310 };
4311 self.conn
4312 .execute(
4313 "INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id, blob_id)
4314 SELECT ?1, ?2 WHERE EXISTS (SELECT 1 FROM _syncular_blobs WHERE blob_id = ?2)",
4315 rusqlite::params![commit.client_commit_id, blob_id],
4316 )
4317 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4318 }
4319 }
4320 Ok(())
4321 }
4322
4323 fn delete_outbox_persisted(&self, client_commit_id: &str) -> Result<(), String> {
4324 self.conn
4325 .execute(
4326 "DELETE FROM _syncular_blob_commit_refs WHERE commit_id = ?1",
4327 rusqlite::params![client_commit_id],
4328 )
4329 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4330 self.conn
4331 .execute(
4332 "DELETE FROM _syncular_outbox WHERE commit_id = ?1",
4333 rusqlite::params![client_commit_id],
4334 )
4335 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4336 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)", [])
4337 .map(|_| ())
4338 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4339 }
4340
4341 fn outcome_status_name(status: CommitOutcomeStatus) -> &'static str {
4342 match status {
4343 CommitOutcomeStatus::Applied => "applied",
4344 CommitOutcomeStatus::Cached => "cached",
4345 CommitOutcomeStatus::Conflict => "conflict",
4346 CommitOutcomeStatus::Rejected => "rejected",
4347 }
4348 }
4349
4350 fn outcome_resolution_name(resolution: CommitOutcomeResolution) -> &'static str {
4351 match resolution {
4352 CommitOutcomeResolution::Active => "active",
4353 CommitOutcomeResolution::ResolvedKeepServer => "resolved_keep_server",
4354 CommitOutcomeResolution::Superseded => "superseded",
4355 CommitOutcomeResolution::Dismissed => "dismissed",
4356 }
4357 }
4358
4359 fn parse_outcome_status(value: &str) -> Result<CommitOutcomeStatus, String> {
4360 match value {
4361 "applied" => Ok(CommitOutcomeStatus::Applied),
4362 "cached" => Ok(CommitOutcomeStatus::Cached),
4363 "conflict" => Ok(CommitOutcomeStatus::Conflict),
4364 "rejected" => Ok(CommitOutcomeStatus::Rejected),
4365 _ => Err(format!("invalid persisted commit outcome status {value:?}")),
4366 }
4367 }
4368
4369 fn parse_outcome_resolution(value: &str) -> Result<CommitOutcomeResolution, String> {
4370 match value {
4371 "active" => Ok(CommitOutcomeResolution::Active),
4372 "resolved_keep_server" => Ok(CommitOutcomeResolution::ResolvedKeepServer),
4373 "superseded" => Ok(CommitOutcomeResolution::Superseded),
4374 "dismissed" => Ok(CommitOutcomeResolution::Dismissed),
4375 _ => Err(format!(
4376 "invalid persisted commit outcome resolution {value:?}"
4377 )),
4378 }
4379 }
4380
4381 fn persist_commit_outcome(
4382 &self,
4383 client_commit_id: &str,
4384 status: CommitOutcomeStatus,
4385 results: &[CommitOperationOutcome],
4386 operations: Option<&[OutboxOp]>,
4387 ) -> Result<(), String> {
4388 let results_json = serde_json::to_string(results).map_err(|error| error.to_string())?;
4389 let operations_json = operations
4390 .map(|items| {
4391 serde_json::to_string(&items.iter().map(CommitOperation::from).collect::<Vec<_>>())
4392 })
4393 .transpose()
4394 .map_err(|error| error.to_string())?;
4395 self.conn
4396 .execute(
4397 "INSERT INTO _syncular_commit_outcomes (
4398 client_commit_id, status, recorded_at_ms, results_json,
4399 operations_json, resolution
4400 ) VALUES (?1, ?2, ?3, ?4, ?5, 'active')",
4401 rusqlite::params![
4402 client_commit_id,
4403 Self::outcome_status_name(status),
4404 self.clock_now_ms(),
4405 results_json,
4406 operations_json
4407 ],
4408 )
4409 .map(|_| ())
4410 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
4411 }
4412
4413 fn stored_cell_is_representable(cell: &Value) -> bool {
4416 cell.is_null()
4417 || cell.is_string()
4418 || cell.is_boolean()
4419 || cell.is_number()
4420 || is_canonical_bytes_envelope(cell)
4421 }
4422
4423 fn stored_row_is_representable(value: &Value) -> bool {
4424 value
4425 .as_object()
4426 .is_some_and(|row| row.values().all(Self::stored_cell_is_representable))
4427 }
4428
4429 fn stored_operation_is_representable(value: &Value) -> bool {
4430 value.get("table").is_some_and(Value::is_string)
4431 && value.get("rowId").is_some_and(Value::is_string)
4432 && value.get("baseVersion").is_none_or(|v| {
4433 v.as_i64()
4434 .is_some_and(|n| n.unsigned_abs() <= MAX_JS_SAFE_INTEGER)
4435 })
4436 && match value.get("op").and_then(Value::as_str) {
4437 Some("upsert") => {
4438 value
4439 .get("values")
4440 .is_some_and(Self::stored_row_is_representable)
4441 && value
4442 .get("insert")
4443 .is_none_or(|insert| *insert == Value::Bool(true))
4444 }
4445 Some("delete") => value.get("values").is_none() && value.get("insert").is_none(),
4446 _ => false,
4447 }
4448 }
4449
4450 fn outbox_op_is_journalable(operation: &OutboxOp) -> bool {
4454 serde_json::to_value(CommitOperation::from(operation))
4455 .is_ok_and(|value| Self::stored_operation_is_representable(&value))
4456 }
4457
4458 fn outcome_from_row(row: StoredCommitOutcomeRow) -> Result<CommitOutcome, String> {
4459 let StoredCommitOutcomeRow {
4460 sequence,
4461 client_commit_id,
4462 status,
4463 recorded_at_ms,
4464 results_json,
4465 operations_json,
4466 resolution,
4467 resolved_at_ms,
4468 replacement_client_commit_id,
4469 } = row;
4470 if sequence.unsigned_abs() > MAX_JS_SAFE_INTEGER
4471 || recorded_at_ms.unsigned_abs() > MAX_JS_SAFE_INTEGER
4472 || resolved_at_ms.is_some_and(|value| value.unsigned_abs() > MAX_JS_SAFE_INTEGER)
4473 {
4474 return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned());
4475 }
4476 let invalid = || "sync.local_corrupt: persisted commit outcome is invalid".to_owned();
4477 let stored: Vec<Value> = serde_json::from_str(&results_json).map_err(|_| invalid())?;
4478 for result in &stored {
4479 let nested = match result.get("status").and_then(Value::as_str) {
4480 Some("conflict") => result.get("conflict"),
4481 Some("error") => result.get("rejection"),
4482 _ => None,
4483 };
4484 if nested
4485 .and_then(|record| record.get("operation"))
4486 .is_some_and(|op| !Self::stored_operation_is_representable(op))
4487 || (result.get("status").and_then(Value::as_str) == Some("conflict")
4488 && nested
4489 .and_then(|record| record.get("serverRow"))
4490 .is_some_and(|row| !Self::stored_row_is_representable(row)))
4491 {
4492 return Err(invalid());
4493 }
4494 }
4495 let results: Vec<CommitOperationOutcome> =
4496 serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())?;
4497 let has_conflict = results
4498 .iter()
4499 .any(|result| matches!(result, CommitOperationOutcome::Conflict { .. }));
4500 let has_error = results
4501 .iter()
4502 .any(|result| matches!(result, CommitOperationOutcome::Error { .. }));
4503 let status = Self::parse_outcome_status(&status).map_err(|_| invalid())?;
4504 let redacted = results.is_empty() && operations_json.is_none();
4505 if match status {
4506 CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => has_conflict || has_error,
4507 CommitOutcomeStatus::Conflict => !(has_conflict || redacted),
4508 CommitOutcomeStatus::Rejected => has_conflict || !(has_error || redacted),
4509 } {
4510 return Err(invalid());
4511 }
4512 let operations: Option<Vec<CommitOperation>> = operations_json
4513 .map(|raw| {
4514 let stored: Vec<Value> = serde_json::from_str(&raw).map_err(|_| invalid())?;
4515 if !stored.iter().all(Self::stored_operation_is_representable) {
4516 return Err(invalid());
4517 }
4518 serde_json::from_value(Value::Array(stored)).map_err(|_| invalid())
4519 })
4520 .transpose()?;
4521 for result in &results {
4522 match result {
4523 CommitOperationOutcome::Conflict { conflict }
4524 if conflict.server_version.unsigned_abs() > MAX_JS_SAFE_INTEGER =>
4525 {
4526 return Err("sync.local_corrupt: persisted commit outcome is invalid".to_owned())
4527 }
4528 CommitOperationOutcome::Error { rejection } => {
4529 if let Some(details) = &rejection.details {
4530 let encoded = serde_json::to_string(details).map_err(|_| {
4531 "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4532 })?;
4533 RejectionDetails::parse(&encoded).map_err(|_| {
4534 "sync.local_corrupt: persisted commit outcome is invalid".to_owned()
4535 })?;
4536 }
4537 }
4538 _ => {}
4539 }
4540 }
4541 Ok(CommitOutcome {
4542 sequence,
4543 client_commit_id,
4544 status,
4545 recorded_at_ms,
4546 results,
4547 operations,
4548 retained_rows: None,
4549 resolution: Self::parse_outcome_resolution(&resolution)?,
4550 resolved_at_ms,
4551 replacement_client_commit_id,
4552 })
4553 }
4554
4555 fn unique_conflicts(
4557 &self,
4558 table: &TableSchema,
4559 values: &Map<String, Value>,
4560 base: bool,
4561 ) -> Result<Vec<RetainedUniqueConflict>, String> {
4562 let source = if base {
4563 base_table(&table.name)
4564 } else {
4565 visible_table(&table.name)
4566 };
4567 let mut conflicts = Vec::new();
4568 for index in table.indexes.iter().filter(|index| index.unique) {
4569 let mut params = vec![json_param_to_sql(
4570 values.get(&table.primary_key).ok_or("sync.local_corrupt")?,
4571 )?];
4572 for name in &index.columns {
4573 let column = table
4574 .columns
4575 .iter()
4576 .find(|column| column.name == *name)
4577 .ok_or("sync.local_corrupt")?;
4578 let cell = json_to_column_value(column, values.get(name))?;
4579 params.push(owned_sql_value(RowParam::Cell(&cell))?);
4580 }
4581 let sql = format!(
4582 "SELECT * FROM {source} WHERE {} != ? AND {}",
4583 quote_ident(&table.primary_key),
4584 index
4585 .columns
4586 .iter()
4587 .map(|column| format!("{} = ?", quote_ident(column)))
4588 .collect::<Vec<_>>()
4589 .join(" AND ")
4590 );
4591 let mut statement = self
4592 .conn
4593 .prepare_cached(&sql)
4594 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4595 let records = statement
4596 .query_map(rusqlite::params_from_iter(params), |record| {
4597 let values = table
4598 .columns
4599 .iter()
4600 .enumerate()
4601 .map(|(index, column)| {
4602 let value = sql_ref_to_json(column, record.get_ref(index)?);
4603 json_to_column_value(column, Some(&value)).map_err(|message| {
4604 rusqlite::Error::ToSqlConversionFailure(message.into())
4605 })
4606 })
4607 .collect::<Result<Row, _>>()?;
4608 Ok((values, record.get::<_, i64>(table.columns.len())?))
4609 })
4610 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4611 for record in records {
4612 let (row, version) =
4613 record.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4614 let row_id = render_row_id_json(Some(&column_value_to_json(&row[table.pk_index])))?;
4615 conflicts.push(RetainedUniqueConflict {
4616 index: index.name.clone(),
4617 columns: index.columns.clone(),
4618 row_id,
4619 server_row: table
4620 .columns
4621 .iter()
4622 .zip(&row)
4623 .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
4624 .collect(),
4625 server_version: version,
4626 });
4627 }
4628 }
4629 Ok(conflicts)
4630 }
4631
4632 fn attach_retained_rows(&self, mut outcome: CommitOutcome) -> Result<CommitOutcome, String> {
4633 if let Some((commit, initial)) = self
4634 .failed_commits
4635 .iter()
4636 .find(|(commit, _)| commit.client_commit_id == outcome.client_commit_id)
4637 {
4638 let mut rows = Vec::new();
4639 for operation in &commit.ops {
4640 let Some(table) = self.schema.table(&operation.table) else {
4642 continue;
4643 };
4644 let key =
4645 serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
4646 .map_err(|_| "sync.local_corrupt".to_owned())?;
4647 let base = self.stored_row(table, &operation.row_id, true)?;
4648 rows.push(RetainedCommitRow {
4649 table: operation.table.clone(),
4650 row_id: operation.row_id.clone(),
4651 unique_conflicts: if operation.upsert {
4652 self.unique_conflicts(
4653 table,
4654 initial
4655 .get(&key)
4656 .and_then(Value::as_object)
4657 .or(operation.values.as_ref())
4658 .ok_or("sync.local_corrupt")?,
4659 true,
4660 )?
4661 } else {
4662 Vec::new()
4663 },
4664 local_row: if operation.upsert {
4665 initial
4666 .get(&key)
4667 .and_then(Value::as_object)
4668 .cloned()
4669 .or_else(|| operation.values.clone())
4670 } else {
4671 None
4672 },
4673 server_row: base.as_ref().map(|(values, _)| {
4674 table
4675 .columns
4676 .iter()
4677 .zip(values)
4678 .map(|(column, value)| {
4679 (column.name.clone(), column_value_to_json(value))
4680 })
4681 .collect()
4682 }),
4683 server_version: base.map(|(_, version)| version),
4684 });
4685 }
4686 outcome.retained_rows = Some(rows);
4687 }
4688 Ok(outcome)
4689 }
4690
4691 pub fn commit_outcome(&self, client_commit_id: &str) -> Result<Option<CommitOutcome>, String> {
4692 let row = self
4693 .conn
4694 .query_row(
4695 "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
4696 resolution, resolved_at_ms, replacement_client_commit_id
4697 FROM _syncular_commit_outcomes WHERE client_commit_id = ?1",
4698 rusqlite::params![client_commit_id],
4699 |row| {
4700 Ok(StoredCommitOutcomeRow {
4701 sequence: row.get(0)?,
4702 client_commit_id: row.get(1)?,
4703 status: row.get(2)?,
4704 recorded_at_ms: row.get(3)?,
4705 results_json: row.get(4)?,
4706 operations_json: row.get(5)?,
4707 resolution: row.get(6)?,
4708 resolved_at_ms: row.get(7)?,
4709 replacement_client_commit_id: row.get(8)?,
4710 })
4711 },
4712 )
4713 .optional()
4714 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4715 row.map(|row| self.attach_retained_rows(Self::outcome_from_row(row)?))
4716 .transpose()
4717 }
4718
4719 #[doc(hidden)]
4721 pub fn prepare_current_base(
4722 &self,
4723 client_commit_id: &str,
4724 sequence: i64,
4725 ) -> Result<CurrentBasePreparation, CurrentBaseProof> {
4726 let outcome = self
4727 .commit_outcome(client_commit_id)
4728 .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?;
4729 let valid = outcome.as_ref().is_some_and(|outcome| {
4730 outcome.sequence == sequence
4731 && outcome.resolution == CommitOutcomeResolution::Active
4732 && matches!(
4733 outcome.status,
4734 CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
4735 )
4736 && outcome
4737 .operations
4738 .as_ref()
4739 .zip(outcome.retained_rows.as_ref())
4740 .is_some_and(|(operations, rows)| {
4741 !rows.is_empty() && operations.len() == rows.len()
4742 })
4743 });
4744 if !valid {
4745 return Err(CurrentBaseProof::failure(
4746 CurrentBaseProofReason::OutcomeUnavailable,
4747 ));
4748 }
4749 if !self.transport_enabled {
4750 return Err(CurrentBaseProof::failure(CurrentBaseProofReason::Offline));
4751 }
4752 Ok(CurrentBasePreparation {
4753 client_commit_id: client_commit_id.to_owned(),
4754 sequence,
4755 units: load_units(&self.conn)
4756 .map_err(|_| CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed))?,
4757 transport_epoch: self.transport_epoch,
4758 registration_epoch: self.registration_epoch,
4759 security_epoch: self.security_epoch,
4760 })
4761 }
4762
4763 #[doc(hidden)]
4765 pub fn finish_current_base(
4766 &mut self,
4767 prepared: CurrentBasePreparation,
4768 drive: SyncOutcome,
4769 ) -> CurrentBaseProof {
4770 if !self.transport_enabled || self.transport_epoch != prepared.transport_epoch {
4771 return CurrentBaseProof::failure(CurrentBaseProofReason::Offline);
4772 }
4773 if self.registration_epoch != prepared.registration_epoch {
4774 return CurrentBaseProof::failure(CurrentBaseProofReason::MissingCoverage);
4775 }
4776 if self.security_preflight || self.security_epoch != prepared.security_epoch {
4777 return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed);
4778 }
4779 let report = match drive {
4780 SyncOutcome::Ok(report) => report,
4781 SyncOutcome::BudgetExhausted(_) => {
4782 return CurrentBaseProof::failure(CurrentBaseProofReason::BudgetExhausted)
4783 }
4784 _ => return CurrentBaseProof::failure(CurrentBaseProofReason::SyncFailed),
4785 };
4786 if report.schema_floor.is_some() {
4787 return CurrentBaseProof::failure(CurrentBaseProofReason::SchemaFloor);
4788 }
4789 if self
4790 .conn
4791 .execute_batch("SAVEPOINT syncular_base_proof")
4792 .is_err()
4793 {
4794 return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
4795 }
4796 let proof = (|| {
4797 let snapshot = snapshot_read_connection(
4798 &self.conn,
4799 &SnapshotReadRequest {
4800 units: prepared.units.iter().map(|unit| unit.id.clone()).collect(),
4801 commit_ids: vec![prepared.client_commit_id.clone()],
4802 ..Default::default()
4803 },
4804 )
4805 .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4806 let current = self
4807 .commit_outcome(&prepared.client_commit_id)
4808 .map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4809 let unavailable = if report.revoked.is_empty() {
4810 CurrentBaseProofReason::OutcomeUnavailable
4811 } else {
4812 CurrentBaseProofReason::Revoked
4813 };
4814 let Some(outcome) = current else {
4815 return Err(unavailable);
4816 };
4817 if !matches!(
4818 snapshot.deliveries.first(),
4819 Some(CommitDelivery::Known { .. })
4820 ) || outcome.sequence != prepared.sequence
4821 || outcome.resolution != CommitOutcomeResolution::Active
4822 || !matches!(
4823 outcome.status,
4824 CommitOutcomeStatus::Conflict | CommitOutcomeStatus::Rejected
4825 )
4826 {
4827 return Err(unavailable);
4828 }
4829 let (Some(operations), Some(rows)) = (outcome.operations, outcome.retained_rows) else {
4830 return Err(unavailable);
4831 };
4832 if rows.is_empty() || operations.len() != rows.len() {
4833 return Err(unavailable);
4834 }
4835 let after =
4836 load_units(&self.conn).map_err(|_| CurrentBaseProofReason::SnapshotFailed)?;
4837 let complete: HashSet<&str> = snapshot
4838 .units
4839 .iter()
4840 .filter_map(|unit| match unit {
4841 UnitCatchup::Known {
4842 id,
4843 bootstrap_complete: true,
4844 ..
4845 } => Some(id.as_str()),
4846 _ => None,
4847 })
4848 .collect();
4849 let candidates: Vec<&UnitRecord> = after
4852 .iter()
4853 .filter(|unit| {
4854 complete.contains(unit.id.as_str())
4855 && prepared.units.iter().any(|before| before.id == unit.id)
4856 })
4857 .collect();
4858 let covered = |table_name: &str, row: &Map<String, Value>| {
4859 let Some(table) = self.schema.table(table_name) else {
4860 return false;
4861 };
4862 candidates.iter().any(|unit| {
4863 covers(table, &unit.scopes)
4864 && pair_scopes(&unit.scopes, table_name, unit.echo.as_deref()).is_some_and(
4865 |scopes| {
4866 scopes.iter().all(|(variable, allowed)| {
4867 table
4868 .scope_column(variable)
4869 .and_then(|column| match row.get(column) {
4870 Some(Value::String(value)) => Some(value.clone()),
4871 Some(Value::Bool(value)) => Some(value.to_string()),
4872 Some(Value::Number(value)) => {
4873 value.as_f64().map(|number| {
4874 ryu_js::Buffer::new()
4875 .format_finite(number)
4876 .to_owned()
4877 })
4878 }
4879 _ => None,
4880 })
4881 .is_some_and(|value| {
4882 !value.is_empty() && allowed.contains(&value)
4883 })
4884 })
4885 },
4886 )
4887 })
4888 };
4889 for row in &rows {
4890 let Some(base) = row.server_row.as_ref().or(row.local_row.as_ref()) else {
4891 return Err(if report.revoked.is_empty() {
4892 CurrentBaseProofReason::MissingCoverage
4893 } else {
4894 CurrentBaseProofReason::Revoked
4895 });
4896 };
4897 if !covered(&row.table, base)
4898 || row
4899 .unique_conflicts
4900 .iter()
4901 .any(|conflict| !covered(&row.table, &conflict.server_row))
4902 {
4903 return Err(if report.revoked.is_empty() {
4904 CurrentBaseProofReason::MissingCoverage
4905 } else {
4906 CurrentBaseProofReason::Revoked
4907 });
4908 }
4909 }
4910 Ok(rows)
4911 })();
4912 if self
4913 .conn
4914 .execute_batch("RELEASE syncular_base_proof")
4915 .is_err()
4916 {
4917 return CurrentBaseProof::failure(CurrentBaseProofReason::SnapshotFailed);
4918 }
4919 match proof {
4920 Ok(rows) => CurrentBaseProof {
4921 proven: true,
4922 rows: Some(rows),
4923 reason: None,
4924 },
4925 Err(reason) => CurrentBaseProof::failure(reason),
4926 }
4927 }
4928
4929 pub fn prove_current_base(
4930 &mut self,
4931 transport: &mut dyn Transport,
4932 client_commit_id: &str,
4933 sequence: i64,
4934 max_rounds: Option<u32>,
4935 ) -> CurrentBaseProof {
4936 let prepared = match self.prepare_current_base(client_commit_id, sequence) {
4937 Ok(prepared) => prepared,
4938 Err(proof) => return proof,
4939 };
4940 let drive = self.sync_until_idle(transport, max_rounds);
4941 self.finish_current_base(prepared, drive)
4942 }
4943
4944 pub fn commit_outcomes(&self, query: CommitOutcomeQuery) -> Result<Vec<CommitOutcome>, String> {
4945 if query.limit == Some(0) {
4946 return Err("sync.invalid_request: commit outcome limit must be positive".to_owned());
4947 }
4948 let mut sql = String::from(
4949 "SELECT seq, client_commit_id, status, recorded_at_ms, results_json, operations_json,
4950 resolution, resolved_at_ms, replacement_client_commit_id
4951 FROM _syncular_commit_outcomes",
4952 );
4953 if query.active_only {
4954 sql.push_str(" WHERE resolution = 'active' AND status IN ('conflict', 'rejected')");
4955 }
4956 sql.push_str(" ORDER BY seq DESC");
4957 if let Some(limit) = query.limit {
4958 sql.push_str(&format!(" LIMIT {limit}"));
4959 }
4960 let mut stmt = self
4961 .conn
4962 .prepare(&sql)
4963 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4964 let rows = stmt
4965 .query_map([], |row| {
4966 Ok(StoredCommitOutcomeRow {
4967 sequence: row.get(0)?,
4968 client_commit_id: row.get(1)?,
4969 status: row.get(2)?,
4970 recorded_at_ms: row.get(3)?,
4971 results_json: row.get(4)?,
4972 operations_json: row.get(5)?,
4973 resolution: row.get(6)?,
4974 resolved_at_ms: row.get(7)?,
4975 replacement_client_commit_id: row.get(8)?,
4976 })
4977 })
4978 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
4979 let mut outcomes = Vec::new();
4980 for row in rows {
4981 outcomes.push(self.attach_retained_rows(Self::outcome_from_row(
4982 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
4983 )?)?);
4984 }
4985 Ok(outcomes)
4986 }
4987
4988 fn prune_commit_outcomes(&self) -> Result<(), String> {
4989 #[cfg(test)]
4990 self.outcome_prune_count
4991 .set(self.outcome_prune_count.get() + 1);
4992 let max_entries = self.limits.outcome_retention_max_entries.unwrap_or(1_000);
4993 let count = self
4994 .conn
4995 .query_row(
4996 "SELECT COUNT(*) FROM _syncular_commit_outcomes",
4997 [],
4998 |row| row.get::<_, i64>(0),
4999 )
5000 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5001 as usize;
5002 let excess = count.saturating_sub(max_entries);
5003 if excess == 0 {
5004 return Ok(());
5005 }
5006 let mut stmt = self
5007 .conn
5008 .prepare(
5009 "SELECT seq FROM _syncular_commit_outcomes
5010 WHERE status IN ('applied', 'cached') OR resolution != 'active'
5011 ORDER BY seq ASC LIMIT ?1",
5012 )
5013 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5014 let rows = stmt
5015 .query_map(rusqlite::params![excess as i64], |row| row.get::<_, i64>(0))
5016 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5017 let sequences = rows
5018 .collect::<Result<Vec<_>, _>>()
5019 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5020 drop(stmt);
5021 for sequence in sequences {
5022 self.conn
5023 .execute(
5024 "DELETE FROM _syncular_commit_outcomes WHERE seq = ?1",
5025 rusqlite::params![sequence],
5026 )
5027 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5028 }
5029 Ok(())
5030 }
5031
5032 pub fn units(&self) -> Result<Vec<UnitRecord>, String> {
5036 self.stored(load_units(&self.conn))
5037 }
5038
5039 pub fn unit(&self, id: &str) -> Result<Option<UnitRecord>, String> {
5040 self.stored(get_unit(&self.conn, id))
5041 }
5042
5043 pub fn subscribe(&mut self, scopes: UnitScopes) -> Result<String, String> {
5045 Ok(self.subscribe_many(vec![scopes])?.remove(0))
5046 }
5047
5048 pub fn subscribe_many(&mut self, units: Vec<UnitScopes>) -> Result<Vec<String>, String> {
5055 self.begin_observation("syncular_subscribe")?;
5056 let mut changed = false;
5057 let registered = (|| {
5058 let mut ids = Vec::with_capacity(units.len());
5059 for scopes in units {
5060 let (id, held) = self.hold_unit(scopes, true)?;
5061 changed |= held;
5062 ids.push(id);
5063 }
5064 self.conn
5065 .execute_batch("RELEASE syncular_subscribe")
5066 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5067 Ok(ids)
5068 })();
5069 let ids = match registered {
5070 Ok(ids) => ids,
5071 Err(error) => {
5072 self.rollback_observation("syncular_subscribe");
5073 return Err(error);
5074 }
5075 };
5076 if changed {
5077 self.registration_epoch = self.registration_epoch.wrapping_add(1);
5078 self.set_sync_needed(true, true);
5079 }
5080 Ok(ids)
5081 }
5082
5083 pub fn unsubscribe(&mut self, id: &str) -> Result<(), String> {
5086 let Some(unit) = self.stored(get_unit(&self.conn, id))? else {
5087 return Ok(());
5088 };
5089 if !unit.explicit {
5090 return Ok(());
5091 }
5092 if !self.stored(window_refs(&self.conn, id))?.is_empty() {
5093 return self.stored(save_unit(
5094 &self.conn,
5095 &UnitRecord {
5096 explicit: false,
5097 ..unit
5098 },
5099 ));
5100 }
5101 self.conn
5102 .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5103 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5104 self.registration_epoch = self.registration_epoch.wrapping_add(1);
5105 if unit.status == UnitStatus::Active {
5106 self.set_sync_needed(true, true);
5107 }
5108 Ok(())
5109 }
5110
5111 fn hold_unit(&mut self, scopes: UnitScopes, explicit: bool) -> Result<(String, bool), String> {
5115 if scopes.is_empty()
5116 || scopes.values().any(|value| value == "*")
5117 || !self
5118 .schema
5119 .tables
5120 .iter()
5121 .any(|table| covers(table, &scopes))
5122 {
5123 return Err("sync.invalid_subscription: a unit names one non-wildcard value per variable and covers a table".to_owned());
5124 }
5125 let id = ssp2::registration::unit_id(&scope_pairs(&scopes));
5126 let existing = self.stored(get_unit(&self.conn, &id))?;
5127 if let Some(existing) = existing
5128 .as_ref()
5129 .filter(|unit| unit.status != UnitStatus::Revoked)
5130 {
5131 if explicit && !existing.explicit {
5132 self.stored(save_unit(
5133 &self.conn,
5134 &UnitRecord {
5135 explicit,
5136 ..existing.clone()
5137 },
5138 ))?;
5139 }
5140 return Ok((id, false));
5141 }
5142 self.delete_pending_evict(&id)?;
5143 self.stored(save_unit(
5144 &self.conn,
5145 &UnitRecord {
5146 id: id.clone(),
5147 scopes,
5148 explicit: explicit || existing.is_some_and(|unit| unit.explicit),
5149 status: UnitStatus::Active,
5150 reason_code: None,
5151 cursor: Some(-1),
5152 bootstrap_state: None,
5153 seeded: Vec::new(),
5154 echo: None,
5155 },
5156 ))?;
5157 Ok((id, true))
5158 }
5159
5160 pub fn set_window(
5168 &mut self,
5169 base: &WindowBase,
5170 units: &[String],
5171 ) -> Result<CommandEffects, String> {
5172 let base_key = window_base_key(base);
5173 let live = self.load_window_units(&base_key)?;
5174 let mut changed = false;
5175 for value in units {
5176 if live.iter().any(|(held, _)| held == value) {
5177 continue;
5178 }
5179 let rollback = self.capture();
5180 self.begin_observation("syncular_window")?;
5181 let widened = (|| {
5182 let (id, registered) = self.hold_unit(window_unit_scopes(base, value), false)?;
5183 self.sync_needed |= registered;
5184 self.conn
5185 .execute(
5186 "INSERT OR REPLACE INTO _syncular_windows(base, unit, sub_id) VALUES (?1, ?2, ?3)",
5187 rusqlite::params![base_key, value, id],
5188 )
5189 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5190 let mut batch = ChangeAccumulator::default();
5191 batch.window(&base_key, value);
5192 batch.status = true;
5193 self.finish_observation("syncular_window", batch)
5194 })();
5195 if let Err(error) = widened {
5196 self.rollback_observation("syncular_window");
5197 self.restore(rollback);
5198 return Err(error);
5199 }
5200 changed = true;
5201 self.registration_epoch = self.registration_epoch.wrapping_add(1);
5202 }
5203 for (value, id) in live {
5204 if units.contains(&value) {
5205 continue;
5206 }
5207 self.rebuild_overlay_if_dirty()?;
5208 let rollback = self.capture();
5209 self.begin_observation("syncular_window")?;
5210 let remaining = self.release_window_unit(&base_key, &value, &id);
5211 let remaining = match remaining {
5212 Ok(remaining) => remaining,
5213 Err(error) => {
5214 self.rollback_observation("syncular_window");
5215 self.restore(rollback);
5216 return Err(error);
5217 }
5218 };
5219 changed = true;
5220 self.registration_epoch = self.registration_epoch.wrapping_add(1);
5221 if remaining {
5222 self.drain_pending_evictions()?;
5223 }
5224 }
5225 Ok(if changed && self.transport_enabled {
5226 CommandEffects::interactive()
5227 } else {
5228 CommandEffects::none()
5229 })
5230 }
5231
5232 pub fn window_state(&self, base: &WindowBase) -> Result<WindowState, String> {
5236 persisted_window_state(&self.conn, base).map_err(|failure| failure.message)
5237 }
5238
5239 fn load_window_units(&self, base_key: &str) -> Result<Vec<(String, String)>, String> {
5241 let mut statement = self
5242 .conn
5243 .prepare_cached(
5244 "SELECT unit, sub_id FROM _syncular_windows WHERE base = ?1 ORDER BY unit ASC",
5245 )
5246 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5247 let rows = statement
5248 .query_map([base_key], |row| Ok((row.get(0)?, row.get(1)?)))
5249 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5250 rows.collect::<Result<_, _>>()
5251 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5252 }
5253
5254 fn load_window_registry(&self) -> Result<Vec<(String, String)>, String> {
5256 let mut statement = self
5257 .conn
5258 .prepare_cached("SELECT base, unit FROM _syncular_windows ORDER BY base, unit")
5259 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5260 let rows = statement
5261 .query_map([], |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 release_window_unit(
5275 &mut self,
5276 base_key: &str,
5277 value: &str,
5278 id: &str,
5279 ) -> Result<bool, String> {
5280 self.conn
5281 .execute(
5282 "DELETE FROM _syncular_windows WHERE base = ?1 AND unit = ?2",
5283 rusqlite::params![base_key, value],
5284 )
5285 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5286 let mut batch = ChangeAccumulator::default();
5287 batch.window(base_key, value);
5288 batch.status = true;
5289 let unit = self.stored(get_unit(&self.conn, id))?;
5290 let mut remaining = false;
5291 if let Some(unit) = unit.filter(|unit| !unit.explicit) {
5292 if self.stored(window_refs(&self.conn, id))?.is_empty() {
5293 let units = self.stored(load_units(&self.conn))?;
5294 self.conn
5295 .execute("DELETE FROM _syncular_units WHERE id = ?1", [id])
5296 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5297 self.sync_needed = true;
5298 for table in self.schema.tables.clone() {
5299 let Some(effective) = unit
5300 .echo
5301 .as_deref()
5302 .filter(|_| covers(&table, &unit.scopes))
5303 .and_then(|echo| pair_scopes(&unit.scopes, &table.name, Some(echo)))
5304 else {
5305 continue;
5306 };
5307 let pinned = self.pinned_row_ids(&table.name);
5308 let owners = unit_owners(&units, &table, id);
5309 let (more, deferred) =
5310 self.evict_scope_rows(&table.name, &effective, &owners, &pinned)?;
5311 remaining |= more;
5312 if deferred {
5313 self.save_pending_evict(id, &table.name, &effective)?;
5314 }
5315 self.record_scope_map(&mut batch, &table.name, &effective);
5316 }
5317 }
5318 }
5319 self.finish_observation("syncular_window", batch)?;
5320 Ok(remaining)
5321 }
5322
5323 fn evict_scope_rows(
5328 &self,
5329 table_name: &str,
5330 effective: &[(String, Vec<String>)],
5331 owners: &[Vec<(String, Vec<String>)>],
5332 pinned: &std::collections::HashSet<String>,
5333 ) -> Result<(bool, bool), String> {
5334 let table = self.schema.table(table_name).ok_or("sync.unknown_table")?;
5335 let Some((scope, mut params)) = local_scope_predicate(table, effective, owners)
5336 .map_err(|()| "sync.scope_revoked".to_owned())?
5337 else {
5338 return Ok((false, false));
5339 };
5340 let scope_params = params.len();
5341 let pk = quote_ident(&table.primary_key);
5342 let predicate = if pinned.is_empty() {
5344 scope.clone()
5345 } else {
5346 params.extend(pinned.iter().cloned().map(SqlValue::Text));
5347 let holes = vec!["?"; pinned.len()].join(", ");
5348 format!("{scope} AND CAST({pk} AS TEXT) NOT IN ({holes})")
5349 };
5350 let base = base_table(table_name);
5351 let visible = visible_table(table_name);
5352 let mut ids: Vec<SqlValue> = Vec::new();
5353 for source in [&base, &visible] {
5354 let mut stmt = self
5355 .conn
5356 .prepare_cached(&format!(
5357 "SELECT {pk} FROM {source} WHERE {predicate} LIMIT 1024"
5358 ))
5359 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5360 ids = stmt
5361 .query_map(rusqlite::params_from_iter(¶ms), |row| row.get(0))
5362 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
5363 .collect::<Result<_, _>>()
5364 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5365 if !ids.is_empty() {
5366 break;
5367 }
5368 }
5369 if !ids.is_empty() {
5370 for id in &ids {
5371 self.conn
5372 .execute(
5373 "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2",
5374 rusqlite::params![table_name, id],
5375 )
5376 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5377 }
5378 let holes = vec!["?"; ids.len()].join(", ");
5379 for source in [&base, &visible] {
5380 self.conn
5381 .execute(
5382 &format!("DELETE FROM {source} WHERE {pk} IN ({holes})"),
5383 rusqlite::params_from_iter(&ids),
5384 )
5385 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5386 }
5387 }
5388 let mut remaining = false;
5389 let mut deferred = false;
5390 for source in [&base, &visible] {
5391 remaining |= self
5392 .conn
5393 .query_row(
5394 &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {predicate})"),
5395 rusqlite::params_from_iter(¶ms),
5396 |row| row.get::<_, bool>(0),
5397 )
5398 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5399 deferred |= self
5400 .conn
5401 .query_row(
5402 &format!("SELECT EXISTS(SELECT 1 FROM {source} WHERE {scope})"),
5403 rusqlite::params_from_iter(¶ms[..scope_params]),
5404 |row| row.get::<_, bool>(0),
5405 )
5406 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5407 }
5408 Ok((remaining, deferred))
5409 }
5410
5411 fn drain_pending_evictions(&mut self) -> Result<(), String> {
5415 let pending = self.load_pending_evictions()?;
5416 if pending.is_empty() {
5417 return Ok(());
5418 }
5419 self.rebuild_overlay_if_dirty()?;
5420 for (unit_id, table_name, effective) in pending {
5421 let Some(table) = self.schema.table(&table_name).cloned() else {
5422 self.delete_pending_evict_table(&unit_id, &table_name)?;
5423 continue;
5424 };
5425 loop {
5426 std::thread::yield_now();
5427 self.begin_observation("syncular_evict")?;
5428 let chunk = (|| {
5429 let pinned = self.pinned_row_ids(&table_name);
5430 let owners =
5431 unit_owners(&self.stored(load_units(&self.conn))?, &table, &unit_id);
5432 let (remaining, deferred) =
5433 self.evict_scope_rows(&table_name, &effective, &owners, &pinned)?;
5434 if !deferred {
5435 self.delete_pending_evict_table(&unit_id, &table_name)?;
5436 }
5437 let mut batch = ChangeAccumulator::default();
5438 self.record_scope_map(&mut batch, &table_name, &effective);
5439 self.finish_observation("syncular_evict", batch)?;
5440 Ok(remaining)
5441 })();
5442 match chunk {
5443 Ok(true) => {}
5444 Ok(false) => break,
5445 Err(error) => {
5446 self.rollback_observation("syncular_evict");
5447 return Err(error);
5448 }
5449 }
5450 }
5451 }
5452 Ok(())
5453 }
5454
5455 fn pinned_row_ids(&self, table: &str) -> std::collections::HashSet<String> {
5458 let mut pinned = std::collections::HashSet::new();
5459 for commit in self
5460 .outbox
5461 .iter()
5462 .map(|commit| &**commit)
5463 .chain(self.failed_commits.iter().map(|(commit, _)| commit))
5464 {
5465 for op in &commit.ops {
5466 if op.table == table {
5467 pinned.insert(op.row_id.clone());
5468 }
5469 }
5470 }
5471 pinned
5472 }
5473
5474 fn save_pending_evict(
5475 &self,
5476 unit_id: &str,
5477 table: &str,
5478 effective: &[(String, Vec<String>)],
5479 ) -> Result<(), String> {
5480 self.conn.execute(
5481 "INSERT OR REPLACE INTO _syncular_pending_evictions(unit_id, tbl, effective_scopes) VALUES (?1, ?2, ?3)",
5482 rusqlite::params![unit_id, table, scope_map_to_json(effective).to_string()],
5483 ).map(|_| ()).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5484 }
5485
5486 fn delete_pending_evict(&self, unit_id: &str) -> Result<(), String> {
5488 self.conn
5489 .execute(
5490 "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1",
5491 [unit_id],
5492 )
5493 .map(|_| ())
5494 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5495 }
5496
5497 fn delete_pending_evict_table(&self, unit_id: &str, table: &str) -> Result<(), String> {
5498 self.conn
5499 .execute(
5500 "DELETE FROM _syncular_pending_evictions WHERE unit_id = ?1 AND tbl = ?2",
5501 [unit_id, table],
5502 )
5503 .map(|_| ())
5504 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
5505 }
5506
5507 fn load_pending_evictions(&self) -> Result<Vec<PendingEvict>, String> {
5508 let mut stmt = self
5509 .conn
5510 .prepare("SELECT unit_id, tbl, effective_scopes FROM _syncular_pending_evictions")
5511 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5512 let rows = stmt
5513 .query_map([], |row| {
5514 Ok((
5515 row.get::<_, String>(0)?,
5516 row.get::<_, String>(1)?,
5517 row.get::<_, String>(2)?,
5518 ))
5519 })
5520 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5521 rows.map(|row| {
5522 let (unit_id, table, json) =
5523 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5524 let value: Value = serde_json::from_str(&json)
5525 .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5526 let effective = json_to_scope_map(&value)
5527 .map_err(|_| "sync.local_corrupt: invalid pending eviction scopes".to_owned())?;
5528 Ok((unit_id, table, effective))
5529 })
5530 .collect()
5531 }
5532
5533 pub fn set_retain_failed_commits(&mut self, enabled: bool) -> Result<(), String> {
5535 self.retain_failed_commits = enabled;
5536 for (commit, _) in self.failed_commits.iter() {
5537 for operation in &commit.ops {
5538 self.overlay_dirty.table(&operation.table);
5539 }
5540 }
5541 self.failed_commits = self.load_failed_commits()?.into();
5542 for (commit, _) in self.failed_commits.iter() {
5543 for operation in &commit.ops {
5544 self.overlay_dirty.table(&operation.table);
5545 }
5546 }
5547 Ok(())
5548 }
5549
5550 fn load_failed_commits(&self) -> Result<Vec<FailedCommit>, String> {
5551 let mut statement = self.conn.prepare("SELECT client_commit_id, operations_json, initial_json FROM _syncular_failed_commits ORDER BY seq")
5552 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5553 let rows = statement
5554 .query_map([], |row| {
5555 Ok((
5556 row.get::<_, String>(0)?,
5557 row.get::<_, String>(1)?,
5558 row.get::<_, String>(2)?,
5559 ))
5560 })
5561 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5562 rows.map(|row| {
5563 let (id, operations, initial) =
5564 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5565 let operations: Vec<CommitOperation> =
5566 serde_json::from_str(&operations).map_err(|_| "sync.local_corrupt".to_owned())?;
5567 let initial =
5568 serde_json::from_str(&initial).map_err(|_| "sync.local_corrupt".to_owned())?;
5569 Ok((
5570 OutboxCommit {
5571 client_commit_id: id,
5572 ops: operations
5573 .into_iter()
5574 .map(|op| OutboxOp {
5575 upsert: op.op == "upsert",
5576 table: op.table,
5577 row_id: op.row_id,
5578 base_version: op.base_version,
5579 values: op.values,
5580 insert: op.insert,
5581 })
5582 .collect(),
5583 },
5584 initial,
5585 ))
5586 })
5587 .collect()
5588 }
5589
5590 fn retain_failed_commit(&mut self, id: &str, operations: &[OutboxOp]) -> Result<(), String> {
5591 let mut initial = Map::new();
5592 for operation in operations {
5593 let Some(table) = self.schema.table(&operation.table) else {
5595 continue;
5596 };
5597 let initial_row = match self.stored_row(table, &operation.row_id, true)? {
5598 Some(row) => Some(row),
5599 None => self.visible_row(table, &operation.row_id)?,
5600 };
5601 if let Some((values, _)) = initial_row {
5602 let mut intended: Map<String, Value> = table
5603 .columns
5604 .iter()
5605 .zip(values.iter())
5606 .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
5607 .collect();
5608 if let Some(patch) = &operation.values {
5609 intended.extend(patch.clone());
5610 }
5611 initial.insert(
5612 serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
5613 .map_err(|_| "sync.local_corrupt".to_owned())?,
5614 Value::Object(intended),
5615 );
5616 }
5617 }
5618 self.conn.execute("INSERT INTO _syncular_failed_commits(client_commit_id, operations_json, initial_json) VALUES (?1, ?2, ?3)", rusqlite::params![id,
5619 serde_json::to_string(&operations.iter().map(CommitOperation::from).collect::<Vec<_>>()).map_err(|_| "sync.local_corrupt".to_owned())?,
5620 serde_json::to_string(&initial).map_err(|_| "sync.local_corrupt".to_owned())?])
5621 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5622 self.failed_commits.push((
5623 OutboxCommit {
5624 client_commit_id: id.to_owned(),
5625 ops: operations.to_vec(),
5626 },
5627 initial,
5628 ));
5629 Ok(())
5630 }
5631
5632 fn drop_failed_commits(
5633 &mut self,
5634 matches: impl Fn(&str, &Map<String, Value>) -> bool,
5635 ) -> Result<Vec<OutboxCommit>, String> {
5636 let mut doomed = self.drop_acknowledged_rows(&matches)?;
5637 for (commit, initial) in self.failed_commits.iter() {
5638 for operation in &commit.ops {
5639 let key =
5640 serde_json::to_string(&(operation.table.clone(), operation.row_id.clone()))
5641 .map_err(|_| "sync.local_corrupt".to_owned())?;
5642 if initial
5643 .get(&key)
5644 .and_then(Value::as_object)
5645 .is_some_and(|values| matches(&operation.table, values))
5646 {
5647 doomed.push(commit.clone());
5648 break;
5649 }
5650 }
5651 }
5652 for commit in &doomed {
5653 self.conn
5654 .execute(
5655 "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
5656 rusqlite::params![commit.client_commit_id],
5657 )
5658 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5659 }
5660 for commit in &doomed {
5661 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))?;
5662 }
5663 self.conflicts.retain(|record| {
5664 !doomed
5665 .iter()
5666 .any(|commit| commit.client_commit_id == record.client_commit_id)
5667 });
5668 self.rejections.retain(|record| {
5669 !doomed
5670 .iter()
5671 .any(|commit| commit.client_commit_id == record.client_commit_id)
5672 });
5673 self.failed_commits.retain(|(commit, _)| {
5674 !doomed
5675 .iter()
5676 .any(|dropped| dropped.client_commit_id == commit.client_commit_id)
5677 });
5678 for commit in &doomed {
5679 for operation in &commit.ops {
5680 self.overlay_dirty.table(&operation.table);
5681 }
5682 }
5683 Ok(doomed)
5684 }
5685
5686 pub fn mutate(&mut self, mutations: Vec<Mutation>) -> Result<String, ClientError> {
5690 let prior = self.storage_failure.borrow_mut().take();
5691 let outcome = (|| -> Result<String, String> {
5692 if mutations.is_empty() {
5693 return Err(
5694 "sync.invalid_request: a commit must contain at least one operation (§6.1)"
5695 .to_owned(),
5696 );
5697 }
5698 let mut ops = Vec::with_capacity(mutations.len());
5699 for mutation in mutations {
5700 match mutation {
5701 Mutation::Patch {
5702 table,
5703 values,
5704 base_version,
5705 } => {
5706 let schema_table = self
5707 .schema
5708 .table(&table)
5709 .ok_or_else(|| "sync.unknown_table".to_owned())?;
5710 let values = normalize_values_casing(schema_table, values)?;
5711 let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
5712 ops.push(self.prepare_patch(&table, &row_id, values, base_version)?);
5713 }
5714 Mutation::Upsert {
5715 table,
5716 values,
5717 base_version,
5718 } => {
5719 let schema_table = self.schema.table(&table).ok_or_else(|| {
5720 format!("sync.unknown_table: unknown table {table:?}")
5721 })?;
5722 let values = normalize_values_casing(schema_table, values)?;
5726 let row_id = render_row_id_json(values.get(&schema_table.primary_key))?;
5727 let values = full_row_values(schema_table, values)?;
5730 self.validate_author_encode(schema_table, &row_id, &values)?;
5736 let insert = !self.visible_row_exists(schema_table, &row_id)?;
5740 ops.push(OutboxOp {
5741 upsert: true,
5742 table,
5743 row_id,
5744 base_version,
5745 values: Some(values),
5746 insert,
5747 });
5748 }
5749 Mutation::Delete {
5750 table,
5751 row_id,
5752 base_version,
5753 } => {
5754 if self.schema.table(&table).is_none() {
5755 return Err(format!("sync.unknown_table: unknown table {table:?}"));
5756 }
5757 if row_id.contains('\0') {
5759 return Err(
5760 "sync.invalid_request: rowId holds U+0000 (§2.4)".to_owned()
5761 );
5762 }
5763 ops.push(OutboxOp {
5764 upsert: false,
5765 table,
5766 row_id,
5767 base_version,
5768 values: None,
5769 insert: false,
5770 });
5771 }
5772 }
5773 }
5774 self.record_outbox_commit(ops)
5775 })();
5776 self.finish_authoring(prior, outcome)
5777 }
5778
5779 fn finish_authoring(
5785 &self,
5786 prior: Option<QueryReadFailure>,
5787 outcome: Result<String, String>,
5788 ) -> Result<String, ClientError> {
5789 let fresh = self.storage_failure.borrow_mut().take();
5790 *self.storage_failure.borrow_mut() = fresh.clone().or(prior);
5791 match outcome {
5792 Ok(id) => Ok(id),
5793 Err(message) => Err(fresh
5794 .map(ClientError::from)
5795 .unwrap_or_else(|| ClientError::from(message))),
5796 }
5797 }
5798
5799 fn record_outbox_commit(&mut self, ops: Vec<OutboxOp>) -> Result<String, String> {
5800 let commit = OutboxCommit {
5801 client_commit_id: uuid::Uuid::new_v4().to_string(),
5802 ops,
5803 };
5804 self.begin_observation("syncular_mutation")?;
5805 let mut batch = ChangeAccumulator::default();
5806 for op in &commit.ops {
5807 let mut precise = self.record_row_scopes(&mut batch, &op.table, &op.row_id, false);
5808 if let Some(values) = &op.values {
5809 if let Some(table) = self.schema.table(&op.table) {
5810 for scope in &table.scope_variables {
5811 if let Some(Value::String(value)) = values.get(&scope.column) {
5812 batch.scope(&op.table, format!("{}:{value}", scope.prefix));
5813 precise = true;
5814 }
5815 }
5816 }
5817 }
5818 if !precise {
5819 batch.table(&op.table);
5820 }
5821 }
5822 if let Err(error) = self.persist_outbox_insert(&commit) {
5823 self.rollback_observation("syncular_mutation");
5824 return Err(error);
5825 }
5826 let was_dirty = self.overlay_dirty.snapshot();
5832 let id = commit.client_commit_id.clone();
5833 let appended = self.rebuild_overlay_if_dirty().and_then(|()| {
5834 commit
5835 .ops
5836 .iter()
5837 .try_for_each(|op| self.apply_outbox_op(op))?;
5838 self.outbox.push(Arc::new(commit));
5839 batch.status = true;
5840 self.finish_observation("syncular_mutation", batch)
5841 .inspect_err(|_| drop(self.outbox.pop()))
5842 });
5843 if let Err(error) = appended {
5844 self.rollback_observation("syncular_mutation");
5845 self.overlay_dirty.restore(was_dirty);
5846 return Err(error);
5847 }
5848 Ok(id)
5849 }
5850
5851 pub fn patch(
5857 &mut self,
5858 table: &str,
5859 row_id: &str,
5860 partial: Map<String, Value>,
5861 base_version: Option<i64>,
5862 ) -> Result<String, ClientError> {
5863 let prior = self.storage_failure.borrow_mut().take();
5864 let outcome = self.perform_patch(table, row_id, partial, base_version);
5865 self.finish_authoring(prior, outcome)
5866 }
5867
5868 fn perform_patch(
5871 &mut self,
5872 table: &str,
5873 row_id: &str,
5874 partial: Map<String, Value>,
5875 base_version: Option<i64>,
5876 ) -> Result<String, String> {
5877 let operation = self.prepare_patch(table, row_id, partial, base_version)?;
5878 self.record_outbox_commit(vec![operation])
5879 }
5880
5881 fn prepare_patch(
5882 &self,
5883 table: &str,
5884 row_id: &str,
5885 partial: Map<String, Value>,
5886 base_version: Option<i64>,
5887 ) -> Result<OutboxOp, String> {
5888 let schema_table = self
5889 .schema
5890 .table(table)
5891 .ok_or_else(|| format!("sync.unknown_table: unknown table {table:?}"))?;
5892 let partial = normalize_values_casing(schema_table, partial)?;
5893 if let Some(pk) = partial.get(&schema_table.primary_key) {
5894 if render_row_id_json(Some(pk)).ok().as_deref() != Some(row_id) {
5895 return Err(format!(
5896 "sync.invalid_request: table {table:?}: patch cannot change the primary key"
5897 ));
5898 }
5899 }
5900 if !self.visible_row_exists(schema_table, row_id)? {
5901 return Err("sync.row_missing: a sparse patch requires a local row".to_owned());
5902 }
5903 for scope in &schema_table.scope_variables {
5913 if !partial.contains_key(&scope.column) || scope.column == schema_table.primary_key {
5914 continue;
5915 }
5916 let Some(column) = schema_table
5917 .columns
5918 .iter()
5919 .find(|column| column.name == scope.column)
5920 else {
5921 continue;
5922 };
5923 let stored = self
5924 .conn
5925 .query_row(
5926 &format!(
5927 "SELECT {} FROM {} WHERE {}",
5928 quote_ident(&scope.column),
5929 visible_table(&schema_table.name),
5930 row_id_predicate(schema_table)
5931 ),
5932 rusqlite::params![row_id],
5933 |row| Ok(sql_ref_to_json(column, row.get_ref(0)?)),
5934 )
5935 .optional()
5936 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
5937 let incoming = json_to_column_value(column, partial.get(&scope.column))
5942 .ok()
5943 .map(|value| column_value_to_json(&value));
5944 let equal = stored.as_ref().is_some_and(|stored| {
5948 stored.get("$bytes").is_none() && incoming.as_ref() == Some(stored)
5949 });
5950 if !equal {
5951 return Err(format!(
5952 "sync.invalid_request: table {table:?}: patch cannot write scope column {:?} (§3.4)",
5953 scope.column
5954 ));
5955 }
5956 }
5957 let mut values = partial;
5958 for scope in &schema_table.scope_variables {
5961 values.remove(&scope.column);
5962 }
5963 let pk_value = match schema_table.columns[schema_table.pk_index].ty {
5964 ColumnType::Integer => match row_id.parse::<i64>() {
5966 Ok(v)
5967 if v.to_string() == row_id
5968 && (-ssp2::primitives::I64_SAFE_MAX..=ssp2::primitives::I64_SAFE_MAX)
5969 .contains(&v) =>
5970 {
5971 Value::from(v)
5972 }
5973 _ => {
5974 return Err(format!(
5975 "sync.invalid_request: table {table:?}: invalid integer primary key {row_id:?}"
5976 ))
5977 }
5978 },
5979 ColumnType::Boolean => match row_id {
5980 "true" => Value::Bool(true),
5981 "false" => Value::Bool(false),
5982 _ => {
5983 return Err(format!(
5984 "sync.invalid_request: table {table:?}: invalid boolean primary key {row_id:?}"
5985 ))
5986 }
5987 },
5988 _ => Value::from(row_id.to_owned()),
5989 };
5990 values.insert(schema_table.primary_key.clone(), pk_value);
5991 self.validate_author_encode(schema_table, row_id, &values)?;
5997 Ok(OutboxOp {
5998 upsert: true,
5999 table: table.to_owned(),
6000 row_id: row_id.to_owned(),
6001 base_version,
6002 values: Some(values),
6003 insert: false,
6004 })
6005 }
6006
6007 fn stored_key_fallback(
6012 &self,
6013 table: &TableSchema,
6014 row_id: &str,
6015 ) -> Result<Option<Row>, String> {
6016 let Some(selector) = self.encryption.key_id_columns.get(&table.name) else {
6017 return Ok(None);
6018 };
6019 let Some(index) = table
6020 .columns
6021 .iter()
6022 .position(|column| &column.name == selector)
6023 else {
6024 return Ok(None);
6025 };
6026 let sql = format!(
6027 "SELECT {} FROM {} WHERE {}",
6028 quote_ident(selector),
6029 visible_table(&table.name),
6030 row_id_predicate(table)
6031 );
6032 let key = self
6033 .conn
6034 .query_row(&sql, rusqlite::params![row_id], |row| {
6035 row.get::<_, Option<String>>(0)
6036 })
6037 .optional()
6038 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6039 .flatten()
6040 .filter(|key| !key.is_empty());
6041 let Some(key) = key else {
6042 return Ok(None);
6043 };
6044 let mut fallback: Row = vec![None; table.columns.len()];
6045 fallback[index] = Some(ColumnValue::String(key));
6046 Ok(Some(fallback))
6047 }
6048
6049 fn validate_author_encode(
6054 &self,
6055 table: &TableSchema,
6056 row_id: &str,
6057 values: &Map<String, Value>,
6058 ) -> Result<(), String> {
6059 match encode_sparse_row_json(table, row_id, values, &self.encryption, None) {
6060 Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => Ok(()),
6061 result => result.map(|_| ()),
6062 }
6063 }
6064
6065 fn drop_unencodable_outbox(
6079 &mut self,
6080 with_encryption: bool,
6081 batch: Option<&mut ChangeAccumulator>,
6082 ) -> Result<bool, String> {
6083 let mut failures = Vec::new();
6084 for commit in self.outbox.iter() {
6085 for op in &commit.ops {
6086 let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6087 continue;
6088 };
6089 let Some(values) = op.presented_values(table) else {
6092 continue;
6093 };
6094 let fallback = self.stored_key_fallback(table, &op.row_id)?;
6095 let failure = match encode_sparse_row_json(
6096 table,
6097 &op.row_id,
6098 &values,
6099 &self.encryption,
6100 fallback.as_ref(),
6101 ) {
6102 Err(error) if error.starts_with(ENCRYPT_FAILED_CODE) => {
6103 with_encryption.then_some((error, ENCRYPT_FAILED_CODE))
6104 }
6105 Err(error) if error.starts_with(INVALID_REQUEST_CODE) => Some((
6110 LEGACY_VALUE_REFUSAL_MESSAGE.to_owned(),
6111 OUTBOX_INCOMPATIBLE_CODE,
6112 )),
6113 _ => None,
6114 };
6115 if let Some((error, code)) = failure {
6116 failures.push((commit.clone(), error, code));
6117 break;
6118 }
6119 }
6120 }
6121 if failures.is_empty() {
6122 return Ok(false);
6123 }
6124 let rollback = self.capture();
6130 let owns_observation = batch.is_none();
6131 let owns_transaction = self.conn.is_autocommit();
6132 let mut domains = ChangeAccumulator::default();
6133 if owns_observation {
6134 self.begin_observation("syncular_value_recovery")?;
6135 }
6136 let dropped = (|| -> Result<(), String> {
6137 for (commit, message, code) in failures {
6138 if self.retain_failed_commits && code == ENCRYPT_FAILED_CODE {
6139 self.retain_failed_commit(&commit.client_commit_id, &commit.ops)?;
6140 }
6141 let representable = commit.ops.iter().all(Self::outbox_op_is_journalable);
6142 let rejection = RejectionRecord {
6143 client_commit_id: commit.client_commit_id.clone(),
6144 op_index: 0,
6145 code: code.to_owned(),
6146 message,
6147 retryable: false,
6148 details: (code == OUTBOX_INCOMPATIBLE_CODE).then(|| RejectionDetails {
6149 field_paths: None,
6150 reason: Some(INVALID_STORED_VALUES_REASON.to_owned()),
6151 required_action: None,
6152 references: None,
6153 }),
6154 operation: representable
6155 .then(|| commit.ops.first())
6156 .flatten()
6157 .map(CommitOperation::from),
6158 };
6159 self.persist_commit_outcome(
6160 &commit.client_commit_id,
6161 CommitOutcomeStatus::Rejected,
6162 &[CommitOperationOutcome::Error {
6163 rejection: rejection.clone(),
6164 }],
6165 representable.then_some(commit.ops.as_slice()),
6166 )?;
6167 self.delete_outbox_persisted(&commit.client_commit_id)?;
6168 self.outbox
6169 .retain(|candidate| candidate.client_commit_id != commit.client_commit_id);
6170 self.rejections.push(rejection);
6171 for operation in &commit.ops {
6172 domains.table(operation.table.as_str());
6173 }
6174 }
6175 domains.status = true;
6176 domains.rejections = true;
6177 domains.outcomes = true;
6178 self.prune_commit_outcomes()?;
6179 self.overlay_dirty.set(true);
6181 self.rebuild_overlay()?;
6182 Ok(())
6183 })();
6184 let result = match batch {
6185 Some(batch) => {
6186 if dropped.is_ok() {
6187 for table in domains.tables.keys() {
6188 batch.table(table.as_str());
6189 }
6190 batch.status |= domains.status;
6191 batch.rejections |= domains.rejections;
6192 batch.outcomes |= domains.outcomes;
6193 }
6194 dropped
6195 }
6196 None => {
6197 dropped.and_then(|()| self.finish_observation("syncular_value_recovery", domains))
6198 }
6199 };
6200 if let Err(error) = result {
6201 if owns_observation {
6202 if owns_transaction {
6203 if let Err(rollback) = self.conn.execute_batch("ROLLBACK") {
6204 let mut failure = self.storage_failure.borrow_mut();
6205 let failure =
6206 failure.get_or_insert_with(|| QueryReadFailure::from(error.clone()));
6207 failure.rollback_failure = Some(Box::new(QueryReadFailure::from(rollback)));
6208 }
6209 } else {
6210 self.rollback_observation("syncular_value_recovery");
6211 }
6212 }
6213 self.restore(rollback);
6214 return Err(error);
6215 }
6216 Ok(true)
6217 }
6218
6219 pub fn pending_commit_ids(&self) -> Vec<String> {
6220 self.outbox
6221 .iter()
6222 .map(|c| c.client_commit_id.clone())
6223 .collect()
6224 }
6225
6226 pub fn pending_payloads(&self) -> Result<Vec<Vec<u8>>, String> {
6230 let mut payloads = Vec::new();
6231 for commit in self.outbox.iter() {
6232 for op in &commit.ops {
6233 let Some(table) = self.schema.table(&op.table).filter(|_| op.upsert) else {
6234 continue;
6235 };
6236 let Some(values) = op.presented_values(table) else {
6237 continue;
6238 };
6239 let fallback = self.stored_key_fallback(table, &op.row_id)?;
6240 if let Ok(payload) = encode_sparse_row_json(
6241 table,
6242 &op.row_id,
6243 &values,
6244 &self.encryption,
6245 fallback.as_ref(),
6246 ) {
6247 payloads.push(payload);
6248 }
6249 }
6250 }
6251 Ok(payloads)
6252 }
6253
6254 pub fn conflicts(&self) -> &[ConflictRecord] {
6255 &self.conflicts
6256 }
6257
6258 pub fn rejections(&self) -> &[RejectionRecord] {
6259 &self.rejections
6260 }
6261
6262 pub fn resolve_commit_outcome(
6263 &mut self,
6264 input: ResolveCommitOutcomeInput,
6265 ) -> Result<CommitOutcome, String> {
6266 let current = self
6267 .commit_outcome(&input.client_commit_id)?
6268 .ok_or_else(|| {
6269 format!(
6270 "sync.outcome_not_found: no durable outcome exists for {:?}",
6271 input.client_commit_id
6272 )
6273 })?;
6274 if current.resolution != CommitOutcomeResolution::Active {
6275 return Ok(current);
6276 }
6277 if input.resolution == CommitOutcomeResolution::Active {
6278 return Err("sync.invalid_request: resolution must leave active state".to_owned());
6279 }
6280 match input.resolution {
6281 CommitOutcomeResolution::Superseded => {
6282 let replacement = input
6283 .replacement_client_commit_id
6284 .as_deref()
6285 .filter(|value| !value.is_empty() && *value != input.client_commit_id)
6286 .ok_or_else(|| {
6287 "sync.invalid_request: superseded outcomes require a distinct replacementClientCommitId"
6288 .to_owned()
6289 })?;
6290 let _ = replacement;
6291 }
6292 _ if input.replacement_client_commit_id.is_some() => {
6293 return Err(
6294 "sync.invalid_request: replacementClientCommitId is valid only for superseded outcomes"
6295 .to_owned(),
6296 );
6297 }
6298 _ => {}
6299 }
6300 let allowed = match current.status {
6301 CommitOutcomeStatus::Conflict => matches!(
6302 input.resolution,
6303 CommitOutcomeResolution::ResolvedKeepServer | CommitOutcomeResolution::Superseded
6304 ),
6305 CommitOutcomeStatus::Rejected => {
6306 matches!(
6307 input.resolution,
6308 CommitOutcomeResolution::Superseded
6309 | CommitOutcomeResolution::ResolvedKeepServer
6310 )
6311 }
6312 CommitOutcomeStatus::Applied | CommitOutcomeStatus::Cached => {
6313 input.resolution == CommitOutcomeResolution::Dismissed
6314 }
6315 };
6316 if !allowed {
6317 return Err(format!(
6318 "sync.invalid_request: resolution {:?} is invalid for {:?} outcome",
6319 input.resolution, current.status
6320 ));
6321 }
6322
6323 let rollback = self.capture();
6324 self.begin_observation("syncular_outcome_resolution")?;
6325 let result = (|| {
6326 self.conn
6327 .execute(
6328 "UPDATE _syncular_commit_outcomes
6329 SET resolution = ?1, resolved_at_ms = ?2,
6330 replacement_client_commit_id = ?3
6331 WHERE client_commit_id = ?4 AND resolution = 'active'",
6332 rusqlite::params![
6333 Self::outcome_resolution_name(input.resolution),
6334 self.clock_now_ms(),
6335 input.replacement_client_commit_id,
6336 input.client_commit_id
6337 ],
6338 )
6339 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6340 let resolved = self
6341 .commit_outcome(¤t.client_commit_id)?
6342 .ok_or_else(|| "sync.outcome_not_found: outcome disappeared".to_owned())?;
6343 self.conn
6344 .execute(
6345 "DELETE FROM _syncular_failed_commits WHERE client_commit_id = ?1",
6346 rusqlite::params![input.client_commit_id],
6347 )
6348 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6349 for (commit, _) in self.failed_commits.iter() {
6350 if commit.client_commit_id == input.client_commit_id {
6351 for operation in &commit.ops {
6352 self.overlay_dirty.table(&operation.table);
6353 }
6354 }
6355 }
6356 self.failed_commits
6357 .retain(|(commit, _)| commit.client_commit_id != input.client_commit_id);
6358 self.prune_commit_outcomes()?;
6359 Ok(resolved)
6360 })();
6361 let resolved = match result {
6362 Ok(outcome) => outcome,
6363 Err(error) => {
6364 self.rollback_observation("syncular_outcome_resolution");
6365 self.restore(rollback);
6366 return Err(error);
6367 }
6368 };
6369 self.conflicts
6370 .retain(|record| record.client_commit_id != current.client_commit_id);
6371 self.rejections
6372 .retain(|record| record.client_commit_id != current.client_commit_id);
6373 let mut batch = ChangeAccumulator {
6374 conflicts: current.status == CommitOutcomeStatus::Conflict,
6375 rejections: current.status == CommitOutcomeStatus::Rejected,
6376 outcomes: true,
6377 ..ChangeAccumulator::default()
6378 };
6379 if let Some(operations) = ¤t.operations {
6380 for operation in operations {
6381 batch.table(&operation.table);
6382 }
6383 }
6384 if let Err(error) = self
6385 .rebuild_overlay_if_dirty()
6386 .and_then(|()| self.finish_observation("syncular_outcome_resolution", batch))
6387 {
6388 self.rollback_observation("syncular_outcome_resolution");
6389 self.restore(rollback);
6390 return Err(error);
6391 }
6392 Ok(resolved)
6393 }
6394
6395 pub fn schema_floor(&self) -> Option<&SchemaFloor> {
6396 self.schema_floor.as_ref()
6397 }
6398
6399 pub fn lease_state(&self) -> Option<&LeaseState> {
6401 self.lease_state.as_ref()
6402 }
6403
6404 fn record_lease_error(&mut self, code: &str) -> Result<(), String> {
6407 if code != "sync.auth_lease_required" && code != "sync.auth_lease_revoked" {
6408 return Ok(());
6409 }
6410 let mut next = self.lease_state.clone().unwrap_or_default();
6411 next.error_code = Some(code.to_owned());
6412 self.set_lease_state(Some(next))
6413 }
6414
6415 fn set_lease_state(&mut self, next: Option<LeaseState>) -> Result<(), String> {
6416 if self.lease_state == next {
6417 return Ok(());
6418 }
6419 self.begin_observation("syncular_lease")?;
6420 let rollback = self.capture();
6421 self.lease_state = next;
6422 let persisted = match &self.lease_state {
6423 Some(lease) => serde_json::to_string(lease)
6424 .map_err(|error| error.to_string())
6425 .and_then(|json| self.set_meta(LEASE_STATE_KEY, &json)),
6426 None => self.delete_meta(LEASE_STATE_KEY),
6427 };
6428 let batch = ChangeAccumulator {
6429 status: true,
6430 ..ChangeAccumulator::default()
6431 };
6432 if let Err(error) =
6433 persisted.and_then(|()| self.finish_observation("syncular_lease", batch))
6434 {
6435 self.rollback_observation("syncular_lease");
6436 self.restore(rollback);
6437 return Err(error);
6438 }
6439 Ok(())
6440 }
6441
6442 fn set_schema_floor(&mut self, next: Option<SchemaFloor>) -> Result<(), String> {
6443 if self.schema_floor == next {
6444 return Ok(());
6445 }
6446 self.begin_observation("syncular_schema_floor")?;
6447 let rollback = self.capture();
6448 self.stopped = next.is_some();
6449 self.schema_floor = next;
6450 let persisted = match &self.schema_floor {
6451 Some(floor) => serde_json::to_string(floor)
6452 .map_err(|error| error.to_string())
6453 .and_then(|json| self.set_meta(SCHEMA_FLOOR_KEY, &json)),
6454 None => self.delete_meta(SCHEMA_FLOOR_KEY),
6455 };
6456 let batch = ChangeAccumulator {
6457 status: true,
6458 ..ChangeAccumulator::default()
6459 };
6460 if let Err(error) =
6461 persisted.and_then(|()| self.finish_observation("syncular_schema_floor", batch))
6462 {
6463 self.rollback_observation("syncular_schema_floor");
6464 self.restore(rollback);
6465 return Err(error);
6466 }
6467 Ok(())
6468 }
6469
6470 fn set_upgrading(&mut self, value: bool) {
6471 if self.upgrading == value {
6472 return;
6473 }
6474 if self.begin_observation("syncular_upgrading").is_err() {
6475 return;
6476 }
6477 self.upgrading = value;
6478 let batch = ChangeAccumulator {
6479 status: true,
6480 ..ChangeAccumulator::default()
6481 };
6482 if self
6483 .finish_observation("syncular_upgrading", batch)
6484 .is_err()
6485 {
6486 self.rollback_observation("syncular_upgrading");
6487 }
6488 }
6489
6490 pub fn sync_needed(&self) -> bool {
6491 self.sync_needed
6492 }
6493
6494 pub fn read_rows(&self, table: &str) -> Result<Vec<RowState>, String> {
6495 let schema_table = self
6496 .schema
6497 .table(table)
6498 .ok_or_else(|| format!("unknown table {table:?}"))?;
6499 let sql = format!(
6500 "SELECT * FROM {} ORDER BY {} ASC",
6501 visible_table(table),
6502 quote_ident(&schema_table.primary_key)
6503 );
6504 let mut stmt = self
6505 .conn
6506 .prepare(&sql)
6507 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6508 let mut rows = stmt
6509 .query([])
6510 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6511 let mut out = Vec::new();
6512 while let Some(row) = rows
6513 .next()
6514 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6515 {
6516 let mut values = Map::new();
6517 for (i, column) in schema_table.columns.iter().enumerate() {
6518 let value = row
6519 .get_ref(i)
6520 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6521 values.insert(column.name.clone(), sql_ref_to_json(column, value));
6522 }
6523 let version: i64 = row
6524 .get(schema_table.columns.len())
6525 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
6526 let row_id = match values.get(&schema_table.primary_key) {
6527 Some(Value::String(s)) => s.clone(),
6528 Some(Value::Number(n)) => n.to_string(),
6529 Some(Value::Bool(b)) => b.to_string(),
6530 other => format!("{}", other.cloned().unwrap_or(Value::Null)),
6531 };
6532 out.push(RowState {
6533 row_id,
6534 version,
6535 values,
6536 });
6537 }
6538 Ok(out)
6539 }
6540
6541 #[cfg(feature = "crdt-yjs")]
6557 fn crdt_column_bytes(
6558 &self,
6559 table: &str,
6560 row_id: &str,
6561 column: &str,
6562 ) -> Result<Option<Vec<u8>>, String> {
6563 let schema_table = self
6564 .schema
6565 .table(table)
6566 .ok_or_else(|| format!("unknown table {table:?}"))?;
6567 let col = schema_table
6568 .columns
6569 .iter()
6570 .find(|c| c.name == column)
6571 .ok_or_else(|| format!("table {table:?} has no column {column:?}"))?;
6572 if col.ty != ColumnType::Crdt {
6573 return Err(format!("column {column:?} is not a crdt column (§5.10.1)"));
6574 }
6575 let sql = format!(
6576 "SELECT {} FROM {} WHERE {}",
6577 quote_ident(column),
6578 visible_table(table),
6579 row_id_predicate(schema_table)
6580 );
6581 let bytes: Option<Vec<u8>> = self
6582 .conn
6583 .prepare_cached(&sql)
6584 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
6585 .query_row(rusqlite::params![row_id], |row| {
6586 row.get::<_, Option<Vec<u8>>>(0)
6587 })
6588 .map_err(|e| match e {
6589 rusqlite::Error::QueryReturnedNoRows => "no such row".to_owned(),
6590 other => Self::sqlite_failure(&self.storage_failure, other),
6591 })?;
6592 Ok(bytes)
6593 }
6594
6595 #[cfg(feature = "crdt-yjs")]
6599 pub fn crdt_text(
6600 &self,
6601 table: &str,
6602 row_id: &str,
6603 column: &str,
6604 name: &str,
6605 ) -> Result<String, String> {
6606 let bytes = self
6607 .crdt_column_bytes(table, row_id, column)?
6608 .unwrap_or_default();
6609 crate::crdt::text(&bytes, name)
6610 }
6611
6612 #[cfg(feature = "crdt-yjs")]
6616 pub fn crdt_insert_text(
6617 &mut self,
6618 table: &str,
6619 row_id: &str,
6620 column: &str,
6621 name: &str,
6622 index: u32,
6623 value: &str,
6624 ) -> Result<String, ClientError> {
6625 let prior = self.storage_failure.borrow_mut().take();
6626 let outcome = (|| -> Result<String, String> {
6627 let current = self
6628 .crdt_column_bytes(table, row_id, column)?
6629 .unwrap_or_default();
6630 let update = crate::crdt::insert_text(¤t, name, index, value)?;
6631 self.perform_crdt_push_update(table, row_id, column, &update)
6632 })();
6633 self.finish_authoring(prior, outcome)
6634 }
6635
6636 #[cfg(feature = "crdt-yjs")]
6640 pub fn crdt_delete_text(
6641 &mut self,
6642 table: &str,
6643 row_id: &str,
6644 column: &str,
6645 name: &str,
6646 index: u32,
6647 len: u32,
6648 ) -> Result<String, ClientError> {
6649 let prior = self.storage_failure.borrow_mut().take();
6650 let outcome = (|| -> Result<String, String> {
6651 let current = self
6652 .crdt_column_bytes(table, row_id, column)?
6653 .unwrap_or_default();
6654 let update = crate::crdt::delete_text(¤t, name, index, len)?;
6655 self.perform_crdt_push_update(table, row_id, column, &update)
6656 })();
6657 self.finish_authoring(prior, outcome)
6658 }
6659
6660 #[cfg(feature = "crdt-yjs")]
6665 pub fn crdt_apply_update(
6666 &mut self,
6667 table: &str,
6668 row_id: &str,
6669 column: &str,
6670 update: &[u8],
6671 ) -> Result<String, ClientError> {
6672 let prior = self.storage_failure.borrow_mut().take();
6673 let outcome = (|| -> Result<String, String> {
6674 let current = self
6675 .crdt_column_bytes(table, row_id, column)?
6676 .unwrap_or_default();
6677 let next = crate::crdt::apply_update(¤t, update)?;
6678 self.perform_crdt_push_update(table, row_id, column, &next)
6679 })();
6680 self.finish_authoring(prior, outcome)
6681 }
6682
6683 #[cfg(feature = "crdt-yjs")]
6690 fn perform_crdt_push_update(
6691 &mut self,
6692 table: &str,
6693 row_id: &str,
6694 column: &str,
6695 crdt_bytes: &[u8],
6696 ) -> Result<String, String> {
6697 let mut bytes_obj = Map::new();
6698 bytes_obj.insert("$bytes".to_owned(), Value::from(bytes_to_hex(crdt_bytes)));
6699 let mut partial = Map::new();
6700 partial.insert(column.to_owned(), Value::Object(bytes_obj));
6701 self.perform_patch(table, row_id, partial, None)
6702 }
6703
6704 pub fn query(&self, sql: &str, params: &[QueryValue]) -> Result<Vec<QueryRow>, String> {
6719 query_connection(&self.conn, sql, params).map_err(|failure| failure.to_string())
6720 }
6721
6722 #[cfg(feature = "bench-internals")]
6724 #[doc(hidden)]
6725 pub fn benchmark_connection(&mut self) -> &mut Connection {
6726 &mut self.conn
6727 }
6728
6729 #[cfg(feature = "bench-internals")]
6731 #[doc(hidden)]
6732 pub fn benchmark_phases(
6733 &self,
6734 enabled: Option<bool>,
6735 reset: bool,
6736 ) -> Result<Option<Value>, String> {
6737 self.benchmark_phases.configure(enabled, reset)?;
6738 Ok(self.benchmark_phases.snapshot())
6739 }
6740
6741 pub fn authority_snapshot(&self) -> Result<Value, String> {
6743 validate_authority_reads(&self.schema, &self.limits.authority_reads)?;
6744 if self.limits.authority_reads.is_empty() {
6745 return Err("client.authority_read_forbidden: no authority reads were declared at client creation".into());
6746 }
6747 self.conn
6748 .execute_batch("SAVEPOINT authority_snapshot")
6749 .map_err(|e| e.to_string())?;
6750 let result = (|| {
6751 let revision = self
6752 .get_meta(LOCAL_REVISION_KEY)?
6753 .ok_or("sync.local_corrupt: authority revision is missing")?;
6754 let parsed_revision = revision
6755 .parse::<u64>()
6756 .map_err(|_| "sync.local_corrupt: authority revision is invalid")?;
6757 if parsed_revision.to_string() != revision {
6758 return Err("sync.local_corrupt: authority revision is invalid".into());
6759 }
6760 let mut tables = Vec::new();
6761 for read in &self.limits.authority_reads {
6762 let table = self
6763 .schema
6764 .table(&read.table)
6765 .ok_or("client.authority_read_forbidden: authority table is not declared")?;
6766 let scalar = |column: &str, value: &Value| -> Result<String, String> {
6767 let ty = table
6768 .columns
6769 .iter()
6770 .find(|c| c.name == column)
6771 .expect("validated authority column")
6772 .ty;
6773 if ty == ColumnType::Boolean {
6774 if let Some(value) = value.as_bool() {
6775 return Ok(value.to_string());
6776 }
6777 return match value.as_i64() {
6778 Some(0) => Ok("false".into()),
6779 Some(1) => Ok("true".into()),
6780 _ => Err("sync.local_corrupt: authority boolean is invalid".into()),
6781 };
6782 }
6783 match value {
6784 Value::String(s) => Ok(s.clone()),
6785 Value::Number(n) => Ok(n.to_string()),
6786 Value::Object(o) if ty == ColumnType::Integer && o.len() == 1 => o
6787 .get("$bigint")
6788 .and_then(Value::as_str)
6789 .map(str::to_owned)
6790 .ok_or("sync.local_corrupt: authority integer is invalid".into()),
6791 _ => {
6792 Err("sync.local_corrupt: authority scalar is missing or invalid".into())
6793 }
6794 }
6795 };
6796 let matches = |row: &QueryRow| -> Result<bool, String> {
6797 for (variable, values) in &read.scopes {
6798 let column = table
6799 .scope_column(variable)
6800 .expect("validated authority scope");
6801 let value = row
6802 .get(column)
6803 .ok_or("sync.local_corrupt: authority scope column is missing")?;
6804 if value.is_null() || !values.contains(&scalar(column, value)?) {
6805 return Ok(false);
6806 }
6807 }
6808 Ok(true)
6809 };
6810 let selected = read
6811 .columns
6812 .iter()
6813 .map(|c| quote_ident(c))
6814 .collect::<Vec<_>>()
6815 .join(",");
6816 let mut intent = BTreeSet::new();
6817 let mut relevant = BTreeSet::new();
6818 for row in query_connection(&self.conn,
6819 "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=?",
6820 &[Value::String(read.table.clone())]).map_err(|e| e.to_string())? {
6821 let id = row.get("id").and_then(Value::as_str).ok_or("sync.local_corrupt: authority intent id is invalid")?.to_owned();
6822 intent.insert(id.clone());
6823 if let Some(raw) = row.get("values_json").and_then(Value::as_str) {
6824 let values: QueryRow = serde_json::from_str(raw).map_err(|_| "sync.local_corrupt: authority intent values are invalid")?;
6825 if read.scopes.keys().all(|v| values.contains_key(table.scope_column(v).expect("validated scope"))) && matches(&values)? {relevant.insert(id);}
6826 }
6827 }
6828 let mut rows = BTreeMap::new();
6829 for full in [base_table(&read.table), visible_table(&read.table)] {
6830 for mut values in query_connection(
6831 &self.conn,
6832 &format!(
6833 "SELECT {selected},_syncular_version AS authority_version FROM {full}"
6834 ),
6835 &[],
6836 )
6837 .map_err(|e| e.to_string())?
6838 {
6839 if !matches(&values)? {
6840 continue;
6841 }
6842 let id = scalar(
6843 &table.primary_key,
6844 values
6845 .get(&table.primary_key)
6846 .expect("selected primary key"),
6847 )?;
6848 relevant.insert(id.clone());
6849 if full == base_table(&read.table) {
6850 let version = values
6851 .remove("authority_version")
6852 .expect("selected version");
6853 let version = version
6854 .as_i64()
6855 .ok_or("sync.local_corrupt: authority server version is invalid")?;
6856 if version >= 0 {
6857 rows.insert(id.clone(), json!({"values": values, "version": version, "hasLocalIntent": intent.contains(&id)}));
6858 }
6859 }
6860 }
6861 }
6862 intent.retain(|id| relevant.contains(id));
6863 let rows = rows.into_values().collect::<Vec<_>>();
6864 let replica = self.stored(replica_cursor(&self.conn))?;
6866 let persisted = self
6867 .stored(load_units(&self.conn))?
6868 .into_iter()
6869 .filter(|unit| covers(table, &unit.scopes))
6870 .map(|unit| {
6871 let effective = unit.echo.as_deref().and_then(|echo| {
6872 pair_scopes(&unit.scopes, &read.table, Some(echo))
6873 });
6874 let requested = read
6875 .scopes
6876 .keys()
6877 .map(|v| (v.clone(), json!(unit.scopes.get(v).into_iter().collect::<Vec<_>>())))
6878 .collect::<Map<_, _>>();
6879 let complete = effective
6880 .as_ref()
6881 .is_some_and(|scopes| scopes.len() == read.scopes.len())
6882 && unit.status == UnitStatus::Active
6883 && !unit.bootstrapping();
6884 let exposed = effective.map(|scopes| {
6885 read.scopes
6886 .keys()
6887 .map(|v| {
6888 let held = scopes.iter().find(|(variable, _)| variable == v);
6889 (v.clone(), json!(held.map_or(&Vec::new(), |(_, values)| values)))
6890 })
6891 .collect::<Map<_, _>>()
6892 });
6893 json!({"requestedScopes": requested, "status": unit.status, "cursor": unit.cursor.unwrap_or(replica), "effectiveScopes": exposed, "complete": complete})
6894 })
6895 .collect::<Vec<_>>();
6896 fn covered(selectors: &[(&String, &Vec<String>)], candidates: &[&Value]) -> bool {
6897 match selectors.split_first() {
6898 None => !candidates.is_empty(),
6899 Some(((variable, values), rest)) => values.iter().all(|value| {
6900 covered(
6901 rest,
6902 &candidates
6903 .iter()
6904 .copied()
6905 .filter(|p| {
6906 p["effectiveScopes"][variable.as_str()]
6907 .as_array()
6908 .is_some_and(|held| {
6909 held.contains(&Value::String(value.clone()))
6910 || held.contains(&Value::String("*".into()))
6911 })
6912 })
6913 .collect::<Vec<_>>(),
6914 )
6915 }),
6916 }
6917 }
6918 let coverage = if covered(
6919 &read.scopes.iter().collect::<Vec<_>>(),
6920 &persisted
6921 .iter()
6922 .filter(|p| p["complete"] == true)
6923 .collect::<Vec<_>>(),
6924 ) {
6925 "complete"
6926 } else if persisted.iter().any(|p| {
6927 p["status"] == "active"
6928 && read.scopes.iter().all(|(v, values)| {
6929 values.iter().any(|value| {
6930 p["requestedScopes"][v].as_array().is_some_and(|held| {
6931 held.contains(&Value::String(value.clone()))
6932 })
6933 })
6934 })
6935 }) {
6936 "pending"
6937 } else {
6938 "missing"
6939 };
6940 tables.push(json!({"table": read.table, "rows": rows, "localIntentRowIds": intent, "scopes": read.scopes, "coverage": coverage, "persisted": persisted}));
6941 }
6942 Ok(
6943 json!({"revision": revision, "complete": tables.iter().all(|t| t["coverage"] == "complete"), "tables": tables}),
6944 )
6945 })();
6946 match result {
6947 Ok(snapshot) => {
6948 self.conn
6949 .execute_batch("RELEASE authority_snapshot")
6950 .map_err(|e| e.to_string())?;
6951 Ok(snapshot)
6952 }
6953 Err(error) => {
6954 self.conn
6955 .execute_batch("ROLLBACK TO authority_snapshot; RELEASE authority_snapshot")
6956 .map_err(|e| format!("{error}; rollback failed: {e}"))?;
6957 Err(error)
6958 }
6959 }
6960 }
6961
6962 pub fn query_snapshot(
6966 &mut self,
6967 sql: &str,
6968 params: &[QueryValue],
6969 coverage: &[WindowCoverage],
6970 owner: Option<QueryOwner<'_>>,
6971 ) -> Result<QuerySnapshot, String> {
6972 let result = snapshot_connection(&self.conn, sql, params, coverage);
6973 if let Some(owner) = owner {
6974 self.record_query_read(owner, result.as_ref().err());
6975 }
6976 result.map_err(|failure| failure.to_string())
6977 }
6978
6979 pub fn record_query_read(&mut self, owner: QueryOwner<'_>, failure: Option<&QueryReadFailure>) {
6983 let position = self
6984 .query_failures
6985 .iter()
6986 .position(|entry| entry.id == owner.id);
6987 let Some(failure) = failure else {
6988 if let Some(index) = position {
6989 self.query_failures.remove(index);
6990 }
6991 return;
6992 };
6993 let tables: Vec<String> = BTreeSet::from_iter(owner.tables.iter().copied())
6994 .into_iter()
6995 .map(str::to_owned)
6996 .collect();
6997 let code = failure.code.unwrap_or("client.query_failed").to_owned();
6998 if position.is_some_and(|index| {
6999 let entry = &self.query_failures[index];
7000 entry.tables == tables && entry.code == code && entry.sqlite_code == failure.sqlite_code
7001 }) {
7002 return;
7003 }
7004 if let Some(index) = position {
7005 self.query_failures.remove(index);
7006 }
7007 self.query_failures.push(DiagnosticQueryFailure {
7008 id: owner.id.to_owned(),
7009 tables,
7010 code,
7011 sqlite_code: failure.sqlite_code,
7012 at_ms: self.clock_now_ms(),
7013 });
7014 if self.query_failures.len() > MAX_DIAGNOSTIC_QUERY_FAILURES {
7015 self.query_failures.remove(0);
7016 }
7017 }
7018
7019 fn build_request(&self, url_capable: bool) -> Result<(Message, RequestMeta), Box<SyncOutcome>> {
7022 #[cfg(feature = "bench-internals")]
7023 let _phase = self.benchmark_phases.start(Phase::RequestPrepare);
7024 let log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7025 Box::new(SyncOutcome::Failed {
7026 error_code: "storage.failed".into(),
7027 message,
7028 details: None,
7029 recommended_action: None,
7030 })
7031 })?;
7032 let max_commits = self.limits.max_push_commits_per_request;
7033 let max_ops = self
7034 .limits
7035 .max_push_operations_per_request
7036 .unwrap_or(PUSH_OPS_PER_REQUEST);
7037 let byte_cap = self.limits.max_push_request_bytes;
7038 let accept = self.limits.accept.unwrap_or(if url_capable {
7041 DEFAULT_ACCEPT | ACCEPT_SIGNED_URLS
7042 } else {
7043 DEFAULT_ACCEPT
7044 });
7045 let storage_failed = |message: String| {
7046 Box::new(SyncOutcome::Failed {
7047 error_code: "storage.failed".into(),
7048 message,
7049 details: None,
7050 recommended_action: None,
7051 })
7052 };
7053 let header = Frame::ReqHeader {
7054 client_id: self.client_id.clone(),
7055 schema_version: self.schema.version,
7056 log_epoch: log_epoch.clone(),
7057 outbox_id: self.get_meta(OUTBOX_ID_KEY).map_err(storage_failed)?,
7058 };
7059 let mut lead = vec![header];
7063 lead.extend(
7064 self.round_failure
7065 .iter()
7066 .map(|code| Frame::RoundFailure { code: code.clone() }),
7067 );
7068 let registered: Vec<UnitRecord> = self
7069 .stored(load_units(&self.conn))
7070 .map_err(storage_failed)?
7071 .into_iter()
7072 .filter(|unit| unit.status == UnitStatus::Active)
7073 .collect();
7074 let registration_digest = ssp2::registration::registration_digest(
7075 registered
7076 .iter()
7077 .map(|unit| scope_pairs(&unit.scopes))
7078 .collect::<Vec<_>>()
7079 .iter()
7080 .map(Vec::as_slice),
7081 );
7082 let echo_digest = self
7083 .get_meta(ECHO_DIGEST_KEY)
7084 .map_err(storage_failed)?
7085 .filter(|hex| !hex.is_empty())
7086 .map(|hex| {
7087 crate::values::hex_to_bytes(&hex)
7088 .ok()
7089 .and_then(|bytes| <[u8; 32]>::try_from(bytes).ok())
7090 .ok_or_else(|| {
7091 "sync.local_corrupt: persisted echo digest is invalid".to_owned()
7092 })
7093 })
7094 .transpose()
7095 .map_err(storage_failed)?;
7096 let pull = Frame::PullHeader {
7097 limit_commits: self.limits.limit_commits.unwrap_or(0),
7098 limit_snapshot_rows: self.limits.limit_snapshot_rows.unwrap_or(0),
7099 max_snapshot_pages: self.limits.max_snapshot_pages.unwrap_or(0),
7100 accept,
7101 cursor: self
7102 .stored(replica_cursor(&self.conn))
7103 .map_err(storage_failed)?,
7104 registration_digest,
7105 echo_digest,
7106 };
7107 let registration_digest = bytes_to_hex(®istration_digest);
7108 let travels = self
7111 .get_meta(REGISTERED_DIGEST_KEY)
7112 .map_err(storage_failed)?
7113 .as_deref()
7114 != Some(registration_digest.as_str());
7115 let mut sub_frames: Vec<Frame> = Vec::new();
7116 if travels {
7117 sub_frames.extend(registered.iter().map(|unit| Frame::Unit {
7118 scopes: scope_pairs(&unit.scopes),
7119 }));
7120 }
7121 sub_frames.extend(registered.iter().filter_map(|unit| {
7123 Some(Frame::Progress {
7124 id: unit.id.clone(),
7125 cursor: unit.cursor?,
7126 bootstrap_state: unit.bootstrap_state.clone().map(RawJson),
7127 })
7128 }));
7129 let fixed_bytes = match byte_cap {
7132 Some(_) => {
7133 let mut frames = lead.clone();
7134 frames.push(pull.clone());
7135 frames.extend(sub_frames.iter().cloned());
7136 encode_message(&Message {
7137 wire_version: WIRE_VERSION,
7138 msg_kind: MsgKind::Request,
7139 frames,
7140 })
7141 .len()
7142 }
7143 None => 0,
7144 };
7145 if let Some(cap) = byte_cap {
7146 if fixed_bytes > cap {
7147 return Err(Self::push_capacity_outcome("bytes", cap, fixed_bytes, None));
7148 }
7149 }
7150 let base_bytes = match byte_cap {
7151 Some(_) => {
7152 let mut frames = lead.clone();
7153 frames.push(pull.clone());
7154 encode_message(&Message {
7155 wire_version: WIRE_VERSION,
7156 msg_kind: MsgKind::Request,
7157 frames,
7158 })
7159 .len()
7160 }
7161 None => 0,
7162 };
7163 let total_outbox = if log_epoch.is_some() {
7164 self.outbox.len()
7165 } else {
7166 0
7167 };
7168 let mut push_frames: Vec<Frame> = Vec::new();
7169 let mut pushed_ids = Vec::new();
7170 let mut ops_in_request = 0usize;
7171 let mut bytes_in_request = 0usize;
7172 let mut deferred_commits = 0usize;
7173 #[cfg(feature = "bench-internals")]
7174 let outbox_phase = self.benchmark_phases.start(Phase::OutboxEncode);
7175 for (index, commit) in self.outbox.iter().take(total_outbox).enumerate() {
7176 if max_commits.is_some_and(|cap| push_frames.len() >= cap) {
7180 deferred_commits = total_outbox - index;
7181 break;
7182 }
7183 if ops_in_request + commit.ops.len() > max_ops {
7184 if push_frames.is_empty() {
7185 return Err(Self::push_capacity_outcome(
7186 "operations",
7187 max_ops,
7188 commit.ops.len(),
7189 Some(commit.client_commit_id.as_str()),
7190 ));
7191 }
7192 deferred_commits = total_outbox - index;
7193 break;
7194 }
7195 let operations = commit
7196 .ops
7197 .iter()
7198 .map(|op| {
7199 let payload = match self
7200 .schema
7201 .table(&op.table)
7202 .and_then(|table| Some((table, op.presented_values(table)?)))
7203 {
7204 Some((table, values)) => {
7205 let fallback =
7215 self.stored_key_fallback(table, &op.row_id)
7216 .map_err(|message| {
7217 Box::new(SyncOutcome::Failed {
7218 error_code: "storage.failed".into(),
7219 message,
7220 details: None,
7221 recommended_action: None,
7222 })
7223 })?;
7224 encode_sparse_row_json(
7225 table,
7226 &op.row_id,
7227 &values,
7228 &self.encryption,
7229 fallback.as_ref(),
7230 )
7231 .ok()
7232 }
7233 None => None,
7234 };
7235 Ok(ssp2::model::Operation {
7236 table: op.table.clone(),
7237 row_id: op.row_id.clone(),
7238 op: if op.upsert { Op::Upsert } else { Op::Delete },
7239 base_version: op.base_version,
7240 payload,
7241 })
7242 })
7243 .collect::<Result<Vec<_>, Box<SyncOutcome>>>()?;
7244 let client_seq = self
7246 .conn
7247 .prepare_cached("SELECT seq FROM _syncular_outbox WHERE commit_id = ?1")
7248 .and_then(|mut statement| {
7249 statement.query_row([&commit.client_commit_id], |row| row.get(0))
7250 })
7251 .map_err(|error| {
7252 storage_failed(Self::sqlite_failure(&self.storage_failure, error))
7253 })?;
7254 let frame = Frame::PushCommit {
7255 client_commit_id: commit.client_commit_id.clone(),
7256 client_seq,
7257 operations,
7258 };
7259 let frame_bytes = match byte_cap {
7260 Some(_) => {
7261 let mut frames = lead.clone();
7262 frames.push(frame.clone());
7263 frames.push(pull.clone());
7264 encode_message(&Message {
7265 wire_version: WIRE_VERSION,
7266 msg_kind: MsgKind::Request,
7267 frames,
7268 })
7269 .len()
7270 - base_bytes
7271 }
7272 None => 0,
7273 };
7274 if let Some(cap) = byte_cap {
7278 if !push_frames.is_empty() && fixed_bytes + bytes_in_request + frame_bytes > cap {
7279 deferred_commits = total_outbox - index;
7280 break;
7281 }
7282 }
7283 push_frames.push(frame);
7284 pushed_ids.push(commit.client_commit_id.clone());
7285 ops_in_request += commit.ops.len();
7286 bytes_in_request += frame_bytes;
7287 }
7288 #[cfg(feature = "bench-internals")]
7289 drop(outbox_phase);
7290 if let Some(cap) = byte_cap {
7291 if fixed_bytes + bytes_in_request > cap {
7292 let blocked = if push_frames.is_empty() {
7295 None
7296 } else {
7297 self.outbox.first().map(|c| c.client_commit_id.as_str())
7298 };
7299 return Err(Self::push_capacity_outcome(
7300 "bytes",
7301 cap,
7302 fixed_bytes + bytes_in_request,
7303 blocked,
7304 ));
7305 }
7306 }
7307 let mut frames = lead;
7308 frames.extend(push_frames);
7309 frames.push(pull);
7310 frames.extend(sub_frames);
7311 let message = Message {
7312 wire_version: WIRE_VERSION,
7313 msg_kind: MsgKind::Request,
7314 frames,
7315 };
7316 Ok((
7317 message,
7318 RequestMeta {
7319 pushed_ids,
7320 registration_digest,
7321 accept,
7322 deferred_commits,
7323 },
7324 ))
7325 }
7326
7327 fn push_capacity_outcome(
7329 kind: &str,
7330 limit: usize,
7331 size: usize,
7332 client_commit_id: Option<&str>,
7333 ) -> Box<SyncOutcome> {
7334 let mut details = Map::new();
7335 details.insert("kind".to_owned(), Value::from(kind));
7336 details.insert("limit".to_owned(), Value::from(limit as u64));
7337 details.insert("size".to_owned(), Value::from(size as u64));
7338 if let Some(id) = client_commit_id {
7339 details.insert("clientCommitId".to_owned(), Value::from(id));
7340 }
7341 Box::new(SyncOutcome::Failed {
7342 error_code: "client.push_request_too_large".into(),
7343 message: "the push request exceeds a configured capacity limit".into(),
7344 details: Some(Value::Object(details)),
7345 recommended_action: None,
7346 })
7347 }
7348
7349 pub fn progress(&self) -> ProgressObserver {
7353 self.progress.clone()
7354 }
7355
7356 pub fn sync(&mut self, transport: &mut dyn Transport) -> SyncOutcome {
7357 let prepared = match self.prepare_sync_round(transport.supports_url_fetch()) {
7358 Ok(prepared) => prepared,
7359 Err(outcome) => return *outcome,
7360 };
7361 let mut next = prepared;
7366 loop {
7367 match self.apply_sync_round(next.exchange(transport)) {
7368 crate::AppliedSyncRound::Continue(prepared) => next = prepared,
7369 crate::AppliedSyncRound::Complete {
7370 outcome, controls, ..
7371 } => {
7372 if self.transport_enabled {
7373 for text in controls {
7374 let _ = transport.realtime_send(&text);
7375 }
7376 } else {
7377 self.disconnect_realtime(transport);
7378 }
7379 return outcome;
7380 }
7381 }
7382 }
7383 }
7384
7385 fn finish_sync_round(&mut self, started_at_ms: i64, mut outcome: SyncOutcome) -> SyncOutcome {
7386 if let SyncOutcome::Failed {
7387 error_code,
7388 message,
7389 details,
7390 ..
7391 } = &mut outcome
7392 {
7393 if let Some((failure, code)) = self
7394 .storage_failure
7395 .borrow()
7396 .as_ref()
7397 .and_then(|failure| failure.code.map(|code| (failure, code)))
7398 {
7399 *error_code = code.to_owned();
7400 *message = match code {
7401 "client.storage_busy" => "local SQLite storage is busy",
7402 "client.storage_full" => "local SQLite storage is full",
7403 "client.storage_io" => "local SQLite storage I/O failed",
7404 "client.storage_corrupt" => "local SQLite storage is corrupt",
7405 _ => unreachable!("unrecognized classified storage failure"),
7406 }
7407 .to_owned();
7408 *details = failure.details();
7409 }
7410 }
7411 let details = match &outcome {
7412 SyncOutcome::Failed { details, .. } => details.as_ref(),
7413 _ => None,
7414 };
7415 let cause_kind = details
7416 .and_then(|details| details.get("causeKind"))
7417 .and_then(Value::as_str)
7418 .and_then(|cause| match cause {
7419 "network" => Some(crate::TransportCauseKind::Network),
7420 "connect" => Some(crate::TransportCauseKind::Connect),
7421 "tls" => Some(crate::TransportCauseKind::Tls),
7422 "io" => Some(crate::TransportCauseKind::Io),
7423 "request" => Some(crate::TransportCauseKind::Request),
7424 "protocol" => Some(crate::TransportCauseKind::Protocol),
7425 "timeout" => Some(crate::TransportCauseKind::Timeout),
7426 "round_deadline" => Some(crate::TransportCauseKind::RoundDeadline),
7427 "aborted" => Some(crate::TransportCauseKind::Aborted),
7428 "body" => Some(crate::TransportCauseKind::Body),
7429 "status" => Some(crate::TransportCauseKind::Status),
7430 "redirect" => Some(crate::TransportCauseKind::Redirect),
7431 "unknown" => Some(crate::TransportCauseKind::Unknown),
7432 _ => None,
7433 });
7434 let http_status = if matches!(
7435 cause_kind,
7436 Some(
7437 crate::TransportCauseKind::Status
7438 | crate::TransportCauseKind::Body
7439 | crate::TransportCauseKind::Redirect
7440 )
7441 ) {
7442 details
7443 .and_then(|details| details.get("httpStatus"))
7444 .and_then(Value::as_f64)
7445 .filter(|status| status.fract() == 0.0 && (100.0..=599.0).contains(status))
7446 .map(|status| status as u16)
7447 } else {
7448 None
7449 };
7450 let retry_delay_ms = self.round_retry_delay_ms;
7451 self.progress.update(|p| match &outcome {
7452 SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report)
7453 if report.failed.is_empty() =>
7454 {
7455 p.state = ProgressState::Complete
7456 }
7457 SyncOutcome::Ok(_) | SyncOutcome::BudgetExhausted(_) => {
7458 p.state = ProgressState::Failed;
7459 p.error_code = Some("sync.scope_revoked".into());
7460 }
7461 SyncOutcome::Failed { error_code, .. } => {
7462 p.state = ProgressState::Failed;
7463 p.error_code = Some(Self::diagnostic_code(error_code));
7464 p.cause_kind = cause_kind;
7465 p.http_status = http_status;
7466 p.retry_delay_ms = retry_delay_ms;
7467 }
7468 SyncOutcome::RealtimeUnavailable { .. } => {
7469 p.state = ProgressState::Failed;
7470 p.error_code = Some(REALTIME_UNAVAILABLE_CODE.to_owned());
7471 p.retry_delay_ms = retry_delay_ms;
7472 }
7473 });
7474 let completed_at_ms = self.clock_now_ms();
7475 self.last_round = Some(match &outcome {
7476 SyncOutcome::Ok(report) | SyncOutcome::BudgetExhausted(report) => DiagnosticLastRound {
7477 status: "succeeded".to_owned(),
7478 started_at_ms,
7479 completed_at_ms,
7480 duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7481 counters: Some(DiagnosticRoundCounters {
7482 pushed: report.pushed,
7483 applied: report.applied.len(),
7484 rejected: report.rejected.len(),
7485 retryable: report.retryable.len(),
7486 conflicts: report.conflicts,
7487 commits_applied: report.commits_applied,
7488 segment_rows_applied: report.segment_rows_applied,
7489 bootstrapping: report.bootstrapping.len(),
7490 resets: report.resets.len(),
7491 revoked: report.revoked.len(),
7492 failed: report.failed.len(),
7493 deferred_commits: report.deferred_commits,
7494 }),
7495 error_code: None,
7496 cause_kind: None,
7497 http_status: None,
7498 },
7499 SyncOutcome::Failed { error_code, .. } => DiagnosticLastRound {
7500 status: "failed".to_owned(),
7501 started_at_ms,
7502 completed_at_ms,
7503 duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7504 counters: None,
7505 error_code: Some(Self::diagnostic_code(error_code)),
7506 cause_kind,
7507 http_status,
7508 },
7509 SyncOutcome::RealtimeUnavailable { .. } => DiagnosticLastRound {
7510 status: "failed".to_owned(),
7511 started_at_ms,
7512 completed_at_ms,
7513 duration_ms: completed_at_ms.saturating_sub(started_at_ms).max(0),
7514 counters: None,
7515 error_code: Some(REALTIME_UNAVAILABLE_CODE.to_owned()),
7516 cause_kind: None,
7517 http_status: None,
7518 },
7519 });
7520 outcome
7521 }
7522
7523 pub fn prepare_sync_round(
7526 &mut self,
7527 url_capable: bool,
7528 ) -> Result<crate::PreparedSyncRound, Box<SyncOutcome>> {
7529 if !self.transport_enabled {
7530 return Err(Box::new(SyncOutcome::Failed {
7531 error_code: "sync.offline".into(),
7532 message: "transport gate is closed".into(),
7533 details: None,
7534 recommended_action: None,
7535 }));
7536 }
7537 if self.active_round.is_some() {
7538 return Err(Box::new(SyncOutcome::Failed {
7539 error_code: "client.round_in_progress".into(),
7540 message: "a sync round is already in flight".into(),
7541 details: None,
7542 recommended_action: None,
7543 }));
7544 }
7545 self.storage_failure.borrow_mut().take();
7546 self.progress.start();
7547 self.round_retry_delay_ms = None;
7548 let started_at_ms = self.clock_now_ms();
7549 let prepared = (|| {
7550 if self.stopped {
7551 return Err(Box::new(SyncOutcome::Ok(SyncReport {
7552 schema_floor: self.schema_floor.clone(),
7553 ..SyncReport::default()
7554 })));
7555 }
7556 if self.security_preflight {
7557 return Err(Box::new(SyncOutcome::Failed {
7558 error_code: SECURITY_PREFLIGHT_REQUIRED_CODE.into(),
7559 message: "security preflight must complete before syncing".into(),
7560 details: None,
7561 recommended_action: None,
7562 }));
7563 }
7564 self.set_sync_needed(false, false);
7565 self.drain_pending_evictions()
7566 .and_then(|_| self.drop_incompatible_outbox())
7567 .and_then(|_| self.drop_unencodable_outbox(true, None))
7568 .map_err(|message| {
7569 Box::new(SyncOutcome::Failed {
7570 error_code: "storage.failed".into(),
7571 message,
7572 details: None,
7573 recommended_action: None,
7574 })
7575 })?;
7576 let has_log_epoch = self.get_meta(LOG_EPOCH_KEY).map_err(|message| {
7577 Box::new(SyncOutcome::Failed {
7578 error_code: "storage.failed".into(),
7579 message,
7580 details: None,
7581 recommended_action: None,
7582 })
7583 })?;
7584 let uploads = if has_log_epoch.is_some() && self.schema_has_blobs() {
7585 self.pending_blob_uploads().map_err(|e| {
7586 Box::new(SyncOutcome::Failed {
7587 error_code: e.code,
7588 message: e.message,
7589 details: e.details,
7590 recommended_action: None,
7591 })
7592 })?
7593 } else {
7594 Vec::new()
7595 };
7596 if self.realtime_state != RealtimeState::Connected
7597 && self.realtime_policy == RealtimePolicy::Required
7598 {
7599 let retry_delay_ms = self.schedule_background_retry();
7600 self.realtime_retry_delay_ms = Some(retry_delay_ms);
7601 return Err(Box::new(SyncOutcome::RealtimeUnavailable {
7602 state: self.realtime_state,
7603 reason_code: self.realtime_reason_code.clone(),
7604 retry_delay_ms,
7605 }));
7606 }
7607 let (message, meta) = self.build_request(url_capable)?;
7608 let id = uuid::Uuid::new_v4();
7609 self.active_round = Some(id);
7610 let phase = if uploads.is_empty() {
7611 crate::round::RoundPhase::Sync
7612 } else {
7613 crate::round::RoundPhase::UploadGrant
7614 };
7615 Ok(crate::PreparedSyncRound {
7616 id,
7617 started_at_ms,
7618 message,
7619 meta,
7620 uploads: uploads.into(),
7621 phase,
7622 encoded: None,
7623 continuation: None,
7624 completed: None,
7625 realtime: self.realtime_state == RealtimeState::Connected,
7626 scopes: self
7628 .stored(load_units(&self.conn))
7629 .map_err(|message| {
7630 Box::new(SyncOutcome::Failed {
7631 error_code: "storage.failed".into(),
7632 message,
7633 details: None,
7634 recommended_action: None,
7635 })
7636 })?
7637 .into_iter()
7638 .map(|unit| {
7639 (
7640 unit.id,
7641 canonical_scope_json(&unit_scope_lists(&unit.scopes)),
7642 )
7643 })
7644 .collect(),
7645 #[cfg(feature = "bench-internals")]
7646 benchmark_phases: self.benchmark_phases.clone(),
7647 progress: self.progress.clone(),
7648 fixed_now: self.now_ms,
7649 round_deadline_at: None,
7650 })
7651 })();
7652 prepared.map_err(|outcome| Box::new(self.finish_sync_round(started_at_ms, *outcome)))
7653 }
7654
7655 pub fn cancel_sync_round(&mut self) {
7658 self.active_round = None;
7659 }
7660
7661 pub fn apply_sync_round(
7664 &mut self,
7665 completed: crate::CompletedSyncRound,
7666 ) -> crate::AppliedSyncRound {
7667 let mut prepared = completed.prepared;
7668 if self.active_round != Some(prepared.id) || self.security_preflight {
7669 return crate::AppliedSyncRound::Complete {
7670 outcome: SyncOutcome::Failed {
7671 error_code: "client.round_cancelled".into(),
7672 message: "sync round belongs to a released client context".into(),
7673 details: None,
7674 recommended_action: None,
7675 },
7676 controls: Vec::new(),
7677 more: false,
7678 bootstrap_advanced: false,
7679 };
7680 }
7681 self.storage_failure.borrow_mut().take();
7682 let (response, mut downloads, transport_failed) = match completed.exchange {
7683 crate::round::ExchangeResult::Upload { id, result } => {
7684 let result = match result {
7685 Err(error)
7690 if error
7691 .details
7692 .as_ref()
7693 .and_then(|details| details.get("retryable"))
7694 == Some(&Value::Bool(false)) =>
7695 {
7696 self.conn
7697 .prepare(
7698 "SELECT commit_id FROM _syncular_blob_commit_refs WHERE blob_id = ?",
7699 )
7700 .and_then(|mut statement| {
7701 statement
7702 .query_map(rusqlite::params![id], |row| row.get::<_, String>(0))?
7703 .collect::<Result<HashSet<_>, _>>()
7704 })
7705 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
7706 .and_then(|refused| {
7707 let commits = self
7708 .outbox
7709 .iter()
7710 .filter(|commit| refused.contains(&commit.client_commit_id))
7711 .cloned()
7712 .collect::<Vec<_>>();
7713 if !commits.is_empty() {
7714 self.drop_outbox_commits(&commits, &error.code, &error.message)?;
7715 }
7716 prepared.message.frames.retain(|frame| {
7717 !matches!(frame, Frame::PushCommit { client_commit_id, .. }
7718 if refused.contains(client_commit_id))
7719 });
7720 prepared.meta.pushed_ids.retain(|id| !refused.contains(id));
7721 prepared.continuation = Some(crate::round::RoundPhase::UploadGrant);
7722 Ok(())
7723 })
7724 .map_err(|message| TransportError::new("client.failed", message))
7725 }
7726 result => result,
7727 };
7728 let result = result.and_then(|()| {
7729 self.conn
7730 .execute(
7731 "DELETE FROM _syncular_blob_uploads WHERE blob_id = ?",
7732 rusqlite::params![id],
7733 )
7734 .map(|_| ())
7735 .map_err(|error| {
7736 TransportError::new(
7737 "client.failed",
7738 Self::sqlite_failure(&self.storage_failure, error),
7739 )
7740 })
7741 });
7742 match result {
7743 Ok(()) => return crate::AppliedSyncRound::Continue(prepared),
7744 Err(TransportError {
7745 code,
7746 message,
7747 details,
7748 }) => {
7749 self.active_round = None;
7750 if Self::unreachable_transport(&details) {
7751 self.set_sync_needed(true, false);
7754 } else if Self::retryable_failure_code(&code) {
7755 self.schedule_background_retry();
7756 }
7757 let recommended_action = recommended_action_of(&details);
7758 let outcome = self.finish_sync_round(
7759 prepared.started_at_ms,
7760 SyncOutcome::Failed {
7761 error_code: code,
7762 message,
7763 details,
7764 recommended_action,
7765 },
7766 );
7767 return crate::AppliedSyncRound::Complete {
7768 outcome,
7769 controls: Vec::new(),
7770 more: false,
7771 bootstrap_advanced: false,
7772 };
7773 }
7774 }
7775 }
7776 crate::round::ExchangeResult::Reply {
7777 response,
7778 downloads,
7779 transport_failed,
7780 } => (response, downloads, transport_failed),
7781 };
7782 self.active_round = None;
7783 let before = self.resume_tokens();
7784 let outcome = (|| {
7785 let response = match response {
7786 Ok(response) => {
7787 self.round_failure = None;
7790 response
7791 }
7792 Err(TransportError {
7793 code,
7794 message,
7795 details,
7796 }) => {
7797 if ssp2::model::valid_round_failure_code(&code) {
7802 self.round_failure = Some(code.clone());
7803 }
7804 if transport_failed {
7805 if prepared.realtime {
7806 self.set_realtime_state(RealtimeState::Lost, Some(&code));
7807 }
7808 if let Err(message) = self.record_lease_error(&code) {
7809 return SyncOutcome::Failed {
7810 error_code: "storage.failed".to_owned(),
7811 message,
7812 details: None,
7813 recommended_action: None,
7814 };
7815 }
7816 }
7817 if Self::retryable_failure_code(&code) && !Self::unreachable_transport(&details)
7818 {
7819 let delay = self.schedule_background_retry();
7820 if prepared.realtime && transport_failed {
7821 self.realtime_retry_delay_ms = Some(delay);
7822 }
7823 }
7824 let recommended_action = recommended_action_of(&details);
7825 return SyncOutcome::Failed {
7826 error_code: code,
7827 message,
7828 details,
7829 recommended_action,
7830 };
7831 }
7832 };
7833 let mut outcome = self.process_response(&mut downloads, response, &prepared.meta);
7834 if let SyncOutcome::Ok(report) = &mut outcome {
7835 report.deferred_commits = prepared.meta.deferred_commits;
7836 }
7837 match &outcome {
7838 SyncOutcome::Ok(_) => self.reset_background_retry(),
7839 SyncOutcome::Failed {
7840 error_code,
7841 details,
7842 ..
7843 } if Self::retryable_failure_code(error_code)
7844 && !Self::unreachable_transport(details) =>
7845 {
7846 self.schedule_background_retry();
7847 }
7848 _ => {}
7849 }
7850 if prepared.meta.deferred_commits > 0 {
7851 self.set_sync_needed(true, true);
7852 }
7853 self.previous_version_lifetime_check();
7854 outcome
7855 })();
7856 match &outcome {
7857 SyncOutcome::Ok(report) if !report.bootstrapping.is_empty() => {
7860 self.set_sync_needed(true, false)
7861 }
7862 SyncOutcome::Failed { details, .. } if Self::unreachable_transport(details) => {
7865 self.set_sync_needed(true, false)
7866 }
7867 _ => {}
7868 }
7869 let more = self.transport_enabled
7870 && matches!(&outcome, SyncOutcome::Ok(report)
7871 if report.schema_floor.is_none()
7872 && (!report.bootstrapping.is_empty()
7873 || report.commits_applied > 0
7874 || report.segment_rows_applied > 0
7875 || !report.resets.is_empty()
7876 || report.deferred_commits > 0
7877 || self.sync_needed));
7878 let bootstrap_advanced = matches!(&outcome, SyncOutcome::Ok(report) if report.segment_rows_applied > 0 && !report.bootstrapping.is_empty())
7879 && before != self.resume_tokens();
7880 crate::AppliedSyncRound::Complete {
7881 outcome: self.finish_sync_round(prepared.started_at_ms, outcome),
7882 controls: if self.transport_enabled {
7883 downloads.controls
7884 } else {
7885 Vec::new()
7886 },
7887 more,
7888 bootstrap_advanced,
7889 }
7890 }
7891
7892 fn resume_tokens(&self) -> Option<Vec<(String, Option<String>)>> {
7894 load_units(&self.conn).ok().map(|units| {
7895 units
7896 .into_iter()
7897 .map(|unit| (unit.id, unit.bootstrap_state))
7898 .collect()
7899 })
7900 }
7901
7902 pub const SYNC_IDLE_TIMEOUT_MS: u64 = 60_000;
7904
7905 pub fn sync_until_idle(
7906 &mut self,
7907 transport: &mut dyn Transport,
7908 max_rounds: Option<u32>,
7909 ) -> SyncOutcome {
7910 self.sync_until_idle_with_deadline(transport, max_rounds, Some(Self::SYNC_IDLE_TIMEOUT_MS))
7911 }
7912
7913 pub fn sync_until_idle_with_deadline(
7918 &mut self,
7919 transport: &mut dyn Transport,
7920 max_rounds: Option<u32>,
7921 timeout_ms: Option<u64>,
7922 ) -> SyncOutcome {
7923 if max_rounds == Some(0) {
7926 return SyncOutcome::Failed {
7927 details: None,
7928 error_code: "sync.invalid_request".into(),
7929 message: "maxRounds must be a positive integer".into(),
7930 recommended_action: None,
7931 };
7932 }
7933 if timeout_ms.is_some_and(|ms| ms == 0 || i64::try_from(ms).is_err()) {
7934 return SyncOutcome::Failed {
7935 details: None,
7936 error_code: "sync.invalid_request".into(),
7937 message: "timeoutMs must be a positive integer".into(),
7938 recommended_action: None,
7939 };
7940 }
7941 let started_at_ms = self.clock_now_ms();
7942 let deadline_ms = timeout_ms.map(|ms| started_at_ms.saturating_add(ms as i64));
7943 self.sync_until_idle_bounded(transport, max_rounds, started_at_ms, deadline_ms)
7944 }
7945
7946 fn sync_until_idle_bounded(
7947 &mut self,
7948 transport: &mut dyn Transport,
7949 max_rounds: Option<u32>,
7950 started_at_ms: i64,
7951 deadline_ms: Option<i64>,
7952 ) -> SyncOutcome {
7953 let rounds = max_rounds.unwrap_or(20);
7954 let mut aggregate = SyncReport::default();
7955 let mut spent = 0;
7956 while spent < rounds {
7957 if let Some(deadline_ms) = deadline_ms {
7958 if self.clock_now_ms() >= deadline_ms {
7959 return SyncOutcome::Failed {
7960 error_code: "sync.idle_timeout".into(),
7961 message: "sync_until_idle exceeded its deadline".into(),
7962 details: Some(serde_json::json!({
7963 "timeoutMs": deadline_ms
7964 .saturating_sub(started_at_ms) as u64,
7965 "rounds": spent,
7966 })),
7967 recommended_action: Some("retryLater".into()),
7968 };
7969 }
7970 }
7971 spent += 1;
7972 let before = self.resume_tokens();
7973 match self.sync(transport) {
7974 SyncOutcome::Failed {
7975 error_code,
7976 message,
7977 details,
7978 recommended_action,
7979 } => {
7980 return SyncOutcome::Failed {
7981 details,
7982 error_code,
7983 message,
7984 recommended_action,
7985 };
7986 }
7987 outcome @ SyncOutcome::RealtimeUnavailable { .. } => return outcome,
7988 SyncOutcome::BudgetExhausted(_) => {
7989 unreachable!("sync() never exhausts a round budget")
7990 }
7991 SyncOutcome::Ok(report) => {
7992 if max_rounds.is_none()
7993 && report.segment_rows_applied > 0
7994 && !report.bootstrapping.is_empty()
7995 && before != self.resume_tokens()
7996 {
7997 spent = 0;
7998 }
7999 let stop = !self.transport_enabled() || report.schema_floor.is_some();
8002 aggregate.merge(&report);
8003 if stop {
8004 return SyncOutcome::Ok(aggregate);
8005 }
8006 let more = !report.bootstrapping.is_empty()
8012 || report.commits_applied > 0
8013 || report.segment_rows_applied > 0
8014 || !report.resets.is_empty()
8015 || report.deferred_commits > 0
8016 || self.sync_needed;
8017 if !more {
8018 return SyncOutcome::Ok(aggregate);
8019 }
8020 }
8021 }
8022 }
8023 SyncOutcome::BudgetExhausted(aggregate)
8026 }
8027
8028 fn process_response(
8029 &mut self,
8030 transport: &mut dyn Transport,
8031 response: Message,
8032 meta: &RequestMeta,
8033 ) -> SyncOutcome {
8034 #[cfg(feature = "bench-internals")]
8035 let _phase = self.benchmark_phases.start(Phase::ResponseApply);
8036 let mut report = SyncReport {
8037 pushed: meta.pushed_ids.len() as u32,
8038 ..SyncReport::default()
8039 };
8040 let mut rejection_details_by_commit: HashMap<String, BTreeMap<i32, RejectionDetails>> =
8041 HashMap::new();
8042 let pushed_ids = meta
8043 .pushed_ids
8044 .iter()
8045 .map(String::as_str)
8046 .collect::<HashSet<_>>();
8047 let mut last_final_push_result_id: Option<String> = None;
8048 for frame in &response.frames {
8049 match frame {
8050 Frame::PushResultDetails {
8051 client_commit_id,
8052 entries,
8053 } => {
8054 let details = rejection_details_by_commit
8055 .entry(client_commit_id.clone())
8056 .or_default();
8057 for entry in entries {
8058 let parsed = match RejectionDetails::parse(&entry.details.0) {
8059 Ok(value) => value,
8060 Err(message) => {
8061 return SyncOutcome::Failed {
8062 details: None,
8063 error_code: "sync.invalid_request".to_owned(),
8064 message,
8065 recommended_action: None,
8066 };
8067 }
8068 };
8069 details.insert(entry.op_index, parsed);
8070 }
8071 }
8072 Frame::PushResult {
8073 client_commit_id,
8074 status,
8075 results,
8076 ..
8077 } if pushed_ids.contains(client_commit_id.as_str())
8078 && Self::push_result_is_final(*status, results) =>
8079 {
8080 last_final_push_result_id = Some(client_commit_id.clone());
8081 }
8082 _ => {}
8083 }
8084 }
8085 let mut frames = response.frames.into_iter().peekable();
8086 match frames.next() {
8087 Some(Frame::RespHeader {
8088 required_schema_version,
8089 latest_schema_version,
8090 log_epoch,
8091 reset_required,
8092 }) => {
8093 if let Some(required) = required_schema_version {
8094 let floor = SchemaFloor {
8097 required_schema_version: Some(required),
8098 latest_schema_version,
8099 };
8100 if let Err(message) = self.set_schema_floor(Some(floor.clone())) {
8101 return SyncOutcome::Failed {
8102 details: None,
8103 error_code: "storage.failed".to_owned(),
8104 message,
8105 recommended_action: None,
8106 };
8107 }
8108 report.schema_floor = Some(floor);
8109 return SyncOutcome::Ok(report);
8110 }
8111 if reset_required {
8112 if frames.next().is_some() {
8113 return SyncOutcome::Failed {
8114 details: None,
8115 error_code: "client.invalid_host_response".to_owned(),
8116 message: "log-epoch reset response contains body frames".to_owned(),
8117 recommended_action: None,
8118 };
8119 }
8120 match self.run_log_epoch_reset(&log_epoch) {
8121 Ok(resets) => {
8122 report.resets = resets;
8123 return SyncOutcome::Ok(report);
8124 }
8125 Err(message) => {
8126 return SyncOutcome::Failed {
8127 details: None,
8128 error_code: "sync.local_corrupt".to_owned(),
8129 message,
8130 recommended_action: None,
8131 };
8132 }
8133 }
8134 }
8135 let stored_epoch = match self.get_meta(LOG_EPOCH_KEY) {
8136 Ok(stored) => stored,
8137 Err(message) => {
8138 return SyncOutcome::Failed {
8139 details: None,
8140 error_code: "storage.failed".to_owned(),
8141 message,
8142 recommended_action: None,
8143 };
8144 }
8145 };
8146 if stored_epoch.as_deref() != Some(log_epoch.as_str()) {
8147 return SyncOutcome::Failed {
8148 details: None,
8149 error_code: "client.invalid_host_response".to_owned(),
8150 message: "server changed logEpoch without requiring a reset".to_owned(),
8151 recommended_action: None,
8152 };
8153 }
8154 }
8155 _ => {
8156 return SyncOutcome::Failed {
8157 details: None,
8158 error_code: "sync.invalid_request".to_owned(),
8159 message: "response does not start with RESP_HEADER".to_owned(),
8160 recommended_action: None,
8161 };
8162 }
8163 }
8164
8165 if let Err(message) = self.begin_coalesced_apply() {
8166 return SyncOutcome::Failed {
8167 details: None,
8168 error_code: "storage.failed".into(),
8169 message,
8170 recommended_action: None,
8171 };
8172 }
8173 let mut failure: Option<(String, String, Option<String>, Option<Value>)> = None;
8174 let mut live: Option<(LiveStatus, String, Vec<UnitRecord>)> = None;
8177 let mut live_ended = false;
8178 while let Some(frame) = frames.next() {
8179 match frame {
8180 frame @ Frame::PushResult { .. } => {
8181 let successful = matches!(
8182 &frame,
8183 Frame::PushResult {
8184 status: PushStatus::Applied | PushStatus::Cached,
8185 ..
8186 }
8187 );
8188 let mut results = vec![frame];
8189 if successful {
8190 while matches!(
8191 frames.peek(),
8192 Some(Frame::PushResult {
8193 status: PushStatus::Applied | PushStatus::Cached,
8194 ..
8195 })
8196 ) {
8197 if let Some(next) = frames.next() {
8198 results.push(next);
8199 }
8200 }
8201 }
8202 if self
8203 .handle_push_results(
8204 &results,
8205 &pushed_ids,
8206 &rejection_details_by_commit,
8207 &mut report,
8208 last_final_push_result_id.as_deref(),
8209 )
8210 .is_err()
8211 {
8212 failure = Some((
8213 "client.outcome_persistence_failed".to_owned(),
8214 "local commit outcome could not be persisted".to_owned(),
8215 None,
8216 None,
8217 ));
8218 break;
8219 }
8220 }
8221 Frame::PushResultDetails { .. } => {}
8222 Frame::SubStart {
8223 id,
8224 status,
8225 reason_code,
8226 bootstrap,
8227 fenced,
8228 } => {
8229 let mut body = Vec::new();
8232 let mut sub_end: Option<(i64, Option<String>)> = None;
8233 let mut error: Option<Frame> = None;
8234 for inner in frames.by_ref() {
8235 match inner {
8236 Frame::SubEnd {
8237 next_cursor,
8238 bootstrap_state,
8239 } => {
8240 sub_end = Some((next_cursor, bootstrap_state.map(|r| r.0)));
8241 break;
8242 }
8243 inner @ Frame::Error { .. } => {
8244 error = Some(inner);
8245 break;
8246 }
8247 Frame::Unknown { .. } => {}
8248 other => body.push(other),
8249 }
8250 }
8251 let ended = sub_end.is_some();
8252 let section = SectionStart {
8253 id,
8254 status,
8255 reason_code,
8256 bootstrap,
8257 fenced,
8258 };
8259 match self.process_section(
8260 transport,
8261 §ion,
8262 body,
8263 sub_end,
8264 meta,
8265 &mut report,
8266 ) {
8267 Err(SectionError::Abort(code, message)) => {
8268 failure = Some((code, message, None, None));
8269 break;
8270 }
8271 Err(SectionError::Transport(error)) => {
8272 failure = Some((error.code, error.message, None, error.details));
8273 break;
8274 }
8275 _ => {}
8276 }
8277 match error {
8278 Some(Frame::Error {
8279 code,
8280 message,
8281 recommended_action,
8282 details,
8283 ..
8284 }) => {
8285 failure = Some(Self::error_frame_failure(
8286 code,
8287 message,
8288 recommended_action,
8289 details,
8290 ));
8291 break;
8292 }
8293 Some(_) => unreachable!("only an ERROR closes a section early"),
8294 None if !ended => {
8295 failure = Some((
8296 "sync.invalid_request".to_owned(),
8297 "unit section without SUB_END".to_owned(),
8298 None,
8299 None,
8300 ));
8301 break;
8302 }
8303 None => {}
8304 }
8305 }
8306 Frame::LiveStart {
8307 status,
8308 reason_code,
8309 } => {
8310 let receivers = match self.stored(load_units(&self.conn)) {
8311 Ok(units) => units
8312 .into_iter()
8313 .filter(|unit| {
8314 unit.status == UnitStatus::Active
8315 && unit.echo.is_some()
8316 && !unit.bootstrapping()
8317 })
8318 .collect(),
8319 Err(message) => {
8320 failure = Some(("storage.failed".to_owned(), message, None, None));
8321 break;
8322 }
8323 };
8324 live = Some((status, reason_code, receivers));
8325 }
8326 Frame::Commit {
8327 commit_seq,
8328 tables,
8329 changes,
8330 ..
8331 } => {
8332 let Some((LiveStatus::Active, _, receivers)) = &live else {
8333 continue;
8334 };
8335 let receivers = receivers.clone();
8336 match self.apply_live_commit(
8337 &receivers,
8338 &tables,
8339 changes,
8340 commit_seq,
8341 AppliedServerCommitSource::Pull,
8342 ) {
8343 Ok(applied) => report.commits_applied += u32::from(applied),
8344 Err(error) => {
8345 failure = Some((error.code, error.message, None, error.details));
8346 break;
8347 }
8348 }
8349 }
8350 Frame::LiveEnd {
8351 through_seq,
8352 echo_digest,
8353 } => {
8354 let Some((status, reason_code, _)) = live.take() else {
8355 continue;
8356 };
8357 live_ended = true;
8358 live = Some((status, String::new(), Vec::new()));
8359 if let Err(message) = self.finish_live_section(
8360 status,
8361 &reason_code,
8362 through_seq,
8363 echo_digest,
8364 &meta.registration_digest,
8365 &mut report,
8366 ) {
8367 failure = Some(("storage.failed".to_owned(), message, None, None));
8368 break;
8369 }
8370 }
8371 Frame::Lease {
8372 lease_id,
8373 expires_at_ms,
8374 } => {
8375 if let Err(message) = self.set_lease_state(Some(LeaseState {
8378 lease_id: Some(lease_id),
8379 expires_at_ms: Some(expires_at_ms),
8380 error_code: None,
8381 })) {
8382 failure = Some(("storage.failed".to_owned(), message, None, None));
8383 break;
8384 }
8385 }
8386 Frame::Error {
8387 code,
8388 message,
8389 recommended_action,
8390 details,
8391 ..
8392 } => {
8393 failure = Some(Self::error_frame_failure(
8396 code,
8397 message,
8398 recommended_action,
8399 details,
8400 ));
8401 break;
8402 }
8403 Frame::Unknown { .. } => {}
8404 _ => {
8405 failure = Some((
8406 "sync.invalid_request".to_owned(),
8407 "unexpected frame in response".to_owned(),
8408 None,
8409 None,
8410 ));
8411 break;
8412 }
8413 }
8414 }
8415
8416 let applied = match failure {
8417 Some(failure) => Err(failure),
8418 None => self
8423 .rebuild_overlay_if_dirty()
8424 .and_then(|()| self.drain_pending_evictions())
8425 .map_err(|message| ("storage.failed".to_owned(), message, None, None)),
8426 };
8427 if let Err(message) = self.finish_coalesced_apply() {
8430 return SyncOutcome::Failed {
8431 details: None,
8432 error_code: "storage.failed".into(),
8433 message,
8434 recommended_action: None,
8435 };
8436 }
8437 if let Err((error_code, message, recommended_action, details)) = applied {
8438 return SyncOutcome::Failed {
8439 details,
8440 error_code,
8441 message,
8442 recommended_action,
8443 };
8444 }
8445 let catching_up = match self.stored(load_units(&self.conn)) {
8446 Ok(units) => units
8447 .into_iter()
8448 .filter(|unit| unit.status == UnitStatus::Active && unit.cursor.is_some())
8449 .map(|unit| unit.id)
8450 .collect::<Vec<_>>(),
8451 Err(message) => {
8452 return SyncOutcome::Failed {
8453 details: None,
8454 error_code: "storage.failed".into(),
8455 message,
8456 recommended_action: None,
8457 }
8458 }
8459 };
8460 let status = live.map(|(status, _, _)| status);
8464 if !live_ended || status != Some(LiveStatus::Active) || !catching_up.is_empty() {
8465 self.set_sync_needed(true, status == Some(LiveStatus::Unregistered));
8466 }
8467 self.ack_after_pull(transport);
8468 if self.upgrading && catching_up.is_empty() {
8471 self.set_upgrading(false);
8472 }
8473 report.bootstrapping = catching_up;
8474 SyncOutcome::Ok(report)
8475 }
8476
8477 fn error_frame_failure(
8479 code: String,
8480 message: String,
8481 recommended_action: String,
8482 details: Option<RawJson>,
8483 ) -> (String, String, Option<String>, Option<Value>) {
8484 let recommended_action = (!recommended_action.is_empty()).then_some(recommended_action);
8485 let details = details
8486 .and_then(|details| serde_json::from_str::<Value>(&details.0).ok())
8487 .filter(Value::is_object);
8488 (code, message, recommended_action, details)
8489 }
8490
8491 fn finish_live_section(
8496 &mut self,
8497 status: LiveStatus,
8498 reason_code: &str,
8499 through_seq: i64,
8500 echo_digest: Option<[u8; 32]>,
8501 registration_digest: &str,
8502 report: &mut SyncReport,
8503 ) -> Result<(), String> {
8504 let rollback = self.capture();
8505 let resets = report.resets.len();
8506 self.begin_observation("syncular_live_end")?;
8507 let finished = (|| {
8508 let mut batch = ChangeAccumulator::default();
8509 let before = self.stored(replica_cursor(&self.conn))?;
8510 let mut cursor = if status == LiveStatus::Unregistered {
8511 before
8512 } else {
8513 -1
8514 };
8515 let joined = before.max(through_seq);
8516 for unit in self.stored(load_units(&self.conn))? {
8517 if unit.status != UnitStatus::Active || unit.bootstrapping() {
8518 continue;
8519 }
8520 match status {
8521 LiveStatus::Reset if unit.cursor.is_none() => {
8524 for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
8525 batch.window(&base_key, &value);
8526 }
8527 report.resets.push(unit.id.clone());
8528 self.stored(save_unit(
8529 &self.conn,
8530 &UnitRecord {
8531 reason_code: Some(reason_code.to_owned()),
8532 cursor: Some(-1),
8533 seeded: Vec::new(),
8534 ..unit
8535 },
8536 ))?;
8537 }
8538 LiveStatus::Active => {
8540 let next = unit.cursor.unwrap_or(joined).max(through_seq);
8541 if next >= joined {
8542 cursor = joined;
8543 }
8544 if unit.cursor.is_some() {
8545 self.stored(save_unit(
8546 &self.conn,
8547 &UnitRecord {
8548 cursor: (next < joined).then_some(next),
8549 ..unit
8550 },
8551 ))?;
8552 }
8553 }
8554 _ => {}
8555 }
8556 }
8557 self.set_meta(REPLICA_CURSOR_KEY, &cursor.to_string())?;
8558 self.set_meta(
8559 ECHO_DIGEST_KEY,
8560 &echo_digest
8561 .map(|digest| bytes_to_hex(&digest))
8562 .unwrap_or_default(),
8563 )?;
8564 if status == LiveStatus::Unregistered {
8565 self.delete_meta(REGISTERED_DIGEST_KEY)?;
8566 } else {
8567 self.set_meta(REGISTERED_DIGEST_KEY, registration_digest)?;
8568 }
8569 self.finish_observation("syncular_live_end", batch)
8570 })();
8571 if finished.is_err() {
8572 self.rollback_observation("syncular_live_end");
8573 self.restore(rollback);
8574 report.resets.truncate(resets);
8575 }
8576 finished
8577 }
8578
8579 fn handle_push_results(
8582 &mut self,
8583 frames: &[Frame],
8584 pushed_ids: &HashSet<&str>,
8585 rejection_details_by_commit: &HashMap<String, BTreeMap<i32, RejectionDetails>>,
8586 report: &mut SyncReport,
8587 last_final_push_result_id: Option<&str>,
8588 ) -> Result<(), String> {
8589 self.begin_observation("syncular_push_results")?;
8590 let rollback = self.capture();
8591 let conflict_count = self.conflicts.len();
8592 let applied_count = report.applied.len();
8593 let rejected_count = report.rejected.len();
8594 let retryable_count = report.retryable.len();
8595 let mut drained = Vec::new();
8596 let mut batch = ChangeAccumulator::default();
8597 let persisted = (|| {
8598 for frame in frames {
8599 let Frame::PushResult {
8600 client_commit_id,
8601 status,
8602 results,
8603 commit_seq,
8604 } = frame
8605 else {
8606 return Err("unexpected acknowledgement frame".to_owned());
8607 };
8608 if !pushed_ids.contains(client_commit_id.as_str()) {
8609 continue;
8610 }
8611 let Some(index) = self
8612 .outbox
8613 .iter()
8614 .position(|commit| commit.client_commit_id == *client_commit_id)
8615 else {
8616 continue;
8617 };
8618 let status = *status;
8619 let rejection_details = rejection_details_by_commit.get(client_commit_id);
8620 let operations = self.outbox[index].ops.clone();
8621 match status {
8622 PushStatus::Applied | PushStatus::Cached => {
8623 let sequence =
8626 commit_seq.ok_or_else(|| "ACK lacks a commit sequence".to_owned())?;
8627 let affected: HashSet<_> = operations
8628 .iter()
8629 .map(|op| (op.table.as_str(), op.row_id.as_str()))
8630 .collect();
8631 let prior = self.acknowledged_operations(Some(&affected), None)?;
8632 for (op_index, operation) in operations.iter().enumerate() {
8633 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))
8634 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
8635 if delivered {
8636 continue;
8637 }
8638 let table = self
8639 .schema
8640 .table(&operation.table)
8641 .ok_or_else(|| "sync.unknown_table".to_owned())?;
8642 let mut intended: Map<String, Value> = self
8643 .stored_row(table, &operation.row_id, true)?
8644 .map(|(row, _)| {
8645 table
8646 .columns
8647 .iter()
8648 .zip(&row)
8649 .map(|(column, value)| {
8650 (column.name.clone(), column_value_to_json(value))
8651 })
8652 .collect()
8653 })
8654 .unwrap_or_default();
8655 let mut scope_image = intended.clone();
8656 for op in prior
8657 .iter()
8658 .chain(
8659 self.failed_commits
8660 .iter()
8661 .flat_map(|(commit, _)| &commit.ops),
8662 )
8663 .chain(
8664 self.outbox
8665 .iter()
8666 .take(index)
8667 .flat_map(|commit| &commit.ops),
8668 )
8669 .chain(operations.iter().take(op_index + 1))
8670 {
8671 if op.table != operation.table || op.row_id != operation.row_id {
8672 continue;
8673 }
8674 if let Some(values) = &op.values {
8675 intended.extend(values.clone());
8676 } else {
8677 scope_image = intended.clone();
8678 intended.clear();
8679 }
8680 }
8681 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)",
8682 rusqlite::params![client_commit_id, op_index as i64, operation.table, operation.row_id, sequence,
8683 serde_json::to_string(&CommitOperation::from(operation)).map_err(|_| "sync.local_corrupt".to_owned())?,
8684 serde_json::to_string(if operation.upsert { &intended } else { &scope_image }).map_err(|_| "sync.local_corrupt".to_owned())?])
8685 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
8686 }
8687 let journal_results = results
8688 .iter()
8689 .map(|result| {
8690 let op_index = match result {
8691 OpResult::Applied { op_index }
8692 | OpResult::Conflict { op_index, .. }
8693 | OpResult::Error { op_index, .. } => *op_index,
8694 };
8695 CommitOperationOutcome::Applied { op_index }
8696 })
8697 .collect::<Vec<_>>();
8698 let outcome_status = if status == PushStatus::Applied {
8699 CommitOutcomeStatus::Applied
8700 } else {
8701 CommitOutcomeStatus::Cached
8702 };
8703 let persisted = self
8704 .persist_commit_outcome(
8705 client_commit_id,
8706 outcome_status,
8707 &journal_results,
8708 None,
8709 )
8710 .and_then(|()| self.delete_outbox_persisted(client_commit_id));
8711 persisted?;
8712 self.sync_needed = true;
8713 batch.status = true;
8714 batch.outcomes = true;
8715 }
8716 PushStatus::Rejected => {
8717 if results.iter().any(|result| {
8718 matches!(
8719 result,
8720 OpResult::Error {
8721 code,
8722 retryable: true,
8723 ..
8724 } if code == "sync.idempotency_cache_miss"
8725 )
8726 }) {
8727 report.retryable.push(client_commit_id.to_owned());
8730 continue;
8731 }
8732
8733 let mut journal_results = Vec::with_capacity(results.len());
8734 let mut conflicts = Vec::new();
8735 let mut rejections = Vec::new();
8736 for result in results {
8737 match result {
8738 OpResult::Applied { op_index } => {
8739 journal_results.push(CommitOperationOutcome::Applied {
8740 op_index: *op_index,
8741 });
8742 }
8743 OpResult::Conflict {
8744 op_index,
8745 code,
8746 message,
8747 server_version,
8748 server_row,
8749 conflict_columns: conflict_columns_bitmap,
8750 } => {
8751 let operation = operations
8752 .get(*op_index as usize)
8753 .map(CommitOperation::from);
8754 let (table, row_id) = operation
8755 .as_ref()
8756 .map(|op| (op.table.clone(), op.row_id.clone()))
8757 .unwrap_or_default();
8758 let server_row_json = self
8759 .schema
8760 .table(&table)
8761 .and_then(|t| {
8762 decode_row_bytes(t, server_row, &self.encryption)
8763 .ok()
8764 .map(|row| (t, row))
8765 })
8766 .map(|(t, row)| {
8767 let mut map = Map::new();
8768 for (i, column) in t.columns.iter().enumerate() {
8769 map.insert(
8770 column.name.clone(),
8771 column_value_to_json(
8772 row.get(i).unwrap_or(&None),
8773 ),
8774 );
8775 }
8776 map
8777 })
8778 .unwrap_or_default();
8779 let conflict_columns = self
8782 .schema
8783 .table(&table)
8784 .map(|t| {
8785 t.columns
8786 .iter()
8787 .enumerate()
8788 .filter(|(index, _)| {
8789 conflict_columns_bitmap
8790 .get(index / 8)
8791 .is_some_and(|byte| {
8792 byte & (1 << (index % 8)) != 0
8793 })
8794 })
8795 .map(|(_, column)| column.name.clone())
8796 .collect::<Vec<_>>()
8797 })
8798 .unwrap_or_default();
8799 let conflict = ConflictRecord {
8800 client_commit_id: client_commit_id.to_owned(),
8801 op_index: *op_index,
8802 table,
8803 row_id,
8804 code: code.clone(),
8805 message: message.clone(),
8806 server_version: *server_version,
8807 server_row: server_row_json,
8808 conflict_columns,
8809 operation,
8810 };
8811 journal_results.push(CommitOperationOutcome::Conflict {
8812 conflict: conflict.clone(),
8813 });
8814 conflicts.push(conflict);
8815 }
8816 OpResult::Error {
8817 op_index,
8818 code,
8819 message,
8820 retryable,
8821 } => {
8822 let rejection = RejectionRecord {
8823 client_commit_id: client_commit_id.to_owned(),
8824 op_index: *op_index,
8825 code: code.clone(),
8826 message: message.clone(),
8827 retryable: *retryable,
8828 details: rejection_details
8829 .and_then(|details| details.get(op_index))
8830 .cloned(),
8831 operation: operations
8832 .get(*op_index as usize)
8833 .map(CommitOperation::from),
8834 };
8835 journal_results.push(CommitOperationOutcome::Error {
8836 rejection: rejection.clone(),
8837 });
8838 rejections.push(rejection);
8839 }
8840 }
8841 }
8842 if self.retain_failed_commits {
8843 self.retain_failed_commit(client_commit_id, &operations)?;
8844 }
8845 let outcome_status = if conflicts.is_empty() {
8846 CommitOutcomeStatus::Rejected
8847 } else {
8848 CommitOutcomeStatus::Conflict
8849 };
8850 let persisted = self
8851 .persist_commit_outcome(
8852 client_commit_id,
8853 outcome_status,
8854 &journal_results,
8855 Some(&operations),
8856 )
8857 .and_then(|()| self.delete_outbox_persisted(client_commit_id));
8858 persisted?;
8859 batch.conflicts = !conflicts.is_empty();
8860 batch.rejections = !rejections.is_empty();
8861 batch.status = true;
8862 batch.outcomes = true;
8863 self.conflicts.extend(conflicts);
8864 self.rejections.extend(rejections);
8865 }
8866 }
8867 drained.push(self.outbox.remove(index));
8868 if batch.status {
8869 for operation in &operations {
8870 if !self.record_row_scopes(
8871 &mut batch,
8872 &operation.table,
8873 &operation.row_id,
8874 false,
8875 ) {
8876 batch.table(&operation.table);
8877 }
8878 }
8879 }
8880 match status {
8881 PushStatus::Applied | PushStatus::Cached => {
8882 report.applied.push(client_commit_id.to_owned())
8883 }
8884 PushStatus::Rejected => report.rejected.push(client_commit_id.to_owned()),
8885 }
8886 }
8887 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)) {
8888 self.prune_commit_outcomes()?;
8889 }
8890 self.reconcile_rows(&drained)?;
8891 self.rebuild_overlay_if_dirty()?;
8892 self.finish_observation("syncular_push_results", batch)
8893 })();
8894 if let Err(error) = persisted {
8895 self.rollback_observation("syncular_push_results");
8896 self.restore(rollback);
8897 report.applied.truncate(applied_count);
8898 report.rejected.truncate(rejected_count);
8899 report.retryable.truncate(retryable_count);
8900 return Err(error);
8901 }
8902 if !rollback.sync_needed && self.sync_needed {
8903 self.sync_intent_queue.push_back(SyncIntent::Interactive);
8904 }
8905 report.conflicts += (self.conflicts.len() - conflict_count) as u32;
8906 Ok(())
8907 }
8908
8909 fn push_result_is_final(status: PushStatus, results: &[OpResult]) -> bool {
8910 status != PushStatus::Rejected
8911 || !results.iter().any(|result| {
8912 matches!(
8913 result,
8914 OpResult::Error {
8915 code,
8916 retryable: true,
8917 ..
8918 } if code == "sync.idempotency_cache_miss"
8919 )
8920 })
8921 }
8922
8923 fn process_section(
8931 &mut self,
8932 transport: &mut dyn Transport,
8933 start: &SectionStart,
8934 body: Vec<Frame>,
8935 sub_end: Option<(i64, Option<String>)>,
8936 meta: &RequestMeta,
8937 report: &mut SyncReport,
8938 ) -> Result<(), SectionError> {
8939 let storage = |message| SectionError::Abort("storage.failed".to_owned(), message);
8940 let Some(unit) = self
8941 .stored(get_unit(&self.conn, &start.id))
8942 .map_err(storage)?
8943 .filter(|unit| unit.status == UnitStatus::Active)
8944 else {
8945 return Ok(());
8946 };
8947 let echo: Vec<EchoRecord> = start
8948 .fenced
8949 .iter()
8950 .map(|record| EchoRecord {
8951 table: record.table.clone(),
8952 status: record.status.name().to_owned(),
8953 scopes: record.scopes.iter().cloned().collect(),
8954 })
8955 .collect();
8956 let mut seeded: BTreeSet<String> = if unit.bootstrap_state.is_none() {
8958 BTreeSet::new()
8959 } else {
8960 unit.seeded.iter().cloned().collect()
8961 };
8962 let applied = (|| {
8963 for frame in body {
8964 match frame {
8965 Frame::SegmentInline { payload } => {
8966 let segment = decode_rows_segment(&payload).map_err(|e| {
8967 SectionError::Abort(e.code.as_str().to_owned(), e.detail)
8968 })?;
8969 self.progress.update(|p| {
8970 p.phase = ProgressPhase::Import;
8971 p.unit_id = Some(unit.id.clone());
8972 p.table = Some(segment.table.clone());
8973 p.segment_id = None;
8974 p.bytes_received = payload.len() as u64;
8975 p.bytes_total = Some(payload.len() as u64);
8976 p.rows_processed = 0;
8977 p.rows_total =
8978 Some(segment.blocks.iter().map(|block| block.len() as u64).sum());
8979 p.import_write_ms = None;
8980 p.import_commit_ms = None;
8981 });
8982 let (pair, clear, effective) =
8983 self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
8984 report.segment_rows_applied +=
8985 self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
8986 seeded.insert(segment.table);
8987 }
8988 Frame::SegmentRef {
8989 segment_id,
8990 byte_length,
8991 media_type,
8992 table,
8993 row_count,
8994 as_of_commit_seq,
8995 scope_digest,
8996 row_cursor,
8997 next_row_cursor,
8998 url,
8999 url_expires_at_ms,
9000 ..
9001 } => {
9002 let advertised = match media_type {
9005 MediaType::Rows => {
9006 meta.accept & ACCEPT_EXTERNAL_ROWS != 0
9007 || meta.accept & ACCEPT_INLINE_ROWS != 0
9008 }
9009 MediaType::Sqlite => meta.accept & ACCEPT_SQLITE != 0,
9010 };
9011 if !advertised {
9012 return Err(SectionError::Abort(
9013 "sync.invalid_request".to_owned(),
9014 format!(
9015 "SEGMENT_REF mediaType {} was not advertised in accept (§4.2)",
9016 media_type.name()
9017 ),
9018 ));
9019 }
9020 self.progress.update(|p| {
9021 p.phase = ProgressPhase::Download;
9022 p.unit_id = Some(unit.id.clone());
9023 p.table = Some(table.clone());
9024 p.segment_id = Some(segment_id.clone());
9025 p.bytes_received = 0;
9026 p.bytes_total = u64::try_from(byte_length).ok();
9027 p.rows_processed = 0;
9028 p.rows_total = u64::try_from(row_count).ok();
9029 p.import_write_ms = None;
9030 p.import_commit_ms = None;
9031 });
9032 let observer = self.progress.clone();
9033 let mut on_progress = |bytes| observer.update(|p| p.bytes_received = bytes);
9034 let bytes = if let Some(url) = url {
9035 if meta.accept & ACCEPT_SIGNED_URLS == 0 {
9040 return Err(SectionError::Abort(
9041 "sync.invalid_request".to_owned(),
9042 "SEGMENT_REF carries a url but accept bit 3 was not advertised (§5.4)"
9043 .to_owned(),
9044 ));
9045 }
9046 if url_expires_at_ms.is_some_and(|exp| {
9048 exp <= transport
9049 .segment_fetch_started_at(&url)
9050 .unwrap_or_else(|| self.clock_now_ms())
9051 }) {
9052 return Err(SectionError::Abort(
9053 "sync.segment_expired".to_owned(),
9054 format!(
9055 "signed URL for segment {segment_id} expired before fetch — re-pull mints fresh descriptors (§5.4)"
9056 ),
9057 ));
9058 }
9059 transport
9060 .fetch_url(
9061 &url,
9062 u64::try_from(byte_length).unwrap_or(0),
9063 &mut on_progress,
9064 )
9065 .map_err(|e| self.segment_fetch_failed(e))?
9066 } else {
9067 let requested_scopes_json =
9069 canonical_scope_json(&unit_scope_lists(&unit.scopes));
9070 transport
9071 .download_segment(
9072 &SegmentRequest {
9073 segment_id: segment_id.clone(),
9074 table: table.clone(),
9075 requested_scopes_json,
9076 byte_length: u64::try_from(byte_length).unwrap_or(0),
9077 },
9078 &mut on_progress,
9079 )
9080 .map_err(|e| self.segment_fetch_failed(e))?
9081 };
9082 if bytes.len() as i64 > byte_length {
9086 self.schedule_background_retry();
9087 return Err(SectionError::Abort(
9088 "sync.invalid_request".to_owned(),
9089 "segment exceeds its byteLength".to_owned(),
9090 ));
9091 }
9092 on_progress(bytes.len() as u64);
9093 let digest = Sha256::digest(&bytes);
9094 let expected = segment_id
9095 .strip_prefix("sha256:")
9096 .unwrap_or(segment_id.as_str());
9097 if bytes_to_hex(&digest) != expected {
9098 self.schedule_background_retry();
9100 return Err(SectionError::Abort(
9101 "sync.invalid_request".to_owned(),
9102 "segment bytes do not match the content address (§5.1)".to_owned(),
9103 ));
9104 }
9105 self.progress.update(|p| p.phase = ProgressPhase::Import);
9106 if media_type == MediaType::Sqlite {
9107 if row_cursor.is_some() || next_row_cursor.is_some() {
9110 return Err(SectionError::Abort(
9111 "sync.invalid_request".to_owned(),
9112 "sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)"
9113 .to_owned(),
9114 ));
9115 }
9116 let (pair, clear, effective) =
9117 self.segment_pair(&unit, &echo, &seeded, &table)?;
9118 report.segment_rows_applied += self.apply_sqlite_segment(
9119 &pair,
9120 &bytes,
9121 clear,
9122 &effective,
9123 &unit.id,
9124 row_count,
9125 as_of_commit_seq,
9126 &scope_digest,
9127 )?;
9128 seeded.insert(table);
9129 } else {
9130 let segment = decode_rows_segment(&bytes).map_err(|e| {
9131 SectionError::Abort(e.code.as_str().to_owned(), e.detail)
9132 })?;
9133 let (pair, clear, effective) =
9134 self.segment_pair(&unit, &echo, &seeded, &segment.table)?;
9135 report.segment_rows_applied +=
9136 self.apply_segment(&pair, &segment, clear, &effective, &unit.id)?;
9137 seeded.insert(segment.table);
9138 }
9139 }
9140 _ => {
9141 return Err(SectionError::Abort(
9142 "sync.invalid_request".to_owned(),
9143 "unexpected frame inside a unit section".to_owned(),
9144 ));
9145 }
9146 }
9147 }
9148 Ok(())
9149 })();
9150 match applied {
9151 Ok(()) => {}
9152 Err(SectionError::FailClosed) => {
9153 self.begin_observation("syncular_section_failure")
9156 .map_err(storage)?;
9157 let failed = (|| {
9158 let mut batch = ChangeAccumulator::default();
9159 for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9160 batch.window(&base_key, &value);
9161 }
9162 batch.status = true;
9163 self.stored(save_unit(
9164 &self.conn,
9165 &UnitRecord {
9166 status: UnitStatus::Failed,
9167 reason_code: Some("sync.scope_revoked".to_owned()),
9168 ..unit.clone()
9169 },
9170 ))?;
9171 self.finish_observation("syncular_section_failure", batch)
9172 })();
9173 if let Err(message) = failed {
9174 self.rollback_observation("syncular_section_failure");
9175 return Err(storage(message));
9176 }
9177 report.failed.push(unit.id);
9178 return Ok(());
9179 }
9180 Err(error) => return Err(error),
9181 }
9182 let Some((next_cursor, bootstrap_state)) = sub_end else {
9183 return Ok(());
9184 };
9185 let rollback = self.capture();
9186 let counts = (
9187 report.resets.len(),
9188 report.revoked.len(),
9189 report.failed.len(),
9190 );
9191 self.begin_observation("syncular_sub_end")
9192 .map_err(storage)?;
9193 let finished = self
9194 .finish_section(start, echo, next_cursor, bootstrap_state, seeded, report)
9195 .and_then(|batch| {
9196 self.rebuild_overlay_if_dirty()?;
9197 self.finish_observation("syncular_sub_end", batch)
9198 });
9199 if let Err(message) = finished {
9200 self.rollback_observation("syncular_sub_end");
9201 self.restore(rollback);
9202 report.resets.truncate(counts.0);
9203 report.revoked.truncate(counts.1);
9204 report.failed.truncate(counts.2);
9205 return Err(storage(message));
9206 }
9207 Ok(())
9208 }
9209
9210 #[allow(clippy::type_complexity)]
9213 fn segment_pair(
9214 &self,
9215 unit: &UnitRecord,
9216 echo: &[EchoRecord],
9217 seeded: &BTreeSet<String>,
9218 name: &str,
9219 ) -> Result<(TableSchema, bool, Vec<(String, Vec<String>)>), SectionError> {
9220 let table = self.schema.table(name).cloned().ok_or_else(|| {
9221 SectionError::Abort(
9222 "sync.schema_mismatch".to_owned(),
9223 format!("segment table {name:?} is not in the client schema"),
9224 )
9225 })?;
9226 let effective = covers(&table, &unit.scopes)
9227 .then(|| pair_scopes(&unit.scopes, name, Some(echo)))
9228 .flatten()
9229 .ok_or_else(|| {
9230 SectionError::Abort(
9231 "sync.invalid_request".to_owned(),
9232 "a segment names no active pair of its unit".to_owned(),
9233 )
9234 })?;
9235 Ok((table, !seeded.contains(name), effective))
9236 }
9237
9238 fn finish_section(
9245 &mut self,
9246 start: &SectionStart,
9247 echo: Vec<EchoRecord>,
9248 next_cursor: i64,
9249 bootstrap_state: Option<String>,
9250 seeded: BTreeSet<String>,
9251 report: &mut SyncReport,
9252 ) -> Result<ChangeAccumulator, String> {
9253 #[cfg(feature = "bench-internals")]
9254 let _phase = self.benchmark_phases.start(Phase::CursorPersist);
9255 let mut batch = ChangeAccumulator::default();
9256 let Some(unit) = self
9258 .stored(get_unit(&self.conn, &start.id))?
9259 .filter(|unit| unit.status == UnitStatus::Active)
9260 else {
9261 return Ok(batch);
9262 };
9263 for (base_key, value) in self.stored(window_refs(&self.conn, &unit.id))? {
9264 batch.window(&base_key, &value);
9265 }
9266 if start.status == SubStatus::Reset {
9267 report.resets.push(unit.id.clone());
9270 self.stored(save_unit(
9271 &self.conn,
9272 &UnitRecord {
9273 reason_code: Some(start.reason_code.clone()),
9274 cursor: Some(-1),
9275 bootstrap_state: None,
9276 seeded: Vec::new(),
9277 ..unit
9278 },
9279 ))?;
9280 return Ok(batch);
9281 }
9282 let revoked = start.status == SubStatus::Revoked;
9283 let mut units = None;
9284 let mut failed = false;
9285 let mut rearmed = false;
9286 for table in self.schema.tables.clone() {
9287 if !covers(&table, &unit.scopes) {
9288 continue;
9289 }
9290 let last = unit
9291 .echo
9292 .as_deref()
9293 .and_then(|last| pair_scopes(&unit.scopes, &table.name, Some(last)));
9294 let next = (!revoked)
9295 .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
9296 .flatten();
9297 rearmed |= unit.echo.is_some() && last.is_none() && next.is_some();
9299 if let (Some(last), None) = (&last, &next) {
9302 let units = match units {
9303 Some(ref units) => units,
9304 None => units.insert(self.stored(load_units(&self.conn))?),
9305 };
9306 let owners = unit_owners(units, &table, &unit.id);
9307 failed |= !self.purge_pair(&mut batch, &table, last, &owners)?;
9308 }
9309 }
9310 if revoked || failed {
9311 if revoked {
9312 report.revoked.push(unit.id.clone());
9313 }
9314 if failed {
9315 report.failed.push(unit.id.clone());
9316 }
9317 batch.status = true;
9318 self.stored(save_unit(
9319 &self.conn,
9320 &UnitRecord {
9321 status: if failed {
9322 UnitStatus::Failed
9323 } else {
9324 UnitStatus::Revoked
9325 },
9326 reason_code: Some(if failed {
9327 "sync.scope_revoked".to_owned()
9328 } else {
9329 start.reason_code.clone()
9330 }),
9331 cursor: Some(-1),
9332 bootstrap_state: None,
9333 seeded: Vec::new(),
9334 echo: None,
9335 ..unit
9336 },
9337 ))?;
9338 return Ok(batch);
9339 }
9340 let completed = start.bootstrap && !rearmed && bootstrap_state.is_none();
9341 let (cursor, bootstrap_state, seeded) = if rearmed {
9342 (Some(-1), None, Vec::new())
9343 } else if start.bootstrap {
9344 let seeded = if bootstrap_state.is_none() {
9345 Vec::new()
9346 } else {
9347 seeded.into_iter().collect()
9348 };
9349 (Some(next_cursor), bootstrap_state, seeded)
9350 } else {
9351 (
9352 unit.cursor,
9353 unit.bootstrap_state.clone(),
9354 unit.seeded.clone(),
9355 )
9356 };
9357 self.stored(save_unit(
9358 &self.conn,
9359 &UnitRecord {
9360 reason_code: None,
9361 echo: Some(echo.clone()),
9362 cursor,
9363 bootstrap_state,
9364 seeded,
9365 ..unit.clone()
9366 },
9367 ))?;
9368 if !completed {
9369 return Ok(batch);
9370 }
9371 for table in self.schema.tables.clone() {
9374 let Some(effective) = covers(&table, &unit.scopes)
9375 .then(|| pair_scopes(&unit.scopes, &table.name, Some(&echo)))
9376 .flatten()
9377 else {
9378 continue;
9379 };
9380 let mut statement = self
9381 .conn
9382 .prepare("SELECT id,intent_json FROM _syncular_acked_rows WHERE tbl=?1 AND commit_seq<=?2")
9383 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9384 let rows = statement
9385 .query_map(rusqlite::params![table.name, next_cursor], |row| {
9386 Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
9387 })
9388 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9389 let mut covered = HashSet::new();
9390 for row in rows {
9391 let (id, intent) =
9392 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9393 let values: Map<String, Value> =
9394 serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
9395 if owns_local_row(&table, &effective, &[], &values) {
9396 covered.insert(id);
9397 }
9398 }
9399 drop(statement);
9400 for id in covered {
9401 self.conn
9402 .execute(
9403 "DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3",
9404 rusqlite::params![table.name, id, next_cursor],
9405 )
9406 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
9407 self.overlay_dirty.table(&table.name);
9408 batch.table(&table.name);
9409 }
9410 }
9411 Ok(batch)
9412 }
9413
9414 fn purge_pair(
9420 &mut self,
9421 batch: &mut ChangeAccumulator,
9422 table: &TableSchema,
9423 last: &[(String, Vec<String>)],
9424 owners: &[Vec<(String, Vec<String>)>],
9425 ) -> Result<bool, String> {
9426 if local_scope_predicate(table, last, owners).is_err() {
9427 return Ok(false);
9428 }
9429 for commit in self.drop_failed_commits(|name, values| {
9430 name == table.name && owns_local_row(table, last, owners, values)
9431 })? {
9432 batch.conflicts = true;
9433 batch.rejections = true;
9434 batch.outcomes = true;
9435 for operation in commit.ops {
9436 batch.table(&operation.table);
9437 }
9438 }
9439 if !self.purge_scope_rows(&table.name, last, owners)? {
9440 return Err("storage.failed: the revoked scope purge failed".to_owned());
9441 }
9442 self.record_scope_map(batch, &table.name, last);
9443 if self.drop_doomed_outbox(table, last, owners)? {
9444 batch.status = true;
9445 batch.rejections = true;
9446 batch.outcomes = true;
9447 }
9448 self.delete_unreferenced_cached_blobs()?;
9450 Ok(true)
9451 }
9452
9453 fn apply_live_commit(
9458 &mut self,
9459 receivers: &[UnitRecord],
9460 tables: &[String],
9461 changes: Vec<ssp2::model::Change>,
9462 commit_seq: i64,
9463 source: AppliedServerCommitSource,
9464 ) -> Result<bool, TransportError> {
9465 let changes: Vec<ssp2::model::Change> = changes
9466 .into_iter()
9467 .filter(|change| {
9468 let Some(table) = tables
9470 .get(change.table_index as usize)
9471 .and_then(|name| self.schema.table(name))
9472 else {
9473 return true;
9474 };
9475 receivers.iter().any(|unit| {
9476 covers(table, &unit.scopes)
9477 && pair_scopes(&unit.scopes, &table.name, unit.echo.as_deref()).is_some_and(
9478 |scopes| {
9479 scopes.iter().all(|(variable, values)| {
9480 change
9481 .scopes
9482 .iter()
9483 .find(|(key, _)| key == variable)
9484 .is_some_and(|(_, value)| values.contains(value))
9485 })
9486 },
9487 )
9488 })
9489 })
9490 .collect();
9491 if changes.is_empty() {
9492 return Ok(false);
9493 }
9494 let affected_tables = changes
9495 .iter()
9496 .filter_map(|change| tables.get(change.table_index as usize))
9497 .cloned()
9498 .collect::<BTreeSet<_>>();
9499 let previous_batches = self.change_queue.len();
9500 self.apply_commit_frame(tables, &changes, commit_seq)?;
9501 if self.change_queue.len() > previous_batches {
9502 if let Some(batch) = self.change_queue.back_mut() {
9503 batch
9504 .applied_commits
9505 .extend(
9506 affected_tables
9507 .into_iter()
9508 .map(|table| AppliedServerCommit {
9509 table,
9510 commit_seq,
9511 source,
9512 }),
9513 );
9514 }
9515 }
9516 Ok(true)
9517 }
9518
9519 fn apply_commit_frame(
9521 &mut self,
9522 tables: &[String],
9523 changes: &[ssp2::model::Change],
9524 sequence: i64,
9525 ) -> Result<(), TransportError> {
9526 #[cfg(feature = "bench-internals")]
9527 let _phase = self.benchmark_phases.start(Phase::CommitApply);
9528 let rollback = self.capture();
9529 self.coalesce_unit(changes.len())
9530 .and_then(|()| self.begin_observation("syncular_commit"))
9531 .map_err(|message| TransportError::new("storage.failed", message))?;
9532 let applied = (|| {
9533 let mut batch = ChangeAccumulator::default();
9534 self.record_commit_changes(&mut batch, tables, changes);
9535 {
9536 let storage_failed = |error| {
9537 TransportError::new(
9538 "storage.failed",
9539 Self::sqlite_failure(&self.storage_failure, error),
9540 )
9541 };
9542 let pinned: HashSet<(&str, &str)> = self
9543 .outbox
9544 .iter()
9545 .flat_map(|commit| &commit.ops)
9546 .map(|op| (op.table.as_str(), op.row_id.as_str()))
9547 .collect();
9548 for change in changes {
9549 let table = tables.get(change.table_index as usize).ok_or_else(|| {
9550 TransportError::new(
9551 "sync.invalid_request",
9552 "change tableIndex out of range".to_owned(),
9553 )
9554 })?;
9555 if pinned.contains(&(table.as_str(), change.row_id.as_str())) {
9556 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)")
9557 .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
9558 .map_err(storage_failed)?;
9559 }
9560 self.conn.prepare_cached("DELETE FROM _syncular_acked_rows WHERE tbl=?1 AND id=?2 AND commit_seq<=?3")
9561 .and_then(|mut statement| statement.execute(rusqlite::params![table, change.row_id, sequence]))
9562 .map_err(storage_failed)?;
9563 }
9564 }
9565 self.apply_commit_changes(tables, changes)?;
9566 self.rebuild_overlay_if_dirty()
9567 .map_err(|message| TransportError::new("storage.failed", message))?;
9568 self.finish_observation("syncular_commit", batch)
9569 .map_err(|message| TransportError::new("storage.failed", message))
9570 })();
9571 if applied.is_err() {
9572 self.rollback_observation("syncular_commit");
9573 self.restore(rollback);
9574 }
9575 applied
9576 }
9577
9578 fn apply_commit_changes(
9579 &mut self,
9580 tables: &[String],
9581 changes: &[ssp2::model::Change],
9582 ) -> Result<(), TransportError> {
9583 let changed_tables: BTreeSet<&str> = changes
9588 .iter()
9589 .filter_map(|change| tables.get(change.table_index as usize))
9590 .map(String::as_str)
9591 .collect();
9592 let mut mirror_visible = !self.overlay_dirty.get();
9593 for name in &changed_tables {
9594 if mirror_visible
9595 && self
9596 .schema
9597 .table(name)
9598 .is_some_and(|table| table.indexes.iter().any(|index| index.unique))
9599 {
9600 let (pending, protected) = self
9601 .table_intent(name)
9602 .map_err(|message| TransportError::new("storage.failed", message))?;
9603 mirror_visible = !pending && !protected;
9604 }
9605 }
9606 for change in changes {
9607 let table_name = tables.get(change.table_index as usize).ok_or_else(|| {
9608 TransportError::new(
9609 "sync.invalid_request",
9610 "change tableIndex out of range".to_owned(),
9611 )
9612 })?;
9613 let table = self.schema.table(table_name).ok_or_else(|| {
9614 TransportError::new(
9615 "sync.schema_mismatch",
9616 format!("change targets unknown table {table_name:?}"),
9617 )
9618 })?;
9619 let landed = match change.op {
9620 Op::Upsert => {
9621 let payload = change.row.as_ref().ok_or_else(|| {
9622 TransportError::new(
9623 "sync.invalid_request",
9624 "upsert change without row payload".to_owned(),
9625 )
9626 })?;
9627 let row = {
9629 #[cfg(feature = "bench-internals")]
9630 let _phase = self.benchmark_phases.start(Phase::RowDecode);
9631 decode_row_bytes(table, payload, &self.encryption)?
9633 };
9634 let table_name = table.name.clone();
9635 let landed = self
9637 .write_base_row(&table_name, &row, change.row_version)
9638 .map_err(|m| TransportError::new("sync.invalid_request", m))?;
9639 if mirror_visible && landed {
9640 self.write_row(
9641 &visible_table(&table_name),
9642 &table_name,
9643 &row,
9644 change.row_version,
9645 )
9646 .map_err(|m| TransportError::new("sync.invalid_request", m))?;
9647 }
9648 landed
9649 }
9650 Op::Delete => self
9653 .delete_base_row(table_name, &change.row_id, change.row_version)
9654 .map_err(|m| TransportError::new("sync.invalid_request", m))?,
9655 };
9656 self.overlay_dirty.table(table_name);
9660 if mirror_visible && !(landed && change.op == Op::Upsert) {
9661 let predicate = row_id_predicate(table);
9662 let visible = visible_table(table_name);
9663 let mut statements = vec![format!("DELETE FROM {visible} WHERE {predicate}")];
9664 if !landed {
9665 statements.push(format!(
9666 "INSERT INTO {visible} SELECT * FROM {} WHERE {predicate}",
9667 base_table(table_name)
9668 ));
9669 }
9670 for statement in &statements {
9671 self.conn
9672 .prepare_cached(statement)
9673 .and_then(|mut statement| {
9674 statement.execute(rusqlite::params![change.row_id])
9675 })
9676 .map_err(|error| {
9677 TransportError::new("sync.invalid_request", error.to_string())
9678 })?;
9679 }
9680 }
9681 }
9682 if mirror_visible {
9683 let changed_rows: HashSet<(&str, &str)> = changes
9684 .iter()
9685 .map(|change| {
9686 (
9687 tables[change.table_index as usize].as_str(),
9688 change.row_id.as_str(),
9689 )
9690 })
9691 .collect();
9692 self.replay_overlay(&changed_tables, Some(&changed_rows))
9693 .map_err(|message| TransportError::new("storage.failed", message))?;
9694 self.overlay_dirty.set(false);
9695 }
9696 Ok(())
9697 }
9698
9699 fn apply_segment(
9704 &mut self,
9705 table: &TableSchema,
9706 segment: &RowsSegment,
9707 first_page: bool,
9708 effective: &[(String, Vec<String>)],
9709 unit_id: &str,
9710 ) -> Result<u32, SectionError> {
9711 let column = if segment.columns.len() != table.wire_columns.len() {
9716 Some(Value::from("count"))
9717 } else {
9718 segment
9719 .columns
9720 .iter()
9721 .zip(table.wire_columns.iter())
9722 .position(|(a, b)| a.name != b.name || a.ty != b.ty || a.nullable != b.nullable)
9723 .map(Value::from)
9724 };
9725 if segment.table != table.name
9726 || segment.schema_version != self.schema.version
9727 || column.is_some()
9728 {
9729 let mut details = Map::new();
9730 details.insert("table".to_owned(), Value::from(table.name.as_str()));
9731 if let Some(column) = column {
9732 details.insert("column".to_owned(), column);
9733 }
9734 return Err(SectionError::Transport(TransportError {
9735 code: "sync.schema_mismatch".to_owned(),
9736 message: "rows segment columns do not match the generated schema (§5.2)".to_owned(),
9737 details: Some(Value::Object(details)),
9738 }));
9739 }
9740 let mut applied = 0u32;
9741 let empty = Vec::new();
9742 let blocks = if segment.blocks.is_empty() {
9743 std::slice::from_ref(&empty)
9744 } else {
9745 &segment.blocks
9746 };
9747 for (index, block) in blocks.iter().enumerate() {
9748 let clear = first_page && index == 0;
9749 if !clear && block.is_empty() {
9750 continue;
9751 }
9752 let rollback = self.capture();
9753 let (pending, protected) = self
9754 .table_intent(&table.name)
9755 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9756 let reconcile_pending =
9757 !protected && pending && table.indexes.iter().any(|index| index.unique);
9758 let mirror_visible = !protected && !reconcile_pending;
9759 self.coalesce_unit(block.len())
9760 .and_then(|()| self.begin_observation("syncular_segment_block"))
9761 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9762 let outcome = (|| {
9763 self.rebuild_overlay_if_dirty()
9764 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9765 let mut changed_keys = Vec::new();
9766 let mut batch = ChangeAccumulator::default();
9767 if clear && self.clear_scope(table, effective, unit_id)? || !block.is_empty() {
9768 batch.table(&table.name);
9769 }
9770 for (row_index, row) in block.iter().enumerate() {
9771 let decrypted;
9772 let values = if table.has_encrypted_columns() {
9773 let mut values = row.values.clone();
9774 crate::values::decrypt_segment_row(table, &mut values, &self.encryption)
9775 .map_err(SectionError::Transport)?;
9776 decrypted = values;
9777 &decrypted
9778 } else {
9779 &row.values
9780 };
9781 if !self
9782 .write_base_row(&table.name, values, row.server_version)
9783 .map_err(|message| {
9784 SectionError::Abort("sync.invalid_request".into(), message)
9785 })?
9786 {
9787 continue;
9788 }
9789 if reconcile_pending {
9790 changed_keys.push(
9791 owned_sql_value(RowParam::Cell(&values[table.pk_index])).map_err(
9792 |message| SectionError::Abort("storage.failed".into(), message),
9793 )?,
9794 );
9795 }
9796 if mirror_visible {
9797 self.write_row(
9798 &visible_table(&table.name),
9799 &table.name,
9800 values,
9801 row.server_version,
9802 )
9803 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9804 }
9805 let processed = u64::from(applied) + row_index as u64 + 1;
9806 if processed.is_multiple_of(1024) {
9807 self.progress.update(|p| p.rows_processed = processed);
9808 }
9809 }
9810 self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
9811 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
9812 self.finish_observation("syncular_segment_block", batch)
9813 .map_err(|message| SectionError::Abort("storage.failed".into(), message))
9814 })();
9815 if let Err(error) = outcome {
9816 self.rollback_observation("syncular_segment_block");
9817 self.restore(rollback);
9818 return Err(error);
9819 }
9820 applied += block.len() as u32;
9821 self.progress
9822 .update(|p| p.rows_processed = u64::from(applied));
9823 std::thread::yield_now();
9824 }
9825 self.progress
9826 .update(|p| p.rows_processed = u64::from(applied));
9827 Ok(applied)
9828 }
9829
9830 #[allow(clippy::too_many_arguments)]
9838 fn apply_sqlite_segment(
9839 &mut self,
9840 table: &TableSchema,
9841 bytes: &[u8],
9842 first_page: bool,
9843 effective: &[(String, Vec<String>)],
9844 unit_id: &str,
9845 row_count: i64,
9846 as_of_commit_seq: i64,
9847 scope_digest: &str,
9848 ) -> Result<u32, SectionError> {
9849 let invalid = |detail: &str| {
9850 SectionError::Abort(
9851 "sync.invalid_request".to_owned(),
9852 format!("sqlite segment rejected: {detail} (§5.3)"),
9853 )
9854 };
9855 if table.has_encrypted_columns() {
9858 return Err(invalid("table has encrypted columns"));
9859 }
9860
9861 let directory = self
9865 .previous_version_replica_path()
9866 .and_then(|replica| std::path::Path::new(&replica).parent().map(Into::into))
9867 .unwrap_or_else(std::env::temp_dir);
9868 let path = directory.join(format!(".syncular-image-{}.tmp", uuid::Uuid::new_v4()));
9869 let outcome = (|| {
9870 let mut options = std::fs::OpenOptions::new();
9871 options.write(true).create_new(true);
9872 #[cfg(unix)]
9873 std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600);
9874 std::io::Write::write_all(
9875 &mut options
9876 .open(&path)
9877 .map_err(|_| invalid("image temp file write failed"))?,
9878 bytes,
9879 )
9880 .map_err(|_| invalid("image temp file write failed"))?;
9881 let img = rusqlite::Connection::open_with_flags(
9882 &path,
9883 rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY,
9884 )
9885 .map_err(|_| invalid("bytes do not open as a SQLite database"))?;
9886 self.apply_sqlite_image(
9887 &img,
9888 table,
9889 first_page,
9890 effective,
9891 unit_id,
9892 row_count,
9893 as_of_commit_seq,
9894 scope_digest,
9895 )
9896 })();
9897 let _ = std::fs::remove_file(&path);
9898 outcome
9899 }
9900
9901 #[allow(clippy::too_many_arguments)]
9902 fn apply_sqlite_image(
9903 &mut self,
9904 img: &rusqlite::Connection,
9905 table: &crate::schema::TableSchema,
9906 first_fresh_page: bool,
9907 effective: &[(String, Vec<String>)],
9908 unit_id: &str,
9909 row_count: i64,
9910 as_of_commit_seq: i64,
9911 scope_digest: &str,
9912 ) -> Result<u32, SectionError> {
9913 let invalid = |detail: String| {
9914 SectionError::Abort(
9915 "sync.invalid_request".to_owned(),
9916 format!("sqlite segment rejected: {detail} (§5.3)"),
9917 )
9918 };
9919
9920 type MetaRow = (i64, String, i64, i64, String, i64, i64);
9923 let meta: MetaRow = img
9924 .query_row(
9925 "SELECT format, \"table\", \"schemaVersion\", \"asOfCommitSeq\",
9926 \"scopeDigest\", \"rowCount\",
9927 (SELECT count(*) FROM _syncular_segment)
9928 FROM _syncular_segment",
9929 [],
9930 |row| {
9931 Ok((
9932 row.get(0)?,
9933 row.get(1)?,
9934 row.get(2)?,
9935 row.get(3)?,
9936 row.get(4)?,
9937 row.get(5)?,
9938 row.get(6)?,
9939 ))
9940 },
9941 )
9942 .map_err(|_| invalid("missing or unreadable _syncular_segment metadata".to_owned()))?;
9943 let (format, meta_table, schema_version, pin, digest, meta_rows, meta_count) = meta;
9944 if meta_count != 1 {
9945 return Err(invalid(format!(
9946 "_syncular_segment must contain exactly one row, found {meta_count}"
9947 )));
9948 }
9949 if format != 1 {
9950 return Err(invalid(format!("format {format}")));
9951 }
9952 if meta_table != table.name {
9953 return Err(invalid(format!("image table {meta_table:?}")));
9954 }
9955 if schema_version != i64::from(self.schema.version) {
9956 return Err(invalid(format!("schemaVersion {schema_version}")));
9957 }
9958 if pin != as_of_commit_seq {
9959 return Err(invalid(format!("asOfCommitSeq {pin}")));
9960 }
9961 if digest != scope_digest {
9962 return Err(invalid("scopeDigest mismatch".to_owned()));
9963 }
9964 if meta_rows != row_count {
9965 return Err(invalid(format!("rowCount {meta_rows}")));
9966 }
9967
9968 let mut names: Vec<String> = Vec::new();
9970 let mut primary_keys: Vec<String> = Vec::new();
9971 {
9972 let mut stmt = img
9973 .prepare(&format!("PRAGMA table_info({})", quote_ident(&table.name)))
9974 .map_err(|_| invalid("image data table missing".to_owned()))?;
9975 let mut rows = stmt
9976 .query([])
9977 .map_err(|_| invalid("image data table unreadable".to_owned()))?;
9978 while let Some(row) = rows
9979 .next()
9980 .map_err(|_| invalid("image data table unreadable".to_owned()))?
9981 {
9982 if row
9983 .get::<_, i64>(5)
9984 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?
9985 > 0
9986 {
9987 primary_keys.push(row.get(1).map_err(|error| {
9988 invalid(Self::sqlite_failure(&self.storage_failure, error))
9989 })?);
9990 }
9991 names.push(
9992 row.get::<_, String>(1)
9993 .map_err(|_| invalid("image data table unreadable".to_owned()))?,
9994 );
9995 }
9996 }
9997 let mut expected: Vec<&str> = table.columns.iter().map(|c| c.name.as_str()).collect();
9998 expected.push("_syncular_version");
9999 if names.len() != expected.len() || names.iter().zip(expected.iter()).any(|(a, b)| a != b) {
10000 return Err(SectionError::Transport(TransportError {
10001 code: "sync.schema_mismatch".to_owned(),
10002 message: "sqlite segment columns do not match the generated schema (§5.3)"
10003 .to_owned(),
10004 details: Some(serde_json::json!({ "table": table.name })),
10005 }));
10006 }
10007
10008 if primary_keys != vec![table.primary_key.clone()] {
10009 return Err(invalid(
10010 "image primary key does not match generated schema".into(),
10011 ));
10012 }
10013 let actual_count: i64 = img
10014 .query_row(
10015 &format!("SELECT count(*) FROM {}", quote_ident(&table.name)),
10016 [],
10017 |row| row.get(0),
10018 )
10019 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10020 if actual_count != row_count {
10021 return Err(invalid("image row count does not match descriptor".into()));
10022 }
10023 let insert = self.insert_row_sql(&base_table(&table.name), table);
10024 let visible_insert = self.insert_row_sql(&visible_table(&table.name), table);
10025 let column_list = names
10026 .iter()
10027 .map(|n| quote_ident(n))
10028 .collect::<Vec<_>>()
10029 .join(", ");
10030 let mut stmt = img
10031 .prepare(&format!(
10032 "SELECT {column_list} FROM {} ORDER BY {}",
10033 quote_ident(&table.name),
10034 quote_ident(&table.primary_key)
10035 ))
10036 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10037 let mut rows = stmt
10038 .query([])
10039 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10040 let mut applied = 0u32;
10041 let mut limit = 1024u32;
10042 let (mut write, mut commit) = (std::time::Duration::ZERO, std::time::Duration::ZERO);
10043 loop {
10044 let clear = applied == 0 && first_fresh_page;
10045 let rollback = self.capture();
10046 let (pending, protected) = self
10047 .table_intent(&table.name)
10048 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10049 let reconcile_pending =
10050 !protected && pending && table.indexes.iter().any(|index| index.unique);
10051 let mirror_visible = !protected && !reconcile_pending;
10052 let chunk = if pending || protected { 1024 } else { limit };
10055 self.coalesce_unit(chunk as usize)
10056 .and_then(|()| self.begin_observation("syncular_image_chunk"))
10057 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10058 let started = std::time::Instant::now();
10059 let result = (|| {
10060 self.rebuild_overlay_if_dirty()
10061 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10062 let mut changed_keys = Vec::new();
10063 let mut batch = ChangeAccumulator::default();
10064 if clear && self.clear_scope(table, effective, unit_id)? {
10065 batch.table(&table.name);
10066 }
10067 let mut processed = 0u32;
10068 {
10069 let mut ins = self.conn.prepare_cached(&insert).map_err(|error| {
10070 invalid(Self::sqlite_failure(&self.storage_failure, error))
10071 })?;
10072 let mut mirror = if mirror_visible {
10073 Some(self.conn.prepare_cached(&visible_insert).map_err(|error| {
10074 invalid(Self::sqlite_failure(&self.storage_failure, error))
10075 })?)
10076 } else {
10077 None
10078 };
10079 for _ in 0..chunk {
10080 let Some(row) = rows.next().map_err(|error| {
10081 invalid(Self::sqlite_failure(&self.storage_failure, error))
10082 })?
10083 else {
10084 break;
10085 };
10086 for (i, column) in table.columns.iter().enumerate() {
10087 let cell = row.get_ref(i).map_err(|error| {
10088 invalid(Self::sqlite_failure(&self.storage_failure, error))
10089 })?;
10090 let param = image_cell_param(column, cell).map_err(invalid)?;
10091 ins.raw_bind_parameter(i + 1, ¶m).map_err(|error| {
10092 invalid(Self::sqlite_failure(&self.storage_failure, error))
10093 })?;
10094 if let Some(mirror) = &mut mirror {
10095 mirror.raw_bind_parameter(i + 1, ¶m).map_err(|error| {
10096 invalid(Self::sqlite_failure(&self.storage_failure, error))
10097 })?;
10098 }
10099 }
10100 let version_index = table.columns.len();
10101 let version: i64 = row.get(version_index).map_err(|error| {
10102 invalid(Self::sqlite_failure(&self.storage_failure, error))
10103 })?;
10104 if version < 1 {
10105 return Err(invalid("image row version must be positive".into()));
10106 }
10107 ins.raw_bind_parameter(version_index + 1, version)
10108 .map_err(|error| {
10109 invalid(Self::sqlite_failure(&self.storage_failure, error))
10110 })?;
10111 let landed = ins.raw_execute().map_err(|error| {
10113 invalid(Self::sqlite_failure(&self.storage_failure, error))
10114 })? > 0;
10115 processed += 1;
10116 if processed.is_multiple_of(1024) && processed < chunk {
10117 self.progress
10118 .update(|p| p.rows_processed = u64::from(applied + processed));
10119 }
10120 if !landed {
10121 continue;
10122 }
10123 if let Some(mirror) = &mut mirror {
10124 mirror
10125 .raw_bind_parameter(version_index + 1, version)
10126 .map_err(|error| {
10127 invalid(Self::sqlite_failure(&self.storage_failure, error))
10128 })?;
10129 mirror.raw_execute().map_err(|error| {
10130 invalid(Self::sqlite_failure(&self.storage_failure, error))
10131 })?;
10132 }
10133 if reconcile_pending {
10134 changed_keys.push(row.get::<_, SqlValue>(table.pk_index).map_err(
10135 |error| invalid(Self::sqlite_failure(&self.storage_failure, error)),
10136 )?);
10137 }
10138 }
10139 }
10140 if processed > 0 {
10141 batch.table(&table.name);
10142 self.overlay_dirty.table(&table.name);
10143 }
10144 self.reconcile_import(table, &mut changed_keys, protected, reconcile_pending)
10145 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10146 let written = std::time::Instant::now();
10147 self.finish_observation("syncular_image_chunk", batch)
10148 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10149 Ok((processed, written))
10150 })();
10151 let (processed, written) = match result {
10152 Ok(done) => done,
10153 Err(error) => {
10154 self.rollback_observation("syncular_image_chunk");
10155 self.restore(rollback);
10156 return Err(error);
10157 }
10158 };
10159 let coalesced = self.coalesced.is_some();
10161 if coalesced {
10162 self.commit_coalesced_apply()
10163 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10164 }
10165 write += written - started;
10166 commit += written.elapsed();
10167 applied += processed;
10168 let last = processed < chunk || i64::from(applied) == actual_count;
10169 if last && self.conn.is_autocommit() {
10171 self.conn
10172 .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
10173 .map_err(|error| invalid(Self::sqlite_failure(&self.storage_failure, error)))?;
10174 }
10175 if coalesced {
10176 self.begin_coalesced_apply()
10177 .map_err(|message| SectionError::Abort("storage.failed".into(), message))?;
10178 }
10179 self.progress.update(|p| {
10180 p.rows_processed = u64::from(applied);
10181 p.import_write_ms = u64::try_from(write.as_millis()).ok();
10182 p.import_commit_ms = u64::try_from(commit.as_millis()).ok();
10183 });
10184 std::thread::yield_now();
10185 if last {
10186 break;
10187 }
10188 limit = (limit * 2).min(65_536);
10189 }
10190 if i64::from(applied) != actual_count {
10191 return Err(invalid(format!(
10192 "image yielded {applied} rows, expected {actual_count}"
10193 )));
10194 }
10195 Ok(applied)
10196 }
10197
10198 fn reconcile_rows(&self, drained: &[Arc<OutboxCommit>]) -> Result<(), String> {
10203 let names: BTreeSet<&str> = drained
10204 .iter()
10205 .flat_map(|commit| &commit.ops)
10206 .map(|op| op.table.as_str())
10207 .collect();
10208 for name in names {
10209 let Some(table) = self.schema.table(name) else {
10210 continue;
10211 };
10212 let ops = drained.iter().flat_map(|commit| &commit.ops);
10213 let tables = BTreeSet::from([name]);
10214 let rows: HashSet<_> = ops
10215 .clone()
10216 .map(|op| (op.table.as_str(), op.row_id.as_str()))
10217 .collect();
10218 let unique = table.indexes.iter().any(|index| index.unique);
10219 let acknowledged = if unique {
10220 self.acknowledged_operations(None, Some(&tables))?
10221 } else {
10222 Vec::new()
10223 };
10224 let peers = acknowledged
10225 .iter()
10226 .chain(
10227 self.failed_commits
10228 .iter()
10229 .flat_map(|(commit, _)| &commit.ops),
10230 )
10231 .chain(self.outbox.iter().flat_map(|commit| &commit.ops))
10232 .filter(|_| unique);
10233 self.restore_base_rows(table, &mut Vec::new(), peers.chain(ops.clone()))?;
10234 self.replay_overlay(&tables, (!unique).then_some(&rows))?;
10235 }
10236 Ok(())
10237 }
10238
10239 fn table_intent(&self, table: &str) -> Result<(bool, bool), String> {
10242 let touches = |op: &OutboxOp| op.table == table;
10243 Ok((
10244 self.outbox
10245 .iter()
10246 .flat_map(|commit| &commit.ops)
10247 .any(touches),
10248 self.failed_commits
10249 .iter()
10250 .flat_map(|(commit, _)| &commit.ops)
10251 .any(touches)
10252 || self
10253 .conn
10254 .query_row(
10255 "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows WHERE tbl=?1)",
10256 [table],
10257 |row| row.get(0),
10258 )
10259 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10260 ))
10261 }
10262
10263 fn reconcile_import(
10267 &mut self,
10268 table: &TableSchema,
10269 keys: &mut Vec<SqlValue>,
10270 protected: bool,
10271 restore: bool,
10272 ) -> Result<(), String> {
10273 if protected {
10274 return self.rebuild_overlay_if_dirty();
10275 }
10276 let pending = self.outbox.iter().flat_map(|commit| &commit.ops);
10277 if restore {
10278 self.restore_base_rows(table, keys, pending.clone())?;
10279 }
10280 self.apply_outbox_ops(pending.filter(|op| op.table == table.name))?;
10281 self.overlay_dirty.set(false);
10282 Ok(())
10283 }
10284
10285 fn restore_base_rows<'a>(
10289 &self,
10290 table: &TableSchema,
10291 keys: &mut Vec<SqlValue>,
10292 ops: impl IntoIterator<Item = &'a OutboxOp>,
10293 ) -> Result<(), String> {
10294 let visible = visible_table(&table.name);
10295 let base = base_table(&table.name);
10296 let pk = quote_ident(&table.primary_key);
10297 let predicate = row_id_predicate(table);
10298 let mut lookup = self.conn.prepare_cached(&format!(
10299 "SELECT {pk} FROM {base} WHERE {predicate} UNION SELECT {pk} FROM {visible} WHERE {predicate}"
10300 )).map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10301 let mut deleted = HashSet::new();
10302 for op in ops.into_iter().filter(|op| op.table == table.name) {
10303 if op.upsert {
10304 if let Some(values) = &op.values {
10305 let key = json_to_column_value(
10306 &table.columns[table.pk_index],
10307 values.get(&table.primary_key),
10308 )?;
10309 keys.push(owned_sql_value(RowParam::Cell(&key))?);
10310 }
10311 } else if deleted.insert(&op.row_id) {
10312 keys.extend(
10313 lookup
10314 .query_map([&op.row_id], |row| row.get::<_, SqlValue>(0))
10315 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
10316 .collect::<Result<Vec<_>, _>>()
10317 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10318 );
10319 }
10320 }
10321 for chunk in keys.chunks(400) {
10324 let holes = vec!["?"; chunk.len()].join(",");
10325 self.conn
10326 .prepare_cached(&format!("DELETE FROM {visible} WHERE {pk} IN ({holes})"))
10327 .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
10328 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10329 }
10330 let updates = table
10331 .columns
10332 .iter()
10333 .map(|column| column.name.as_str())
10334 .chain(std::iter::once("_syncular_version"))
10335 .filter(|name| *name != table.primary_key)
10336 .map(|name| {
10337 let name = quote_ident(name);
10338 format!("{name}=excluded.{name}")
10339 })
10340 .collect::<Vec<_>>()
10341 .join(",");
10342 for chunk in keys.chunks(400) {
10343 let holes = vec!["?"; chunk.len()].join(",");
10344 self.conn.prepare_cached(&format!("INSERT INTO {visible} SELECT * FROM {base} WHERE {pk} IN ({holes}) ON CONFLICT ({pk}) DO UPDATE SET {updates}"))
10345 .and_then(|mut statement| statement.execute(rusqlite::params_from_iter(chunk)))
10346 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10347 }
10348 Ok(())
10349 }
10350
10351 fn compile_local_data_purge(
10354 &self,
10355 input: &LocalDataPurgeInput,
10356 ) -> Result<(Vec<CompiledLocalDataPurgeTarget>, String), String> {
10357 let invalid = |message: String| format!("sync.invalid_request: {message}");
10358 if input.purge_id.is_empty()
10359 || input.purge_id.len() > 128
10360 || !is_local_operation_code_like(&input.purge_id)
10361 {
10362 return Err(invalid(
10363 "local purge purgeId must be a 1–128 character code-like identifier".to_owned(),
10364 ));
10365 }
10366 if input.targets.is_empty() || input.targets.len() > MAX_LOCAL_PURGE_TARGETS {
10367 return Err(invalid(format!(
10368 "local purge needs between 1 and {MAX_LOCAL_PURGE_TARGETS} targets"
10369 )));
10370 }
10371
10372 let mut deduplicated: BTreeMap<
10373 String,
10374 (CompiledLocalDataPurgeTarget, LocalDataPurgeTarget),
10375 > = BTreeMap::new();
10376 for target in &input.targets {
10377 let table = self.schema.table(&target.table).ok_or_else(|| {
10378 invalid(format!(
10379 "local purge names unknown table {:?}",
10380 target.table
10381 ))
10382 })?;
10383 if target.selectors.is_empty() || target.selectors.len() > MAX_LOCAL_PURGE_SELECTORS {
10384 return Err(invalid(format!(
10385 "local purge target {:?} needs between 1 and {MAX_LOCAL_PURGE_SELECTORS} selectors",
10386 target.table
10387 )));
10388 }
10389 let mut selectors = Vec::with_capacity(target.selectors.len());
10390 let mut canonical_selectors = BTreeMap::new();
10391 for (column_name, raw_values) in &target.selectors {
10392 let Some((column_index, column)) = table
10393 .columns
10394 .iter()
10395 .enumerate()
10396 .find(|(_, column)| column.name == *column_name)
10397 else {
10398 return Err(invalid(format!(
10399 "local purge target {:?} names unknown column {:?}",
10400 target.table, column_name
10401 )));
10402 };
10403 let encrypted = table
10404 .encrypted_columns
10405 .iter()
10406 .any(|candidate| candidate.index == column_index);
10407 if column.ty != ColumnType::String || encrypted {
10408 return Err(invalid(format!(
10409 "local purge selector {:?}.{:?} must be a plaintext string column",
10410 target.table, column_name
10411 )));
10412 }
10413 if raw_values.is_empty() || raw_values.len() > MAX_LOCAL_PURGE_VALUES {
10414 return Err(invalid(format!(
10415 "local purge selector {:?}.{:?} needs between 1 and {MAX_LOCAL_PURGE_VALUES} values",
10416 target.table, column_name
10417 )));
10418 }
10419 let mut values = raw_values.clone();
10420 values.sort();
10421 values.dedup();
10422 if values.iter().any(|value| {
10423 value.is_empty()
10424 || value.len() > MAX_LOCAL_PURGE_VALUE_LENGTH
10425 || !is_local_operation_code_like(value)
10426 }) {
10427 return Err(invalid(format!(
10428 "local purge selector values must be 1–{MAX_LOCAL_PURGE_VALUE_LENGTH} character code-like identifiers"
10429 )));
10430 }
10431 selectors.push((column_name.clone(), values.clone()));
10432 canonical_selectors.insert(column_name.clone(), values);
10433 }
10434 let canonical = LocalDataPurgeTarget {
10435 table: target.table.clone(),
10436 selectors: canonical_selectors,
10437 };
10438 let key = serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
10439 deduplicated.insert(
10440 key,
10441 (
10442 CompiledLocalDataPurgeTarget {
10443 table: target.table.clone(),
10444 selectors,
10445 },
10446 canonical,
10447 ),
10448 );
10449 }
10450 let targets = deduplicated
10451 .values()
10452 .map(|(compiled, _)| compiled.clone())
10453 .collect::<Vec<_>>();
10454 let canonical = deduplicated
10455 .values()
10456 .map(|(_, target)| target.clone())
10457 .collect::<Vec<_>>();
10458 let canonical_plan =
10459 serde_json::to_string(&canonical).map_err(|error| error.to_string())?;
10460 Ok((targets, canonical_plan))
10461 }
10462
10463 fn local_purge_base_row_ids(
10464 &self,
10465 targets: &[CompiledLocalDataPurgeTarget],
10466 ) -> Result<BTreeMap<String, BTreeSet<String>>, String> {
10467 let mut by_table: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
10468 for target in targets {
10469 let table = self
10470 .schema
10471 .table(&target.table)
10472 .ok_or_else(|| format!("sync.invalid_request: unknown table {:?}", target.table))?;
10473 let mut clauses = Vec::with_capacity(target.selectors.len());
10474 let mut params = Vec::new();
10475 for (column, values) in &target.selectors {
10476 clauses.push(format!(
10477 "{} IN ({})",
10478 quote_ident(column),
10479 values.iter().map(|_| "?").collect::<Vec<_>>().join(", ")
10480 ));
10481 params.extend(values.iter().cloned().map(SqlValue::Text));
10482 }
10483 let sql = format!(
10484 "SELECT CAST({} AS TEXT) FROM {} WHERE {}",
10485 quote_ident(&table.primary_key),
10486 base_table(&target.table),
10487 clauses.join(" AND ")
10488 );
10489 let mut statement = self
10490 .conn
10491 .prepare(&sql)
10492 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10493 let rows = statement
10494 .query_map(rusqlite::params_from_iter(params), |row| {
10495 let value = sql_ref_to_json(&table.columns[table.pk_index], row.get_ref(0)?);
10496 render_row_id_json(Some(&value))
10497 .map_err(|message| rusqlite::Error::ToSqlConversionFailure(message.into()))
10498 })
10499 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10500 let ids = by_table.entry(target.table.clone()).or_default();
10501 for row in rows {
10502 ids.insert(
10503 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?,
10504 );
10505 }
10506 }
10507 Ok(by_table)
10508 }
10509
10510 fn local_purge_values_match(
10511 target: &CompiledLocalDataPurgeTarget,
10512 values: &Map<String, Value>,
10513 ) -> bool {
10514 target.selectors.iter().all(|(column, allowed)| {
10515 values
10516 .get(column)
10517 .and_then(Value::as_str)
10518 .is_some_and(|value| allowed.iter().any(|candidate| candidate == value))
10519 })
10520 }
10521
10522 pub fn purge_local_data(
10526 &mut self,
10527 input: &LocalDataPurgeInput,
10528 ) -> Result<LocalDataPurgeResult, String> {
10529 let (targets, canonical_plan) = self.compile_local_data_purge(input)?;
10530 let meta_key = format!("localPurge:{}", input.purge_id);
10531 let applied_plan = self
10532 .conn
10533 .query_row(
10534 "SELECT value FROM _syncular_meta WHERE key = ?1",
10535 rusqlite::params![meta_key],
10536 |row| row.get::<_, String>(0),
10537 )
10538 .optional()
10539 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10540 if let Some(applied_plan) = applied_plan {
10541 if applied_plan != canonical_plan {
10542 return Err(format!(
10543 "sync.invalid_request: local purge id {:?} was already used with a different plan",
10544 input.purge_id
10545 ));
10546 }
10547 return Ok(LocalDataPurgeResult {
10548 already_applied: true,
10549 purged_rows: 0,
10550 dropped_commits: 0,
10551 });
10552 }
10553
10554 let _ = self.drop_previous_version();
10558
10559 let rollback = self.capture();
10560 self.begin_observation("syncular_local_purge")?;
10561 let applied = (|| -> Result<(ChangeAccumulator, LocalDataPurgeResult), String> {
10562 let row_ids = self.local_purge_base_row_ids(&targets)?;
10563 let retained_dropped = self.drop_failed_commits(|table, values| {
10564 targets.iter().any(|target| {
10565 target.table == table && Self::local_purge_values_match(target, values)
10566 })
10567 })?;
10568 let doomed = self
10569 .outbox
10570 .iter()
10571 .filter(|commit| {
10572 commit.ops.iter().any(|operation| {
10573 let matching_targets = targets
10574 .iter()
10575 .filter(|target| target.table == operation.table)
10576 .collect::<Vec<_>>();
10577 if matching_targets.is_empty() {
10578 return false;
10579 }
10580 if row_ids
10581 .get(&operation.table)
10582 .is_some_and(|ids| ids.contains(&operation.row_id))
10583 {
10584 return true;
10585 }
10586 operation.values.as_ref().is_some_and(|values| {
10587 matching_targets
10588 .iter()
10589 .any(|target| Self::local_purge_values_match(target, values))
10590 })
10591 })
10592 })
10593 .cloned()
10594 .collect::<Vec<_>>();
10595 let doomed_ids = doomed
10596 .iter()
10597 .map(|commit| commit.client_commit_id.clone())
10598 .collect::<BTreeSet<_>>();
10599 let mut batch = ChangeAccumulator::default();
10600 for commit in &retained_dropped {
10601 batch.conflicts = true;
10602 batch.rejections = true;
10603 batch.outcomes = true;
10604 for operation in &commit.ops {
10605 batch.table(&operation.table);
10606 }
10607 }
10608 let mut rejections = Vec::new();
10609 for commit in &doomed {
10610 for operation in &commit.ops {
10611 batch.table(&operation.table);
10612 self.overlay_dirty.table(&operation.table);
10613 }
10614 let results = commit
10615 .ops
10616 .iter()
10617 .enumerate()
10618 .map(|(op_index, operation)| {
10619 let rejection = RejectionRecord {
10620 client_commit_id: commit.client_commit_id.clone(),
10621 op_index: op_index as i32,
10622 code: "client.local_data_purged".to_owned(),
10623 message: "the commit was dropped by an application-authorized local data purge".to_owned(),
10624 retryable: false,
10625 details: None,
10626 operation: Some(CommitOperation::from(operation)),
10627 };
10628 rejections.push(rejection.clone());
10629 CommitOperationOutcome::Error { rejection }
10630 })
10631 .collect::<Vec<_>>();
10632 self.persist_commit_outcome(
10633 &commit.client_commit_id,
10634 CommitOutcomeStatus::Rejected,
10635 &results,
10636 Some(&commit.ops),
10637 )?;
10638 self.delete_outbox_persisted(&commit.client_commit_id)?;
10639 }
10640 if !doomed.is_empty() {
10641 self.outbox
10642 .retain(|commit| !doomed_ids.contains(&commit.client_commit_id));
10643 self.rejections.extend(rejections);
10644 self.prune_commit_outcomes()?;
10645 batch.status = true;
10646 batch.rejections = true;
10647 batch.outcomes = true;
10648 }
10649
10650 let mut purged_rows = 0usize;
10651 for (table, ids) in &row_ids {
10652 if ids.is_empty() {
10653 continue;
10654 }
10655 batch.table(table);
10656 self.overlay_dirty.table(table);
10657 for row_id in ids {
10658 self.delete_base_row(table, row_id, i64::MAX)?;
10659 purged_rows += 1;
10660 }
10661 }
10662 self.rebuild_overlay_if_dirty()?;
10663 self.delete_unreferenced_cached_blobs()?;
10664 self.conn
10665 .execute(
10666 "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
10667 rusqlite::params![meta_key, canonical_plan],
10668 )
10669 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10670 Ok((
10671 batch,
10672 LocalDataPurgeResult {
10673 already_applied: false,
10674 purged_rows,
10675 dropped_commits: doomed.len(),
10676 },
10677 ))
10678 })()
10679 .and_then(|(batch, result)| {
10680 self.finish_observation("syncular_local_purge", batch)
10681 .map(|()| result)
10682 });
10683 let result = match applied {
10684 Ok(result) => result,
10685 Err(error) => {
10686 self.rollback_observation("syncular_local_purge");
10687 self.restore(rollback);
10688 return Err(error);
10689 }
10690 };
10691 self.cancel_sync_round();
10692 Ok(result)
10693 }
10694
10695 pub fn rebootstrap_local_data(
10701 &mut self,
10702 input: &LocalDataRebootstrapInput,
10703 ) -> Result<LocalDataRebootstrapResult, String> {
10704 if input.rebootstrap_id.is_empty()
10705 || input.rebootstrap_id.len() > 128
10706 || !is_local_operation_code_like(&input.rebootstrap_id)
10707 {
10708 return Err(
10709 "sync.invalid_request: local rebootstrap rebootstrapId must be a 1–128 character code-like identifier"
10710 .to_owned(),
10711 );
10712 }
10713 let meta_key = format!("localRebootstrap:{}", input.rebootstrap_id);
10714 if let Some(persisted) = meta_get(&self.conn, &meta_key).map_err(|_| {
10715 "sync.local_corrupt: persisted local rebootstrap receipt is unreadable".to_owned()
10716 })? {
10717 let (retained_commits, reset_subscriptions) =
10718 decode_local_rebootstrap_receipt(&persisted)?;
10719 return Ok(LocalDataRebootstrapResult {
10720 already_applied: true,
10721 retained_commits,
10722 reset_subscriptions,
10723 });
10724 }
10725 if self.stopped || self.schema_floor.is_some() {
10726 return Err(
10727 "sync.invalid_request: local rebootstrap cannot bypass an active schema-floor stop; update the application first"
10728 .to_owned(),
10729 );
10730 }
10731
10732 let retained_commits = self.outbox.len();
10733 let reset_subscriptions = self.stored(load_units(&self.conn))?.len();
10734 let receipt = encode_local_rebootstrap_receipt(retained_commits, reset_subscriptions)?;
10735 let rollback = self.capture();
10736 self.begin_observation("syncular_local_rebootstrap")?;
10737 let mut batch = ChangeAccumulator::default();
10738 let applied = (|| -> Result<(), String> {
10739 self.run_schema_reset_observed(&mut batch, false)?;
10740 self.conn
10741 .execute(
10742 "INSERT INTO _syncular_meta(key, value) VALUES (?1, ?2)",
10743 rusqlite::params![meta_key, receipt],
10744 )
10745 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10746 self.sync_needed = true;
10747 self.sync_intent_queue.push_back(SyncIntent::Interactive);
10748 batch.status = true;
10749 Ok(())
10750 })()
10751 .and_then(|()| self.finish_observation("syncular_local_rebootstrap", batch));
10752 if let Err(error) = applied {
10753 self.rollback_observation("syncular_local_rebootstrap");
10754 self.restore(rollback);
10755 return Err(error);
10756 }
10757
10758 Ok(LocalDataRebootstrapResult {
10759 already_applied: false,
10760 retained_commits,
10761 reset_subscriptions,
10762 })
10763 }
10764
10765 fn purge_scope_rows(
10771 &mut self,
10772 table_name: &str,
10773 effective: &[(String, Vec<String>)],
10774 owners: &[Vec<(String, Vec<String>)>],
10775 ) -> Result<bool, String> {
10776 let Some(table) = self.schema.table(table_name) else {
10777 return Ok(false);
10778 };
10779 let Ok(predicate) = local_scope_predicate(table, effective, owners) else {
10780 return Ok(false);
10781 };
10782 let Some((predicate, params)) = predicate else {
10783 return Ok(true);
10784 };
10785 self.overlay_dirty.table(table_name);
10786 for source in [base_table(table_name), visible_table(table_name)] {
10787 self.conn
10788 .execute(
10789 &format!("DELETE FROM {source} WHERE {predicate}"),
10790 rusqlite::params_from_iter(¶ms),
10791 )
10792 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10793 }
10794 Ok(true)
10795 }
10796
10797 fn drop_doomed_outbox(
10801 &mut self,
10802 table: &TableSchema,
10803 effective: &[(String, Vec<String>)],
10804 owners: &[Vec<(String, Vec<String>)>],
10805 ) -> Result<bool, String> {
10806 let doomed: Vec<_> =
10807 self.outbox
10808 .iter()
10809 .filter(|commit| {
10810 commit.ops.iter().any(|op| {
10811 op.upsert
10812 && op.table == table.name
10813 && op.values.as_ref().is_some_and(|values| {
10814 owns_local_row(table, effective, owners, values)
10815 })
10816 })
10817 })
10818 .cloned()
10819 .collect();
10820 if doomed.is_empty() {
10821 return Ok(false);
10822 }
10823 let mut rejections = Vec::new();
10824 for commit in &doomed {
10825 let results = commit
10826 .ops
10827 .iter()
10828 .enumerate()
10829 .map(|(op_index, operation)| {
10830 self.overlay_dirty.table(&operation.table);
10831 let rejection = RejectionRecord {
10832 client_commit_id: commit.client_commit_id.clone(),
10833 op_index: op_index as i32,
10834 code: "sync.scope_revoked".to_owned(),
10835 message: "the commit was dropped because its effective scope was revoked"
10836 .to_owned(),
10837 retryable: false,
10838 details: None,
10839 operation: Some(CommitOperation::from(operation)),
10840 };
10841 rejections.push(rejection.clone());
10842 CommitOperationOutcome::Error { rejection }
10843 })
10844 .collect::<Vec<_>>();
10845 self.persist_commit_outcome(
10846 &commit.client_commit_id,
10847 CommitOutcomeStatus::Rejected,
10848 &results,
10849 Some(&commit.ops),
10850 )?;
10851 self.delete_outbox_persisted(&commit.client_commit_id)?;
10852 }
10853 self.prune_commit_outcomes()?;
10854 let doomed_ids = doomed
10855 .iter()
10856 .map(|commit| commit.client_commit_id.as_str())
10857 .collect::<BTreeSet<_>>();
10858 self.outbox
10859 .retain(|commit| !doomed_ids.contains(commit.client_commit_id.as_str()));
10860 self.rejections.extend(rejections);
10861 Ok(true)
10862 }
10863
10864 pub fn upload_blob(
10871 &mut self,
10872 bytes: &[u8],
10873 media_type: Option<String>,
10874 name: Option<String>,
10875 ) -> Result<Value, String> {
10876 let blob_id = blob_id_for(bytes);
10877 let now = self.clock_now_ms();
10878 let tx = self
10879 .conn
10880 .transaction()
10881 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10882 tx.execute(
10883 "INSERT INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,?,?)
10884 ON CONFLICT(blob_id) DO NOTHING",
10885 rusqlite::params![blob_id, bytes, bytes.len() as i64, media_type, now],
10886 )
10887 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10888 tx.execute(
10889 "INSERT OR IGNORE INTO _syncular_blob_uploads(blob_id, media_type, created_at_ms) VALUES (?,?,?)",
10890 rusqlite::params![blob_id, media_type, now],
10891 )
10892 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10893 tx.commit()
10894 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
10895 self.enforce_blob_cache_cap();
10896 let mut obj = Map::new();
10897 obj.insert("blobId".to_owned(), Value::from(blob_id));
10898 obj.insert("byteLength".to_owned(), Value::from(bytes.len() as i64));
10899 if let Some(mt) = media_type {
10900 obj.insert("mediaType".to_owned(), Value::from(mt));
10901 }
10902 if let Some(n) = name {
10903 obj.insert("name".to_owned(), Value::from(n));
10904 }
10905 Ok(Value::Object(obj))
10906 }
10907
10908 pub fn fetch_blob_bytes(
10912 &mut self,
10913 transport: &mut dyn Transport,
10914 blob_id_or_ref: &str,
10915 ) -> Result<FetchedBlob, (String, String)> {
10916 let simple = |m: String| ("client.failed".to_owned(), m);
10917 let (blob_id, byte_length) = if blob_id_or_ref.starts_with("sha256:") {
10920 (blob_id_or_ref.to_owned(), None)
10921 } else {
10922 let value: Value = serde_json::from_str(blob_id_or_ref)
10923 .map_err(|_| simple("blob ref is not JSON".to_owned()))?;
10924 (
10925 value
10926 .get("blobId")
10927 .and_then(Value::as_str)
10928 .ok_or_else(|| simple("blob ref has no blobId".to_owned()))?
10929 .to_owned(),
10930 value.get("byteLength").and_then(Value::as_u64),
10931 )
10932 };
10933 if let Some(cached) = self.get_cached_blob_bytes(&blob_id).map_err(simple)? {
10934 return Ok(cached);
10935 }
10936 if !self.transport_enabled {
10937 return Err(("sync.offline".into(), "transport gate is closed".into()));
10938 }
10939 #[cfg(feature = "bench-internals")]
10945 let download_phase = self.benchmark_phases.start(Phase::BlobDownload);
10946 let bytes = match transport
10947 .blob_download(&blob_id, byte_length)
10948 .map_err(|e| (e.code, e.message))?
10949 {
10950 BlobDownload::Bytes(bytes) => bytes,
10951 BlobDownload::Url {
10952 url,
10953 url_expires_at_ms,
10954 } => {
10955 if url_expires_at_ms.is_some_and(|exp| exp <= self.clock_now_ms()) {
10957 return Err((
10958 "sync.segment_expired".to_owned(),
10959 format!(
10960 "blob url for {blob_id} expired before fetch — re-request mints a fresh url (§5.9.5)"
10961 ),
10962 ));
10963 }
10964 transport
10965 .fetch_blob_url(&url, byte_length)
10966 .map_err(|e| (e.code, e.message))?
10967 }
10968 };
10969 #[cfg(feature = "bench-internals")]
10970 drop(download_phase);
10971 #[cfg(feature = "bench-internals")]
10972 let validate_phase = self.benchmark_phases.start(Phase::BlobValidate);
10973 if byte_length.is_some_and(|cap| bytes.len() as u64 > cap) {
10976 return Err((
10977 "sync.invalid_request".to_owned(),
10978 "blob exceeds its byteLength".to_owned(),
10979 ));
10980 }
10981 if blob_id_for(&bytes) != blob_id {
10982 return Err(simple(format!(
10983 "blob content address mismatch for {blob_id}"
10984 )));
10985 }
10986 #[cfg(feature = "bench-internals")]
10987 drop(validate_phase);
10988 #[cfg(feature = "bench-internals")]
10989 let insert_phase = self.benchmark_phases.start(Phase::BlobCacheInsert);
10990 let now = self.clock_now_ms();
10991 self.conn
10992 .execute(
10993 "INSERT OR IGNORE INTO _syncular_blobs(blob_id, bytes, byte_length, media_type, created_at_ms) VALUES (?,?,?,NULL,?)",
10994 rusqlite::params![blob_id, bytes, bytes.len() as i64, now],
10995 )
10996 .map_err(|e| simple(e.to_string()))?;
10997 self.conn
10998 .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))
10999 .map_err(|e| simple(e.to_string()))?;
11000 self.enforce_blob_cache_cap();
11001 #[cfg(feature = "bench-internals")]
11002 drop(insert_phase);
11003 self.get_cached_blob_bytes(&blob_id)
11004 .map_err(simple)?
11005 .ok_or_else(|| simple("blob cache write failed".to_owned()))
11006 }
11007
11008 fn get_cached_blob_bytes(&self, blob_id: &str) -> Result<Option<FetchedBlob>, String> {
11009 #[cfg(feature = "bench-internals")]
11010 let _phase = self.benchmark_phases.start(Phase::BlobCacheRead);
11011 let mut stmt = self
11012 .conn
11013 .prepare("SELECT bytes, byte_length, media_type FROM _syncular_blobs WHERE blob_id = ?")
11014 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11015 let mut rows = stmt
11016 .query(rusqlite::params![blob_id])
11017 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11018 if let Some(row) = rows
11019 .next()
11020 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11021 {
11022 let bytes: Vec<u8> = row
11023 .get(0)
11024 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11025 let byte_length: i64 = row
11026 .get(1)
11027 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11028 let media_type: Option<String> = row
11029 .get(2)
11030 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11031 return Ok(Some(FetchedBlob {
11032 blob_id: blob_id.to_owned(),
11033 byte_length,
11034 bytes,
11035 media_type,
11036 }));
11037 }
11038 Ok(None)
11039 }
11040
11041 fn pending_blob_uploads(&self) -> Result<Vec<crate::round::PendingUpload>, TransportError> {
11043 let pending: Vec<(String, Option<String>)> = {
11044 let mut stmt = self
11045 .conn
11046 .prepare(
11047 "SELECT blob_id, media_type FROM (
11048 SELECT blob_id, media_type, created_at_ms FROM _syncular_blob_uploads
11049 UNION ALL
11050 SELECT DISTINCT r.blob_id, b.media_type, 9223372036854775807 AS created_at_ms
11051 FROM _syncular_blob_commit_refs r LEFT JOIN _syncular_blobs b ON b.blob_id = r.blob_id
11052 WHERE NOT EXISTS (SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id = r.blob_id)
11053 ) ORDER BY created_at_ms, blob_id",
11054 )
11055 .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11056 let rows = stmt
11057 .query_map([], |row| {
11058 Ok((row.get::<_, String>(0)?, row.get::<_, Option<String>>(1)?))
11059 })
11060 .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11061 rows.collect::<Result<_, _>>()
11062 .map_err(|error| match error {
11063 rusqlite::Error::InvalidColumnType(..)
11064 | rusqlite::Error::FromSqlConversionFailure(..) => TransportError::new(
11065 "sync.local_corrupt",
11066 "Pending blob upload metadata is invalid",
11067 ),
11068 _ => TransportError::new("client.failed", error.to_string()),
11069 })?
11070 };
11071 let mut uploads = Vec::new();
11072 for (blob_id, media_type) in pending {
11073 let bytes = (|| {
11074 let stored: Option<(SqlValue, SqlValue)> = self
11075 .conn
11076 .query_row(
11077 "SELECT bytes, byte_length FROM _syncular_blobs WHERE blob_id = ?",
11078 rusqlite::params![blob_id],
11079 |row| Ok((row.get(0)?, row.get(1)?)),
11080 )
11081 .optional()
11082 .map_err(|e| TransportError::new("client.failed", e.to_string()))?;
11083 let Some((SqlValue::Blob(bytes), SqlValue::Integer(byte_length))) = stored else {
11084 return Err(TransportError::new(
11085 "sync.local_corrupt",
11086 "Pending blob upload body is missing or corrupt",
11087 ));
11088 };
11089 if byte_length != bytes.len() as i64 || blob_id_for(&bytes) != blob_id {
11090 return Err(TransportError::new(
11091 "sync.local_corrupt",
11092 "Pending blob upload body is missing or corrupt",
11093 ));
11094 }
11095 Ok(bytes)
11096 })();
11097 let failed = bytes.is_err();
11098 uploads.push(crate::round::PendingUpload {
11099 id: blob_id,
11100 bytes,
11101 media_type,
11102 });
11103 if failed {
11104 break;
11105 }
11106 }
11107 Ok(uploads)
11108 }
11109
11110 fn visible_blob_ids_sql(&self) -> String {
11111 let mut selects = Vec::new();
11112 for table in &self.schema.tables {
11113 for column in table
11114 .columns
11115 .iter()
11116 .filter(|column| column.ty == ColumnType::BlobRef)
11117 {
11118 let identifier = quote_ident(&column.name);
11119 selects.push(format!(
11120 "SELECT json_extract({identifier}, '$.blobId') AS blob_id FROM {} \
11121 WHERE typeof({identifier}) = 'text' AND json_valid({identifier}) \
11122 AND json_type({identifier}, '$.blobId') = 'text'",
11123 quote_ident(&table.name),
11124 ));
11125 }
11126 }
11127 if selects.is_empty() {
11128 "SELECT NULL AS blob_id WHERE 0".to_owned()
11129 } else {
11130 selects.join(" UNION ")
11131 }
11132 }
11133
11134 fn enforce_blob_cache_cap(&self) {
11137 let Some(max_bytes) = self.limits.blob_cache_max_bytes else {
11138 return;
11139 };
11140 let mut total: i64 = self
11141 .conn
11142 .query_row(
11143 "SELECT COALESCE(SUM(byte_length), 0) FROM _syncular_blobs",
11144 [],
11145 |row| row.get(0),
11146 )
11147 .unwrap_or(0);
11148 if total <= max_bytes {
11149 return;
11150 }
11151 let query = format!(
11152 "SELECT blob_id, byte_length FROM _syncular_blobs
11153 WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
11154 AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
11155 AND blob_id NOT IN ({})
11156 ORDER BY created_at_ms ASC, blob_id ASC",
11157 self.visible_blob_ids_sql(),
11158 );
11159 let candidates: Vec<(String, i64)> = {
11160 let Ok(mut stmt) = self.conn.prepare(&query) else {
11161 return;
11162 };
11163 let Ok(rows) = stmt.query_map([], |row| {
11164 Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
11165 }) else {
11166 return;
11167 };
11168 rows.filter_map(Result::ok).collect()
11169 };
11170 for (blob_id, byte_length) in candidates {
11171 if total <= max_bytes {
11172 break;
11173 }
11174 let _ = self.conn.execute(
11175 "DELETE FROM _syncular_blobs WHERE blob_id = ?",
11176 rusqlite::params![blob_id],
11177 );
11178 total -= byte_length;
11179 }
11180 }
11181
11182 fn delete_unreferenced_cached_blobs(&mut self) -> Result<(), String> {
11183 #[cfg(feature = "bench-internals")]
11184 let _phase = self.benchmark_phases.start(Phase::BlobRetention);
11185 if !self.schema_has_blobs() {
11186 return Ok(());
11187 }
11188 self.rebuild_overlay_if_dirty()?;
11189 self.conn
11190 .execute(
11191 &format!(
11192 "DELETE FROM _syncular_blobs
11193 WHERE blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
11194 AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_commit_refs)
11195 AND blob_id NOT IN ({})",
11196 self.visible_blob_ids_sql(),
11197 ),
11198 [],
11199 )
11200 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11201 Ok(())
11202 }
11203
11204 fn insert_row_sql(&self, full_table: &str, table: &crate::schema::TableSchema) -> String {
11209 if let Some(sql) = self.insert_sql.borrow().get(full_table) {
11210 return sql.clone();
11211 }
11212 let mut columns: Vec<String> = table.columns.iter().map(|c| quote_ident(&c.name)).collect();
11213 columns.push(quote_ident("_syncular_version"));
11214 let placeholders: Vec<&str> = columns.iter().map(|_| "?").collect();
11215 let primary_key = quote_ident(&table.primary_key);
11216 let updates = columns
11217 .iter()
11218 .filter(|column| **column != primary_key)
11219 .map(|column| format!("{column}=excluded.{column}"))
11220 .collect::<Vec<_>>()
11221 .join(", ");
11222 let guard = if full_table == base_table(&table.name) {
11225 format!(" WHERE excluded._syncular_version > {full_table}._syncular_version")
11226 } else {
11227 String::new()
11228 };
11229 let sql = format!(
11230 "INSERT INTO {full_table} ({}) VALUES ({}) ON CONFLICT ({primary_key}) DO UPDATE SET {updates}{guard}",
11231 columns.join(", "),
11232 placeholders.join(", ")
11233 );
11234 self.insert_sql
11235 .borrow_mut()
11236 .insert(full_table.to_owned(), sql.clone());
11237 sql
11238 }
11239
11240 fn write_base_row(&self, table_name: &str, row: &Row, version: i64) -> Result<bool, String> {
11243 let landed = self.write_row(&base_table(table_name), table_name, row, version)?;
11244 if landed {
11245 self.overlay_dirty.table(table_name);
11246 }
11247 Ok(landed)
11248 }
11249
11250 fn write_row(
11251 &self,
11252 full_table: &str,
11253 table_name: &str,
11254 row: &Row,
11255 version: i64,
11256 ) -> Result<bool, String> {
11257 #[cfg(feature = "bench-internals")]
11258 let _phase = self.benchmark_phases.start(Phase::RowWrite);
11259 let table = self
11260 .schema
11261 .table(table_name)
11262 .ok_or_else(|| format!("unknown table {table_name:?}"))?;
11263 let sql = self.insert_row_sql(full_table, table);
11264 let mut stmt = self
11265 .conn
11266 .prepare_cached(&sql)
11267 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11268 let params = row
11269 .iter()
11270 .map(RowParam::Cell)
11271 .chain(std::iter::once(RowParam::Version(version)));
11272 stmt.execute(rusqlite::params_from_iter(params))
11273 .map(|changed| changed > 0)
11274 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11275 }
11276
11277 fn delete_base_row(
11280 &self,
11281 table_name: &str,
11282 row_id: &str,
11283 version: i64,
11284 ) -> Result<bool, String> {
11285 let table = self
11286 .schema
11287 .table(table_name)
11288 .ok_or_else(|| format!("unknown table {table_name:?}"))?;
11289 let sql = format!(
11290 "DELETE FROM {} WHERE {} AND _syncular_version < ?2",
11291 base_table(table_name),
11292 row_id_predicate(table)
11293 );
11294 let mut stmt = self
11295 .conn
11296 .prepare_cached(&sql)
11297 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11298 let landed = stmt
11299 .execute(rusqlite::params![row_id, version])
11300 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11301 > 0;
11302 if landed {
11303 self.overlay_dirty.table(table_name);
11304 }
11305 Ok(landed)
11306 }
11307
11308 fn has_acknowledged_rows(&self) -> Result<bool, String> {
11309 self.conn
11310 .query_row(
11311 "SELECT EXISTS(SELECT 1 FROM _syncular_acked_rows)",
11312 [],
11313 |row| row.get(0),
11314 )
11315 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11316 }
11317
11318 fn acknowledged_operations(
11319 &self,
11320 rows: Option<&HashSet<(&str, &str)>>,
11321 tables: Option<&BTreeSet<&str>>,
11322 ) -> Result<Vec<OutboxOp>, String> {
11323 let keys = rows.map(|rows| serde_json::to_string(&rows).expect("row keys"));
11324 let mut statement = self
11325 .conn
11326 .prepare_cached(if keys.is_some() {
11327 ACKED_ROWS_BY_ROW
11328 } else {
11329 "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"
11330 })
11331 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11332 let rows = statement
11333 .query_map(
11334 rusqlite::params![
11335 keys,
11336 tables.map(|tables| serde_json::to_string(tables).expect("table keys"))
11337 ],
11338 |row| {
11339 #[cfg(test)]
11340 self.acknowledged_replay_count
11341 .set(self.acknowledged_replay_count.get() + 1);
11342 Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
11343 },
11344 )
11345 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11346 rows.map(|row| {
11347 let (op, intent) =
11348 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11349 let op: CommitOperation =
11350 serde_json::from_str(&op).map_err(|_| "sync.local_corrupt".to_owned())?;
11351 let table = self
11352 .schema
11353 .table(&op.table)
11354 .ok_or_else(|| "sync.unknown_table".to_owned())?;
11355 let values = if op.op == "upsert" && self.visible_row(table, &op.row_id)?.is_none() {
11356 Some(serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?)
11357 } else {
11358 op.values
11359 };
11360 Ok(OutboxOp {
11361 table: op.table,
11362 row_id: op.row_id,
11363 upsert: op.op == "upsert",
11364 base_version: op.base_version,
11365 values,
11366 insert: op.insert,
11367 })
11368 })
11369 .collect()
11370 }
11371
11372 fn drop_acknowledged_rows(
11373 &self,
11374 matches: impl Fn(&str, &Map<String, Value>) -> bool,
11375 ) -> Result<Vec<OutboxCommit>, String> {
11376 let mut statement = self
11377 .conn
11378 .prepare("SELECT commit_id,tbl,intent_json,id FROM _syncular_acked_rows")
11379 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11380 let rows = statement
11381 .query_map([], |row| {
11382 Ok((
11383 row.get::<_, String>(0)?,
11384 row.get::<_, String>(1)?,
11385 row.get::<_, String>(2)?,
11386 row.get::<_, String>(3)?,
11387 ))
11388 })
11389 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11390 let mut doomed = HashSet::new();
11391 for row in rows {
11392 let (id, table, intent, row_id) =
11393 row.map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11394 let values =
11395 serde_json::from_str(&intent).map_err(|_| "sync.local_corrupt".to_owned())?;
11396 let base_matches = self
11397 .schema
11398 .table(&table)
11399 .map(|schema| self.stored_row(schema, &row_id, true))
11400 .transpose()?
11401 .flatten()
11402 .is_some_and(|(base, _)| {
11403 let schema = self.schema.table(&table).expect("acknowledged table");
11404 let values = schema
11405 .columns
11406 .iter()
11407 .zip(base.iter())
11408 .map(|(column, value)| (column.name.clone(), column_value_to_json(value)))
11409 .collect();
11410 matches(&table, &values)
11411 });
11412 if matches(&table, &values) || base_matches {
11413 doomed.insert(id);
11414 }
11415 }
11416 let mut dropped = Vec::new();
11417 for id in doomed {
11418 let mut statement = self
11419 .conn
11420 .prepare("SELECT op_json FROM _syncular_acked_rows WHERE commit_id=?1 ORDER BY idx")
11421 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11422 let operations = statement
11423 .query_map([&id], |row| row.get::<_, String>(0))
11424 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11425 let mut ops = Vec::new();
11426 for operation in operations {
11427 let json = operation
11428 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11429 let op: CommitOperation =
11430 serde_json::from_str(&json).map_err(|_| "sync.local_corrupt".to_owned())?;
11431 self.overlay_dirty.table(&op.table);
11432 ops.push(OutboxOp {
11433 table: op.table,
11434 row_id: op.row_id,
11435 upsert: op.op == "upsert",
11436 base_version: op.base_version,
11437 values: op.values,
11438 insert: op.insert,
11439 });
11440 }
11441 dropped.push(OutboxCommit {
11442 client_commit_id: id.clone(),
11443 ops,
11444 });
11445 self.conn
11446 .execute("DELETE FROM _syncular_acked_rows WHERE commit_id=?1", [id])
11447 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11448 }
11449 Ok(dropped)
11450 }
11451
11452 fn rebuild_overlay_if_dirty(&mut self) -> Result<(), String> {
11455 if self.overlay_dirty.get() {
11456 self.rebuild_overlay()?;
11457 }
11458 Ok(())
11459 }
11460
11461 fn rebuild_overlay(&mut self) -> Result<(), String> {
11465 #[cfg(feature = "bench-internals")]
11466 let _phase = self.benchmark_phases.start(Phase::OverlayRebuild);
11467 #[cfg(test)]
11468 self.overlay_rebuild_count
11469 .set(self.overlay_rebuild_count.get() + 1);
11470 let dirty = self.overlay_dirty.snapshot();
11471 let tables: Vec<_> = self
11472 .schema
11473 .tables
11474 .iter()
11475 .filter(|table| {
11476 dirty
11477 .as_ref()
11478 .is_none_or(|names| names.is_empty() || names.contains(&table.name))
11479 })
11480 .cloned()
11481 .collect();
11482 let names: BTreeSet<_> = tables.iter().map(|table| table.name.as_str()).collect();
11483 self.begin_observation("syncular_overlay")?;
11484 let rebuilt = (|| {
11485 for table in &tables {
11486 for index in &table.fts_indexes {
11487 self.drop_fts_triggers(index)?;
11488 }
11489 let visible = visible_table(&table.name);
11490 let base = base_table(&table.name);
11491 self.conn
11492 .execute_batch(&format!(
11493 "DELETE FROM {visible}; INSERT INTO {visible} SELECT * FROM {base}"
11494 ))
11495 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11496 }
11497 self.replay_overlay(&names, None)?;
11498 for table in &tables {
11499 for index in &table.fts_indexes {
11500 self.rebuild_fts_projection(table, index)?;
11501 self.create_fts_triggers(table, index)?;
11502 }
11503 }
11504 self.conn
11505 .execute_batch("RELEASE syncular_overlay")
11506 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11507 Ok(())
11508 })();
11509 if rebuilt.is_err() {
11510 self.conn
11511 .execute_batch("ROLLBACK TO syncular_overlay; RELEASE syncular_overlay")
11512 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11513 } else {
11514 self.overlay_dirty.set(false);
11515 }
11516 rebuilt
11517 }
11518
11519 fn replay_overlay(
11523 &self,
11524 tables: &BTreeSet<&str>,
11525 rows: Option<&HashSet<(&str, &str)>>,
11526 ) -> Result<(), String> {
11527 let replays = |op: &&OutboxOp| {
11528 tables.contains(op.table.as_str())
11529 && rows.is_none_or(|rows| rows.contains(&(op.table.as_str(), op.row_id.as_str())))
11530 };
11531 self.apply_outbox_ops(&self.acknowledged_operations(rows, Some(tables))?)?;
11532 for (commit, initial) in self.failed_commits.iter() {
11533 for operation in commit.ops.iter().filter(replays) {
11534 let Some(table) = self.schema.table(&operation.table) else {
11535 continue;
11536 };
11537 if operation.upsert
11538 && self.visible_row(table, &operation.row_id)?.is_none()
11539 && operation.presented_values(table).is_some_and(|values| {
11540 table
11541 .columns
11542 .iter()
11543 .all(|column| values.contains_key(&column.name))
11544 })
11545 {
11546 let key = serde_json::to_string(&(&operation.table, &operation.row_id))
11547 .expect("row key serialization");
11548 if let Some(Value::Object(values)) = initial.get(&key) {
11549 self.apply_outbox_ops(&[OutboxOp {
11550 values: Some(values.clone()),
11551 ..operation.clone()
11552 }])?;
11553 }
11554 }
11555 }
11556 self.apply_outbox_ops(commit.ops.iter().filter(replays))?;
11557 }
11558 self.apply_outbox_ops(
11559 self.outbox
11560 .iter()
11561 .flat_map(|commit| &commit.ops)
11562 .filter(replays),
11563 )
11564 }
11565
11566 fn apply_outbox_ops<'a>(
11571 &self,
11572 ops: impl IntoIterator<Item = &'a OutboxOp>,
11573 ) -> Result<(), String> {
11574 #[cfg(feature = "bench-internals")]
11575 let mut phase = self.benchmark_phases.start(Phase::PendingReplay);
11576 for op in ops {
11577 #[cfg(feature = "bench-internals")]
11578 if let Some(phase) = &mut phase {
11579 phase.unit();
11580 }
11581 if op.upsert {
11582 if let Some((table, values)) = self
11583 .schema
11584 .table(&op.table)
11585 .filter(|table| table.indexes.iter().any(|index| index.unique))
11586 .and_then(|table| Some((table, op.presented_values(table)?)))
11587 {
11588 let mut intended: Map<String, Value> = self
11589 .visible_row(table, &op.row_id)?
11590 .map(|(row, _)| {
11591 table
11592 .columns
11593 .iter()
11594 .zip(&row)
11595 .map(|(column, value)| {
11596 (column.name.clone(), column_value_to_json(value))
11597 })
11598 .collect()
11599 })
11600 .unwrap_or_default();
11601 intended.extend(values.into_owned());
11602 if !self.unique_conflicts(table, &intended, false)?.is_empty() {
11603 continue;
11604 }
11605 }
11606 }
11607 self.apply_outbox_op(op)?;
11608 }
11609 Ok(())
11610 }
11611
11612 fn apply_outbox_op(&self, op: &OutboxOp) -> Result<(), String> {
11613 let Some(table) = self.schema.table(&op.table) else {
11614 return Ok(());
11615 };
11616 let visible = visible_table(&table.name);
11617 if !op.upsert {
11618 let sql = format!("DELETE FROM {visible} WHERE {}", row_id_predicate(table));
11619 self.conn
11620 .prepare_cached(&sql)
11621 .and_then(|mut statement| statement.execute(rusqlite::params![op.row_id]))
11622 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11623 return Ok(());
11624 }
11625 let Some(values) = op.presented_values(table) else {
11629 return Ok(());
11630 };
11631 let full = table
11637 .columns
11638 .iter()
11639 .all(|column| values.contains_key(&column.name));
11640 let local = self.visible_row(table, &op.row_id)?;
11641 if local.is_none() && !full {
11642 return Ok(());
11643 }
11644 let mut row: Row = Vec::with_capacity(table.columns.len());
11645 for (index, column) in table.columns.iter().enumerate() {
11646 let incoming = match values.get(&column.name) {
11647 Some(raw) => json_to_column_value(
11648 if raw.get("$bytes").is_some()
11649 && table
11650 .encrypted_columns
11651 .iter()
11652 .any(|encrypted| encrypted.index == index)
11653 {
11654 &table.wire_columns[index]
11655 } else {
11656 column
11657 },
11658 Some(raw),
11659 ),
11660 None => Ok(local
11661 .as_ref()
11662 .and_then(|(values, _)| values.get(index).cloned())
11663 .flatten()),
11664 };
11665 row.push(incoming.map_err(|_| {
11666 "sync.local_corrupt: persisted optimistic row value is invalid".to_owned()
11667 })?);
11668 }
11669 let version = local.as_ref().map_or(-1, |(_, version)| *version);
11670 self.write_row(&visible, &table.name, &row, version)
11671 .map(|_| ())
11672 .map_err(|error| {
11673 if error.starts_with("UNIQUE constraint failed:") {
11674 "sync.constraint_violation: local write violates a unique constraint".to_owned()
11675 } else {
11676 error
11677 }
11678 })
11679 }
11680
11681 fn visible_row_exists(&self, table: &TableSchema, row_id: &str) -> Result<bool, String> {
11685 self.conn
11686 .query_row(
11687 &format!(
11688 "SELECT EXISTS(SELECT 1 FROM {} WHERE {})",
11689 visible_table(&table.name),
11690 row_id_predicate(table)
11691 ),
11692 rusqlite::params![row_id],
11693 |row| row.get(0),
11694 )
11695 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))
11696 }
11697
11698 fn visible_row(&self, table: &TableSchema, row_id: &str) -> Result<Option<(Row, i64)>, String> {
11701 self.stored_row(table, row_id, false)
11702 }
11703
11704 fn stored_row(
11705 &self,
11706 table: &TableSchema,
11707 row_id: &str,
11708 base: bool,
11709 ) -> Result<Option<(Row, i64)>, String> {
11710 let sql = format!(
11711 "SELECT * FROM {} WHERE {}",
11712 if base {
11713 base_table(&table.name)
11714 } else {
11715 visible_table(&table.name)
11716 },
11717 row_id_predicate(table)
11718 );
11719 let mut stmt = self
11720 .conn
11721 .prepare_cached(&sql)
11722 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11723 let mut rows = stmt
11724 .query(rusqlite::params![row_id])
11725 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11726 let Some(row) = rows
11727 .next()
11728 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?
11729 else {
11730 return Ok(None);
11731 };
11732 let mut values = Vec::with_capacity(table.columns.len());
11733 for (index, column) in table.columns.iter().enumerate() {
11734 let raw = row
11735 .get_ref(index)
11736 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11737 if let rusqlite::types::ValueRef::Blob(bytes) = raw {
11738 if table
11739 .encrypted_columns
11740 .iter()
11741 .any(|encrypted| encrypted.index == index)
11742 {
11743 values.push(Some(ColumnValue::Bytes(bytes.to_vec())));
11744 continue;
11745 }
11746 }
11747 let json = sql_ref_to_json(column, raw);
11748 values.push(json_to_column_value(column, Some(&json)).map_err(|_| {
11749 "sync.local_corrupt: persisted local row value is invalid".to_owned()
11750 })?);
11751 }
11752 let version: i64 = row
11753 .get(table.columns.len())
11754 .map_err(|error| Self::sqlite_failure(&self.storage_failure, error))?;
11755 Ok(Some((values, version)))
11756 }
11757
11758 #[must_use]
11762 pub fn realtime_policy(&self) -> RealtimePolicy {
11763 self.realtime_policy
11764 }
11765
11766 #[must_use]
11768 pub fn realtime_state(&self) -> RealtimeState {
11769 self.realtime_state
11770 }
11771
11772 pub fn set_realtime_policy(&mut self, policy: RealtimePolicy) -> Result<(), String> {
11775 if self.realtime_state == RealtimeState::Connected && policy != self.realtime_policy {
11776 return Err(
11777 "sync.invalid_request: disconnect realtime before changing the realtime policy"
11778 .to_owned(),
11779 );
11780 }
11781 self.realtime_policy = policy;
11782 match policy {
11783 RealtimePolicy::Off => self.set_realtime_state(RealtimeState::Disabled, None),
11784 RealtimePolicy::Required | RealtimePolicy::Optional
11785 if self.realtime_state == RealtimeState::Disabled =>
11786 {
11787 self.set_realtime_state(RealtimeState::Disconnected, None);
11788 }
11789 RealtimePolicy::Required | RealtimePolicy::Optional => {}
11790 }
11791 Ok(())
11792 }
11793
11794 fn set_realtime_state(&mut self, state: RealtimeState, reason_code: Option<&str>) {
11797 self.realtime_state = state;
11798 self.realtime_reason_code = reason_code.map(Self::diagnostic_code);
11799 if matches!(state, RealtimeState::Connected | RealtimeState::Disabled) {
11800 self.realtime_reason_code = None;
11801 self.realtime_retry_delay_ms = None;
11802 }
11803 }
11804
11805 #[must_use]
11806 fn realtime_connected(&self) -> bool {
11807 self.realtime_state == RealtimeState::Connected
11808 }
11809
11810 pub fn connect_realtime(&mut self, transport: &mut dyn Transport) -> Result<(), String> {
11811 if !self.transport_enabled {
11812 return Err("sync.offline: transport gate is closed".into());
11813 }
11814 if self.realtime_policy == RealtimePolicy::Off {
11815 return Err(
11816 "sync.invalid_request: realtime is off; realtime connect is refused".to_owned(),
11817 );
11818 }
11819 if self.realtime_connected() {
11820 return Ok(());
11821 }
11822 self.realtime_state = RealtimeState::Connecting;
11823 match transport.realtime_connect_for_client(&self.client_id) {
11824 Ok(()) => {
11825 self.set_realtime_state(RealtimeState::Connected, None);
11826 Ok(())
11827 }
11828 Err(error) => {
11829 self.set_realtime_state(RealtimeState::Refused, Some(&error.code));
11830 Err(format!("{}: {}", error.code, error.message))
11831 }
11832 }
11833 }
11834
11835 pub fn disconnect_realtime(&mut self, transport: &mut dyn Transport) {
11836 self.cancel_sync_round();
11837 if self.realtime_state == RealtimeState::Disconnected
11840 || self.realtime_state == RealtimeState::Disabled
11841 {
11842 return;
11843 }
11844 let _ = transport.realtime_close();
11845 self.set_realtime_state(
11846 if self.realtime_policy == RealtimePolicy::Off {
11847 RealtimeState::Disabled
11848 } else {
11849 RealtimeState::Disconnected
11850 },
11851 None,
11852 );
11853 self.presence.clear(); }
11855
11856 pub fn realtime_lost(&mut self, transport: &mut dyn Transport, error: &TransportError) {
11862 if self.realtime_state != RealtimeState::Connected {
11863 return;
11864 }
11865 self.cancel_sync_round();
11866 let _ = transport.realtime_close();
11867 self.set_realtime_state(RealtimeState::Lost, Some(&error.code));
11868 self.realtime_retry_delay_ms = Some(self.schedule_background_retry());
11869 self.presence.clear();
11870 }
11871
11872 pub fn set_presence(
11878 &mut self,
11879 transport: &mut dyn Transport,
11880 scope_key: &str,
11881 doc: Option<&Value>,
11882 ) -> Result<(), String> {
11883 if !self.transport_enabled {
11884 return Err("sync.offline: transport gate is closed".into());
11885 }
11886 if !self.realtime_connected() {
11887 return Err("setPresence requires a connected realtime socket (§8.6)".to_string());
11888 }
11889 let text = encode_presence_publish(scope_key, doc);
11890 transport
11891 .realtime_send(&text)
11892 .map_err(|e| format!("{}: {}", e.code, e.message))
11893 }
11894
11895 pub fn presence(&self, scope_key: &str) -> Vec<PresencePeer> {
11897 self.presence
11898 .get(scope_key)
11899 .map(|peers| peers.values().cloned().collect())
11900 .unwrap_or_default()
11901 }
11902
11903 fn apply_presence(
11905 &mut self,
11906 scope_key: String,
11907 kind: Option<PresenceKind>,
11908 actor_id: Option<String>,
11909 client_id: Option<String>,
11910 doc: Option<Value>,
11911 error: Option<String>,
11912 ) {
11913 if error.is_some() {
11916 return;
11917 }
11918 let (Some(kind), Some(actor_id), Some(client_id)) = (kind, actor_id, client_id) else {
11919 return;
11920 };
11921 let peer_key = format!("{actor_id} {client_id}");
11922 match kind {
11923 PresenceKind::Leave => {
11924 if let Some(peers) = self.presence.get_mut(&scope_key) {
11925 peers.remove(&peer_key);
11926 if peers.is_empty() {
11927 self.presence.remove(&scope_key);
11928 }
11929 }
11930 }
11931 _ => {
11932 let doc = match doc {
11933 Some(Value::Object(_)) => doc.unwrap(),
11934 _ => return,
11935 };
11936 self.presence.entry(scope_key).or_default().insert(
11937 peer_key,
11938 PresencePeer {
11939 actor_id,
11940 client_id,
11941 doc,
11942 },
11943 );
11944 }
11945 }
11946 }
11947
11948 pub fn on_realtime_text(&mut self, text: &str) {
11950 if self.stopped || !self.transport_enabled || self.security_preflight {
11951 return;
11952 }
11953 match parse_control(text) {
11954 Ok(ControlMessage::Hello { requires_sync, .. }) => {
11955 if requires_sync {
11956 self.set_sync_needed(true, true);
11958 }
11959 }
11960 Ok(ControlMessage::Presence {
11961 scope_key,
11962 kind,
11963 actor_id,
11964 client_id,
11965 doc,
11966 error,
11967 ..
11968 }) => {
11969 self.apply_presence(scope_key, kind, actor_id, client_id, doc, error);
11970 }
11971 Ok(ControlMessage::Wake { .. }) => {
11972 self.set_sync_needed(true, true);
11974 }
11975 _ => {}
11976 }
11977 }
11978
11979 pub fn on_realtime_binary_queued(&mut self, bytes: &[u8]) -> Vec<String> {
11983 let mut transport = crate::round::DownloadResults::default();
11984 self.on_realtime_binary(&mut transport, bytes);
11985 transport.controls
11986 }
11987
11988 pub fn on_realtime_binary(&mut self, transport: &mut dyn Transport, bytes: &[u8]) {
11994 if self.stopped || !self.transport_enabled || self.security_preflight {
11995 return;
11996 }
11997 #[cfg(feature = "bench-internals")]
11998 let decode_phase = self.benchmark_phases.start(Phase::ResponseDecode);
11999 let message = match decode_message(bytes) {
12000 Ok(m) if m.msg_kind == MsgKind::Response => m,
12001 _ => {
12002 self.set_sync_needed(true, true);
12003 return;
12004 }
12005 };
12006 #[cfg(feature = "bench-internals")]
12007 drop(decode_phase);
12008 if let Some(Frame::RespHeader {
12011 required_schema_version: Some(required),
12012 latest_schema_version,
12013 ..
12014 }) = message.frames.first()
12015 {
12016 let floor = SchemaFloor {
12017 required_schema_version: Some(*required),
12018 latest_schema_version: *latest_schema_version,
12019 };
12020 if self.set_schema_floor(Some(floor)).is_err() {
12021 self.set_sync_needed(true, true);
12022 }
12023 return;
12024 }
12025 let through = message.frames.iter().find_map(|frame| match frame {
12026 Frame::LiveEnd { through_seq, .. } => Some(*through_seq),
12027 _ => None,
12028 });
12029 let epoch = self.get_meta(LOG_EPOCH_KEY).ok().flatten();
12030 let mut dropped = !matches!(message.frames.first(), Some(Frame::RespHeader {
12031 reset_required: false,
12032 log_epoch,
12033 ..
12034 }) if Some(log_epoch) == epoch.as_ref());
12035 let mut applied: Option<i64> = None;
12036 dropped |= self.begin_coalesced_apply().is_err();
12037 let mut receivers: Option<Vec<UnitRecord>> = None;
12038 for frame in message.frames {
12039 if dropped {
12040 break;
12041 }
12042 match frame {
12043 Frame::LiveStart { status, .. } => {
12044 let Ok(cursor) = self.stored(replica_cursor(&self.conn)) else {
12045 dropped = true;
12046 break;
12047 };
12048 if status != LiveStatus::Active || cursor < 0 {
12049 dropped = true;
12050 } else if !through.is_some_and(|through| through <= cursor) {
12051 receivers = self.stored(load_units(&self.conn)).ok().map(|units| {
12053 units
12054 .into_iter()
12055 .filter(|unit| {
12056 unit.status == UnitStatus::Active
12057 && unit.echo.is_some()
12058 && unit.cursor.is_none()
12059 })
12060 .collect()
12061 });
12062 dropped = receivers.is_none();
12063 }
12064 }
12065 Frame::Commit {
12066 commit_seq,
12067 tables,
12068 changes,
12069 ..
12070 } => {
12071 let Some(receivers) = receivers.clone() else {
12072 continue;
12073 };
12074 dropped = self
12075 .apply_live_commit(
12076 &receivers,
12077 &tables,
12078 changes,
12079 commit_seq,
12080 AppliedServerCommitSource::Delta,
12081 )
12082 .is_err();
12083 }
12084 Frame::LiveEnd { through_seq, .. } if receivers.is_some() => {
12085 dropped = self
12086 .set_meta(REPLICA_CURSOR_KEY, &through_seq.to_string())
12087 .is_err();
12088 applied = Some(through_seq);
12089 }
12090 Frame::Error { .. } => dropped = true,
12091 _ => {}
12092 }
12093 }
12094 if self.finish_coalesced_apply().is_err() || dropped {
12097 applied = None;
12098 dropped = true;
12099 }
12100 if let Some(cursor) = applied {
12101 let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
12103 let _ = transport.realtime_send(&ack);
12104 }
12105 if dropped {
12106 self.set_sync_needed(true, true);
12107 }
12108 }
12109
12110 fn ack_after_pull(&mut self, transport: &mut dyn Transport) {
12113 if !self.realtime_connected() {
12114 return;
12115 }
12116 if let Ok(cursor @ 0..) = self.stored(replica_cursor(&self.conn)) {
12117 let ack = format!("{{\"type\":\"ack\",\"cursor\":{cursor}}}");
12118 let _ = transport.realtime_send(&ack);
12119 }
12120 }
12121}
12122
12123#[cfg(test)]
12124mod previous_version_wiring_tests;
12125
12126#[cfg(test)]
12127mod identity_tests;
12128
12129#[cfg(test)]
12130mod insert_intent_tests;
12131
12132#[cfg(test)]
12133mod robustness_tests;