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