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