1mod documents;
15mod memory;
16mod records;
17mod session;
18mod transaction;
19
20pub use documents::{CheckpointInfo, Doc, DocDefinition, DocSemantics, Owner};
21pub use memory::{CommitSink, MemoryStorage, PreparedCommit};
22pub use records::*;
23pub use session::{CommitChange, CommitPublication, Session, SessionEnd, SessionError, Subscription};
24pub use transaction::{
25 ConversationOwnership, EntryDraft, EntryHead, SubmissionCreate, SubmissionSettlement, TaskDefinition, TaskOptions,
26 TaskOwnership, Tx, TxScope,
27};
28
29use serde_json::{Value, json};
30use std::collections::HashMap;
31use std::fmt;
32
33#[derive(Clone, Debug, PartialEq, Eq)]
36pub enum StorageError {
37 Request(String),
38 Failed(String),
39 Corrupt(String),
41}
42
43impl StorageError {
44 pub fn name(&self) -> &'static str {
46 match self {
47 StorageError::Request(_) => "StorageRequestError",
48 StorageError::Failed(_) => "Error",
49 StorageError::Corrupt(_) => "JsonlCorruptionError",
50 }
51 }
52
53 pub fn message(&self) -> &str {
54 match self {
55 StorageError::Request(message) | StorageError::Failed(message) | StorageError::Corrupt(message) => message,
56 }
57 }
58}
59
60impl fmt::Display for StorageError {
61 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
62 f.write_str(self.message())
63 }
64}
65
66impl std::error::Error for StorageError {}
67
68pub type Result<T> = std::result::Result<T, StorageError>;
69
70pub(crate) fn failed<T>(message: impl Into<String>) -> Result<T> {
71 Err(StorageError::Failed(message.into()))
72}
73
74pub(crate) fn request<T>(message: impl Into<String>) -> Result<T> {
75 Err(StorageError::Request(message.into()))
76}
77
78pub trait Storage {
84 fn commit(&mut self, writes: Vec<StorageWrite>) -> Result<Seq>;
86 fn mint_id(&mut self) -> Result<u64>;
88 fn conversation(&self, id: ConversationId) -> Result<Option<ConversationRecord>>;
89 fn scan_conversations(
90 &self,
91 query: &ConversationQuery,
92 limit: usize,
93 cursor: Option<&Cursor>,
94 ) -> Result<Page<ConversationRecord>>;
95 fn entry(&self, id: EntryId) -> Result<Option<StoredEntry>>;
96 fn visible_entry(&self, conversation_id: ConversationId, id: EntryId) -> Result<Option<StoredEntry>>;
98 fn find_latest_head_marker(
100 &self,
101 conversation_id: ConversationId,
102 at_or_before: Option<EntryId>,
103 ) -> Result<Option<EntryRecord>>;
104 fn scan_entries(&self, query: &EntryQuery, limit: usize, cursor: Option<&Cursor>) -> Result<Page<EntryRecord>>;
105 fn task(&self, id: TaskId) -> Result<Option<TaskRecord>>;
106 fn scan_tasks(&self, query: &TaskQuery, limit: usize, cursor: Option<&Cursor>) -> Result<Page<TaskRecord>>;
107 fn submission(&self, id: SubmissionId) -> Result<Option<SubmissionRecord>>;
108 fn scan_submissions(
109 &self,
110 query: &SubmissionQuery,
111 limit: usize,
112 cursor: Option<&Cursor>,
113 ) -> Result<Page<SubmissionRecord>>;
114 fn submission_by_request(
115 &self,
116 conversation_id: ConversationId,
117 request_id: &str,
118 ) -> Result<Option<SubmissionRecord>>;
119 fn find_document(&self, address: &DocumentAddress, at: DocumentPoint) -> Result<Option<DocumentRecord>>;
121 fn document(&self, id: DocumentId, at: DocumentPoint) -> Result<Option<StoredDocument>>;
123 fn scan_documents(
124 &self,
125 query: &DocumentQuery,
126 limit: usize,
127 cursor: Option<&Cursor>,
128 ) -> Result<Page<DocumentRecord>>;
129 fn close(&mut self) -> Result<()>;
131}
132
133#[derive(Clone, Copy, Debug)]
135pub(crate) struct ScanStart {
136 pub order: ScanOrder,
137 pub after: Option<i64>,
138}
139
140pub(crate) fn cursor_after(cursor: &Cursor) -> Result<Option<i64>> {
142 match cursor.get("after") {
143 None => Ok(None),
144 Some(after) => match after.as_i64() {
145 Some(after) if after.unsigned_abs() <= MAX_SAFE_ID => Ok(Some(after)),
146 _ => request("Invalid storage cursor"),
147 },
148 }
149}
150
151pub(crate) fn scan_start(
154 requested: Option<ScanOrder>,
155 cursor: Option<&Cursor>,
156 fallback: ScanOrder,
157) -> Result<ScanStart> {
158 let Some(cursor) = cursor else {
159 return Ok(ScanStart {
160 order: requested.unwrap_or(fallback),
161 after: None,
162 });
163 };
164 let Some(after) = cursor_after(cursor)? else {
165 return request("Invalid storage cursor");
166 };
167 let order = match cursor.get("order") {
168 None => fallback,
169 Some(value) => match serde_json::from_value::<ScanOrder>(value.clone()) {
170 Ok(order) => order,
171 Err(_) => return request("Invalid storage cursor"),
172 },
173 };
174 if let Some(requested) = requested
175 && requested != order
176 {
177 return request(format!(
178 "The cursor continues a {} scan; the query asks for {}",
179 order.as_str(),
180 requested.as_str()
181 ));
182 }
183 Ok(ScanStart {
184 order,
185 after: Some(after),
186 })
187}
188
189pub(crate) fn next_cursor(id: u64, order: ScanOrder) -> Cursor {
191 match json!({ "after": id, "order": order.as_str() }) {
192 Value::Object(cursor) => cursor,
193 _ => unreachable!("json! object literal"),
194 }
195}
196
197#[derive(Clone, Copy, Debug, PartialEq, Eq)]
199pub(crate) enum Table {
200 Conversation,
201 Entry,
202 Task,
203 Submission,
204 Document,
205}
206
207impl Table {
208 pub(crate) fn as_str(self) -> &'static str {
209 match self {
210 Table::Conversation => "conversation",
211 Table::Entry => "entry",
212 Table::Task => "task",
213 Table::Submission => "submission",
214 Table::Document => "document",
215 }
216 }
217}
218
219impl fmt::Display for Table {
220 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
221 f.write_str(self.as_str())
222 }
223}
224
225pub(crate) fn check_global_ids(
228 writes: &[StorageWrite],
229 mut existing: impl FnMut(u64) -> Result<Option<Table>>,
230) -> Result<()> {
231 let mut claimed: HashMap<u64, Table> = HashMap::new();
232 for write in writes {
233 let (table, id) = match write {
234 StorageWrite::Conversation { value } => (Table::Conversation, value.id.0),
235 StorageWrite::Entry { value } => (Table::Entry, value.id.0),
236 StorageWrite::Task { value } => (Table::Task, value.id.0),
237 StorageWrite::Submission { value } => (Table::Submission, value.id.0),
238 StorageWrite::DocumentCreate { record, .. } | StorageWrite::DocumentCopy { record, .. } => {
239 (Table::Document, record.id.0)
240 }
241 StorageWrite::DocumentChange { .. } | StorageWrite::DocumentRetire { .. } => continue,
242 };
243 let existing = existing(id)?;
244 let earlier = claimed.get(&id).copied();
245 if matches!(table, Table::Conversation | Table::Entry | Table::Document) {
246 if let Some(existing) = existing {
247 return failed(format!("ID {id} already belongs to {existing}"));
248 }
249 if earlier.is_some() {
250 return failed(format!("ID {id} is written more than once"));
251 }
252 } else {
253 if let Some(existing) = existing.filter(|existing| *existing != table) {
254 return failed(format!("ID {id} already belongs to {existing}"));
255 }
256 if earlier.is_some_and(|earlier| earlier != table) {
257 return failed(format!("ID {id} is written as two record types"));
258 }
259 }
260 claimed.insert(id, table);
261 }
262 Ok(())
263}
264
265#[derive(Default)]
267pub(crate) struct DocumentAction {
268 pub create: Option<DocumentCreate>,
269 pub copy: Option<DocumentCopySource>,
270 pub content: Option<DocumentContent>,
271 pub retire: bool,
272}
273
274pub(crate) fn document_actions(writes: &[StorageWrite]) -> Result<Vec<(u64, DocumentAction)>> {
276 let mut actions: Vec<(u64, DocumentAction)> = Vec::new();
277 for write in writes {
278 let id = match write {
279 StorageWrite::DocumentCreate { record, .. } | StorageWrite::DocumentCopy { record, .. } => record.id.0,
280 StorageWrite::DocumentChange { id, .. } | StorageWrite::DocumentRetire { id } => id.0,
281 _ => continue,
282 };
283 let index = match actions.iter().position(|(existing, _)| *existing == id) {
284 Some(index) => index,
285 None => {
286 actions.push((id, DocumentAction::default()));
287 actions.len() - 1
288 }
289 };
290 let action = &mut actions[index].1;
291 let more_than_one = || failed(format!("Document {id} has more than one content command"));
292 match write {
293 StorageWrite::DocumentCreate { record, content } => {
294 if action.create.is_some() || action.content.is_some() || action.copy.is_some() {
295 return more_than_one();
296 }
297 action.create = Some(record.clone());
298 action.content = Some(content.clone());
299 }
300 StorageWrite::DocumentCopy { record, source } => {
301 if action.create.is_some() || action.content.is_some() || action.copy.is_some() {
302 return more_than_one();
303 }
304 action.create = Some(record.clone());
305 action.copy = Some(*source);
306 }
307 StorageWrite::DocumentChange { content, .. } => {
308 if action.content.is_some() || action.copy.is_some() {
309 return more_than_one();
310 }
311 action.content = Some(content.clone());
312 }
313 StorageWrite::DocumentRetire { .. } => {
314 if action.retire {
315 return failed(format!("Document {id} is retired more than once"));
316 }
317 action.retire = true;
318 }
319 _ => unreachable!("filtered above"),
320 }
321 }
322 Ok(actions)
323}
324
325pub(crate) fn page<T>(mut values: Vec<T>, limit: usize, order: ScanOrder, id: impl Fn(&T) -> u64) -> Page<T> {
327 if values.len() <= limit {
328 return Page {
329 items: values,
330 next: None,
331 };
332 }
333 values.truncate(limit);
334 let next = values.last().map(|last| next_cursor(id(last), order));
335 Page { items: values, next }
336}