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