Skip to main content

uqa_storage_sqlite/
notifications.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Physical notification registry transactions and encrypted connection ownership.
8
9mod control;
10mod listeners;
11mod publication;
12mod reservations;
13mod scan;
14mod schema;
15#[cfg(test)]
16mod tests;
17
18use crate::{ManagedConnection, SQLiteConnectionLease};
19use rusqlite::params;
20use std::{path::Path, time::Duration};
21use uqa_storage::{
22    notifications::{NotificationListenerRow, NotificationQueueEntry, NotificationQueueState},
23    StorageBackendError, StorageBackendResult, StorageEncryptionKey,
24};
25
26const REGISTRY_BUSY_TIMEOUT: Duration = Duration::from_secs(30);
27
28#[derive(Clone)]
29pub struct NotificationRegistry {
30    connection: ManagedConnection,
31}
32
33impl NotificationRegistry {
34    pub fn open(path: &Path, key: Option<&StorageEncryptionKey>) -> StorageBackendResult<Self> {
35        schema::open_registry(path, key)
36            .map(|connection| Self { connection })
37            .map_err(StorageBackendError::Other)
38    }
39
40    pub fn begin(&self) -> StorageBackendResult<NotificationRegistryTransaction> {
41        open_registry_transaction(&self.connection)
42    }
43
44    /// Admit the original registry writer with cancellable pool, native lock and statement waits. Cancellation rolls back unfinished work; it never replays an evaluated statement.
45    pub fn begin_with_control(
46        &self,
47        control: &uqa_storage::read_control::StorageReadControl,
48    ) -> StorageBackendResult<NotificationRegistryTransaction> {
49        open_controlled_registry_transaction(&self.connection, Some(control))
50    }
51}
52
53pub struct NotificationRegistryTransaction {
54    connection: SQLiteConnectionLease,
55    control: Option<uqa_storage::read_control::StorageReadControl>,
56    finished: bool,
57    poisoned: bool,
58    pending_acknowledgement: Option<[u8; 32]>,
59    preparing: bool,
60}
61
62impl NotificationRegistryTransaction {
63    pub const fn pending_acknowledgement(&self) -> Option<[u8; 32]> {
64        self.pending_acknowledgement
65    }
66
67    pub fn allocate_backend_process_id(&self) -> Result<i32, StorageBackendError> {
68        let _operation = control::operation(&self.connection, self.control.as_ref())?;
69        let next = self
70            .connection
71            .query_row(
72                "SELECT next_process_id FROM backend_process_id_state WHERE singleton = 1",
73                [],
74                |row| row.get::<_, i64>(0),
75            )
76            .map_err(|error| registry_error("load backend process identifier", &error))?;
77        let process_id = i32::try_from(next).map_err(|_| {
78            StorageBackendError::Other(
79                "exhausted positive cross-process backend process identifiers".into(),
80            )
81        })?;
82        if process_id <= 0 {
83            return Err(StorageBackendError::Other(format!(
84                "corrupt asynchronous notification backend process identifier {process_id}"
85            )));
86        }
87        self.connection
88            .execute(
89                "UPDATE backend_process_id_state SET next_process_id = ?1 WHERE singleton = 1",
90                params![next + 1],
91            )
92            .map_err(|error| registry_error("advance backend process identifier", &error))?;
93        Ok(process_id)
94    }
95
96    pub fn queue_state(&self) -> Result<NotificationQueueState, StorageBackendError> {
97        let _operation = control::operation(&self.connection, self.control.as_ref())?;
98        self.connection
99            .query_row(
100                "SELECT next_sequence, head_position FROM queue_state WHERE singleton = 1",
101                [],
102                |row| Ok((row.get::<_, i64>(0)?, row.get::<_, i64>(1)?)),
103            )
104            .map_err(|error| registry_error("load queue state", &error))
105            .and_then(|(next_sequence, head_position)| {
106                Ok(NotificationQueueState {
107                    next_sequence: nonnegative_u64(next_sequence, "queue sequence")?,
108                    head_position: nonnegative_u64(head_position, "queue position")?,
109                })
110            })
111    }
112
113    pub fn save_queue_state(
114        &self,
115        state: NotificationQueueState,
116    ) -> Result<(), StorageBackendError> {
117        let _operation = control::operation(&self.connection, self.control.as_ref())?;
118        self.connection
119            .execute(
120                "UPDATE queue_state SET next_sequence = ?1, head_position = ?2 WHERE singleton = 1",
121                params![
122                    sqlite_integer(state.next_sequence, "queue sequence")?,
123                    sqlite_integer(state.head_position, "queue position")?,
124                ],
125            )
126            .map_err(|error| registry_error("save queue state", &error))?;
127        Ok(())
128    }
129
130    pub fn append_entries(
131        &self,
132        entries: &[NotificationQueueEntry],
133    ) -> Result<(), StorageBackendError> {
134        let _operation = control::operation(&self.connection, self.control.as_ref())?;
135        let mut statement = self
136            .connection
137            .prepare_cached(
138                "INSERT INTO queue_entries (sequence, process_id, channel, payload) VALUES (?1, ?2, ?3, ?4)",
139            )
140            .map_err(|error| registry_error("prepare queue append", &error))?;
141        for entry in entries {
142            statement
143                .execute(params![
144                    sqlite_integer(entry.sequence, "entry sequence")?,
145                    entry.process_id,
146                    entry.channel,
147                    entry.payload,
148                ])
149                .map_err(|error| registry_error("append queue entry", &error))?;
150        }
151        Ok(())
152    }
153
154    pub fn entries_from(
155        &self,
156        from_sequence: u64,
157    ) -> Result<Vec<NotificationQueueEntry>, StorageBackendError> {
158        let _operation = control::operation(&self.connection, self.control.as_ref())?;
159        let mut entries = Vec::new();
160        self.visit_entries_from(
161            from_sequence,
162            std::num::NonZeroUsize::MAX,
163            &uqa_storage::read_control::StorageReadControl::with_limit(usize::MAX),
164            &mut |entry| {
165                entries.push(NotificationQueueEntry {
166                    sequence: entry.sequence,
167                    process_id: entry.process_id,
168                    channel: entry.channel.into(),
169                    payload: entry.payload.into(),
170                });
171                Ok(std::ops::ControlFlow::Continue(()))
172            },
173        )?;
174        Ok(entries)
175    }
176
177    pub fn delete_entries_before(&self, sequence: u64) -> Result<(), StorageBackendError> {
178        let _operation = control::operation(&self.connection, self.control.as_ref())?;
179        self.connection
180            .execute(
181                "DELETE FROM queue_entries WHERE sequence < ?1",
182                params![sqlite_integer(sequence, "cleanup sequence")?],
183            )
184            .map_err(|error| registry_error("clean queue entries", &error))?;
185        Ok(())
186    }
187
188    pub fn listeners(&self) -> Result<Vec<NotificationListenerRow>, StorageBackendError> {
189        let _operation = control::operation(&self.connection, self.control.as_ref())?;
190        let mut statement = self.connection.prepare_cached(
191            "SELECT owner_id, session_id, process_id, wake_port, transaction_open, next_sequence, position, channels_json FROM listeners ORDER BY owner_id, session_id",
192        ).map_err(|error| registry_error("prepare listener scan", &error))?;
193        let mut rows = statement
194            .query([])
195            .map_err(|error| registry_error("scan listeners", &error))?;
196        let mut listeners = Vec::new();
197        while let Some(row) = rows
198            .next()
199            .map_err(|error| registry_error("read listener", &error))?
200        {
201            if let Some(control) = self.control.as_ref() {
202                control.check()?;
203            }
204            listeners.push(listeners::read_listener(row, None)?);
205        }
206        Ok(listeners)
207    }
208
209    pub fn save_listener(
210        &self,
211        listener: &NotificationListenerRow,
212    ) -> Result<(), StorageBackendError> {
213        let _operation = control::operation(&self.connection, self.control.as_ref())?;
214        let channels_json = serde_json::to_string(&listener.channels).map_err(|error| {
215            StorageBackendError::Other(format!(
216                "encode asynchronous notification listener channels: {error}"
217            ))
218        })?;
219        self.connection
220            .execute(
221                "INSERT INTO listeners (owner_id, session_id, process_id, wake_port, channels_json, transaction_open, next_sequence, position) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8) ON CONFLICT(owner_id, session_id) DO UPDATE SET process_id = excluded.process_id, wake_port = excluded.wake_port, channels_json = excluded.channels_json, transaction_open = excluded.transaction_open, next_sequence = excluded.next_sequence, position = excluded.position",
222                params![
223                    listener.owner_id.as_slice(),
224                    listener.session_id.to_be_bytes().as_slice(),
225                    listener.process_id,
226                    i64::from(listener.wake_port),
227                    channels_json,
228                    listener.transaction_open,
229                    sqlite_integer(listener.next_sequence, "listener sequence")?,
230                    sqlite_integer(listener.position, "listener position")?,
231                ],
232            )
233            .map_err(|error| registry_error("save listener", &error))?;
234        Ok(())
235    }
236
237    pub fn drop_listener(
238        &self,
239        owner_id: [u8; 16],
240        session_id: u64,
241    ) -> Result<(), StorageBackendError> {
242        let _operation = control::operation(&self.connection, self.control.as_ref())?;
243        self.connection
244            .execute(
245                "DELETE FROM listeners WHERE owner_id = ?1 AND session_id = ?2",
246                params![owner_id.as_slice(), session_id.to_be_bytes().as_slice()],
247            )
248            .map_err(|error| registry_error("remove listener", &error))?;
249        Ok(())
250    }
251
252    /// Complete an already authoritative publication even if its original query was cancelled.
253    pub fn commit(self) -> Result<(), StorageBackendError> {
254        self.commit_inner(None)
255    }
256
257    /// Commit a cancellable registration or consumption attempt. An interrupted native wait drops and rolls back the uncommitted attempt.
258    pub fn commit_with_control(
259        self,
260        control: &uqa_storage::read_control::StorageReadControl,
261    ) -> StorageBackendResult<()> {
262        self.commit_inner(Some(control))
263    }
264
265    fn commit_inner(
266        mut self,
267        control: Option<&uqa_storage::read_control::StorageReadControl>,
268    ) -> StorageBackendResult<()> {
269        if self.poisoned {
270            return Err(StorageBackendError::Other(
271                "cannot commit notification registry after failed publication rollback".into(),
272            ));
273        }
274        let operation = match control {
275            Some(control) => {
276                control::operation_with(&self.connection, self.control.as_ref(), Some(control))?
277            }
278            None => control::operation(&self.connection, None)?,
279        };
280        self.connection
281            .execute_batch("COMMIT")
282            .map_err(|error| registry_error("commit registry transaction", &error))?;
283        drop(operation);
284        self.finished = true;
285        Ok(())
286    }
287}
288
289impl Drop for NotificationRegistryTransaction {
290    fn drop(&mut self) {
291        if !self.finished {
292            let _ = self.connection.execute_batch("ROLLBACK");
293        }
294    }
295}
296
297fn registry_error(action: &str, error: &rusqlite::Error) -> StorageBackendError {
298    if control::interrupted()
299        && matches!(
300            error.sqlite_error_code(),
301            Some(rusqlite::ErrorCode::DatabaseBusy | rusqlite::ErrorCode::OperationInterrupted)
302        )
303    {
304        return uqa_core::QueryCancelled::USER_REQUEST.into();
305    }
306    StorageBackendError::Other(format!(
307        "{action} in asynchronous notification registry: {error}"
308    ))
309}
310
311fn open_registry_transaction(
312    registry: &ManagedConnection,
313) -> Result<NotificationRegistryTransaction, StorageBackendError> {
314    open_controlled_registry_transaction(registry, None)
315}
316
317fn open_controlled_registry_transaction(
318    registry: &ManagedConnection,
319    control: Option<&uqa_storage::read_control::StorageReadControl>,
320) -> StorageBackendResult<NotificationRegistryTransaction> {
321    let connection = match control {
322        Some(control) => registry.lease_connection_with_control(control),
323        None => registry.lease_connection(),
324    }
325    .map_err(StorageBackendError::from)?;
326    connection
327        .busy_timeout(REGISTRY_BUSY_TIMEOUT)
328        .map_err(|error| registry_error("set registry busy timeout", &error))?;
329    let operation = control::operation(&connection, control)?;
330    schema::register_writer(&connection).map_err(control::schema_error)?;
331    connection
332        .pragma_update(None, "secure_delete", true)
333        .map_err(|error| registry_error("enable registry secure deletion", &error))?;
334    connection
335        .execute_batch("BEGIN IMMEDIATE")
336        .map_err(|error| registry_error("begin registry transaction", &error))?;
337    drop(operation);
338    let transaction = NotificationRegistryTransaction {
339        control: control.cloned(),
340        connection,
341        finished: false,
342        poisoned: false,
343        pending_acknowledgement: None,
344        preparing: false,
345    };
346    {
347        let _operation = control::operation(&transaction.connection, transaction.control.as_ref())?;
348        schema::validate_writer(&transaction.connection).map_err(control::schema_error)?;
349    }
350    Ok(transaction)
351}
352
353fn sqlite_integer(value: u64, label: &str) -> Result<i64, StorageBackendError> {
354    i64::try_from(value).map_err(|_| {
355        StorageBackendError::Other(format!(
356            "asynchronous notification {label} {value} exceeds SQLite INTEGER"
357        ))
358    })
359}
360
361fn nonnegative_u64(value: i64, label: &str) -> Result<u64, StorageBackendError> {
362    u64::try_from(value).map_err(|_| {
363        StorageBackendError::Other(format!("corrupt asynchronous notification {label} {value}"))
364    })
365}
366
367fn fixed_bytes<const N: usize>(
368    bytes: Vec<u8>,
369    label: &str,
370) -> Result<[u8; N], StorageBackendError> {
371    let length = bytes.len();
372    bytes.try_into().map_err(|_| {
373        StorageBackendError::Other(format!(
374            "corrupt asynchronous notification {label} has {length} bytes"
375        ))
376    })
377}