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;