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