Skip to main content

syncular_client/
schema.rs

1//! Client schema IR (SPEC.md §2.4) — the same JSON shape the conformance
2//! fixture uses (`DriverSchema`): tables with typed columns, a primary key,
3//! and §3.1 scope patterns (`'prefix:{variable}'`, column defaults to the
4//! variable name).
5
6use std::collections::BTreeSet;
7
8use serde::Deserialize;
9use ssp2::segment::{Column, ColumnType};
10
11#[derive(Debug, Clone, Deserialize)]
12pub struct SchemaIr {
13    #[serde(alias = "schemaVersion")]
14    pub version: i32,
15    pub tables: Vec<TableIr>,
16}
17
18#[derive(Debug, Clone, Deserialize)]
19#[serde(rename_all = "camelCase")]
20pub struct TableIr {
21    pub name: String,
22    pub columns: Vec<ColumnIr>,
23    pub primary_key: String,
24    pub scopes: Vec<ScopePatternIr>,
25    /// Local secondary indexes; absent in the IR for index-free tables
26    /// (typegen omits the key), so default to empty on deserialize.
27    #[serde(default)]
28    pub indexes: Vec<IndexIr>,
29    /// Client-local FTS5 projections; absent for tables without local search.
30    #[serde(default, rename = "ftsIndexes")]
31    pub fts_indexes: Vec<FtsIndexIr>,
32    /// §7.4.3 table generation (typegen); absent for hand-written schemas.
33    #[serde(default)]
34    pub generation: Option<String>,
35}
36
37#[derive(Debug, Clone, Deserialize)]
38pub struct ColumnIr {
39    pub name: String,
40    #[serde(rename = "type")]
41    pub column_type: String,
42    pub nullable: bool,
43    /// §5.11: this column is encrypted end-to-end. When set, `column_type` is
44    /// `bytes` (the wire type) and `declared_type` is the app type.
45    #[serde(default)]
46    pub encrypted: bool,
47    /// §5.11: the app-side type of an encrypted column (`declaredType` in JSON).
48    #[serde(default, rename = "declaredType")]
49    pub declared_type: Option<String>,
50    /// §6.7: the server sets this column inside the push; a client never
51    /// authors it (`serverOwned` in JSON).
52    #[serde(default, rename = "serverOwned")]
53    pub server_owned: bool,
54}
55
56/// One local secondary index (the CREATE INDEX migration subset, §2.4).
57#[derive(Debug, Clone, Deserialize)]
58pub struct IndexIr {
59    pub name: String,
60    pub columns: Vec<String>,
61    pub unique: bool,
62}
63
64/// One client-local contentful FTS5 projection.
65#[derive(Debug, Clone, Deserialize)]
66pub struct FtsIndexIr {
67    pub name: String,
68    pub columns: Vec<String>,
69    pub tokenize: String,
70}
71
72/// One compiled local secondary index — created on the base + visible tables.
73#[derive(Debug, Clone)]
74pub struct IndexSchema {
75    pub name: String,
76    pub columns: Vec<String>,
77    pub unique: bool,
78}
79
80#[derive(Debug, Clone)]
81pub struct FtsIndexSchema {
82    pub name: String,
83    pub columns: Vec<String>,
84    pub tokenize: String,
85}
86
87#[derive(Debug, Clone, Deserialize)]
88pub struct ScopePatternIr {
89    pub pattern: String,
90    #[serde(default)]
91    pub column: Option<String>,
92}
93
94/// One declared scope variable, mapped to its local column (§3.1, §3.3).
95#[derive(Debug, Clone)]
96pub struct ScopeVariable {
97    pub variable: String,
98    pub column: String,
99    pub prefix: String,
100}
101
102/// §5.11: one encrypted column — its positional index and its app-side
103/// declared type name (`string`, `integer`, …). The wire `Column.ty` is
104/// `bytes`; this carries the pre-flip type for the encrypt/decrypt seam.
105#[derive(Debug, Clone)]
106pub struct EncryptedColumn {
107    pub index: usize,
108    pub declared_type: String,
109}
110
111#[derive(Debug, Clone)]
112pub struct TableSchema {
113    pub name: String,
114    /// LOCAL columns (declaration order). For an encrypted column (§5.11) the
115    /// `ty` is the DECLARED type — the local mirror stores plaintext, so
116    /// read-back and DDL use the real type. Identical to `wire_columns` when
117    /// the table has no encrypted columns.
118    pub columns: Vec<Column>,
119    /// WIRE columns (§2.4 positional codec): identical to `columns` except an
120    /// encrypted column's `ty` is `bytes` (the ciphertext envelope rides the
121    /// bytes machinery). Used by `encode_row_json`/`decode_row_bytes` and the
122    /// §5.2 segment column-table validation.
123    pub wire_columns: Vec<Column>,
124    pub primary_key: String,
125    pub pk_index: usize,
126    pub scope_variables: Vec<ScopeVariable>,
127    /// Local secondary indexes, in declaration order (empty when none).
128    pub indexes: Vec<IndexSchema>,
129    /// Client-local FTS5 projections, in declaration order.
130    pub fts_indexes: Vec<FtsIndexSchema>,
131    /// §5.11: encrypted columns (index + declared type). Empty ⇒ no E2EE.
132    pub encrypted_columns: Vec<EncryptedColumn>,
133    /// §6.7: indices of server-owned columns. Empty ⇒ every column is authored.
134    pub server_owned_columns: Vec<usize>,
135    /// §7.4.3: a schema bump keeps the table while this equals the persisted one.
136    pub generation: Option<String>,
137}
138
139impl TableSchema {
140    /// §5.11: true when any column is encrypted (skip the seam entirely else).
141    pub fn has_encrypted_columns(&self) -> bool {
142        !self.encrypted_columns.is_empty()
143    }
144
145    /// §5.11 sealed apply: the reserved `_sync_sealed_key` and `_sync_sealed`
146    /// columns every table with an encrypted column stores after
147    /// `_syncular_version`, in this order.
148    pub fn sealed_columns(&self) -> &'static [&'static str] {
149        if self.has_encrypted_columns() {
150            &["_sync_sealed_key", "_sync_sealed"]
151        } else {
152            &[]
153        }
154    }
155}
156
157impl TableSchema {
158    /// §3.3 purge mapping: the generated local scope column for a variable,
159    /// or `None` (the fail-closed case).
160    pub fn scope_column(&self, variable: &str) -> Option<&str> {
161        self.scope_variables
162            .iter()
163            .find(|s| s.variable == variable)
164            .map(|s| s.column.as_str())
165    }
166}
167
168#[derive(Debug, Clone)]
169pub struct ClientSchema {
170    pub version: i32,
171    pub tables: Vec<TableSchema>,
172}
173
174impl ClientSchema {
175    pub fn table(&self, name: &str) -> Option<&TableSchema> {
176        self.tables.iter().find(|t| t.name == name)
177    }
178}
179
180fn parse_column_type(name: &str) -> Result<ColumnType, String> {
181    match name {
182        "string" => Ok(ColumnType::String),
183        "integer" => Ok(ColumnType::Integer),
184        "float" => Ok(ColumnType::Float),
185        "boolean" => Ok(ColumnType::Boolean),
186        "json" => Ok(ColumnType::Json),
187        "bytes" => Ok(ColumnType::Bytes),
188        "blob_ref" => Ok(ColumnType::BlobRef),
189        "crdt" => Ok(ColumnType::Crdt),
190        other => Err(format!("unknown column type {other:?}")),
191    }
192}
193
194/// Extract `{variable}` from a `'prefix:{variable}'` pattern (§3.1).
195fn parse_pattern_variable(pattern: &str) -> Result<String, String> {
196    let open = pattern
197        .find('{')
198        .ok_or_else(|| format!("scope pattern {pattern:?} has no {{variable}}"))?;
199    let close = pattern
200        .rfind('}')
201        .filter(|end| *end > open)
202        .ok_or_else(|| format!("scope pattern {pattern:?} has no closing brace"))?;
203    let variable = &pattern[open + 1..close];
204    if variable.is_empty() {
205        return Err(format!("scope pattern {pattern:?} has an empty variable"));
206    }
207    Ok(variable.to_owned())
208}
209
210pub fn compile_schema(ir: &SchemaIr) -> Result<ClientSchema, String> {
211    // §7.4.2: the persisted marker is a canonical positive i32 and a replica
212    // refuses any requested version outside that range before it touches
213    // storage, so a client can never persist a marker it would reject on the
214    // next open.
215    if ir.version < 1 {
216        return Err(
217            "sync.invalid_request: generated schema version must be an integer in 1..=2147483647"
218                .to_owned(),
219        );
220    }
221    let mut tables = Vec::with_capacity(ir.tables.len());
222    let mut schema_object_names = BTreeSet::new();
223    for table in &ir.tables {
224        if !schema_object_names.insert(table.name.clone()) {
225            return Err(format!("duplicate table or schema object {:?}", table.name));
226        }
227    }
228    for table in &ir.tables {
229        // wire_columns carry the on-the-wire type (bytes for encrypted); the
230        // local `columns` carry the declared type so the local mirror is
231        // plaintext (§5.11).
232        let mut wire_columns = Vec::with_capacity(table.columns.len());
233        let mut columns = Vec::with_capacity(table.columns.len());
234        let mut encrypted_columns = Vec::new();
235        let mut server_owned_columns = Vec::new();
236        for (index, column) in table.columns.iter().enumerate() {
237            // §6.7: typegen and the servers refuse an ineligible column.
238            if column.server_owned {
239                server_owned_columns.push(index);
240            }
241            let wire_ty = parse_column_type(&column.column_type)?;
242            wire_columns.push(Column {
243                name: column.name.clone(),
244                ty: wire_ty,
245                nullable: column.nullable,
246            });
247            if column.encrypted {
248                let declared_name = column.declared_type.clone().ok_or_else(|| {
249                    format!(
250                        "table {:?}: encrypted column {:?} has no declaredType (§5.11)",
251                        table.name, column.name
252                    )
253                })?;
254                let declared_ty = parse_column_type(&declared_name)?;
255                columns.push(Column {
256                    name: column.name.clone(),
257                    ty: declared_ty,
258                    nullable: column.nullable,
259                });
260                encrypted_columns.push(EncryptedColumn {
261                    index,
262                    declared_type: declared_name,
263                });
264            } else {
265                columns.push(Column {
266                    name: column.name.clone(),
267                    ty: wire_ty,
268                    nullable: column.nullable,
269                });
270            }
271        }
272        let pk_index = columns
273            .iter()
274            .position(|c| c.name == table.primary_key)
275            .ok_or_else(|| {
276                format!(
277                    "table {:?}: primary key {:?} is not a column",
278                    table.name, table.primary_key
279                )
280            })?;
281        // §2.4 primary-key eligibility: a primary key MUST render to a
282        // `rowId` string every implementation produces identically and local
283        // storage resolves without deferring to a SQLite build.
284        if !matches!(
285            columns[pk_index].ty,
286            ColumnType::String | ColumnType::Integer | ColumnType::Boolean | ColumnType::Json
287        ) {
288            return Err(format!(
289                "table {:?}: primary key {:?} has an ineligible column type (§2.4); a primary key must be string, integer, boolean, or json",
290                table.name, table.primary_key
291            ));
292        }
293        let mut scope_variables = Vec::with_capacity(table.scopes.len());
294        for scope in &table.scopes {
295            let variable = parse_pattern_variable(&scope.pattern)?;
296            let column = scope.column.clone().unwrap_or_else(|| variable.clone());
297            if !columns.iter().any(|c| {
298                c.name == column && matches!(c.ty, ColumnType::String | ColumnType::Integer)
299            }) {
300                return Err(format!(
301                    "table {:?}: scope column {column:?} must be a string or integer column (§3.1)",
302                    table.name
303                ));
304            }
305            let open = scope.pattern.find('{').expect("validated scope pattern");
306            let prefix = scope.pattern[..open]
307                .strip_suffix(':')
308                .unwrap_or(&scope.pattern[..open])
309                .to_owned();
310            scope_variables.push(ScopeVariable {
311                variable,
312                column,
313                prefix,
314            });
315        }
316        let mut indexes = Vec::with_capacity(table.indexes.len());
317        for index in &table.indexes {
318            if !schema_object_names.insert(index.name.clone()) {
319                return Err(format!(
320                    "table {:?}: index {:?} conflicts with another schema object",
321                    table.name, index.name
322                ));
323            }
324            for col in &index.columns {
325                if !columns.iter().any(|c| &c.name == col) {
326                    return Err(format!(
327                        "table {:?}: index {:?} names unknown column {col:?}",
328                        table.name, index.name
329                    ));
330                }
331            }
332            indexes.push(IndexSchema {
333                name: index.name.clone(),
334                columns: index.columns.clone(),
335                unique: index.unique,
336            });
337        }
338        let mut fts_indexes = Vec::with_capacity(table.fts_indexes.len());
339        for index in &table.fts_indexes {
340            if !schema_object_names.insert(index.name.clone()) {
341                return Err(format!(
342                    "table {:?}: FTS projection {:?} conflicts with another schema object",
343                    table.name, index.name
344                ));
345            }
346            if index.columns.is_empty() || index.columns.len() > 32 {
347                return Err(format!(
348                    "table {:?}: FTS projection {:?} needs between 1 and 32 columns",
349                    table.name, index.name
350                ));
351            }
352            let mut seen_columns = BTreeSet::new();
353            for column_name in &index.columns {
354                if !seen_columns.insert(column_name) {
355                    return Err(format!(
356                        "table {:?}: FTS projection {:?} repeats column {:?}",
357                        table.name, index.name, column_name
358                    ));
359                }
360                let Some((_column_index, column)) = columns
361                    .iter()
362                    .enumerate()
363                    .find(|(_, candidate)| &candidate.name == column_name)
364                else {
365                    return Err(format!(
366                        "table {:?}: FTS projection {:?} names unknown column {:?}",
367                        table.name, index.name, column_name
368                    ));
369                };
370                if !matches!(column.ty, ColumnType::String) {
371                    return Err(format!(
372                        "table {:?}: FTS projection {:?} column {:?} must have string type",
373                        table.name, index.name, column_name
374                    ));
375                }
376            }
377            if !matches!(
378                index.tokenize.as_str(),
379                "unicode61"
380                    | "unicode61 remove_diacritics 0"
381                    | "unicode61 remove_diacritics 1"
382                    | "unicode61 remove_diacritics 2"
383                    | "porter unicode61"
384                    | "trigram"
385            ) {
386                return Err(format!(
387                    "table {:?}: FTS projection {:?} tokenizer {:?} is not allowlisted",
388                    table.name, index.name, index.tokenize
389                ));
390            }
391            fts_indexes.push(FtsIndexSchema {
392                name: index.name.clone(),
393                columns: index.columns.clone(),
394                tokenize: index.tokenize.clone(),
395            });
396        }
397        if table.generation.as_deref() == Some("") {
398            return Err(format!(
399                "table {:?}: generation must be a non-empty string (§7.4.3)",
400                table.name
401            ));
402        }
403        tables.push(TableSchema {
404            generation: table.generation.clone(),
405            name: table.name.clone(),
406            columns,
407            wire_columns,
408            primary_key: table.primary_key.clone(),
409            pk_index,
410            scope_variables,
411            indexes,
412            fts_indexes,
413            encrypted_columns,
414            server_owned_columns,
415        });
416    }
417    Ok(ClientSchema {
418        version: ir.version,
419        tables,
420    })
421}
422
423pub fn parse_schema_json(json: &serde_json::Value) -> Result<ClientSchema, String> {
424    // §7.4.2: validate the requested version before the typed IR decode, so a
425    // missing, non-integer, or out-of-i32-range version is a request error
426    // (matching the TS core) instead of a generic parse failure. `SchemaIr`
427    // accepts the server IR spelling `schemaVersion` as an alias; giving both
428    // spellings stays a duplicate-field error from the decode below.
429    let version = json
430        .get("version")
431        .or_else(|| json.get("schemaVersion"))
432        .and_then(serde_json::Value::as_i64);
433    if !version.is_some_and(|version| (1..=i32::MAX as i64).contains(&version)) {
434        return Err(
435            "sync.invalid_request: generated schema version must be an integer in 1..=2147483647"
436                .to_owned(),
437        );
438    }
439    let ir: SchemaIr =
440        serde_json::from_value(json.clone()).map_err(|e| format!("bad schema IR: {e}"))?;
441    compile_schema(&ir)
442}
443
444#[cfg(test)]
445mod tests {
446    use super::*;
447    use serde_json::json;
448
449    fn schema_with_fts(column: serde_json::Value, tokenize: &str) -> serde_json::Value {
450        json!({
451            "version": 1,
452            "tables": [{
453                "name": "docs",
454                "primaryKey": "id",
455                "columns": [
456                    { "name": "id", "type": "string", "nullable": false },
457                    { "name": "org_id", "type": "string", "nullable": false },
458                    column
459                ],
460                "scopes": [{ "pattern": "org:{org_id}" }],
461                "ftsIndexes": [{
462                    "name": "docs_fts",
463                    "columns": ["body"],
464                    "tokenize": tokenize
465                }]
466            }]
467        })
468    }
469
470    #[test]
471    fn accepts_the_schema_version_alias_and_refuses_conflicting_spellings() {
472        let schema = json!({
473            "schemaVersion": 2,
474            "tables": [{
475                "name": "tasks",
476                "primaryKey": "id",
477                "columns": [{ "name": "id", "type": "string", "nullable": false }],
478                "scopes": []
479            }]
480        });
481        let compiled = parse_schema_json(&schema).expect("the server IR alias compiles");
482        assert_eq!(compiled.version, 2);
483        // Both spellings name the same field: the duplicate is a decode error,
484        // never a silent choice between the two values.
485        let mut both = schema.clone();
486        both["version"] = json!(3);
487        let error = parse_schema_json(&both).expect_err("duplicate version spellings");
488        assert!(error.starts_with("bad schema IR:"), "{error}");
489        // The alias is subject to the same range check.
490        let mut out_of_range = schema.clone();
491        out_of_range["schemaVersion"] = json!(0);
492        let error = parse_schema_json(&out_of_range).expect_err("out-of-range alias");
493        assert!(error.starts_with("sync.invalid_request:"), "{error}");
494    }
495
496    #[test]
497    fn compiles_server_owned_column_indices() {
498        let compiled = parse_schema_json(&json!({
499            "version": 1,
500            "tables": [{
501                "name": "tasks",
502                "primaryKey": "id",
503                "columns": [
504                    { "name": "id", "type": "string", "nullable": false },
505                    { "name": "title", "type": "string", "nullable": true },
506                    { "name": "stamp", "type": "string", "nullable": true, "serverOwned": true }
507                ],
508                "scopes": []
509            }]
510        }))
511        .expect("compiles");
512        assert_eq!(compiled.tables[0].server_owned_columns, vec![2]);
513    }
514
515    #[test]
516    fn compiles_an_allowlisted_string_fts_projection() {
517        let schema = parse_schema_json(&schema_with_fts(
518            json!({ "name": "body", "type": "string", "nullable": false }),
519            "unicode61 remove_diacritics 2",
520        ))
521        .expect("valid FTS schema");
522        assert_eq!(schema.tables[0].fts_indexes[0].name, "docs_fts");
523    }
524
525    #[test]
526    fn accepts_encrypted_declared_strings_and_rejects_other_fts_definitions() {
527        let encrypted = schema_with_fts(
528            json!({
529                "name": "body", "type": "bytes", "nullable": false,
530                "encrypted": true, "declaredType": "string"
531            }),
532            "unicode61",
533        );
534        parse_schema_json(&encrypted).expect("local plaintext FTS accepts encrypted strings");
535
536        let non_string = schema_with_fts(
537            json!({ "name": "body", "type": "integer", "nullable": false }),
538            "unicode61",
539        );
540        assert!(parse_schema_json(&non_string)
541            .expect_err("non-string FTS must fail")
542            .contains("must have string type"));
543
544        let tokenizer = schema_with_fts(
545            json!({ "name": "body", "type": "string", "nullable": false }),
546            "custom",
547        );
548        assert!(parse_schema_json(&tokenizer)
549            .expect_err("custom tokenizer must fail")
550            .contains("not allowlisted"));
551    }
552}