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