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