1use serde_json::{json, Value};
17use ssp2::segment::{decode_rows_segment, encode_rows_segment};
18use ssp2::{
19 decode_message, encode_message, parse_control, render_message, render_rows_segment,
20 ControlMessage,
21};
22use syncular_client::previous_version::{PreviousVersionContextConfig, PreviousVersionReadSpec};
23use syncular_client::{
24 ClientError, ClientLimits, CommandEffects, CommitOutcomeQuery, LocalDataPurgeInput,
25 LocalDataRebootstrapInput, Mutation, QueryOwner, QueryReadFailure, RealtimePolicy,
26 ResolveCommitOutcomeInput, SyncClient, Transport, TransportError, UnitScopes, WindowBase,
27 WindowCoverage, LOCAL_AUTHORITY_UNCONFIGURED_CODE,
28};
29
30pub fn bytes_to_hex(bytes: &[u8]) -> String {
33 syncular_client::values::bytes_to_hex(bytes)
34}
35
36pub fn hex_to_bytes(hex: &str) -> Result<Vec<u8>, String> {
37 syncular_client::values::hex_to_bytes(hex)
38}
39
40pub fn bytes_value(bytes: &[u8]) -> Value {
41 Value::Object(serde_json::Map::from_iter([(
42 "$bytes".to_owned(),
43 Value::from(bytes_to_hex(bytes)),
44 )]))
45}
46
47pub fn value_bytes(value: Option<&Value>) -> Result<Vec<u8>, String> {
48 let hex = value
49 .and_then(|v| v.get("$bytes"))
50 .and_then(Value::as_str)
51 .ok_or_else(|| "expected a {\"$bytes\": hex} value".to_owned())?;
52 hex_to_bytes(hex)
53}
54
55#[derive(Debug, Clone)]
59pub struct CommandError {
60 pub code: String,
61 pub message: String,
62 pub details: Option<Value>,
63 pub retryable: bool,
64}
65
66impl CommandError {
67 pub fn new(code: impl Into<String>, message: impl Into<String>) -> Self {
68 Self {
69 code: code.into(),
70 message: message.into(),
71 details: None,
72 retryable: false,
73 }
74 }
75
76 pub fn from_client(error: ClientError) -> Self {
78 Self {
79 code: error.code,
80 message: error.message,
81 details: error.details,
82 retryable: error.retryable,
83 }
84 }
85}
86
87impl From<(String, String)> for CommandError {
88 fn from((code, message): (String, String)) -> Self {
89 Self {
90 code,
91 message,
92 details: None,
93 retryable: false,
94 }
95 }
96}
97
98#[derive(Debug, Default, Clone)]
102pub struct CreateEffects {
103 pub signed_urls: bool,
106 pub security_preflight_pending: bool,
122}
123
124fn read_command_error(failure: QueryReadFailure) -> CommandError {
127 let details = failure.details();
128 let retryable = failure.retryable();
129 CommandError {
130 code: failure.code.unwrap_or("client.failed").to_owned(),
131 message: failure.message,
132 details,
133 retryable,
134 }
135}
136
137fn client_err(message: String) -> CommandError {
141 let code = ClientError::from(message.clone()).code;
142 let retryable = code == "client.storage_busy";
143 CommandError {
144 code,
145 message,
146 details: None,
147 retryable,
148 }
149}
150
151fn optional<'a, T>(
155 value: Option<&'a Value>,
156 field: &str,
157 read: impl FnOnce(&'a Value) -> Option<T>,
158) -> Result<Option<T>, String> {
159 match value {
160 None | Some(Value::Null) => Ok(None),
161 Some(value) => read(value)
162 .map(Some)
163 .ok_or_else(|| format!("sync.invalid_request: {field} has the wrong type")),
164 }
165}
166
167fn transport_command_error(error: TransportError) -> CommandError {
170 CommandError {
171 code: error.code,
172 message: error.message,
173 details: error.details,
174 retryable: false,
175 }
176}
177
178fn need_client(client: &mut Option<SyncClient>) -> Result<&mut SyncClient, CommandError> {
179 client
180 .as_mut()
181 .ok_or_else(|| client_err("no client instance created".to_owned()))
182}
183
184pub fn parse_previous_version_context(
189 value: Option<&Value>,
190) -> Result<Option<PreviousVersionContextConfig>, CommandError> {
191 let Some(value) = value else {
192 return Ok(None);
193 };
194 let object = value.as_object().ok_or_else(|| {
195 client_err("sync.invalid_request: previousVersionContext must be an object".to_owned())
196 })?;
197 let enabled = match object.get("enabled") {
198 None => false,
199 Some(Value::Bool(enabled)) => *enabled,
200 Some(_) => {
201 return Err(client_err(
202 "sync.invalid_request: previousVersionContext.enabled must be a boolean".to_owned(),
203 ))
204 }
205 };
206 let mut config = PreviousVersionContextConfig {
207 enabled,
208 ..PreviousVersionContextConfig::default()
209 };
210 for (key, slot) in [
211 ("maxBytes", &mut config.max_bytes),
212 ("maxRows", &mut config.max_rows),
213 ("maxTables", &mut config.max_tables),
214 ("maxRowBytes", &mut config.max_row_bytes),
215 ("maxAgeMs", &mut config.max_age_ms),
216 ] {
217 if let Some(raw) = object.get(key) {
218 *slot = raw.as_i64().ok_or_else(|| {
219 client_err(format!(
220 "sync.invalid_request: previousVersionContext.{key} must be a positive safe integer"
221 ))
222 })?;
223 }
224 }
225 config.validate().map_err(client_err)?;
226 Ok(Some(config))
227}
228
229fn parse_previous_version_snapshot_spec(
231 params: &Value,
232) -> Result<PreviousVersionReadSpec, CommandError> {
233 let table = params.get("table").and_then(Value::as_str).ok_or_else(|| {
234 client_err("sync.invalid_request: previousVersionSnapshot missing table".to_owned())
235 })?;
236 let row_ids = match params.get("rowIds") {
237 None | Some(Value::Null) => Vec::new(),
238 Some(Value::Array(ids)) => ids
239 .iter()
240 .map(|id| match id {
241 Value::String(id) => Ok(id.clone()),
242 Value::Number(number) => Ok(number.to_string()),
243 Value::Bool(boolean) => Ok(boolean.to_string()),
244 _ => Err(client_err(
245 "sync.invalid_request: previousVersionSnapshot rowIds must be strings"
246 .to_owned(),
247 )),
248 })
249 .collect::<Result<Vec<_>, _>>()?,
250 Some(_) => {
251 return Err(client_err(
252 "sync.invalid_request: previousVersionSnapshot rowIds must be an array".to_owned(),
253 ))
254 }
255 };
256 let limit = match params.get("limit") {
257 None | Some(Value::Null) => None,
258 Some(value) => Some(value.as_i64().ok_or_else(|| {
259 client_err(
260 "sync.invalid_request: previousVersionSnapshot limit must be a positive number"
261 .to_owned(),
262 )
263 })?),
264 };
265 Ok(PreviousVersionReadSpec {
266 table: table.to_owned(),
267 row_ids,
268 limit,
269 })
270}
271
272pub fn parse_limits(value: Option<&Value>) -> Result<ClientLimits, CommandError> {
273 let mut limits = ClientLimits::default();
274 let Some(object) = optional(value, "limits", Value::as_object).map_err(client_err)? else {
275 return Ok(limits);
276 };
277 let i32_field = |key: &str| {
278 optional(object.get(key), key, |v| {
279 v.as_i64().and_then(|n| i32::try_from(n).ok())
280 })
281 .map_err(client_err)
282 };
283 limits.limit_commits = i32_field("limitCommits")?;
284 limits.limit_snapshot_rows = i32_field("limitSnapshotRows")?;
285 limits.max_snapshot_pages = i32_field("maxSnapshotPages")?;
286 limits.accept = optional(object.get("accept"), "limits.accept", |v| {
287 v.as_u64().and_then(|n| u8::try_from(n).ok())
288 })
289 .map_err(client_err)?;
290 limits.blob_cache_max_bytes = optional(
291 object.get("blobCacheMaxBytes"),
292 "limits.blobCacheMaxBytes",
293 Value::as_i64,
294 )
295 .map_err(client_err)?;
296 limits.outcome_retention_max_entries = optional(
297 object.get("outcomeRetentionMaxEntries"),
298 "limits.outcomeRetentionMaxEntries",
299 |v| v.as_u64().and_then(|n| usize::try_from(n).ok()),
300 )
301 .map_err(client_err)?;
302 limits.max_push_commits_per_request = parse_push_limit(object, "maxPushCommitsPerRequest")?;
303 limits.max_push_operations_per_request =
304 parse_push_limit(object, "maxPushOperationsPerRequest")?;
305 limits.max_push_request_bytes = parse_push_limit(object, "maxPushRequestBytes")?;
306 Ok(limits)
307}
308
309fn parse_push_limit(
312 object: &serde_json::Map<String, Value>,
313 key: &str,
314) -> Result<Option<usize>, CommandError> {
315 match object.get(key) {
316 None | Some(Value::Null) => Ok(None),
317 Some(value) => value
318 .as_u64()
319 .and_then(|n| usize::try_from(n).ok())
320 .filter(|n| *n >= 1 && *n <= u32::MAX as usize)
321 .map(Some)
322 .ok_or_else(|| CommandError {
323 code: "sync.invalid_request".to_owned(),
324 message: "push limit must be an integer in 1..=4294967295".to_owned(),
325 details: Some(serde_json::json!({ "limit": key })),
326 retryable: false,
327 }),
328 }
329}
330
331fn parse_realtime_policy(value: Option<&Value>) -> Result<RealtimePolicy, CommandError> {
333 match value {
334 None => Ok(RealtimePolicy::Optional),
335 Some(Value::String(text)) => match text.as_str() {
336 "required" => Ok(RealtimePolicy::Required),
337 "optional" => Ok(RealtimePolicy::Optional),
338 "off" => Ok(RealtimePolicy::Off),
339 other => Err(client_err(format!(
340 "sync.invalid_request: realtimePolicy must be 'required', 'optional', or 'off', got {other:?}"
341 ))),
342 },
343 Some(_) => Err(client_err(
344 "sync.invalid_request: realtimePolicy must be a string".to_owned(),
345 )),
346 }
347}
348
349pub fn parse_encryption(
354 value: &Value,
355) -> Result<syncular_client::values::EncryptionConfig, String> {
356 let mut config = syncular_client::values::EncryptionConfig::default();
357 let keys = optional(value.get("keys"), "encryption.keys", Value::as_object)?;
358 for (key_id, key_val) in keys.into_iter().flatten() {
359 let bytes =
360 value_bytes(Some(key_val)).map_err(|e| format!("encryption key {key_id:?}: {e}"))?;
361 if bytes.len() != 32 {
362 return Err(format!(
363 "encryption key {key_id:?} must be 32 bytes, got {}",
364 bytes.len()
365 ));
366 }
367 config.keys.insert(key_id.clone(), bytes);
368 }
369 if let Some(columns) = value.get("keyIdColumns") {
370 let columns = columns
371 .as_object()
372 .ok_or_else(|| "encryption keyIdColumns must be an object".to_owned())?;
373 for (table, column) in columns {
374 let column = column.as_str().ok_or_else(|| {
375 format!("encryption keyIdColumns entry for {table:?} must be a string")
376 })?;
377 if column.is_empty() {
378 return Err(format!(
379 "encryption keyIdColumns entry for {table:?} must not be empty"
380 ));
381 }
382 config
383 .key_id_columns
384 .insert(table.clone(), column.to_owned());
385 }
386 }
387 config.missing_key = match value.get("missingKey") {
388 None | Some(Value::Null) => syncular_client::values::MissingKey::Fail,
389 Some(Value::String(mode)) if mode == "fail" => syncular_client::values::MissingKey::Fail,
390 Some(Value::String(mode)) if mode == "seal" => syncular_client::values::MissingKey::Seal,
391 Some(_) => return Err("encryption missingKey must be 'fail' or 'seal'".to_owned()),
392 };
393 Ok(config)
394}
395
396pub fn parse_headers(value: &Value) -> Result<Vec<(String, String)>, String> {
401 let object = value.as_object().ok_or_else(|| {
402 "sync.invalid_request: headers must be an object of string values".to_owned()
403 })?;
404 let mut headers = Vec::with_capacity(object.len());
405 for (name, value) in object {
406 let value = value
407 .as_str()
408 .ok_or_else(|| format!("sync.invalid_request: header {name:?} must be a string"))?;
409 headers.push((name.clone(), value.to_owned()));
410 }
411 Ok(headers)
412}
413
414pub fn parse_mutations(value: Option<&Value>) -> Result<Vec<Mutation>, String> {
415 let list = value
416 .and_then(Value::as_array)
417 .ok_or_else(|| "mutations must be a list".to_owned())?;
418 let mut out = Vec::with_capacity(list.len());
419 for entry in list {
420 let op = entry
421 .get("op")
422 .and_then(Value::as_str)
423 .ok_or_else(|| "mutation missing op".to_owned())?;
424 let table = entry
425 .get("table")
426 .and_then(Value::as_str)
427 .ok_or_else(|| "mutation missing table".to_owned())?
428 .to_owned();
429 let base_version = optional(entry.get("baseVersion"), "baseVersion", Value::as_i64)?;
430 match op {
431 "upsert" | "patch" => {
432 let mut values = entry
433 .get("values")
434 .and_then(Value::as_object)
435 .cloned()
436 .ok_or_else(|| "upsert missing values".to_owned())?;
437 decode_bigint_members(&mut values)?;
438 out.push(if op == "patch" {
439 Mutation::Patch {
440 table,
441 values,
442 base_version,
443 }
444 } else {
445 Mutation::Upsert {
446 table,
447 values,
448 base_version,
449 }
450 });
451 }
452 "delete" => {
453 let row_id = entry
454 .get("rowId")
455 .and_then(Value::as_str)
456 .ok_or_else(|| "delete missing rowId".to_owned())?
457 .to_owned();
458 out.push(Mutation::Delete {
459 table,
460 row_id,
461 base_version,
462 });
463 }
464 other => return Err(format!("unknown mutation op {other:?}")),
465 }
466 }
467 Ok(out)
468}
469
470fn decode_bigint_members(values: &mut serde_json::Map<String, Value>) -> Result<(), String> {
471 for value in values.values_mut() {
472 let Some(decimal) = value.get("$bigint").and_then(Value::as_str) else {
473 continue;
474 };
475 let integer = decimal
476 .parse::<i64>()
477 .map_err(|_| format!("bigint value {decimal:?} is outside SQLite's i64 range"))?;
478 *value = Value::from(integer);
479 }
480 Ok(())
481}
482
483fn unit_scopes(value: Option<&Value>) -> Result<UnitScopes, String> {
485 serde_json::from_value(value.cloned().unwrap_or(Value::Null)).map_err(|_| {
486 "sync.invalid_request: a unit scope map is an object of string values".to_owned()
487 })
488}
489
490fn window_base_from_params(value: Option<&Value>) -> Result<WindowBase, String> {
493 let object = value
494 .and_then(Value::as_object)
495 .ok_or_else(|| "sync.invalid_request: window base must be an object".to_owned())?;
496 let variable = object
497 .get("variable")
498 .and_then(Value::as_str)
499 .ok_or_else(|| "sync.invalid_request: window base missing variable".to_owned())?
500 .to_owned();
501 Ok(WindowBase {
502 variable,
503 fixed_scopes: match object.get("fixedScopes") {
504 None | Some(Value::Null) => UnitScopes::new(),
505 scopes => unit_scopes(scopes)?,
506 },
507 })
508}
509
510pub fn parse_window_coverage(value: Option<&Value>) -> Result<Vec<WindowCoverage>, String> {
515 let entries = match value {
516 None | Some(Value::Null) => return Ok(Vec::new()),
517 Some(Value::Array(entries)) => entries,
518 Some(_) => return Err("sync.invalid_request: coverage must be a list".to_owned()),
519 };
520 let mut coverage = Vec::with_capacity(entries.len());
521 for entry in entries {
522 let units = match entry.get("units") {
523 None | Some(Value::Null) => Vec::new(),
524 Some(Value::Array(values)) => values
525 .iter()
526 .map(|value| value.as_str().map(str::to_owned))
527 .collect::<Option<Vec<_>>>()
528 .ok_or_else(|| {
529 "sync.invalid_request: coverage units must be a list of strings".to_owned()
530 })?,
531 Some(_) => {
532 return Err(
533 "sync.invalid_request: coverage units must be a list of strings".to_owned(),
534 )
535 }
536 };
537 coverage.push(WindowCoverage {
538 base: window_base_from_params(entry.get("base"))?,
539 units,
540 });
541 }
542 Ok(coverage)
543}
544
545fn parse_query_owner<'a>(
548 params: &'a Value,
549 method: &str,
550) -> Result<Option<(&'a str, Vec<&'a str>)>, CommandError> {
551 match params.get("owner") {
552 None | Some(Value::Null) => Ok(None),
553 Some(value) => {
554 let id = value
555 .get("id")
556 .and_then(Value::as_str)
557 .filter(|id| !id.is_empty());
558 let tables = value
559 .get("tables")
560 .and_then(Value::as_array)
561 .and_then(|list| {
562 list.iter()
563 .map(Value::as_str)
564 .collect::<Option<Vec<&str>>>()
565 });
566 match (id, tables) {
567 (Some(id), Some(tables)) => Ok(Some((id, tables))),
568 _ => Err(client_err(format!(
569 "sync.invalid_request: {method} owner must be {{id: non-empty string, tables: string[]}}"
570 ))),
571 }
572 }
573 }
574}
575
576fn snapshot_string_list(value: Option<&Value>) -> Result<Vec<String>, CommandError> {
579 match value {
580 None | Some(Value::Null) => Ok(Vec::new()),
581 Some(Value::Array(items)) => items
582 .iter()
583 .map(|item| item.as_str().map(str::to_owned))
584 .collect::<Option<Vec<String>>>()
585 .ok_or_else(|| {
586 client_err(
587 "sync.invalid_request: snapshotRead list must contain strings".to_owned(),
588 )
589 }),
590 Some(_) => Err(client_err(
591 "sync.invalid_request: snapshotRead list must be a list of strings".to_owned(),
592 )),
593 }
594}
595
596#[cfg(feature = "crdt-yjs")]
600fn crdt_target(params: &Value) -> Result<(String, String, String, String), CommandError> {
601 let table = params
602 .get("table")
603 .and_then(Value::as_str)
604 .ok_or_else(|| client_err("crdt command missing table".to_owned()))?
605 .to_owned();
606 let row_id = params
607 .get("rowId")
608 .and_then(Value::as_str)
609 .ok_or_else(|| client_err("crdt command missing rowId".to_owned()))?
610 .to_owned();
611 let column = params
612 .get("column")
613 .and_then(Value::as_str)
614 .ok_or_else(|| client_err("crdt command missing column".to_owned()))?
615 .to_owned();
616 let name = optional(params.get("name"), "crdt name", Value::as_str)
617 .map_err(client_err)?
618 .unwrap_or("text")
619 .to_owned();
620 Ok((table, row_id, column, name))
621}
622
623pub fn dispatch<T: Transport>(
633 transport: &mut T,
634 client: &mut Option<SyncClient>,
635 effects: &mut CreateEffects,
636 method: &str,
637 params: &Value,
638) -> Result<Value, CommandError> {
639 if method == "create" {
640 let requests_preflight = optional(
647 params.get("securityPreflight"),
648 "securityPreflight",
649 Value::as_bool,
650 )
651 .map_err(client_err)?
652 .unwrap_or(false);
653 let preflight_engaged = client.as_ref().map_or(
654 effects.security_preflight_pending,
655 SyncClient::security_preflight,
656 );
657 if preflight_engaged && !requests_preflight {
658 return Err(CommandError::new(
659 syncular_client::SECURITY_PREFLIGHT_REQUIRED_CODE,
660 "the local replica is in security preflight; a replacement create must itself request securityPreflight, and protected data opens only after activateSecurity",
661 ));
662 }
663 } else {
664 let allowed_during_preflight = matches!(
665 method,
666 "authoritySnapshot"
667 | "securityLifecycle"
668 | "beginSecurityPreflight"
669 | "activateSecurity"
670 | "setTransportEnabled"
671 | "disconnectRealtime"
672 | "purgeLocalData"
673 | "previousVersionDiscard"
674 | "localRevision"
675 | "statusSnapshot"
676 | "localAuthorityState"
677 | "drainRealtime"
678 | "shutdown"
679 );
680 if client
681 .as_ref()
682 .is_some_and(|running| running.security_preflight())
683 && !allowed_during_preflight
684 {
685 return Err(CommandError::new(
686 syncular_client::SECURITY_PREFLIGHT_REQUIRED_CODE,
687 "the local replica is in security preflight; complete quarantine checks and call activateSecurity before accessing protected data",
688 ));
689 }
690 }
691 let mut result = match method {
692 "create" => {
693 let client_id = optional(params.get("clientId"), "clientId", Value::as_str)
694 .map_err(client_err)?
695 .map(str::to_owned);
696 let db_path =
697 optional(params.get("dbPath"), "dbPath", Value::as_str).map_err(client_err)?;
698 let schema = params
699 .get("schema")
700 .ok_or_else(|| client_err("create missing schema".to_owned()))?;
701 let limits = parse_limits(params.get("limits"))?;
702 let previous_version_context =
706 parse_previous_version_context(params.get("previousVersionContext"))?;
707 let mut limits = limits;
708 limits.previous_version_context = previous_version_context;
709 if let Some(reads) = params.get("authorityReads") {
710 limits.authority_reads = serde_json::from_value(reads.clone()).map_err(|_| {
711 client_err(
712 "client.authority_read_forbidden: invalid authority declaration".into(),
713 )
714 })?;
715 }
716 transport
719 .open_local_authority(schema, db_path)
720 .map_err(transport_command_error)?;
721 let mut instance = match db_path {
725 Some(path) => SyncClient::open_path_with_identity(client_id, schema, limits, path)
726 .map_err(client_err)?,
727 None => {
728 SyncClient::new_with_identity(client_id, schema, limits).map_err(client_err)?
729 }
730 };
731 instance
732 .set_retain_failed_commits(
733 optional(
734 params.get("retainFailedCommits"),
735 "retainFailedCommits",
736 Value::as_bool,
737 )
738 .map_err(client_err)?
739 .unwrap_or(false),
740 )
741 .map_err(client_err)?;
742 let realtime_policy = parse_realtime_policy(params.get("realtimePolicy"))?;
745 instance
746 .set_realtime_policy(realtime_policy)
747 .map_err(client_err)?;
748 if let Some(now_ms) =
750 optional(params.get("nowMs"), "nowMs", Value::as_i64).map_err(client_err)?
751 {
752 instance.set_now_ms(now_ms);
753 }
754 effects.signed_urls = optional(params.get("signedUrls"), "signedUrls", Value::as_bool)
757 .map_err(client_err)?
758 .unwrap_or(false);
759 let security_preflight = optional(
764 params.get("securityPreflight"),
765 "securityPreflight",
766 Value::as_bool,
767 )
768 .map_err(client_err)?
769 .unwrap_or(false);
770 if instance.security_preflight() && !security_preflight {
778 return Err(CommandError::new(
779 syncular_client::SECURITY_PREFLIGHT_REQUIRED_CODE,
780 "the local replica is in security preflight; a replacement create must itself request securityPreflight, and protected data opens only after activateSecurity",
781 ));
782 }
783 if security_preflight && params.get("encryption").is_some() {
784 return Err(client_err(
785 "sync.invalid_request: securityPreflight and encryption are mutually exclusive; install keys with activateSecurity after preflight"
786 .to_owned(),
787 ));
788 }
789 if let Some(enc) = params.get("encryption") {
790 let config = parse_encryption(enc).map_err(client_err)?;
791 instance.set_encryption(config);
792 }
793 if security_preflight {
794 instance.begin_security_preflight().map_err(client_err)?;
795 }
796 if let Some(enabled) = params.get("transportEnabled") {
797 let enabled = enabled.as_bool().ok_or_else(|| {
798 client_err("sync.invalid_request: transportEnabled must be a boolean".into())
799 })?;
800 instance.set_transport_enabled(transport, enabled);
801 }
802 effects.security_preflight_pending = security_preflight;
803 *client = Some(instance);
804 Ok(json!({}))
805 }
806 "securityLifecycle" => Ok(json!({
807 "state": need_client(client)?.security_lifecycle()
808 })),
809 "beginSecurityPreflight" => {
810 let running = need_client(client)?;
811 running.disconnect_realtime(transport);
812 running.begin_security_preflight().map_err(client_err)?;
813 effects.security_preflight_pending = true;
814 Ok(json!({}))
815 }
816 "authoritySnapshot" => {
817 if !params.as_object().is_some_and(|p| p.is_empty()) {
818 return Err(client_err(
819 "client.authority_read_forbidden: authoritySnapshot accepts no arguments"
820 .into(),
821 ));
822 }
823 client
824 .as_ref()
825 .ok_or_else(|| client_err("client.closed: no authority client is open".into()))?
826 .authority_snapshot()
827 .map_err(client_err)
828 }
829 "activateSecurity" => {
830 let encryption = match params.get("encryption") {
831 Some(value) => parse_encryption(value).map_err(client_err)?,
832 None => syncular_client::values::EncryptionConfig::default(),
833 };
834 if let Some(headers) = params.get("headers") {
840 parse_headers(headers).map_err(client_err)?;
841 }
842 need_client(client)?
843 .activate_security(encryption)
844 .map_err(client_err)?;
845 effects.security_preflight_pending = false;
846 Ok(json!({}))
847 }
848 "setTransportEnabled" => {
849 let enabled = params
850 .get("enabled")
851 .and_then(Value::as_bool)
852 .ok_or_else(|| {
853 client_err(
854 "sync.invalid_request: setTransportEnabled.enabled must be a boolean"
855 .into(),
856 )
857 })?;
858 need_client(client)?.set_transport_enabled(transport, enabled);
859 Ok(json!({}))
860 }
861 "setHeaders" => {
862 let headers = params
863 .get("headers")
864 .ok_or_else(|| client_err("setHeaders missing headers".to_owned()))?;
865 parse_headers(headers).map_err(client_err)?;
866 Ok(json!({}))
867 }
868 "shutdown" => {
869 if let Some(running) = client.as_mut() {
870 effects.security_preflight_pending = running.security_preflight();
875 running.disconnect_realtime(transport);
876 running.seal_security_on_teardown();
880 }
881 *client = None;
882 Ok(json!({}))
883 }
884 "subscribe" => {
885 let scopes = unit_scopes(params.get("scopes")).map_err(client_err)?;
886 let id = need_client(client)?.subscribe(scopes).map_err(client_err)?;
887 Ok(json!({ "id": id }))
888 }
889 "subscribeMany" => {
890 let units = params
891 .get("units")
892 .and_then(Value::as_array)
893 .ok_or_else(|| {
894 client_err(
895 "sync.invalid_request: subscribeMany units must be a list".to_owned(),
896 )
897 })?
898 .iter()
899 .map(|scopes| unit_scopes(Some(scopes)))
900 .collect::<Result<Vec<_>, _>>()
901 .map_err(client_err)?;
902 let ids = need_client(client)?
903 .subscribe_many(units)
904 .map_err(client_err)?;
905 Ok(json!({ "ids": ids }))
906 }
907 "unsubscribe" => {
908 let id = params
909 .get("id")
910 .and_then(Value::as_str)
911 .ok_or_else(|| client_err("unsubscribe missing id".to_owned()))?;
912 need_client(client)?.unsubscribe(id).map_err(client_err)?;
913 Ok(json!({}))
914 }
915 "setWindow" => {
916 let base = window_base_from_params(params.get("base")).map_err(client_err)?;
917 let units: Vec<String> = optional(params.get("units"), "setWindow units", |v| {
918 v.as_array()?
919 .iter()
920 .map(|unit| unit.as_str().map(str::to_owned))
921 .collect()
922 })
923 .map_err(client_err)?
924 .unwrap_or_default();
925 let command_effects = need_client(client)?
926 .set_window(&base, &units)
927 .map_err(client_err)?;
928 Ok(json!({ "effects": command_effects }))
929 }
930 "windowState" => {
931 let base = window_base_from_params(params.get("base")).map_err(client_err)?;
932 let state = need_client(client)?
933 .window_state(&base)
934 .map_err(client_err)?;
935 Ok(json!({ "units": state.units, "pending": state.pending }))
936 }
937 "timeWindowSugar" => {
938 let created_at_ms = params
939 .get("createdAtMs")
940 .and_then(Value::as_i64)
941 .ok_or_else(|| client_err("timeWindowSugar missing createdAtMs".to_owned()))?;
942 let count = params
943 .get("count")
944 .and_then(Value::as_u64)
945 .and_then(|value| usize::try_from(value).ok())
946 .ok_or_else(|| client_err("timeWindowSugar missing count".to_owned()))?;
947 let now_ms = params
948 .get("nowMs")
949 .and_then(Value::as_i64)
950 .ok_or_else(|| client_err("timeWindowSugar missing nowMs".to_owned()))?;
951 if params.get("unit").and_then(Value::as_str) != Some("month") {
952 return Err(client_err(
953 "sync.invalid_request: timeWindowSugar requires the month unit".to_owned(),
954 ));
955 }
956 let unit = syncular_client::TimeBucketUnit::Month;
957 Ok(json!({
958 "bucket": syncular_client::creation_time_bucket(created_at_ms, unit)
959 .map_err(client_err)?,
960 "units": syncular_client::last(count, unit, now_ms).map_err(client_err)?,
961 }))
962 }
963 "mutate" => {
964 let mutations = parse_mutations(params.get("mutations")).map_err(client_err)?;
965 let client_commit_id = match params.get("clientCommitId") {
967 None | Some(Value::Null) => None,
968 Some(Value::String(id)) => Some(id.clone()),
969 Some(_) => {
970 return Err(client_err(
971 "sync.invalid_request: clientCommitId must be a string".to_owned(),
972 ))
973 }
974 };
975 let id = need_client(client)?
976 .mutate_with_commit_id(mutations, client_commit_id)
977 .map_err(CommandError::from_client)?;
978 Ok(json!({
979 "clientCommitId": id,
980 "effects": CommandEffects::interactive()
981 }))
982 }
983 "patch" => {
984 let table = params
985 .get("table")
986 .and_then(Value::as_str)
987 .ok_or_else(|| client_err("patch missing table".to_owned()))?;
988 let row_id = params
989 .get("rowId")
990 .and_then(Value::as_str)
991 .ok_or_else(|| client_err("patch missing rowId".to_owned()))?;
992 let mut partial = params
993 .get("partial")
994 .and_then(Value::as_object)
995 .cloned()
996 .ok_or_else(|| client_err("patch missing partial object".to_owned()))?;
997 decode_bigint_members(&mut partial).map_err(client_err)?;
998 let base_version = optional(params.get("baseVersion"), "baseVersion", Value::as_i64)
999 .map_err(client_err)?;
1000 let id = need_client(client)?
1001 .patch(table, row_id, partial, base_version)
1002 .map_err(CommandError::from_client)?;
1003 Ok(json!({
1004 "clientCommitId": id,
1005 "effects": CommandEffects::interactive()
1006 }))
1007 }
1008 "purgeLocalData" => {
1009 let input: LocalDataPurgeInput =
1010 serde_json::from_value(params.get("input").cloned().ok_or_else(|| {
1011 client_err("sync.invalid_request: purgeLocalData missing input".to_owned())
1012 })?)
1013 .map_err(|error| {
1014 client_err(format!(
1015 "sync.invalid_request: invalid purgeLocalData input: {error}"
1016 ))
1017 })?;
1018 let result = need_client(client)?
1019 .purge_local_data(&input)
1020 .map_err(client_err)?;
1021 serde_json::to_value(result).map_err(|error| client_err(error.to_string()))
1022 }
1023 "rebootstrapLocalData" => {
1024 let input: LocalDataRebootstrapInput =
1025 serde_json::from_value(params.get("input").cloned().ok_or_else(|| {
1026 client_err(
1027 "sync.invalid_request: rebootstrapLocalData missing input".to_owned(),
1028 )
1029 })?)
1030 .map_err(|error| {
1031 client_err(format!(
1032 "sync.invalid_request: invalid rebootstrapLocalData input: {error}"
1033 ))
1034 })?;
1035 let result = need_client(client)?
1036 .rebootstrap_local_data(&input)
1037 .map_err(client_err)?;
1038 Ok(json!({
1039 "alreadyApplied": result.already_applied,
1040 "retainedCommits": result.retained_commits,
1041 "resetSubscriptions": result.reset_subscriptions,
1042 "effects": if result.already_applied {
1043 CommandEffects::none()
1044 } else {
1045 CommandEffects::interactive()
1046 }
1047 }))
1048 }
1049 "sync" => {
1050 let outcome = need_client(client)?.sync(transport);
1051 Ok(outcome.to_json())
1052 }
1053 "resetClientId" | "reset_client_id" => {
1054 let client_id = need_client(client)?
1055 .reset_client_id(transport)
1056 .map_err(client_err)?;
1057 Ok(json!({ "clientId": client_id }))
1058 }
1059 "syncUntilIdle" => {
1060 let max_rounds = match params.get("maxRounds") {
1061 None | Some(Value::Null) => None,
1062 Some(value) => Some(
1063 value
1064 .as_u64()
1065 .and_then(|n| u32::try_from(n).ok())
1066 .filter(|n| *n >= 1)
1067 .ok_or_else(|| {
1068 client_err(
1069 "sync.invalid_request: maxRounds must be a positive integer"
1070 .to_owned(),
1071 )
1072 })?,
1073 ),
1074 };
1075 let timeout_ms = match params.get("timeoutMs") {
1076 None | Some(Value::Null) => None,
1077 Some(value) => Some(value.as_u64().filter(|ms| *ms >= 1).ok_or_else(|| {
1078 client_err(
1079 "sync.invalid_request: timeoutMs must be a positive integer".to_owned(),
1080 )
1081 })?),
1082 };
1083 let client = need_client(client)?;
1084 let outcome = match timeout_ms {
1085 Some(timeout_ms) => {
1086 client.sync_until_idle_with_deadline(transport, max_rounds, Some(timeout_ms))
1087 }
1088 None => client.sync_until_idle(transport, max_rounds),
1089 };
1090 Ok(outcome.to_json())
1091 }
1092 "proveCurrentBase" => {
1093 let outcome = params
1094 .get("outcome")
1095 .and_then(Value::as_object)
1096 .ok_or_else(|| client_err("proveCurrentBase missing outcome".to_owned()))?;
1097 let id = outcome
1098 .get("clientCommitId")
1099 .and_then(Value::as_str)
1100 .ok_or_else(|| client_err("proveCurrentBase missing clientCommitId".to_owned()))?;
1101 let sequence = outcome
1102 .get("sequence")
1103 .and_then(Value::as_i64)
1104 .ok_or_else(|| client_err("proveCurrentBase missing sequence".to_owned()))?;
1105 let max_rounds = match params.get("maxRounds") {
1106 None | Some(Value::Null) => None,
1107 Some(value) => Some(
1108 value
1109 .as_u64()
1110 .and_then(|n| u32::try_from(n).ok())
1111 .filter(|n| *n >= 1)
1112 .ok_or_else(|| {
1113 client_err(
1114 "sync.invalid_request: maxRounds must be a positive integer"
1115 .to_owned(),
1116 )
1117 })?,
1118 ),
1119 };
1120 Ok(json!(
1121 need_client(client)?.prove_current_base(transport, id, sequence, max_rounds)
1122 ))
1123 }
1124 "readRows" => {
1125 let table = params
1126 .get("table")
1127 .and_then(Value::as_str)
1128 .ok_or_else(|| client_err("readRows missing table".to_owned()))?;
1129 let rows = need_client(client)?.read_rows(table).map_err(client_err)?;
1130 Ok(json!({ "rows": rows }))
1131 }
1132 "query" => {
1133 let sql = params
1137 .get("sql")
1138 .and_then(Value::as_str)
1139 .ok_or_else(|| client_err("query missing sql".to_owned()))?;
1140 let bind = match params.get("params") {
1141 Some(Value::Array(list)) => list.as_slice(),
1142 None | Some(Value::Null) => &[],
1143 Some(_) => return Err(client_err("query params must be a list".to_owned())),
1144 };
1145 let rows = need_client(client)?.query(sql, bind).map_err(client_err)?;
1146 Ok(Value::Object(serde_json::Map::from_iter([(
1147 "rows".to_owned(),
1148 Value::Array(rows.into_iter().map(Value::Object).collect()),
1149 )])))
1150 }
1151 "querySnapshot" => {
1152 let sql = params
1153 .get("sql")
1154 .and_then(Value::as_str)
1155 .ok_or_else(|| client_err("querySnapshot missing sql".to_owned()))?;
1156 let bind = match params.get("params") {
1157 Some(Value::Array(list)) => list.as_slice(),
1158 None | Some(Value::Null) => &[],
1159 Some(_) => {
1160 return Err(client_err("querySnapshot params must be a list".to_owned()))
1161 }
1162 };
1163 let coverage = parse_window_coverage(params.get("coverage")).map_err(client_err)?;
1164 let owner = parse_query_owner(params, "querySnapshot")?;
1165 let mut snapshot = need_client(client)?
1166 .query_snapshot(
1167 sql,
1168 bind,
1169 &coverage,
1170 owner.as_ref().map(|(id, tables)| QueryOwner { id, tables }),
1171 )
1172 .map_err(client_err)?;
1173 let rows = std::mem::take(&mut snapshot.rows);
1174 let mut result = serde_json::to_value(snapshot).expect("snapshot serializes");
1175 result["rows"] = Value::Array(rows.into_iter().map(Value::Object).collect());
1176 Ok(result)
1177 }
1178 "localRevision" => {
1179 let read = need_client(client)?
1183 .snapshot_read(&syncular_client::SnapshotReadRequest::default(), None)
1184 .map_err(read_command_error)?;
1185 Ok(json!({ "revision": read.revision }))
1186 }
1187 "snapshotRead" => {
1188 let mut statement_sql: Vec<String> = Vec::new();
1189 let mut statement_params: Vec<Vec<Value>> = Vec::new();
1190 match params.get("statements") {
1191 None | Some(Value::Null) => {}
1192 Some(Value::Array(items)) => {
1193 for item in items {
1194 let Some(sql) = item.get("sql").and_then(Value::as_str) else {
1195 return Err(client_err(
1196 "sync.invalid_request: snapshotRead statements need a sql string"
1197 .to_owned(),
1198 ));
1199 };
1200 let bind = match item.get("params") {
1201 None | Some(Value::Null) => Vec::new(),
1202 Some(Value::Array(values)) => values.clone(),
1203 Some(_) => {
1204 return Err(client_err(
1205 "sync.invalid_request: snapshotRead statement params must be a list"
1206 .to_owned(),
1207 ))
1208 }
1209 };
1210 statement_sql.push(sql.to_owned());
1211 statement_params.push(bind);
1212 }
1213 }
1214 Some(_) => {
1215 return Err(client_err(
1216 "sync.invalid_request: snapshotRead statements must be a list".to_owned(),
1217 ))
1218 }
1219 }
1220 let units = snapshot_string_list(params.get("units"))?;
1221 let commit_ids = snapshot_string_list(params.get("commitIds"))?;
1222 let coverage = parse_window_coverage(params.get("coverage")).map_err(client_err)?;
1223 let owner = parse_query_owner(params, "snapshotRead")?;
1224 let statements: Vec<syncular_client::SnapshotStatement<'_>> = statement_sql
1225 .iter()
1226 .zip(&statement_params)
1227 .map(|(sql, params)| syncular_client::SnapshotStatement { sql, params })
1228 .collect();
1229 let read = need_client(client)?
1230 .snapshot_read(
1231 &syncular_client::SnapshotReadRequest {
1232 statements,
1233 coverage: &coverage,
1234 units,
1235 commit_ids,
1236 },
1237 owner.as_ref().map(|(id, tables)| QueryOwner { id, tables }),
1238 )
1239 .map_err(read_command_error)?;
1240 serde_json::to_value(read).map_err(|error| client_err(error.to_string()))
1241 }
1242 "previousVersionSnapshot" | "previous_version_snapshot" => {
1243 let spec = parse_previous_version_snapshot_spec(params)?;
1244 let snapshot = need_client(client)?
1245 .previous_version_snapshot(&spec)
1246 .map_err(client_err)?;
1247 serde_json::to_value(snapshot).map_err(|error| client_err(error.to_string()))
1248 }
1249 "previousVersionAudit" | "previous_version_audit" => Ok(
1250 match need_client(client)?
1251 .previous_version_audit()
1252 .map_err(client_err)?
1253 {
1254 Some(audit) => {
1255 serde_json::to_value(audit).map_err(|error| client_err(error.to_string()))?
1256 }
1257 None => Value::Null,
1258 },
1259 ),
1260 "previousVersionDiscard" | "previous_version_discard" => {
1261 let outcome = need_client(client)?
1262 .previous_version_discard()
1263 .map_err(client_err)?;
1264 Ok(json!({
1265 "present": outcome.present,
1266 "discarded": outcome.discarded,
1267 }))
1268 }
1269 "statusSnapshot" => Ok(serde_json::to_value(need_client(client)?.status_snapshot())
1270 .expect("status serializes")),
1271 "diagnosticsSnapshot" => {
1272 let snapshot = need_client(client)?
1273 .diagnostics_snapshot()
1274 .map_err(client_err)?;
1275 Ok(serde_json::to_value(snapshot).expect("diagnostics serialize"))
1276 }
1277 "progressSnapshot" => Ok(
1282 serde_json::to_value(need_client(client)?.progress().snapshot())
1283 .expect("progress JSON"),
1284 ),
1285 "drainChangeBatches" => Ok(json!({
1286 "batches": need_client(client)?.drain_change_batches()
1287 })),
1288 "drainSyncIntents" => Ok(json!({
1289 "intents": need_client(client)?.drain_sync_intents()
1290 })),
1291 #[cfg(feature = "crdt-yjs")]
1297 "crdtText" => {
1298 let (table, row_id, column, name) = crdt_target(params)?;
1299 let text = need_client(client)?
1300 .crdt_text(&table, &row_id, &column, &name)
1301 .map_err(client_err)?;
1302 Ok(json!({ "text": text }))
1303 }
1304 #[cfg(feature = "crdt-yjs")]
1305 "crdtInsertText" => {
1306 let (table, row_id, column, name) = crdt_target(params)?;
1307 let index = params
1308 .get("index")
1309 .and_then(Value::as_u64)
1310 .and_then(|n| u32::try_from(n).ok())
1311 .ok_or_else(|| {
1312 client_err(
1313 "sync.invalid_request: crdtInsertText index must be a u32".to_owned(),
1314 )
1315 })?;
1316 let value = params
1317 .get("value")
1318 .and_then(Value::as_str)
1319 .ok_or_else(|| client_err("crdtInsertText missing value".to_owned()))?;
1320 let id = need_client(client)?
1321 .crdt_insert_text(&table, &row_id, &column, &name, index, value)
1322 .map_err(CommandError::from_client)?;
1323 Ok(json!({ "clientCommitId": id }))
1324 }
1325 #[cfg(feature = "crdt-yjs")]
1326 "crdtDeleteText" => {
1327 let (table, row_id, column, name) = crdt_target(params)?;
1328 let index = params
1329 .get("index")
1330 .and_then(Value::as_u64)
1331 .and_then(|n| u32::try_from(n).ok())
1332 .ok_or_else(|| {
1333 client_err(
1334 "sync.invalid_request: crdtDeleteText index must be a u32".to_owned(),
1335 )
1336 })?;
1337 let len = params
1338 .get("len")
1339 .and_then(Value::as_u64)
1340 .and_then(|n| u32::try_from(n).ok())
1341 .ok_or_else(|| {
1342 client_err("sync.invalid_request: crdtDeleteText len must be a u32".to_owned())
1343 })?;
1344 let id = need_client(client)?
1345 .crdt_delete_text(&table, &row_id, &column, &name, index, len)
1346 .map_err(CommandError::from_client)?;
1347 Ok(json!({ "clientCommitId": id }))
1348 }
1349 #[cfg(feature = "crdt-yjs")]
1350 "crdtApplyUpdate" => {
1351 let (table, row_id, column, _name) = crdt_target(params)?;
1352 let update = value_bytes(params.get("update")).map_err(client_err)?;
1353 let id = need_client(client)?
1354 .crdt_apply_update(&table, &row_id, &column, &update)
1355 .map_err(CommandError::from_client)?;
1356 Ok(json!({ "clientCommitId": id }))
1357 }
1358 #[cfg(not(feature = "crdt-yjs"))]
1359 "crdtText" | "crdtInsertText" | "crdtDeleteText" | "crdtApplyUpdate" => {
1360 Err(CommandError::new(
1361 "client.crdt_unavailable",
1362 "native CRDT support requires the `crdt-yjs` feature (§5.10.5)",
1363 ))
1364 }
1365
1366 "uploadBlob" => {
1367 let bytes = value_bytes(params.get("bytes")).map_err(client_err)?;
1368 let media_type = optional(params.get("mediaType"), "mediaType", Value::as_str)
1369 .map_err(client_err)?
1370 .map(str::to_owned);
1371 let name = optional(params.get("name"), "blob name", Value::as_str)
1372 .map_err(client_err)?
1373 .map(str::to_owned);
1374 let reference = need_client(client)?
1375 .upload_blob(&bytes, media_type, name)
1376 .map_err(client_err)?;
1377 Ok(json!({ "ref": reference }))
1378 }
1379 "fetchBlob" => {
1380 let blob = params
1381 .get("blob")
1382 .and_then(Value::as_str)
1383 .ok_or_else(|| client_err("fetchBlob missing blob".to_owned()))?
1384 .to_owned();
1385 let blob = need_client(client)?.fetch_blob_bytes(transport, &blob)?;
1389 let mut value = serde_json::Map::new();
1390 value.insert("blobId".to_owned(), Value::from(blob.blob_id));
1391 value.insert("byteLength".to_owned(), Value::from(blob.byte_length));
1392 value.insert("bytes".to_owned(), bytes_value(&blob.bytes));
1393 if let Some(media_type) = blob.media_type {
1394 value.insert("mediaType".to_owned(), Value::from(media_type));
1395 }
1396 Ok(Value::Object(serde_json::Map::from_iter([(
1397 "blob".to_owned(),
1398 Value::Object(value),
1399 )])))
1400 }
1401 "conflicts" => {
1402 let conflicts = need_client(client)?.conflicts().to_vec();
1403 Ok(json!({ "conflicts": conflicts }))
1404 }
1405 "rejections" => {
1406 let rejections = need_client(client)?.rejections().to_vec();
1407 Ok(json!({ "rejections": rejections }))
1408 }
1409 "commitOutcome" => {
1410 let client_commit_id = params
1411 .get("clientCommitId")
1412 .and_then(Value::as_str)
1413 .ok_or_else(|| {
1414 client_err(
1415 "sync.invalid_request: commitOutcome missing clientCommitId".to_owned(),
1416 )
1417 })?;
1418 let outcome = need_client(client)?
1419 .commit_outcome(client_commit_id)
1420 .map_err(client_err)?;
1421 Ok(json!({ "outcome": outcome }))
1422 }
1423 "commitOutcomes" => {
1424 let query = serde_json::from_value::<CommitOutcomeQuery>(
1425 params.get("query").cloned().unwrap_or_else(|| json!({})),
1426 )
1427 .map_err(|error| {
1428 client_err(format!(
1429 "sync.invalid_request: invalid commit outcome query: {error}"
1430 ))
1431 })?;
1432 let outcomes = need_client(client)?
1433 .commit_outcomes(query)
1434 .map_err(client_err)?;
1435 Ok(json!({ "outcomes": outcomes }))
1436 }
1437 "resolveCommitOutcome" => {
1438 let input = serde_json::from_value::<ResolveCommitOutcomeInput>(
1439 params.get("input").cloned().ok_or_else(|| {
1440 client_err(
1441 "sync.invalid_request: resolveCommitOutcome missing input".to_owned(),
1442 )
1443 })?,
1444 )
1445 .map_err(|error| {
1446 client_err(format!(
1447 "sync.invalid_request: invalid outcome resolution: {error}"
1448 ))
1449 })?;
1450 let outcome = need_client(client)?
1451 .resolve_commit_outcome(input)
1452 .map_err(client_err)?;
1453 Ok(json!({ "outcome": outcome }))
1454 }
1455 "pendingCommitIds" => {
1456 let ids = need_client(client)?.pending_commit_ids();
1457 Ok(json!({ "ids": ids }))
1458 }
1459 "pendingPayloads" => {
1460 let payloads = need_client(client)?
1461 .pending_payloads()
1462 .map_err(client_err)?;
1463 Ok(json!({
1464 "payloads": payloads.iter().map(|p| bytes_value(p)).collect::<Vec<_>>()
1465 }))
1466 }
1467 "units" => Ok(json!({ "units": need_client(client)?.units().map_err(client_err)? })),
1468 "unit" => {
1469 let id = params
1470 .get("id")
1471 .and_then(Value::as_str)
1472 .ok_or_else(|| client_err("unit missing id".to_owned()))?;
1473 Ok(json!({ "unit": need_client(client)?.unit(id).map_err(client_err)? }))
1474 }
1475 "recreateWithSchema" => {
1476 let schema = params
1480 .get("schema")
1481 .ok_or_else(|| client_err("recreateWithSchema missing schema".to_owned()))?;
1482 need_client(client)?
1483 .recreate_with_schema(schema)
1484 .map_err(client_err)?;
1485 Ok(json!({}))
1486 }
1487 "localAuthorityState" => Ok(json!({ "state": transport.local_authority_state() })),
1488 "drainRealtime" => Ok(json!({})),
1492 "attachLocalAuthority" | "abandonLocalAuthorityAttach" => {
1493 let running = need_client(client)?;
1494 if transport.local_authority_state().is_none() {
1495 return Err(CommandError::new(
1496 LOCAL_AUTHORITY_UNCONFIGURED_CODE,
1497 "the host configured no localAuthorityPath",
1498 ));
1499 }
1500 let enabled = running.transport_enabled();
1503 running.set_transport_enabled(transport, false);
1504 let outcome = if method == "attachLocalAuthority" {
1505 transport.attach_local_authority()
1506 } else {
1507 transport.abandon_local_authority_attach()
1508 };
1509 running.set_transport_enabled(transport, enabled);
1510 outcome.map_err(transport_command_error)?;
1511 Ok(json!({ "effects": CommandEffects::interactive() }))
1512 }
1513 "connectRealtime" => {
1514 need_client(client)?
1515 .connect_realtime(transport)
1516 .map_err(client_err)?;
1517 Ok(json!({}))
1518 }
1519 "disconnectRealtime" => {
1520 if let Some(running) = client.as_mut() {
1522 running.disconnect_realtime(transport);
1523 }
1524 Ok(json!({}))
1525 }
1526 "setPresence" => {
1527 let scope_key = params
1528 .get("scopeKey")
1529 .and_then(Value::as_str)
1530 .ok_or_else(|| client_err("setPresence missing scopeKey".to_owned()))?
1531 .to_owned();
1532 let doc = params.get("doc");
1534 let doc_ref = match doc {
1535 None | Some(Value::Null) => None,
1536 Some(v) => Some(v),
1537 };
1538 need_client(client)?
1539 .set_presence(transport, &scope_key, doc_ref)
1540 .map_err(client_err)?;
1541 Ok(json!({}))
1542 }
1543 "presence" => {
1544 let scope_key = params
1545 .get("scopeKey")
1546 .and_then(Value::as_str)
1547 .ok_or_else(|| client_err("presence missing scopeKey".to_owned()))?;
1548 let peers = need_client(client)?.presence(scope_key);
1549 Ok(json!({ "peers": peers }))
1550 }
1551
1552 "messageRoundtrip" => {
1554 let bytes = value_bytes(params.get("bytes")).map_err(client_err)?;
1555 match decode_message(&bytes) {
1556 Ok(message) => Ok(json!({
1557 "ok": true,
1558 "bytes": bytes_value(&encode_message(&message)),
1559 "renderedJson": render_message(&message).to_string(),
1560 })),
1561 Err(error) => Ok(json!({ "ok": false, "errorCode": error.code.as_str() })),
1562 }
1563 }
1564 "segmentRoundtrip" => {
1565 let bytes = value_bytes(params.get("bytes")).map_err(client_err)?;
1566 match decode_rows_segment(&bytes) {
1567 Ok(segment) => Ok(json!({
1568 "ok": true,
1569 "bytes": bytes_value(&encode_rows_segment(&segment)),
1570 "renderedJson": render_rows_segment(&segment).to_string(),
1571 })),
1572 Err(error) => Ok(json!({ "ok": false, "errorCode": error.code.as_str() })),
1573 }
1574 }
1575 "realtimeKnown" => {
1576 let text = params
1577 .get("text")
1578 .and_then(Value::as_str)
1579 .ok_or_else(|| client_err("realtimeKnown missing text".to_owned()))?;
1580 let known = matches!(
1581 parse_control(text),
1582 Ok(ControlMessage::Hello { .. })
1583 | Ok(ControlMessage::Wake { .. })
1584 | Ok(ControlMessage::Heartbeat { .. })
1585 | Ok(ControlMessage::Scopes { .. })
1586 | Ok(ControlMessage::Presence { .. })
1587 );
1588 Ok(json!({ "value": known }))
1589 }
1590
1591 other => Err(client_err(format!("unknown method {other:?}"))),
1592 };
1593 if client
1594 .as_ref()
1595 .is_some_and(|running| !running.transport_enabled())
1596 {
1597 if let Ok(value) = &mut result {
1598 if let Some(effects) = value.get_mut("effects").and_then(Value::as_object_mut) {
1599 effects.remove("sync");
1600 }
1601 }
1602 }
1603 result
1604}
1605
1606#[cfg(test)]
1607mod tests {
1608 use serde_json::{json, Value};
1609 use syncular_client::{
1610 Mutation, SegmentRequest, SyncClient, Transport, TransportError,
1611 SECURITY_PREFLIGHT_REQUIRED_CODE,
1612 };
1613
1614 use super::{
1615 client_err, dispatch, parse_encryption, parse_headers, parse_previous_version_context,
1616 parse_window_coverage, CreateEffects, UnitScopes,
1617 };
1618
1619 #[derive(Default)]
1620 struct NoNetwork {
1621 realtime_connects: usize,
1622 realtime_closes: usize,
1623 }
1624
1625 impl Transport for NoNetwork {
1626 fn sync(&mut self, _request: &[u8]) -> Result<Vec<u8>, TransportError> {
1627 Err(TransportError::new("sync.transport_failed", "offline"))
1628 }
1629
1630 fn realtime_sync(&mut self, _request: &[u8]) -> Result<Vec<u8>, TransportError> {
1631 Err(TransportError::new("sync.transport_failed", "offline"))
1632 }
1633
1634 fn download_segment(
1635 &mut self,
1636 _request: &SegmentRequest,
1637 _on_progress: &mut dyn FnMut(u64),
1638 ) -> Result<Vec<u8>, TransportError> {
1639 Err(TransportError::new("sync.transport_failed", "offline"))
1640 }
1641
1642 fn realtime_connect(&mut self) -> Result<(), TransportError> {
1643 self.realtime_connects += 1;
1644 Ok(())
1645 }
1646
1647 fn realtime_send(&mut self, _text: &str) -> Result<(), TransportError> {
1648 Ok(())
1649 }
1650
1651 fn realtime_close(&mut self) -> Result<(), TransportError> {
1652 self.realtime_closes += 1;
1653 Ok(())
1654 }
1655 }
1656
1657 fn schema() -> Value {
1658 json!({
1659 "version": 1,
1660 "tables": [{
1661 "name": "todos",
1662 "columns": [
1663 { "name": "id", "type": "string", "nullable": false },
1664 { "name": "list_id", "type": "string", "nullable": false }
1665 ],
1666 "primaryKey": "id",
1667 "scopes": [{ "pattern": "list:{list_id}", "column": "list_id" }]
1668 }]
1669 })
1670 }
1671
1672 #[test]
1673 fn native_command_realtime_connection_is_idempotent() {
1674 let mut transport = NoNetwork::default();
1675 let mut client: Option<SyncClient> = None;
1676 let mut effects = CreateEffects::default();
1677 dispatch(
1678 &mut transport,
1679 &mut client,
1680 &mut effects,
1681 "create",
1682 &json!({ "schema": schema() }),
1683 )
1684 .expect("create client");
1685
1686 for _ in 0..2 {
1687 dispatch(
1688 &mut transport,
1689 &mut client,
1690 &mut effects,
1691 "connectRealtime",
1692 &json!({}),
1693 )
1694 .expect("idempotent connect command");
1695 }
1696 assert_eq!(transport.realtime_connects, 1);
1697
1698 dispatch(
1699 &mut transport,
1700 &mut client,
1701 &mut effects,
1702 "disconnectRealtime",
1703 &json!({}),
1704 )
1705 .expect("disconnect command");
1706 dispatch(
1707 &mut transport,
1708 &mut client,
1709 &mut effects,
1710 "disconnectRealtime",
1711 &json!({}),
1712 )
1713 .expect("idempotent disconnect command");
1714 assert_eq!(transport.realtime_closes, 1);
1715 dispatch(
1716 &mut transport,
1717 &mut client,
1718 &mut effects,
1719 "connectRealtime",
1720 &json!({}),
1721 )
1722 .expect("deliberate reconnect command");
1723 assert_eq!(transport.realtime_connects, 2);
1724 }
1725
1726 #[test]
1727 fn local_authority_commands_without_one_report_the_unconfigured_code() {
1728 let mut transport = NoNetwork::default();
1729 let mut client: Option<SyncClient> = None;
1730 let mut effects = CreateEffects::default();
1731 let state = dispatch(
1732 &mut transport,
1733 &mut client,
1734 &mut effects,
1735 "localAuthorityState",
1736 &json!({}),
1737 )
1738 .expect("state without a client");
1739 assert_eq!(state, json!({ "state": null }));
1740 dispatch(
1741 &mut transport,
1742 &mut client,
1743 &mut effects,
1744 "create",
1745 &json!({ "schema": schema() }),
1746 )
1747 .expect("create client");
1748 for method in ["attachLocalAuthority", "abandonLocalAuthorityAttach"] {
1749 let error = dispatch(
1750 &mut transport,
1751 &mut client,
1752 &mut effects,
1753 method,
1754 &json!({}),
1755 )
1756 .expect_err("no local authority");
1757 assert_eq!(error.code, "client.local_authority_unconfigured");
1758 }
1759 let running = client.as_mut().expect("client");
1760 assert!(running.transport_enabled());
1761 assert!(
1762 running.drain_sync_intents().is_empty(),
1763 "the gate never toggled"
1764 );
1765 }
1766
1767 struct ScriptedAuthority {
1769 opened: Vec<(Value, Option<String>)>,
1770 open_error: Option<TransportError>,
1771 attach_error: Option<TransportError>,
1772 abandons: usize,
1773 }
1774
1775 impl Transport for ScriptedAuthority {
1776 fn sync(&mut self, _request: &[u8]) -> Result<Vec<u8>, TransportError> {
1777 Err(TransportError::new("sync.transport_failed", "offline"))
1778 }
1779 fn realtime_sync(&mut self, _request: &[u8]) -> Result<Vec<u8>, TransportError> {
1780 Err(TransportError::new("sync.transport_failed", "offline"))
1781 }
1782 fn download_segment(
1783 &mut self,
1784 _request: &SegmentRequest,
1785 _on_progress: &mut dyn FnMut(u64),
1786 ) -> Result<Vec<u8>, TransportError> {
1787 Err(TransportError::new("sync.transport_failed", "offline"))
1788 }
1789 fn realtime_connect(&mut self) -> Result<(), TransportError> {
1790 Ok(())
1791 }
1792 fn realtime_send(&mut self, _text: &str) -> Result<(), TransportError> {
1793 Ok(())
1794 }
1795 fn realtime_close(&mut self) -> Result<(), TransportError> {
1796 Ok(())
1797 }
1798 fn open_local_authority(
1799 &mut self,
1800 schema: &Value,
1801 replica_path: Option<&str>,
1802 ) -> Result<(), TransportError> {
1803 self.opened
1804 .push((schema.clone(), replica_path.map(str::to_owned)));
1805 self.open_error.take().map_or(Ok(()), Err)
1806 }
1807 fn local_authority_state(&self) -> Option<&'static str> {
1808 (!self.opened.is_empty()).then_some("local")
1809 }
1810 fn attach_local_authority(&mut self) -> Result<(), TransportError> {
1811 self.attach_error.take().map_or(Ok(()), Err)
1812 }
1813 fn abandon_local_authority_attach(&mut self) -> Result<(), TransportError> {
1814 self.abandons += 1;
1815 Ok(())
1816 }
1817 }
1818
1819 #[test]
1820 fn local_authority_opens_at_create_and_attach_errors_keep_code_and_details() {
1821 let mut transport = ScriptedAuthority {
1822 opened: Vec::new(),
1823 open_error: Some(TransportError::new("sync.internal_error", "open failed")),
1824 attach_error: Some(TransportError {
1825 code: "sync.attach_rejected".to_owned(),
1826 message: "the remote server refused an attach commit".to_owned(),
1827 details: Some(json!({ "reason": "commit_rejected", "opIndex": 0 })),
1828 }),
1829 abandons: 0,
1830 };
1831 let mut client: Option<SyncClient> = None;
1832 let mut effects = CreateEffects::default();
1833 let error = dispatch(
1834 &mut transport,
1835 &mut client,
1836 &mut effects,
1837 "create",
1838 &json!({ "schema": schema() }),
1839 )
1840 .expect_err("an authority that fails to open fails create");
1841 assert_eq!(error.code, "sync.internal_error");
1842 assert!(client.is_none());
1843
1844 dispatch(
1845 &mut transport,
1846 &mut client,
1847 &mut effects,
1848 "create",
1849 &json!({ "schema": schema() }),
1850 )
1851 .expect("create client");
1852 assert_eq!(transport.opened.len(), 2);
1853 assert_eq!(transport.opened[1], (schema(), None));
1854 let state = dispatch(
1855 &mut transport,
1856 &mut client,
1857 &mut effects,
1858 "localAuthorityState",
1859 &json!({}),
1860 )
1861 .expect("state");
1862 assert_eq!(state, json!({ "state": "local" }));
1863
1864 let error = dispatch(
1865 &mut transport,
1866 &mut client,
1867 &mut effects,
1868 "attachLocalAuthority",
1869 &json!({}),
1870 )
1871 .expect_err("scripted rejection");
1872 assert_eq!(error.code, "sync.attach_rejected");
1873 assert_eq!(
1874 error.details,
1875 Some(json!({ "reason": "commit_rejected", "opIndex": 0 }))
1876 );
1877 assert!(client.as_ref().expect("client").transport_enabled());
1878
1879 let abandoned = dispatch(
1880 &mut transport,
1881 &mut client,
1882 &mut effects,
1883 "abandonLocalAuthorityAttach",
1884 &json!({}),
1885 )
1886 .expect("abandon");
1887 assert_eq!(abandoned["effects"]["sync"]["kind"], "interactive");
1888 assert_eq!(transport.abandons, 1);
1889
1890 dispatch(
1892 &mut transport,
1893 &mut client,
1894 &mut effects,
1895 "setTransportEnabled",
1896 &json!({ "enabled": false }),
1897 )
1898 .expect("go offline");
1899 let attached = dispatch(
1900 &mut transport,
1901 &mut client,
1902 &mut effects,
1903 "attachLocalAuthority",
1904 &json!({}),
1905 )
1906 .expect("attach");
1907 assert!(attached["effects"].get("sync").is_none());
1908 assert!(!client.as_ref().expect("client").transport_enabled());
1909 }
1910
1911 #[test]
1912 fn schema_downgrade_has_structured_code_at_create_and_recreate_boundaries() {
1913 let path = temp_db_path("schema-downgrade");
1914 let mut newer = schema();
1915 newer["version"] = json!(3);
1916 let mut older = schema();
1917 older["version"] = json!(2);
1918 let mut transport = NoNetwork::default();
1919 let mut client = None;
1920 let mut effects = CreateEffects::default();
1921 dispatch(
1922 &mut transport,
1923 &mut client,
1924 &mut effects,
1925 "create",
1926 &json!({ "schema": newer, "dbPath": path }),
1927 )
1928 .expect("v3 create");
1929 let error = dispatch(
1930 &mut transport,
1931 &mut client,
1932 &mut effects,
1933 "recreateWithSchema",
1934 &json!({ "schema": older }),
1935 )
1936 .expect_err("refuse recreation");
1937 assert_eq!(error.code, "client.schema_downgrade");
1938 assert_eq!(
1939 error.message,
1940 "client.schema_downgrade: persisted local schema is newer than the requested schema"
1941 );
1942 dispatch(
1943 &mut transport,
1944 &mut client,
1945 &mut effects,
1946 "shutdown",
1947 &json!({}),
1948 )
1949 .expect("shutdown");
1950 let error = dispatch(
1951 &mut transport,
1952 &mut client,
1953 &mut effects,
1954 "create",
1955 &json!({ "schema": older, "dbPath": path }),
1956 )
1957 .expect_err("refuse open");
1958 assert_eq!(error.code, "client.schema_downgrade");
1959 assert!(client.is_none());
1960 dispatch(
1961 &mut transport,
1962 &mut client,
1963 &mut effects,
1964 "create",
1965 &json!({ "schema": newer, "dbPath": path }),
1966 )
1967 .expect("compatible reopen");
1968 dispatch(
1969 &mut transport,
1970 &mut client,
1971 &mut effects,
1972 "shutdown",
1973 &json!({}),
1974 )
1975 .expect("shutdown");
1976 let _ = std::fs::remove_file(path);
1977 }
1978
1979 #[test]
1980 fn native_command_realtime_policy_rides_create_and_refuses_http() {
1981 let mut transport = NoNetwork::default();
1982 let mut client: Option<SyncClient> = None;
1983 let mut effects = CreateEffects::default();
1984 dispatch(
1985 &mut transport,
1986 &mut client,
1987 &mut effects,
1988 "create",
1989 &json!({ "schema": schema(), "realtimePolicy": "required" }),
1990 )
1991 .expect("create client with a required realtime policy");
1992 let result = dispatch(
1993 &mut transport,
1994 &mut client,
1995 &mut effects,
1996 "sync",
1997 &json!({}),
1998 )
1999 .expect("sync command");
2000 assert_eq!(result["ok"], json!(false));
2001 assert_eq!(result["errorCode"], json!("sync.realtime_unavailable"));
2002 assert_eq!(result["realtimeState"], json!("disconnected"));
2003 assert_eq!(result["retryDelayMs"], json!(250));
2004 let snapshot = dispatch(
2005 &mut transport,
2006 &mut client,
2007 &mut effects,
2008 "diagnosticsSnapshot",
2009 &json!({}),
2010 )
2011 .expect("diagnostics command");
2012 assert_eq!(snapshot["host"]["realtime"], json!("disconnected"));
2013 assert_eq!(snapshot["host"]["realtimePolicy"], json!("required"));
2014 assert_eq!(snapshot["host"]["realtimeRetryDelayMs"], json!(250));
2015
2016 let mut second: Option<SyncClient> = None;
2017 let error = dispatch(
2018 &mut transport,
2019 &mut second,
2020 &mut effects,
2021 "create",
2022 &json!({ "schema": schema(), "realtimePolicy": "always" }),
2023 )
2024 .expect_err("an unknown policy is refused");
2025 assert_eq!(error.code, "sync.invalid_request");
2026 }
2027
2028 #[test]
2029 fn parses_portable_encryption_keyring_and_key_id_columns() {
2030 let key_hex = "2a".repeat(32);
2031 let config = parse_encryption(&json!({
2032 "keys": { "practice-key-v1": { "$bytes": key_hex } },
2033 "keyIdColumns": { "patients": "encryption_key_id" }
2034 }))
2035 .expect("portable keyring parses");
2036 assert_eq!(config.keys["practice-key-v1"], vec![0x2a; 32]);
2037 assert_eq!(config.key_id_columns["patients"], "encryption_key_id");
2038 }
2039
2040 #[test]
2041 fn parses_missing_key_mode_with_fail_as_default() {
2042 use syncular_client::values::MissingKey;
2043 let mode = |value: Value| parse_encryption(&value).map(|config| config.missing_key);
2044 assert_eq!(mode(json!({})), Ok(MissingKey::Fail));
2045 assert_eq!(mode(json!({ "missingKey": "fail" })), Ok(MissingKey::Fail));
2046 assert_eq!(mode(json!({ "missingKey": "seal" })), Ok(MissingKey::Seal));
2047 assert!(mode(json!({ "missingKey": "skip" }))
2048 .expect_err("an unknown mode is refused")
2049 .contains("missingKey"));
2050 }
2051
2052 #[test]
2053 fn rejects_non_string_key_id_columns() {
2054 let error = parse_encryption(&json!({
2055 "keys": {},
2056 "keyIdColumns": { "patients": 7 }
2057 }))
2058 .expect_err("invalid selector must fail");
2059 assert!(error.contains("must be a string"), "{error}");
2060 }
2061
2062 #[test]
2063 fn subscribe_many_registers_every_unit() {
2064 let mut transport = NoNetwork::default();
2065 let mut client: Option<SyncClient> = None;
2066 let mut effects = CreateEffects::default();
2067 let mut run = |command: &str, params: Value| {
2068 dispatch(&mut transport, &mut client, &mut effects, command, ¶ms)
2069 };
2070 run("create", json!({ "schema": schema() })).expect("create client");
2071 let ids = run(
2072 "subscribeMany",
2073 json!({ "units": [{ "list_id": "list-1" }, { "list_id": "list-2" }] }),
2074 )
2075 .expect("register units")["ids"]
2076 .clone();
2077 let single = run("subscribe", json!({ "scopes": { "list_id": "list-1" } }))
2078 .expect("re-register a unit");
2079 assert_eq!(single["id"], ids[0], "a unit id derives from its scope map");
2080 let units = run("units", json!({})).expect("units");
2081 assert_eq!(units["units"].as_array().map(Vec::len), Some(2));
2082 for (index, list) in ["list-1", "list-2"].into_iter().enumerate() {
2083 let unit = run("unit", json!({ "id": ids[index] })).expect("unit");
2084 assert_eq!(unit["unit"]["scopes"], json!({ "list_id": list }));
2085 assert_eq!(unit["unit"]["cursor"], -1);
2086 }
2087 assert_eq!(
2088 run("unit", json!({ "id": "absent" })).expect("unit")["unit"],
2089 Value::Null
2090 );
2091 for scopes in [json!({ "list_id": "*" }), json!({ "other": "x" })] {
2092 let error = run("subscribe", json!({ "scopes": scopes }))
2093 .expect_err("a unit names a non-wildcard value per covered variable");
2094 assert_eq!(error.code, "sync.invalid_subscription", "{scopes}");
2095 }
2096 }
2097
2098 #[test]
2099 fn window_coverage_parser_reads_the_generated_descriptor_and_rejects_malformed_units() {
2100 let parsed = parse_window_coverage(Some(&json!([{
2101 "base": { "variable": "project_id", "fixedScopes": { "tenant_id": "one" } },
2102 "units": ["a", "b"]
2103 }])))
2104 .expect("parse coverage");
2105 assert_eq!(parsed[0].base.variable, "project_id");
2106 assert_eq!(
2107 parsed[0].base.fixed_scopes,
2108 UnitScopes::from([("tenant_id".to_owned(), "one".to_owned())])
2109 );
2110 assert_eq!(parsed[0].units, ["a", "b"]);
2111 for coverage in [
2112 json!({}),
2113 json!([{ "base": { "variable": "project_id" }, "units": ["a", 1] }]),
2114 json!([{ "base": { "fixedScopes": {} }, "units": [] }]),
2115 ] {
2116 let error = parse_window_coverage(Some(&coverage)).expect_err("malformed coverage");
2117 assert!(error.starts_with("sync.invalid_request: "), "{error}");
2118 }
2119 }
2120
2121 #[test]
2122 fn subscribe_and_unsubscribe_queue_an_interactive_sync_intent() {
2123 let mut transport = NoNetwork::default();
2124 let mut client: Option<SyncClient> = None;
2125 let mut effects = CreateEffects::default();
2126 let mut run = |command: &str, params: Value| {
2127 dispatch(&mut transport, &mut client, &mut effects, command, ¶ms)
2128 .expect("command succeeds")
2129 };
2130 run("create", json!({ "schema": schema() }));
2131 run("drainSyncIntents", json!({}));
2132 let id = run("subscribe", json!({ "scopes": { "list_id": "list-1" } }))["id"].clone();
2133 let intents = run("drainSyncIntents", json!({}));
2134 assert_eq!(intents["intents"], json!([{ "kind": "interactive" }]));
2135 run("unsubscribe", json!({ "id": id }));
2136 let intents = run("drainSyncIntents", json!({}));
2137 assert_eq!(intents["intents"], json!([{ "kind": "interactive" }]));
2138 }
2139
2140 #[test]
2141 fn security_preflight_is_fail_closed_until_exact_activation() {
2142 let mut transport = NoNetwork::default();
2143 let mut client: Option<SyncClient> = None;
2144 let mut effects = CreateEffects::default();
2145 dispatch(
2146 &mut transport,
2147 &mut client,
2148 &mut effects,
2149 "create",
2150 &json!({ "schema": schema(), "securityPreflight": true }),
2151 )
2152 .expect("preflight create");
2153
2154 let lifecycle = dispatch(
2155 &mut transport,
2156 &mut client,
2157 &mut effects,
2158 "securityLifecycle",
2159 &json!({}),
2160 )
2161 .expect("lifecycle");
2162 assert_eq!(lifecycle, json!({ "state": "preflight" }));
2163
2164 let query_error = dispatch(
2165 &mut transport,
2166 &mut client,
2167 &mut effects,
2168 "query",
2169 &json!({ "sql": "SELECT id FROM todos", "params": [] }),
2170 )
2171 .expect_err("protected query must fail");
2172 assert_eq!(query_error.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2173 let diagnostics_error = dispatch(
2174 &mut transport,
2175 &mut client,
2176 &mut effects,
2177 "diagnosticsSnapshot",
2178 &json!({}),
2179 )
2180 .expect_err("diagnostics unit evidence remains protected");
2181 assert_eq!(diagnostics_error.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2182
2183 dispatch(
2184 &mut transport,
2185 &mut client,
2186 &mut effects,
2187 "purgeLocalData",
2188 &json!({
2189 "input": {
2190 "purgeId": "directive-1",
2191 "targets": [{
2192 "table": "todos",
2193 "selectors": { "list_id": ["list-1"] }
2194 }]
2195 }
2196 }),
2197 )
2198 .expect("authorized local purge remains available");
2199
2200 let repair_error = dispatch(
2201 &mut transport,
2202 &mut client,
2203 &mut effects,
2204 "rebootstrapLocalData",
2205 &json!({ "input": { "rebootstrapId": "blocked-repair" } }),
2206 )
2207 .expect_err("projection repair must remain protected during preflight");
2208 assert_eq!(repair_error.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2209
2210 dispatch(
2211 &mut transport,
2212 &mut client,
2213 &mut effects,
2214 "activateSecurity",
2215 &json!({}),
2216 )
2217 .expect("activation");
2218 let rows = dispatch(
2219 &mut transport,
2220 &mut client,
2221 &mut effects,
2222 "query",
2223 &json!({ "sql": "SELECT id FROM todos", "params": [] }),
2224 )
2225 .expect("active query");
2226 assert_eq!(rows, json!({ "rows": [] }));
2227
2228 dispatch(
2229 &mut transport,
2230 &mut client,
2231 &mut effects,
2232 "beginSecurityPreflight",
2233 &json!({}),
2234 )
2235 .expect("re-enter preflight");
2236 let blocked = dispatch(
2237 &mut transport,
2238 &mut client,
2239 &mut effects,
2240 "mutate",
2241 &json!({ "mutations": [] }),
2242 )
2243 .expect_err("mutation must be gated");
2244 assert_eq!(blocked.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2245 }
2246
2247 #[test]
2248 fn mutate_and_patch_forward_typed_storage_failures() {
2249 let path = temp_db_path("busy-authoring");
2250 let schema = json!({
2251 "version": 1,
2252 "tables": [{
2253 "name": "todos",
2254 "columns": [
2255 { "name": "id", "type": "string", "nullable": false },
2256 { "name": "list_id", "type": "string", "nullable": false },
2257 { "name": "title", "type": "string", "nullable": false }
2258 ],
2259 "primaryKey": "id",
2260 "scopes": [{ "pattern": "list:{list_id}", "column": "list_id" }]
2261 }]
2262 });
2263 let mut transport = NoNetwork::default();
2264 let mut client: Option<SyncClient> = None;
2265 let mut effects = CreateEffects::default();
2266 dispatch(
2267 &mut transport,
2268 &mut client,
2269 &mut effects,
2270 "create",
2271 &json!({ "schema": schema, "dbPath": path }),
2272 )
2273 .expect("create file-backed client");
2274 let upsert = |id: &str| {
2275 json!({ "mutations": [{ "op": "upsert", "table": "todos", "values": {
2276 "id": id, "list_id": "l1", "title": "first" } }] })
2277 };
2278 dispatch(
2279 &mut transport,
2280 &mut client,
2281 &mut effects,
2282 "mutate",
2283 &upsert("t1"),
2284 )
2285 .expect("seed row");
2286
2287 let locker = rusqlite::Connection::open(&path).expect("second connection");
2288 locker.execute_batch("BEGIN IMMEDIATE").unwrap();
2289 let busy = dispatch(
2290 &mut transport,
2291 &mut client,
2292 &mut effects,
2293 "mutate",
2294 &upsert("t2"),
2295 )
2296 .expect_err("busy mutate");
2297 assert_eq!(busy.code, "client.storage_busy");
2298 assert!(busy.retryable);
2299 assert_eq!(busy.details.as_ref().unwrap()["sqliteCode"], 5);
2300
2301 let busy_patch = dispatch(
2302 &mut transport,
2303 &mut client,
2304 &mut effects,
2305 "patch",
2306 &json!({ "table": "todos", "rowId": "t1", "partial": { "title": "second" } }),
2307 )
2308 .expect_err("busy patch");
2309 assert_eq!(busy_patch.code, "client.storage_busy");
2310 assert!(busy_patch.retryable);
2311 assert_eq!(busy_patch.details.as_ref().unwrap()["sqliteCode"], 5);
2312
2313 locker.execute_batch("ROLLBACK").unwrap();
2314 let retried = dispatch(
2315 &mut transport,
2316 &mut client,
2317 &mut effects,
2318 "mutate",
2319 &upsert("t2"),
2320 )
2321 .expect("retry after busy");
2322 assert!(retried.get("clientCommitId").is_some());
2323 let _ = std::fs::remove_file(&path);
2324 }
2325
2326 #[test]
2327 fn read_command_error_preserves_code_details_and_retryability() {
2328 let corrupt = super::read_command_error(syncular_client::QueryReadFailure {
2329 code: Some("sync.local_corrupt"),
2330 sqlite_code: None,
2331 sqlite_message: None,
2332 rollback_failure: None,
2333 message: "persisted local revision is invalid".to_owned(),
2334 });
2335 assert_eq!(corrupt.code, "sync.local_corrupt");
2336 assert!(!corrupt.retryable);
2337 assert!(corrupt.details.is_none());
2338
2339 let busy = super::read_command_error(syncular_client::QueryReadFailure {
2340 code: Some("client.storage_busy"),
2341 sqlite_code: Some(5),
2342 sqlite_message: Some("database is locked".to_owned()),
2343 rollback_failure: None,
2344 message: "local SQLite storage is busy".to_owned(),
2345 });
2346 assert_eq!(busy.code, "client.storage_busy");
2347 assert!(busy.retryable);
2348 assert_eq!(
2349 busy.details.expect("busy details")["sqliteCode"],
2350 serde_json::json!(5)
2351 );
2352 }
2353
2354 #[test]
2355 fn mutate_and_patch_report_caller_value_failures_as_invalid_request() {
2356 let path = temp_db_path("caller-values");
2357 let schema = json!({
2358 "version": 1,
2359 "tables": [{
2360 "name": "todos",
2361 "columns": [
2362 { "name": "id", "type": "string", "nullable": false },
2363 { "name": "list_id", "type": "string", "nullable": false },
2364 { "name": "title", "type": "string", "nullable": false },
2365 { "name": "priority", "type": "integer", "nullable": false }
2366 ],
2367 "primaryKey": "id",
2368 "scopes": [{ "pattern": "list:{list_id}", "column": "list_id" }]
2369 }]
2370 });
2371 let mut transport = NoNetwork::default();
2372 let mut client: Option<SyncClient> = None;
2373 let mut effects = CreateEffects::default();
2374 dispatch(
2375 &mut transport,
2376 &mut client,
2377 &mut effects,
2378 "create",
2379 &json!({ "schema": schema, "dbPath": path }),
2380 )
2381 .expect("create file-backed client");
2382 let seed = dispatch(
2383 &mut transport,
2384 &mut client,
2385 &mut effects,
2386 "mutate",
2387 &json!({ "mutations": [{ "op": "upsert", "table": "todos", "values": {
2388 "id": "t1", "list_id": "l1", "title": "first", "priority": 1 } }] }),
2389 )
2390 .expect("seed row");
2391 let seed_id = seed["clientCommitId"].clone();
2392
2393 let unknown = dispatch(
2396 &mut transport,
2397 &mut client,
2398 &mut effects,
2399 "mutate",
2400 &json!({ "mutations": [{ "op": "upsert", "table": "todos", "values": {
2401 "id": "t2", "list_id": "l1", "title": "second", "priority": 1,
2402 "missing_column": 1 } }] }),
2403 )
2404 .expect_err("unknown column");
2405 assert_eq!(unknown.code, "sync.invalid_request");
2406 assert_eq!(unknown.message, "the authoring request is invalid");
2407 assert!(!unknown.retryable);
2408 assert!(unknown.details.as_ref().unwrap()["legacyCause"]
2409 .as_str()
2410 .unwrap()
2411 .contains("unknown column"));
2412
2413 let bad_patch = dispatch(
2414 &mut transport,
2415 &mut client,
2416 &mut effects,
2417 "patch",
2418 &json!({ "table": "todos", "rowId": "t1", "partial": { "priority": "high" } }),
2419 )
2420 .expect_err("bad patch value");
2421 assert_eq!(bad_patch.code, "sync.invalid_request");
2422 assert_eq!(bad_patch.message, "the authoring request is invalid");
2423 assert!(bad_patch.details.as_ref().unwrap()["legacyCause"]
2424 .as_str()
2425 .unwrap()
2426 .contains("priority"));
2427
2428 let pending = dispatch(
2430 &mut transport,
2431 &mut client,
2432 &mut effects,
2433 "pendingCommitIds",
2434 &json!({}),
2435 )
2436 .expect("pending commit ids");
2437 assert_eq!(pending["ids"], json!([seed_id]));
2438 let rows = dispatch(
2439 &mut transport,
2440 &mut client,
2441 &mut effects,
2442 "query",
2443 &json!({ "sql": "SELECT id, priority FROM todos ORDER BY id" }),
2444 )
2445 .expect("visible rows");
2446 assert_eq!(rows["rows"], json!([{ "id": "t1", "priority": 1 }]));
2447
2448 let accepted = dispatch(
2450 &mut transport,
2451 &mut client,
2452 &mut effects,
2453 "mutate",
2454 &json!({ "mutations": [{ "op": "upsert", "table": "todos", "values": {
2455 "id": "t2", "list_id": "l1", "title": "second", "priority": 2 } }] }),
2456 )
2457 .expect("retry after rejection");
2458 assert!(accepted.get("clientCommitId").is_some());
2459 let _ = std::fs::remove_file(&path);
2460 }
2461
2462 #[test]
2463 fn client_err_preserves_retryable_for_storage_busy() {
2464 let busy = client_err("client.storage_busy: local SQLite storage is busy".to_owned());
2465 assert_eq!(busy.code, "client.storage_busy");
2466 assert!(busy.retryable);
2467 assert_eq!(
2469 busy.message,
2470 "client.storage_busy: local SQLite storage is busy"
2471 );
2472 let full = client_err("client.storage_full: local SQLite storage is full".to_owned());
2473 assert_eq!(full.code, "client.storage_full");
2474 assert!(!full.retryable);
2475 }
2476
2477 #[test]
2478 fn client_err_keeps_a_colon_less_code_identity() {
2479 let error = client_err("sync.unknown_table".to_owned());
2480 assert_eq!(error.code, "sync.unknown_table");
2481 let error = client_err("no client instance created".to_owned());
2482 assert_eq!(error.code, "client.failed");
2483 }
2484
2485 #[cfg(feature = "crdt-yjs")]
2486 #[test]
2487 fn crdt_offsets_outside_u32_are_invalid_requests() {
2488 let mut transport = NoNetwork::default();
2489 let mut client: Option<SyncClient> = None;
2490 let mut effects = CreateEffects::default();
2491 dispatch(
2492 &mut transport,
2493 &mut client,
2494 &mut effects,
2495 "create",
2496 &json!({ "schema": schema() }),
2497 )
2498 .expect("create");
2499 let target = json!({ "table": "todos", "rowId": "t1", "column": "body" });
2500 for (method, extra) in [
2501 (
2502 "crdtInsertText",
2503 json!({ "index": 4_294_967_296u64, "value": "x" }),
2504 ),
2505 ("crdtInsertText", json!({ "index": "0", "value": "x" })),
2506 (
2507 "crdtDeleteText",
2508 json!({ "index": 0, "len": 4_294_967_296u64 }),
2509 ),
2510 ] {
2511 let mut params = target.clone();
2512 params
2513 .as_object_mut()
2514 .unwrap()
2515 .extend(extra.as_object().unwrap().clone());
2516 let error = dispatch(&mut transport, &mut client, &mut effects, method, ¶ms)
2517 .expect_err("out-of-range offset");
2518 assert_eq!(error.code, "sync.invalid_request", "{method} {params}");
2519 }
2520 }
2521
2522 #[test]
2523 fn wrong_typed_optional_fields_are_invalid_requests() {
2524 let created = || {
2525 let mut transport = NoNetwork::default();
2526 let mut client: Option<SyncClient> = None;
2527 let mut effects = CreateEffects::default();
2528 dispatch(
2529 &mut transport,
2530 &mut client,
2531 &mut effects,
2532 "create",
2533 &json!({ "schema": schema() }),
2534 )
2535 .expect("create");
2536 (transport, client, effects)
2537 };
2538 for params in [
2539 json!({ "schema": schema(), "limits": "x" }),
2540 json!({ "schema": schema(), "limits": { "accept": 256 } }),
2541 json!({ "schema": schema(), "limits": { "accept": "15" } }),
2542 json!({ "schema": schema(), "limits": { "limitCommits": 4_294_967_296i64 } }),
2543 json!({ "schema": schema(), "limits": { "outcomeRetentionMaxEntries": -1 } }),
2544 json!({ "schema": schema(), "clientId": 7 }),
2545 json!({ "schema": schema(), "nowMs": "1" }),
2546 json!({ "schema": schema(), "signedUrls": "true" }),
2547 json!({ "schema": schema(), "securityPreflight": 1 }),
2548 json!({ "schema": schema(), "encryption": { "keys": "k" } }),
2549 ] {
2550 let mut transport = NoNetwork::default();
2551 let mut client: Option<SyncClient> = None;
2552 let mut effects = CreateEffects::default();
2553 let error = dispatch(&mut transport, &mut client, &mut effects, "create", ¶ms)
2554 .expect_err("wrong-typed create field");
2555 assert_eq!(error.code, "sync.invalid_request", "{params}");
2556 }
2557 let base = json!({ "variable": "list_id" });
2558 for (method, params) in [
2559 ("setWindow", json!({ "base": base, "units": [1] })),
2560 ("setWindow", json!({ "base": base, "units": "l1" })),
2561 (
2562 "setWindow",
2563 json!({ "base": { "variable": "list_id", "fixedScopes": ["x"] }, "units": [] }),
2564 ),
2565 ("windowState", json!({ "base": {} })),
2566 (
2567 "mutate",
2568 json!({ "mutations": [{ "op": "delete", "table": "todos", "rowId": "t1", "baseVersion": "7" }] }),
2569 ),
2570 (
2571 "patch",
2572 json!({ "table": "todos", "rowId": "t1", "partial": { "title": "x" }, "baseVersion": "7" }),
2573 ),
2574 ("subscribe", json!({ "scopes": { "list_id": ["l1"] } })),
2575 (
2576 "subscribeMany",
2577 json!({ "units": [{ "list_id": "l1" }, 7] }),
2578 ),
2579 (
2580 "uploadBlob",
2581 json!({ "bytes": { "$bytes": "00" }, "mediaType": 1 }),
2582 ),
2583 ] {
2584 let (mut transport, mut client, mut effects) = created();
2585 let error = dispatch(&mut transport, &mut client, &mut effects, method, ¶ms)
2586 .expect_err("wrong-typed field");
2587 assert_eq!(error.code, "sync.invalid_request", "{method} {params}");
2588 }
2589 let (mut transport, mut client, mut effects) = created();
2591 dispatch(
2592 &mut transport,
2593 &mut client,
2594 &mut effects,
2595 "mutate",
2596 &json!({ "mutations": [{ "op": "delete", "table": "todos", "rowId": "t1", "baseVersion": null }] }),
2597 )
2598 .expect("null baseVersion is absent");
2599 }
2600
2601 #[test]
2602 fn sync_until_idle_rejects_an_invalid_max_rounds_budget() {
2603 for value in [json!(0), json!(-1), json!(1.5), json!(4_294_967_296u64)] {
2604 let mut transport = NoNetwork::default();
2605 let mut client: Option<SyncClient> = None;
2606 let mut effects = CreateEffects::default();
2607 dispatch(
2608 &mut transport,
2609 &mut client,
2610 &mut effects,
2611 "create",
2612 &json!({ "schema": schema() }),
2613 )
2614 .expect("create");
2615 let error = dispatch(
2616 &mut transport,
2617 &mut client,
2618 &mut effects,
2619 "syncUntilIdle",
2620 &json!({ "maxRounds": value }),
2621 )
2622 .expect_err("invalid budget");
2623 assert_eq!(error.code, "sync.invalid_request", "{value}");
2624 }
2625 }
2626
2627 #[test]
2628 fn sync_until_idle_rejects_an_invalid_timeout() {
2629 for value in [json!(0), json!(-1), json!(1.5)] {
2630 let mut transport = NoNetwork::default();
2631 let mut client: Option<SyncClient> = None;
2632 let mut effects = CreateEffects::default();
2633 dispatch(
2634 &mut transport,
2635 &mut client,
2636 &mut effects,
2637 "create",
2638 &json!({ "schema": schema() }),
2639 )
2640 .expect("create");
2641 let error = dispatch(
2642 &mut transport,
2643 &mut client,
2644 &mut effects,
2645 "syncUntilIdle",
2646 &json!({ "timeoutMs": value }),
2647 )
2648 .expect_err("invalid timeout");
2649 assert_eq!(error.code, "sync.invalid_request", "{value}");
2650 }
2651 }
2652
2653 #[test]
2654 fn create_rejects_invalid_push_limits() {
2655 for value in [json!(0), json!(-1), json!(1.5), json!(4_294_967_296u64)] {
2656 let mut transport = NoNetwork::default();
2657 let mut client: Option<SyncClient> = None;
2658 let mut effects = CreateEffects::default();
2659 let error = dispatch(
2660 &mut transport,
2661 &mut client,
2662 &mut effects,
2663 "create",
2664 &json!({
2665 "schema": schema(),
2666 "limits": { "maxPushRequestBytes": value }
2667 }),
2668 )
2669 .expect_err("invalid push limit");
2670 assert_eq!(error.code, "sync.invalid_request", "{value}");
2671 assert_eq!(
2672 error.details.as_ref().unwrap()["limit"],
2673 json!("maxPushRequestBytes")
2674 );
2675 }
2676 }
2677
2678 #[test]
2679 fn preflight_allows_only_the_authorized_previous_version_discard() {
2680 let mut transport = NoNetwork::default();
2681 let mut client: Option<SyncClient> = None;
2682 let mut effects = CreateEffects::default();
2683 dispatch(
2684 &mut transport,
2685 &mut client,
2686 &mut effects,
2687 "create",
2688 &json!({ "schema": schema(), "securityPreflight": true }),
2689 )
2690 .expect("preflight create");
2691
2692 for method in ["previousVersionSnapshot", "previousVersionAudit"] {
2694 let error = dispatch(
2695 &mut transport,
2696 &mut client,
2697 &mut effects,
2698 method,
2699 &json!({}),
2700 )
2701 .expect_err("previous-version reads stay gated during preflight");
2702 assert_eq!(error.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2703 }
2704 let discarded = dispatch(
2707 &mut transport,
2708 &mut client,
2709 &mut effects,
2710 "previousVersionDiscard",
2711 &json!({}),
2712 )
2713 .expect("authorized cleanup is allowed during preflight");
2714 assert_eq!(discarded, json!({ "present": false, "discarded": false }));
2715 dispatch(
2717 &mut transport,
2718 &mut client,
2719 &mut effects,
2720 "disconnectRealtime",
2721 &json!({}),
2722 )
2723 .expect("disconnect is allowed during preflight");
2724 assert!(client.as_ref().is_some_and(SyncClient::security_preflight));
2725 }
2726
2727 #[test]
2728 fn disconnect_without_a_client_succeeds() {
2729 let mut transport = NoNetwork::default();
2730 let mut client: Option<SyncClient> = None;
2731 let mut effects = CreateEffects::default();
2732 dispatch(
2733 &mut transport,
2734 &mut client,
2735 &mut effects,
2736 "disconnectRealtime",
2737 &json!({}),
2738 )
2739 .expect("a missing client holds no socket");
2740 dispatch(
2741 &mut transport,
2742 &mut client,
2743 &mut effects,
2744 "create",
2745 &json!({ "schema": schema() }),
2746 )
2747 .expect("create");
2748 dispatch(
2749 &mut transport,
2750 &mut client,
2751 &mut effects,
2752 "shutdown",
2753 &json!({}),
2754 )
2755 .expect("shutdown");
2756 dispatch(
2757 &mut transport,
2758 &mut client,
2759 &mut effects,
2760 "disconnectRealtime",
2761 &json!({}),
2762 )
2763 .expect("a shut-down client holds no socket");
2764 }
2765
2766 #[test]
2767 fn preflight_refuses_a_replacement_create_without_the_flag() {
2768 let mut transport = NoNetwork::default();
2769 let mut client: Option<SyncClient> = None;
2770 let mut effects = CreateEffects::default();
2771 dispatch(
2772 &mut transport,
2773 &mut client,
2774 &mut effects,
2775 "create",
2776 &json!({ "schema": schema(), "securityPreflight": true }),
2777 )
2778 .expect("preflight create");
2779
2780 let escape = dispatch(
2782 &mut transport,
2783 &mut client,
2784 &mut effects,
2785 "create",
2786 &json!({ "schema": schema() }),
2787 )
2788 .expect_err("plain create must be refused during preflight");
2789 assert_eq!(escape.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2790 let query_error = dispatch(
2792 &mut transport,
2793 &mut client,
2794 &mut effects,
2795 "query",
2796 &json!({ "sql": "SELECT id FROM todos", "params": [] }),
2797 )
2798 .expect_err("protected query stays gated");
2799 assert_eq!(query_error.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2800
2801 dispatch(
2803 &mut transport,
2804 &mut client,
2805 &mut effects,
2806 "create",
2807 &json!({ "schema": schema(), "securityPreflight": true }),
2808 )
2809 .expect("preflighted replacement create");
2810 let still_gated = dispatch(
2811 &mut transport,
2812 &mut client,
2813 &mut effects,
2814 "query",
2815 &json!({ "sql": "SELECT id FROM todos", "params": [] }),
2816 )
2817 .expect_err("replacement stays gated");
2818 assert_eq!(still_gated.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2819
2820 dispatch(
2822 &mut transport,
2823 &mut client,
2824 &mut effects,
2825 "activateSecurity",
2826 &json!({}),
2827 )
2828 .expect("activation");
2829 dispatch(
2830 &mut transport,
2831 &mut client,
2832 &mut effects,
2833 "create",
2834 &json!({ "schema": schema() }),
2835 )
2836 .expect("plain create after activation");
2837 let rows = dispatch(
2838 &mut transport,
2839 &mut client,
2840 &mut effects,
2841 "query",
2842 &json!({ "sql": "SELECT id FROM todos", "params": [] }),
2843 )
2844 .expect("active query");
2845 assert_eq!(rows, json!({ "rows": [] }));
2846 }
2847
2848 fn temp_db_path(tag: &str) -> String {
2851 std::env::temp_dir()
2852 .join(format!(
2853 "syncular-command-{tag}-{}-{:?}.db",
2854 std::process::id(),
2855 std::time::SystemTime::now()
2856 .duration_since(std::time::UNIX_EPOCH)
2857 .expect("clock")
2858 .as_nanos()
2859 ))
2860 .to_string_lossy()
2861 .into_owned()
2862 }
2863
2864 #[test]
2865 fn an_activated_replica_reopens_plainly_after_shutdown() {
2866 let path = temp_db_path("activated-reopen");
2872 let mut transport = NoNetwork::default();
2873 let mut client: Option<SyncClient> = None;
2874 let mut effects = CreateEffects::default();
2875
2876 dispatch(
2877 &mut transport,
2878 &mut client,
2879 &mut effects,
2880 "create",
2881 &json!({ "schema": schema(), "securityPreflight": true, "dbPath": path }),
2882 )
2883 .expect("preflight create");
2884 dispatch(
2885 &mut transport,
2886 &mut client,
2887 &mut effects,
2888 "activateSecurity",
2889 &json!({}),
2890 )
2891 .expect("activation clears the gate");
2892 dispatch(
2893 &mut transport,
2894 &mut client,
2895 &mut effects,
2896 "shutdown",
2897 &json!({}),
2898 )
2899 .expect("shutdown after activation");
2900
2901 dispatch(
2903 &mut transport,
2904 &mut client,
2905 &mut effects,
2906 "create",
2907 &json!({ "schema": schema(), "dbPath": path }),
2908 )
2909 .expect("an activated replica must reopen plainly after shutdown");
2910 let state = dispatch(
2911 &mut transport,
2912 &mut client,
2913 &mut effects,
2914 "securityLifecycle",
2915 &json!({}),
2916 )
2917 .expect("lifecycle");
2918 assert_eq!(state, json!({ "state": "active" }));
2919
2920 let _ = std::fs::remove_file(&path);
2921 }
2922
2923 #[test]
2924 fn an_unactivated_replica_stays_quarantined_across_shutdown_on_disk() {
2925 let path = temp_db_path("quarantined-reopen");
2930 let mut transport = NoNetwork::default();
2931 let mut client: Option<SyncClient> = None;
2932 let mut effects = CreateEffects::default();
2933
2934 dispatch(
2935 &mut transport,
2936 &mut client,
2937 &mut effects,
2938 "create",
2939 &json!({ "schema": schema(), "securityPreflight": true, "dbPath": path }),
2940 )
2941 .expect("preflight create");
2942 dispatch(
2943 &mut transport,
2944 &mut client,
2945 &mut effects,
2946 "shutdown",
2947 &json!({}),
2948 )
2949 .expect("shutdown during preflight");
2950
2951 let mut rebuilt = CreateEffects::default();
2954 let escape = dispatch(
2955 &mut transport,
2956 &mut client,
2957 &mut rebuilt,
2958 "create",
2959 &json!({ "schema": schema(), "dbPath": path }),
2960 )
2961 .expect_err("a quarantined replica must refuse a plain re-create");
2962 assert_eq!(escape.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2963
2964 let _ = std::fs::remove_file(&path);
2965 }
2966
2967 #[test]
2968 fn preflight_gate_survives_shutdown_before_replacement_creates() {
2969 let mut transport = NoNetwork::default();
2970 let mut client: Option<SyncClient> = None;
2971 let mut effects = CreateEffects::default();
2972 dispatch(
2973 &mut transport,
2974 &mut client,
2975 &mut effects,
2976 "create",
2977 &json!({ "schema": schema(), "securityPreflight": true }),
2978 )
2979 .expect("preflight create");
2980 dispatch(
2981 &mut transport,
2982 &mut client,
2983 &mut effects,
2984 "shutdown",
2985 &json!({}),
2986 )
2987 .expect("shutdown during preflight");
2988 assert!(client.is_none());
2989
2990 let escape = dispatch(
2992 &mut transport,
2993 &mut client,
2994 &mut effects,
2995 "create",
2996 &json!({ "schema": schema() }),
2997 )
2998 .expect_err("shutdown + plain create must stay refused");
2999 assert_eq!(escape.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
3000
3001 dispatch(
3002 &mut transport,
3003 &mut client,
3004 &mut effects,
3005 "create",
3006 &json!({ "schema": schema(), "securityPreflight": true }),
3007 )
3008 .expect("preflighted re-create");
3009 dispatch(
3010 &mut transport,
3011 &mut client,
3012 &mut effects,
3013 "activateSecurity",
3014 &json!({}),
3015 )
3016 .expect("activation");
3017
3018 dispatch(
3020 &mut transport,
3021 &mut client,
3022 &mut effects,
3023 "shutdown",
3024 &json!({}),
3025 )
3026 .expect("shutdown after activation");
3027 dispatch(
3028 &mut transport,
3029 &mut client,
3030 &mut effects,
3031 "create",
3032 &json!({ "schema": schema() }),
3033 )
3034 .expect("plain create after an activated shutdown");
3035 }
3036
3037 #[test]
3038 fn activate_security_validates_optional_headers_atomically() {
3039 let mut transport = NoNetwork::default();
3040 let mut client: Option<SyncClient> = None;
3041 let mut effects = CreateEffects::default();
3042 dispatch(
3043 &mut transport,
3044 &mut client,
3045 &mut effects,
3046 "create",
3047 &json!({ "schema": schema(), "securityPreflight": true }),
3048 )
3049 .expect("preflight create");
3050
3051 let invalid = dispatch(
3053 &mut transport,
3054 &mut client,
3055 &mut effects,
3056 "activateSecurity",
3057 &json!({ "headers": { "authorization": 7 } }),
3058 )
3059 .expect_err("non-string header must fail");
3060 assert_eq!(invalid.code, "sync.invalid_request");
3061 let lifecycle = dispatch(
3062 &mut transport,
3063 &mut client,
3064 &mut effects,
3065 "securityLifecycle",
3066 &json!({}),
3067 )
3068 .expect("lifecycle");
3069 assert_eq!(lifecycle, json!({ "state": "preflight" }));
3070
3071 dispatch(
3073 &mut transport,
3074 &mut client,
3075 &mut effects,
3076 "activateSecurity",
3077 &json!({ "headers": { "authorization": "Bearer fresh" } }),
3078 )
3079 .expect("activation with fresh headers");
3080 let lifecycle = dispatch(
3081 &mut transport,
3082 &mut client,
3083 &mut effects,
3084 "securityLifecycle",
3085 &json!({}),
3086 )
3087 .expect("lifecycle");
3088 assert_eq!(lifecycle, json!({ "state": "active" }));
3089 }
3090
3091 #[test]
3092 fn parse_headers_reads_the_full_replacement_set() {
3093 let parsed = parse_headers(&json!({
3094 "authorization": "Bearer fresh",
3095 "x-tenant": "t1"
3096 }))
3097 .expect("valid headers parse");
3098 assert_eq!(
3099 parsed,
3100 vec![
3101 ("authorization".to_owned(), "Bearer fresh".to_owned()),
3102 ("x-tenant".to_owned(), "t1".to_owned())
3103 ]
3104 );
3105 assert!(parse_headers(&json!(["authorization"])).is_err());
3106 assert!(parse_headers(&json!({ "authorization": null })).is_err());
3107 }
3108
3109 #[test]
3110 fn set_headers_validates_replacement_and_respects_preflight() {
3111 let mut transport = NoNetwork::default();
3112 let mut client: Option<SyncClient> = None;
3113 let mut effects = CreateEffects::default();
3114 dispatch(
3115 &mut transport,
3116 &mut client,
3117 &mut effects,
3118 "create",
3119 &json!({ "schema": schema() }),
3120 )
3121 .expect("create");
3122 dispatch(
3123 &mut transport,
3124 &mut client,
3125 &mut effects,
3126 "setHeaders",
3127 &json!({ "headers": { "authorization": "Bearer fresh" } }),
3128 )
3129 .expect("valid replacement");
3130 let invalid = dispatch(
3131 &mut transport,
3132 &mut client,
3133 &mut effects,
3134 "setHeaders",
3135 &json!({ "headers": { "authorization": 7 } }),
3136 )
3137 .expect_err("invalid replacement");
3138 assert_eq!(invalid.code, "sync.invalid_request");
3139
3140 dispatch(
3141 &mut transport,
3142 &mut client,
3143 &mut effects,
3144 "beginSecurityPreflight",
3145 &json!({}),
3146 )
3147 .expect("preflight");
3148 let gated = dispatch(
3149 &mut transport,
3150 &mut client,
3151 &mut effects,
3152 "setHeaders",
3153 &json!({ "headers": {} }),
3154 )
3155 .expect_err("direct rotation must respect preflight");
3156 assert_eq!(gated.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
3157 }
3158
3159 fn schema_v2() -> Value {
3160 json!({
3161 "version": 2,
3162 "tables": [{
3163 "name": "todos",
3164 "columns": [
3165 { "name": "id", "type": "string", "nullable": false },
3166 { "name": "list_id", "type": "string", "nullable": false },
3167 { "name": "note", "type": "string", "nullable": true }
3168 ],
3169 "primaryKey": "id",
3170 "scopes": [{ "pattern": "list:{list_id}", "column": "list_id" }]
3171 }]
3172 })
3173 }
3174
3175 fn previous_version_enabled() -> Value {
3176 json!({ "enabled": true })
3177 }
3178
3179 fn container_path(db_path: &str) -> String {
3180 format!("{db_path}.prev-context")
3181 }
3182
3183 #[test]
3184 fn previous_version_config_parser_matches_ts_keys_and_defaults() {
3185 assert_eq!(parse_previous_version_context(None).expect("absent"), None);
3186 let defaults = parse_previous_version_context(Some(&json!({})))
3187 .expect("empty")
3188 .expect("present");
3189 assert!(!defaults.enabled);
3190 assert_eq!(defaults.max_bytes, 8 * 1024 * 1024);
3191 assert_eq!(defaults.max_rows, 20_000);
3192 assert_eq!(defaults.max_tables, 32);
3193 assert_eq!(defaults.max_row_bytes, 1024 * 1024);
3194 assert_eq!(defaults.max_age_ms, 24 * 60 * 60 * 1000);
3195
3196 let configured = parse_previous_version_context(Some(&json!({
3197 "enabled": true,
3198 "maxBytes": 1024,
3199 "maxRows": 3,
3200 "maxTables": 2,
3201 "maxRowBytes": 5,
3202 "maxAgeMs": 7
3203 })))
3204 .expect("configured")
3205 .expect("present");
3206 assert!(configured.enabled);
3207 assert_eq!(configured.max_bytes, 1024);
3208 assert_eq!(configured.max_rows, 3);
3209 assert_eq!(configured.max_tables, 2);
3210 assert_eq!(configured.max_row_bytes, 5);
3211 assert_eq!(configured.max_age_ms, 7);
3212
3213 for (value, expected) in [
3215 (json!([]), "must be an object"),
3216 (json!({ "enabled": "yes" }), "enabled must be a boolean"),
3217 (
3218 json!({ "maxBytes": 0 }),
3219 "maxBytes must be a positive safe integer",
3220 ),
3221 (
3222 json!({ "maxRows": -1 }),
3223 "maxRows must be a positive safe integer",
3224 ),
3225 (
3226 json!({ "maxTables": 1.5 }),
3227 "maxTables must be a positive safe integer",
3228 ),
3229 (
3230 json!({ "maxRowBytes": "1" }),
3231 "maxRowBytes must be a positive safe integer",
3232 ),
3233 (
3234 json!({ "maxAgeMs": 0 }),
3235 "maxAgeMs must be a positive safe integer",
3236 ),
3237 ] {
3238 let error = parse_previous_version_context(Some(&value)).expect_err("must fail");
3239 assert_eq!(error.code, "sync.invalid_request", "{value}");
3240 assert!(
3241 error.message.contains(expected),
3242 "{value}: {}",
3243 error.message
3244 );
3245 }
3246 }
3247
3248 #[test]
3249 fn invalid_previous_version_config_fails_create_loudly() {
3250 let mut transport = NoNetwork::default();
3251 let mut client: Option<SyncClient> = None;
3252 let mut effects = CreateEffects::default();
3253 let error = dispatch(
3254 &mut transport,
3255 &mut client,
3256 &mut effects,
3257 "create",
3258 &json!({ "schema": schema(), "previousVersionContext": { "enabled": true, "maxRows": 0 } }),
3259 )
3260 .expect_err("invalid config must fail the create");
3261 assert_eq!(error.code, "sync.invalid_request");
3262 assert!(error.message.contains("maxRows"), "{}", error.message);
3263 assert!(client.is_none(), "no client may be installed");
3264 }
3265
3266 #[test]
3267 fn previous_version_snapshot_reports_not_configured_by_default() {
3268 let mut transport = NoNetwork::default();
3269 let mut client: Option<SyncClient> = None;
3270 let mut effects = CreateEffects::default();
3271 dispatch(
3272 &mut transport,
3273 &mut client,
3274 &mut effects,
3275 "create",
3276 &json!({ "schema": schema() }),
3277 )
3278 .expect("create");
3279 let snapshot = dispatch(
3280 &mut transport,
3281 &mut client,
3282 &mut effects,
3283 "previousVersionSnapshot",
3284 &json!({ "table": "todos" }),
3285 )
3286 .expect("snapshot");
3287 assert_eq!(snapshot["state"], json!("previousVersion"));
3288 assert_eq!(snapshot["available"], json!(false));
3289 assert_eq!(snapshot["reason"], json!("not-configured"));
3290 assert_eq!(snapshot["rows"], json!([]));
3291 assert_eq!(snapshot["truncated"], json!(false));
3292 assert_eq!(snapshot["currentVersion"], json!(1));
3293 let discarded = dispatch(
3294 &mut transport,
3295 &mut client,
3296 &mut effects,
3297 "previousVersionDiscard",
3298 &json!({}),
3299 )
3300 .expect("discard");
3301 assert_eq!(discarded, json!({ "present": false, "discarded": false }));
3302 assert_eq!(
3303 dispatch(
3304 &mut transport,
3305 &mut client,
3306 &mut effects,
3307 "previousVersionAudit",
3308 &json!({}),
3309 )
3310 .expect("audit"),
3311 Value::Null
3312 );
3313 }
3314
3315 #[test]
3316 fn previous_version_commands_round_trip_through_the_dispatcher() {
3317 let path = temp_db_path("previous-version");
3318 let mut transport = NoNetwork::default();
3319 let mut client: Option<SyncClient> = None;
3320 let mut effects = CreateEffects::default();
3321
3322 dispatch(
3324 &mut transport,
3325 &mut client,
3326 &mut effects,
3327 "create",
3328 &json!({
3329 "schema": schema(),
3330 "dbPath": path,
3331 "previousVersionContext": previous_version_enabled()
3332 }),
3333 )
3334 .expect("create v1");
3335 client
3336 .as_mut()
3337 .expect("client")
3338 .mutate(vec![Mutation::Upsert {
3339 table: "todos".to_owned(),
3340 values: serde_json::Map::from_iter([
3341 ("id".to_owned(), json!("t1")),
3342 ("list_id".to_owned(), json!("l1")),
3343 ]),
3344 base_version: None,
3345 }])
3346 .expect("seed a local row");
3347 dispatch(
3348 &mut transport,
3349 &mut client,
3350 &mut effects,
3351 "shutdown",
3352 &json!({}),
3353 )
3354 .expect("shutdown");
3355
3356 dispatch(
3358 &mut transport,
3359 &mut client,
3360 &mut effects,
3361 "create",
3362 &json!({
3363 "schema": schema_v2(),
3364 "dbPath": path,
3365 "previousVersionContext": previous_version_enabled()
3366 }),
3367 )
3368 .expect("create v2");
3369 assert!(
3370 std::path::Path::new(&container_path(&path)).exists(),
3371 "the bump must leave a container file"
3372 );
3373 let status = dispatch(
3374 &mut transport,
3375 &mut client,
3376 &mut effects,
3377 "statusSnapshot",
3378 &json!({}),
3379 )
3380 .expect("status");
3381 assert_eq!(
3382 status["previousVersionContext"]["present"],
3383 json!(true),
3384 "{status}"
3385 );
3386 assert!(
3387 status["previousVersionContext"]["createdAtMs"].is_i64(),
3388 "{status}"
3389 );
3390
3391 let snapshot = dispatch(
3392 &mut transport,
3393 &mut client,
3394 &mut effects,
3395 "previousVersionSnapshot",
3396 &json!({ "table": "todos" }),
3397 )
3398 .expect("snapshot");
3399 assert_eq!(snapshot["state"], json!("previousVersion"));
3400 assert_eq!(snapshot["available"], json!(true));
3401 assert_eq!(snapshot["previousVersion"], json!(1));
3402 assert_eq!(snapshot["currentVersion"], json!(2));
3403 assert_eq!(snapshot["truncated"], json!(false));
3404 assert_eq!(snapshot["rows"][0]["id"], json!("t1"));
3405 assert_eq!(snapshot["rows"][0]["list_id"], json!("l1"));
3406
3407 let unknown = dispatch(
3409 &mut transport,
3410 &mut client,
3411 &mut effects,
3412 "previousVersionSnapshot",
3413 &json!({ "table": "absent" }),
3414 )
3415 .expect_err("unknown previous table");
3416 assert_eq!(unknown.code, "sync.invalid_request");
3417 let bad_limit = dispatch(
3418 &mut transport,
3419 &mut client,
3420 &mut effects,
3421 "previousVersionSnapshot",
3422 &json!({ "table": "todos", "limit": 0 }),
3423 )
3424 .expect_err("bad limit");
3425 assert_eq!(bad_limit.code, "sync.invalid_request");
3426
3427 let audit = dispatch(
3430 &mut transport,
3431 &mut client,
3432 &mut effects,
3433 "previousVersionAudit",
3434 &json!({}),
3435 )
3436 .expect("audit");
3437 assert_eq!(audit["v"], json!(1));
3438 assert_eq!(audit["fromVersion"], json!(1));
3439 assert_eq!(audit["toVersion"], json!(2));
3440 assert_eq!(audit["pending"], json!(1));
3441 assert_eq!(audit["encodable"], json!(1));
3442 assert_eq!(audit["incompatible"], json!([]));
3443 assert!(audit.get("operations").is_none());
3444
3445 let discarded = dispatch(
3447 &mut transport,
3448 &mut client,
3449 &mut effects,
3450 "previousVersionDiscard",
3451 &json!({}),
3452 )
3453 .expect("discard");
3454 assert_eq!(discarded, json!({ "present": true, "discarded": true }));
3455 assert!(!std::path::Path::new(&container_path(&path)).exists());
3456 let again = dispatch(
3457 &mut transport,
3458 &mut client,
3459 &mut effects,
3460 "previousVersionDiscard",
3461 &json!({}),
3462 )
3463 .expect("idempotent discard");
3464 assert_eq!(again, json!({ "present": false, "discarded": false }));
3465
3466 let inspect = rusqlite::Connection::open(&path).expect("inspect replica");
3468 let remaining: i64 = inspect
3469 .query_row(
3470 "SELECT COUNT(*) FROM _syncular_meta WHERE key IN (?1, ?2)",
3471 rusqlite::params!["previousVersionContext", "previousVersionAudit"],
3472 |row| row.get(0),
3473 )
3474 .expect("count meta");
3475 assert_eq!(remaining, 0);
3476
3477 let _ = std::fs::remove_file(&path);
3478 }
3479
3480 #[test]
3481 fn previous_version_ttl_expires_at_read_through_the_dispatcher() {
3482 let path = temp_db_path("previous-version-ttl");
3483 let mut transport = NoNetwork::default();
3484 let mut client: Option<SyncClient> = None;
3485 let mut effects = CreateEffects::default();
3486 dispatch(
3487 &mut transport,
3488 &mut client,
3489 &mut effects,
3490 "create",
3491 &json!({
3492 "schema": schema(),
3493 "dbPath": path,
3494 "previousVersionContext": previous_version_enabled()
3495 }),
3496 )
3497 .expect("create v1");
3498 dispatch(
3499 &mut transport,
3500 &mut client,
3501 &mut effects,
3502 "shutdown",
3503 &json!({}),
3504 )
3505 .expect("shutdown");
3506
3507 let now_ms = std::time::SystemTime::now()
3511 .duration_since(std::time::UNIX_EPOCH)
3512 .expect("clock")
3513 .as_millis() as i64
3514 + 2_000;
3515 dispatch(
3516 &mut transport,
3517 &mut client,
3518 &mut effects,
3519 "create",
3520 &json!({
3521 "schema": schema_v2(),
3522 "dbPath": path,
3523 "nowMs": now_ms,
3524 "previousVersionContext": { "enabled": true, "maxAgeMs": 500 }
3525 }),
3526 )
3527 .expect("create v2");
3528 assert!(std::path::Path::new(&container_path(&path)).exists());
3529 let snapshot = dispatch(
3530 &mut transport,
3531 &mut client,
3532 &mut effects,
3533 "previousVersionSnapshot",
3534 &json!({ "table": "todos" }),
3535 )
3536 .expect("snapshot");
3537 assert_eq!(snapshot["available"], json!(false));
3538 assert_eq!(snapshot["reason"], json!("expired"));
3539 assert_eq!(snapshot["rows"], json!([]));
3540 assert!(!std::path::Path::new(&container_path(&path)).exists());
3542
3543 let _ = std::fs::remove_file(&path);
3544 }
3545}