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