Skip to main content

coven_database/
declaration.rs

1//! The application's declarations, independent of any SQLite connection.
2
3/// How independently inserted rows choose their identity (§9.2).
4#[derive(Clone, Debug, Eq, PartialEq)]
5pub enum RowIdentity {
6    /// A canonical lowercase UUID, version 4 or 7, in a primary-key component.
7    IndependentUuid,
8    /// Equal derived keys identify one row on every device.
9    SharedKey,
10}
11
12#[derive(Clone, Debug, Eq, PartialEq)]
13pub(crate) enum AudienceSource {
14    Store,
15    Column(String),
16    ForeignKey(String),
17    Both { column: String, foreign_key: String },
18}
19
20/// Who may change a synced table's rows directly (§9.6, E2). Shared-trigger
21/// targets count as direct changes; an exact foreign-key action of an
22/// authorized change may still reach any row.
23#[derive(Clone, Copy, Debug, Eq, PartialEq)]
24pub enum WritePermission {
25    /// Every member.
26    Anyone,
27    /// Only the member whose write originally created the row.
28    Owner,
29    /// Only a member who is an admin in the state just before the write's
30    /// slot, whoever created the row.
31    Admin,
32}
33
34/// A synced table's key, audience, file references, shared triggers and who
35/// may change its rows directly (E2).
36#[derive(Clone, Debug, Eq, PartialEq)]
37pub struct SyncedTable {
38    pub(crate) name: String,
39    pub(crate) identity: RowIdentity,
40    pub(crate) key: Vec<String>,
41    pub(crate) audience: AudienceSource,
42    pub(crate) files: Vec<FileColumn>,
43    pub(crate) shared_triggers: Vec<String>,
44    pub(crate) permission: WritePermission,
45}
46
47impl SyncedTable {
48    /// The table name exactly as supplied to the declaration.
49    pub fn name(&self) -> &str {
50        &self.name
51    }
52
53    /// The declared kind of row identity.
54    pub fn identity(&self) -> &RowIdentity {
55        &self.identity
56    }
57
58    /// The declared primary-key columns, in order; defaults to `id`.
59    pub fn get_key_columns(&self) -> &[String] {
60        &self.key
61    }
62
63    /// Who may change the table's rows directly.
64    pub fn write_permission(&self) -> WritePermission {
65        self.permission
66    }
67
68    /// The root audience column, including when inheritance was also declared.
69    /// Opening refuses a declaration with both audience sources.
70    pub fn get_audience_column(&self) -> Option<&str> {
71        match &self.audience {
72            AudienceSource::Column(column) | AudienceSource::Both { column, .. } => Some(column),
73            AudienceSource::Store | AudienceSource::ForeignKey(_) => None,
74        }
75    }
76
77    /// The audience foreign key, including when a root column was also declared.
78    /// Opening refuses a declaration with both audience sources.
79    pub fn get_audience_from(&self) -> Option<&str> {
80        match &self.audience {
81            AudienceSource::ForeignKey(foreign_key) | AudienceSource::Both { foreign_key, .. } => {
82                Some(foreign_key)
83            }
84            AudienceSource::Store | AudienceSource::Column(_) => None,
85        }
86    }
87
88    /// The declared file reference columns, in declaration order.
89    pub fn file_columns(&self) -> &[FileColumn] {
90        &self.files
91    }
92
93    /// The shared trigger names, in declaration order, including repetitions.
94    pub fn shared_triggers(&self) -> &[String] {
95        &self.shared_triggers
96    }
97
98    /// Declare a synced table with the one-column primary key `id`.
99    pub fn new(name: impl Into<String>, identity: RowIdentity) -> Self {
100        Self {
101            name: name.into(),
102            identity,
103            key: vec!["id".into()],
104            audience: AudienceSource::Store,
105            files: Vec::new(),
106            shared_triggers: Vec::new(),
107            permission: WritePermission::Anyone,
108        }
109    }
110
111    /// Only each row's original creating member may directly update or
112    /// delete it (§9.6). Shared-trigger targets count as direct writes;
113    /// foreign-key actions from authorized changes may still reach the row.
114    /// No app owner column is needed. Changing a table's write permission
115    /// is a breaking schema change (§18.1).
116    pub fn owner_only(mut self) -> Self {
117        self.permission = WritePermission::Owner;
118        self
119    }
120
121    /// Only a member who is an admin as of the write's slot may directly
122    /// insert, update or delete its rows, whoever created them (§9.6).
123    /// Shared-trigger targets count as direct writes; foreign-key actions
124    /// from authorized changes may still reach the row. Changing a table's
125    /// write permission is a breaking schema change (§18.1).
126    pub fn admin_only(mut self) -> Self {
127        self.permission = WritePermission::Admin;
128        self
129    }
130
131    /// The columns in PRIMARY KEY order.
132    pub fn key_columns<I, S>(mut self, columns: I) -> Self
133    where
134        I: IntoIterator<Item = S>,
135        S: Into<String>,
136    {
137        self.key = columns.into_iter().map(Into::into).collect();
138        self
139    }
140
141    /// Set the root's non-null text audience column. Declaring inheritance too is an error.
142    pub fn audience_column(mut self, column: impl Into<String>) -> Self {
143        let column = column.into();
144        self.audience = match self.audience {
145            AudienceSource::ForeignKey(foreign_key) | AudienceSource::Both { foreign_key, .. } => {
146                AudienceSource::Both { column, foreign_key }
147            }
148            AudienceSource::Store | AudienceSource::Column(_) => AudienceSource::Column(column),
149        };
150        self
151    }
152
153    /// Inherit the audience through this foreign key. Declaring a root column too is an error.
154    pub fn audience_from(mut self, foreign_key: impl Into<String>) -> Self {
155        let foreign_key = foreign_key.into();
156        self.audience = match self.audience {
157            AudienceSource::Column(column) | AudienceSource::Both { column, .. } => {
158                AudienceSource::Both { column, foreign_key }
159            }
160            AudienceSource::Store | AudienceSource::ForeignKey(_) => {
161                AudienceSource::ForeignKey(foreign_key)
162            }
163        };
164        self
165    }
166
167    /// Declare a column holding a file reference. Opening and migrating check
168    /// the column against this synced table's actual schema.
169    pub fn file_column(mut self, column: FileColumn) -> Self {
170        self.files.push(column);
171        self
172    }
173
174    /// Declare a trigger as shared; all other triggers are local.
175    pub fn shared_trigger(mut self, name: impl Into<String>) -> Self {
176        self.shared_triggers.push(name.into());
177        self
178    }
179}
180
181/// A namespace's kind: whose bytes its files are (§17.1).
182#[derive(Clone, Debug, Eq, PartialEq)]
183pub enum Provenance {
184    /// The user's original, which coven never modifies or deletes.
185    UserProvided,
186    /// Bytes that coven owns.
187    AppProvided,
188}
189
190/// When a write setting a file reference goes out (§17.4, E2).
191#[derive(Clone, Debug, Eq, PartialEq)]
192pub enum Binding {
193    /// Once its file is stored, together with it: the write and every later
194    /// write of this device wait for the upload. Its files are app files of
195    /// at most `limit` bytes.
196    Bound {
197        /// The largest file the reference may name, in bytes.
198        limit: u64,
199    },
200    /// At once; the file is on its uploader only until it is stored.
201    Trailing,
202}
203
204/// The size limit of a bound reference that declares none: 1.5 MiB (§17.4).
205pub const BOUND_FILE_LIMIT: u64 = 3 << 19;
206
207/// A column holding a file's id, or NULL (§17.2, E2). It references the file
208/// as a foreign key references its parent.
209#[derive(Clone, Debug, Eq, PartialEq)]
210pub struct FileColumn {
211    pub(crate) column: String,
212    pub(crate) write_once: bool,
213    pub(crate) binding: Binding,
214}
215
216impl FileColumn {
217    /// A trailing file reference held in `column`.
218    pub fn new(column: impl Into<String>) -> Self {
219        Self { column: column.into(), write_once: false, binding: Binding::Trailing }
220    }
221
222    /// Bound, naming files of at most `BOUND_FILE_LIMIT` bytes (§17.4).
223    pub fn bound(self) -> Self {
224        self.bound_with_limit(BOUND_FILE_LIMIT)
225    }
226
227    /// Bound, naming files of at most `limit` bytes (§17.4).
228    pub fn bound_with_limit(mut self, limit: u64) -> Self {
229        self.binding = Binding::Bound { limit };
230        self
231    }
232
233    /// Refuse a write that changes the reference once it names a file.
234    pub fn write_once(mut self) -> Self {
235        self.write_once = true;
236        self
237    }
238
239    /// The column exactly as declared.
240    pub fn column(&self) -> &str {
241        &self.column
242    }
243
244    /// When a write setting the reference goes out.
245    pub fn binding(&self) -> &Binding {
246        &self.binding
247    }
248
249    /// Whether a reference, once it names a file, can't change.
250    pub fn is_write_once(&self) -> bool {
251        self.write_once
252    }
253}
254
255/// A kind of file with its cache budget, declared when the store opens
256/// (§17.1, §17.8, E1).
257#[derive(Clone, Debug, Eq, PartialEq)]
258pub struct Namespace {
259    pub(crate) name: String,
260    pub(crate) kind: Provenance,
261    pub(crate) cache_budget: u64,
262}
263
264impl Namespace {
265    /// A namespace of this kind. The budget applies when the namespace is
266    /// first declared; `set_cache_budget` changes it after.
267    pub fn new(name: impl Into<String>, kind: Provenance, cache_budget: u64) -> Self {
268        Self { name: name.into(), kind, cache_budget }
269    }
270
271    /// The name exactly as declared.
272    pub fn name(&self) -> &str {
273        &self.name
274    }
275
276    /// Whose bytes its files are.
277    pub fn kind(&self) -> &Provenance {
278        &self.kind
279    }
280
281    /// The initial cache budget in bytes, as declared, not its current
282    /// setting. Pinned files' bytes don't count toward it.
283    pub fn cache_budget(&self) -> u64 {
284        self.cache_budget
285    }
286}
287
288#[cfg(test)]
289#[path = "declaration_tests.rs"]
290mod tests;