Skip to main content

uqa_storage_sqlite/notifications/
publication.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Queue publication and its bounded acknowledgement share one registry transaction.
8
9use super::control;
10
11use super::{
12    fixed_bytes, nonnegative_u64, registry_error, sqlite_integer, NotificationListenerRow,
13    NotificationRegistry, NotificationRegistryTransaction, StorageBackendError,
14    StorageBackendResult,
15};
16use rusqlite::{params, Connection};
17use uqa_storage::{
18    mvcc::VersionError,
19    notifications::{
20        NotificationPublication, NotificationPublicationStart, NotificationPublicationStore,
21        NotificationPublicationView, PendingNotification,
22    },
23    read_control::StorageReadControl,
24};
25
26pub(super) struct PublicationState {
27    pub(super) registry_id: [u8; 16],
28    pub(super) next_publication: u64,
29    pub(super) acknowledged: Option<[u8; 32]>,
30    pub(super) reservation: Option<([u8; 32], [u8; 16])>,
31}
32
33pub(super) fn state(connection: &Connection) -> StorageBackendResult<PublicationState> {
34    let (registry_id, next, acknowledged, reserved, owner) = connection.query_row(
35        "SELECT registry_id, next_publication, acknowledged_fingerprint, reserved_fingerprint, reservation_owner FROM publication_state WHERE singleton = 1", [],
36        |row| Ok((row.get::<_, Vec<u8>>(0)?, row.get::<_, i64>(1)?, row.get::<_, Option<Vec<u8>>>(2)?, row.get::<_, Option<Vec<u8>>>(3)?, row.get::<_, Option<Vec<u8>>>(4)?)),
37    ).map_err(|error| registry_error("read publication state", &error))?;
38    Ok(PublicationState {
39        registry_id: fixed_bytes(registry_id, "registry identity")?,
40        next_publication: nonnegative_u64(next, "publication sequence")?,
41        acknowledged: acknowledged
42            .map(|value| fixed_bytes(value, "publication acknowledgement"))
43            .transpose()?,
44        reservation: match (reserved, owner) {
45            (Some(reserved), Some(owner)) => Some((
46                fixed_bytes(reserved, "reserved publication")?,
47                fixed_bytes(owner, "publication reservation owner")?,
48            )),
49            (None, None) => None,
50            _ => {
51                return Err(StorageBackendError::Other(
52                    "incomplete notification reservation".into(),
53                ))
54            }
55        },
56    })
57}
58
59impl NotificationRegistry {
60    /// Observe committed work without taking the registry writer. A racing publication is picked up by the next poll; admission rechecks all state before applying changes.
61    pub fn poll_needed(
62        &self,
63        store: &dyn NotificationPublicationStore,
64        local_owners: &[[u8; 16]],
65        control: &StorageReadControl,
66    ) -> StorageBackendResult<bool> {
67        let mut pending = false;
68        store.visit_notification_publication(control, &mut |publication| {
69            pending = publication.is_some();
70            Ok(())
71        })?;
72        if pending || local_owners.is_empty() {
73            return Ok(pending);
74        }
75        let connection = self.connection.lease_connection_with_control(control)?;
76        let _operation = control::operation(&connection, Some(control))?;
77        super::schema::validate_writer(&connection).map_err(control::schema_error)?;
78        let mut statement = connection.prepare_cached(
79            "SELECT EXISTS (SELECT 1 FROM listeners, queue_state WHERE queue_state.singleton = 1 AND listeners.owner_id = ?1 AND listeners.transaction_open = 0 AND listeners.next_sequence < queue_state.next_sequence)",
80        ).map_err(|error| registry_error("prepare committed polling state", &error))?;
81        for owner in local_owners {
82            control.check()?;
83            if statement
84                .query_row([owner.as_slice()], |row| row.get::<_, bool>(0))
85                .map_err(|error| registry_error("read committed polling state", &error))?
86            {
87                return Ok(true);
88            }
89        }
90        Ok(false)
91    }
92
93    /// Recover any committed slot before admitting another publisher. Each recovery commits its queue acknowledgement before conditionally clearing the main-store slot. A concurrent cleanup or publisher cannot make a stale acknowledgement delete a newer intent.
94    pub fn begin_recovered(
95        &self,
96        store: &dyn NotificationPublicationStore,
97        control: &StorageReadControl,
98    ) -> StorageBackendResult<NotificationRegistryTransaction> {
99        let mut acknowledged = None;
100        loop {
101            control.check()?;
102            let mut transaction = self.begin_with_control(control)?;
103            let mut recovered = None;
104            store.visit_notification_publication(control, &mut |publication| {
105                if let Some(publication) = publication {
106                    transaction.apply_publication(publication, control)?;
107                    recovered = Some(publication.fingerprint());
108                }
109                Ok(())
110            })?;
111            let Some(fingerprint) = recovered else {
112                return Ok(transaction);
113            };
114            if acknowledged == Some(fingerprint) {
115                transaction.pending_acknowledgement = acknowledged;
116                return Ok(transaction);
117            }
118            transaction.commit_with_control(control)?;
119            if !store.try_acknowledge_notification_publication(fingerprint, control)? {
120                acknowledged = Some(fingerprint);
121            }
122        }
123    }
124}
125
126impl NotificationRegistryTransaction {
127    /// Prepare the original evaluated batch and final subscription under registry admission. The caller stages the returned immutable record in its main transaction before committing either resource.
128    pub fn prepare_publication(
129        &mut self,
130        process_id: i32,
131        pending: &[PendingNotification],
132        listener: Option<&NotificationListenerRow>,
133        control: &StorageReadControl,
134    ) -> StorageBackendResult<NotificationPublication> {
135        let operation =
136            control::operation_with(&self.connection, self.control.as_ref(), Some(control))?;
137        control.check()?;
138        let state = state(&self.connection)?;
139        let queue = self.queue_state()?;
140        let publication = NotificationPublication::encode(
141            NotificationPublicationStart {
142                registry_id: state.registry_id,
143                publication_sequence: state.next_publication,
144                first_sequence: queue.next_sequence,
145                first_position: queue.head_position,
146                process_id,
147            },
148            pending,
149            listener,
150            control,
151        )
152        .map_err(VersionError::into_storage_error)?;
153        drop(operation);
154        self.apply_publication(publication.view(), control)?;
155        Ok(publication)
156    }
157
158    /// Append exactly the authoritative committed intent, or recognize its already committed acknowledgement. A savepoint prevents failed decoding, cancellation or memory admission from leaving half a publication in this registry transaction.
159    pub fn apply_publication(
160        &mut self,
161        publication: NotificationPublicationView<'_>,
162        control: &StorageReadControl,
163    ) -> StorageBackendResult<()> {
164        control.check()?;
165        let mut savepoint = self
166            .connection
167            .savepoint()
168            .map_err(|error| registry_error("begin publication savepoint", &error))?;
169        let result = {
170            let _operation =
171                control::operation_with(&savepoint, self.control.as_ref(), Some(control))?;
172            apply(&savepoint, publication, control)
173        };
174        if let Err(error) = result {
175            if savepoint.is_autocommit() && matches!(&error, StorageBackendError::Cancelled(_)) {
176                self.poisoned = true;
177                return Err(error);
178            }
179            if let Err(rollback) = savepoint.rollback().and_then(|()| savepoint.commit()) {
180                self.poisoned = true;
181                return Err(StorageBackendError::Other(format!(
182                    "{error}; rollback notification publication failed: {rollback}"
183                )));
184            }
185            return Err(error);
186        }
187        savepoint
188            .commit()
189            .map_err(|error| registry_error("finish publication savepoint", &error))
190    }
191}
192
193fn apply(
194    connection: &Connection,
195    publication: NotificationPublicationView<'_>,
196    control: &StorageReadControl,
197) -> StorageBackendResult<()> {
198    let header = publication.header();
199    let state = state(connection)?;
200    let fingerprint = publication.fingerprint();
201    let queue = connection
202        .query_row(
203            "SELECT next_sequence, head_position FROM queue_state WHERE singleton = 1",
204            [],
205            |row| Ok((row.get::<_, i64>(0)?, row.get::<_, i64>(1)?)),
206        )
207        .map_err(|error| registry_error("read publication queue boundary", &error))?;
208    let queue = (
209        nonnegative_u64(queue.0, "queue sequence")?,
210        nonnegative_u64(queue.1, "queue position")?,
211    );
212    if state.registry_id != header.registry_id {
213        return Err(StorageBackendError::Other(
214            "committed notification belongs to a different registry incarnation".into(),
215        ));
216    }
217    if state.acknowledged == Some(fingerprint) {
218        if state.next_publication != header.publication_sequence + 1
219            || queue != (header.next_sequence, header.end_position)
220        {
221            return Err(StorageBackendError::Other(
222                "notification acknowledgement has an inconsistent queue boundary".into(),
223            ));
224        }
225        return Ok(());
226    }
227    if state.next_publication != header.publication_sequence
228        || queue != (header.first_sequence, header.first_position)
229    {
230        return Err(StorageBackendError::Other(
231            "committed notification conflicts with the registry publication boundary".into(),
232        ));
233    }
234    if state
235        .reservation
236        .is_some_and(|(reserved, _)| reserved != fingerprint)
237    {
238        return Err(StorageBackendError::Other(
239            "committed notification conflicts with the reserved publication".into(),
240        ));
241    }
242    apply_subscription(connection, publication, control)?;
243    let mut insert = connection.prepare_cached("INSERT INTO queue_entries (sequence, process_id, channel, payload) VALUES (?1, ?2, ?3, ?4)")
244        .map_err(|error| registry_error("prepare recovered queue append", &error))?;
245    for (sequence, message) in
246        (header.first_sequence..header.next_sequence).zip(publication.messages())
247    {
248        control.check()?;
249        let message = message.map_err(VersionError::into_storage_error)?;
250        insert
251            .execute(params![
252                sqlite_integer(sequence, "recovered entry sequence")?,
253                header.process_id,
254                message.channel,
255                message.payload
256            ])
257            .map_err(|error| registry_error("append recovered queue entry", &error))?;
258    }
259    control.check()?;
260    connection
261        .execute(
262            "UPDATE queue_state SET next_sequence = ?1, head_position = ?2 WHERE singleton = 1",
263            params![
264                sqlite_integer(header.next_sequence, "queue sequence")?,
265                sqlite_integer(header.end_position, "queue position")?
266            ],
267        )
268        .map_err(|error| registry_error("advance recovered queue state", &error))?;
269    connection.execute("UPDATE publication_state SET next_publication = ?1, acknowledged_fingerprint = ?2, reserved_fingerprint = NULL, reservation_owner = NULL WHERE singleton = 1", params![sqlite_integer(header.publication_sequence + 1, "publication sequence")?, fingerprint.as_slice()])
270        .map_err(|error| registry_error("acknowledge recovered publication", &error))?;
271    Ok(())
272}
273
274fn apply_subscription(
275    connection: &Connection,
276    publication: NotificationPublicationView<'_>,
277    control: &StorageReadControl,
278) -> StorageBackendResult<()> {
279    let header = publication.header();
280    if let Some(subscription) = publication.subscription() {
281        control.check()?;
282        if subscription.is_unlisten() {
283            connection
284                .execute(
285                    "DELETE FROM listeners WHERE owner_id = ?1 AND session_id = ?2",
286                    params![
287                        subscription.owner_id.as_slice(),
288                        subscription.session_id.to_be_bytes().as_slice()
289                    ],
290                )
291                .map_err(|error| registry_error("apply committed unlisten", &error))?;
292        } else {
293            let channels = subscription
294                .channels_json(control)
295                .map_err(VersionError::into_storage_error)?;
296            let channels = std::str::from_utf8(&channels).map_err(|_| {
297                StorageBackendError::Other("invalid encoded notification channels".into())
298            })?;
299            connection.execute(
300                "INSERT INTO listeners (owner_id, session_id, process_id, wake_port, channels_json, transaction_open, next_sequence, position) VALUES (?1, ?2, ?3, ?4, ?5, 0, ?6, ?7) 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 = 0, next_sequence = excluded.next_sequence, position = excluded.position",
301                params![subscription.owner_id.as_slice(), subscription.session_id.to_be_bytes().as_slice(), header.process_id, i64::from(subscription.wake_port), channels, sqlite_integer(subscription.next_sequence, "listener sequence")?, sqlite_integer(subscription.position, "listener position")?],
302            ).map_err(|error| registry_error("apply committed listen", &error))?;
303        }
304    }
305    Ok(())
306}