Skip to main content

uqa_storage_sqlite/notifications/
reservations.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Retain one unresolved publication range without retaining a physical registry writer.
8
9use super::control;
10
11use super::{
12    publication::state, registry_error, NotificationRegistry, NotificationRegistryTransaction,
13    StorageBackendError, StorageBackendResult, REGISTRY_BUSY_TIMEOUT,
14};
15use rusqlite::params;
16use std::time::{Duration, Instant};
17use uqa_storage::{
18    notifications::{NotificationPublication, NotificationPublicationStore},
19    read_control::StorageReadControl,
20};
21
22impl NotificationRegistry {
23    /// Publishers wait for the original reserved range; consumers and recovery can continue using ordinary registry transactions. Owner liveness comes from a retained process lease.
24    pub fn begin_publishing(
25        &self,
26        store: &dyn NotificationPublicationStore,
27        control: &StorageReadControl,
28        resume: Option<(&NotificationPublication, [u8; 16])>,
29        owner_alive: &mut dyn FnMut([u8; 16]) -> StorageBackendResult<bool>,
30    ) -> StorageBackendResult<NotificationRegistryTransaction> {
31        let started = Instant::now();
32        loop {
33            control.check()?;
34            let mut transaction = self.begin_recovered(store, control)?;
35            let operation = control::operation(&transaction.connection, Some(control))?;
36            let current = state(&transaction.connection)?;
37            if resume.is_some_and(|(publication, _)| {
38                current.registry_id != publication.view().header().registry_id
39            }) {
40                return Err(StorageBackendError::Other(
41                    "retained notification belongs to a different registry incarnation".into(),
42                ));
43            }
44            let already_applied = resume.is_some_and(|(publication, _)| {
45                let header = publication.view().header();
46                current.next_publication > header.publication_sequence
47            });
48            let resume_identity =
49                resume.map(|(publication, owner)| (publication.fingerprint(), owner));
50            let pending = current
51                .reservation
52                .filter(|pending| !already_applied && Some(*pending) != resume_identity);
53            if let Some((fingerprint, owner)) = pending {
54                if owner_alive(owner)? {
55                    drop(operation);
56                    drop(transaction);
57                    if started.elapsed() >= REGISTRY_BUSY_TIMEOUT {
58                        return Err(registry_error(
59                            "wait for unresolved notification publication",
60                            &rusqlite::Error::SqliteFailure(
61                                rusqlite::ffi::Error::new(rusqlite::ffi::SQLITE_BUSY),
62                                None,
63                            ),
64                        ));
65                    }
66                    std::thread::park_timeout(Duration::from_millis(10));
67                    continue;
68                }
69                transaction.connection.execute(
70                    "UPDATE publication_state SET reserved_fingerprint = NULL, reservation_owner = NULL WHERE singleton = 1 AND reserved_fingerprint = ?1 AND reservation_owner = ?2",
71                    params![fingerprint.as_slice(), owner.as_slice()],
72                ).map_err(|error| registry_error("discard abandoned publication reservation", &error))?;
73            }
74            transaction
75                .connection
76                .execute_batch("SAVEPOINT notification_preparation")
77                .map_err(|error| {
78                    registry_error("retain notification preparation boundary", &error)
79                })?;
80            transaction.preparing = true;
81            drop(operation);
82            return Ok(transaction);
83        }
84    }
85}
86
87impl NotificationRegistryTransaction {
88    /// Roll back the private queue append and persist only its reservation. The sender keeps the matching publication and liveness lease until its authoritative main outcome is resolved.
89    pub fn suspend_publication(
90        &mut self,
91        publication: &NotificationPublication,
92        owner: [u8; 16],
93    ) -> StorageBackendResult<()> {
94        let _operation = control::operation(&self.connection, None)?;
95        if !self.preparing || self.finished || self.poisoned {
96            return Err(StorageBackendError::Other(
97                "notification publication has no resumable preparation boundary".into(),
98            ));
99        }
100        self.connection
101            .execute_batch("ROLLBACK TO notification_preparation; RELEASE notification_preparation")
102            .map_err(|error| registry_error("restore reserved notification boundary", &error))?;
103        self.preparing = false;
104        let current = state(&self.connection)?;
105        let header = publication.view().header();
106        let fingerprint = publication.fingerprint();
107        if current.registry_id != header.registry_id
108            || current.next_publication != header.publication_sequence
109            || current
110                .reservation
111                .is_some_and(|pending| pending != (fingerprint, owner))
112        {
113            self.poisoned = true;
114            return Err(StorageBackendError::Other(
115                "notification reservation no longer matches its original publication".into(),
116            ));
117        }
118        self.connection.execute(
119            "UPDATE publication_state SET reserved_fingerprint = ?1, reservation_owner = ?2 WHERE singleton = 1",
120            params![fingerprint.as_slice(), owner.as_slice()],
121        ).map_err(|error| registry_error("retain unresolved notification publication", &error))?;
122        self.connection.execute_batch("COMMIT").map_err(|error| {
123            registry_error("commit notification publication reservation", &error)
124        })?;
125        self.finished = true;
126        Ok(())
127    }
128
129    /// Return true when an independent recovery already applied this original main commit. Later publications may have advanced the single acknowledgement since then.
130    pub fn resume_publication(
131        &mut self,
132        publication: &NotificationPublication,
133        owner: [u8; 16],
134        control: &StorageReadControl,
135    ) -> StorageBackendResult<bool> {
136        let operation =
137            control::operation_with(&self.connection, self.control.as_ref(), Some(control))?;
138        let current = state(&self.connection)?;
139        let header = publication.view().header();
140        if current.registry_id != header.registry_id {
141            return Err(StorageBackendError::Other(
142                "retained notification belongs to a different registry incarnation".into(),
143            ));
144        }
145        if current.next_publication > header.publication_sequence {
146            return Ok(true);
147        }
148        if current.reservation != Some((publication.fingerprint(), owner)) {
149            return Err(StorageBackendError::Other(
150                "retained notification has no matching publication reservation".into(),
151            ));
152        }
153        drop(operation);
154        self.apply_publication(publication.view(), control)?;
155        Ok(false)
156    }
157}