Skip to main content

uqa_execution/statement/
notifications.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Admission and execution policy for session-owned SQL notification listeners.
8
9use uqa_core::CancellationToken;
10use uqa_sql::{SQLBatchError, SQLError};
11
12/// Check the host's live session policy at the actual listener command boundary.
13pub fn require_sql_listener_session(requires_subscription: bool) -> Result<(), SQLError> {
14    if requires_subscription {
15        Err(SQLError::NotificationRequiresSubscription)
16    } else {
17        Ok(())
18    }
19}
20
21/// Admit every SQL message of an API batch before it can produce effects. Parsing classifies only direct commands; semantic compilation remains at each statement's original boundary.
22pub fn admit_sql_batch<'sql>(
23    requires_subscription: bool,
24    settings: uqa_sql::parser::ParserSettings,
25    messages: impl IntoIterator<Item = &'sql str>,
26    cancellation: &CancellationToken,
27) -> Result<(), SQLError> {
28    admit_sql_batch_diagnosed(requires_subscription, settings, messages, cancellation)
29        .map_err(SQLBatchError::into_error)
30}
31
32/// The same admission boundary with the exact zero-based message that failed.
33pub fn admit_sql_batch_diagnosed<'sql>(
34    requires_subscription: bool,
35    settings: uqa_sql::parser::ParserSettings,
36    messages: impl IntoIterator<Item = &'sql str>,
37    cancellation: &CancellationToken,
38) -> Result<(), SQLBatchError> {
39    if !requires_subscription {
40        return Ok(());
41    }
42    for (index, sql) in messages.into_iter().enumerate() {
43        let at_statement = |error| SQLBatchError::statement(error, index);
44        cancellation
45            .check()
46            .map_err(SQLError::from)
47            .map_err(at_statement)?;
48        // Admission precedes the batch's effects, including SET. Execution parses
49        // each admitted message again with the settings live at that boundary.
50        // Keep successful admission silent so execution delivers each notice once.
51        let (statements, _) =
52            uqa_sql::parser::with_settings(settings, || uqa_sql::parse_statements(sql));
53        let statements = statements.map_err(at_statement)?;
54        for statement in statements {
55            cancellation
56                .check()
57                .map_err(SQLError::from)
58                .map_err(at_statement)?;
59            if statement.is_notification_listener_command() {
60                return Err(at_statement(SQLError::NotificationRequiresSubscription));
61            }
62        }
63    }
64    Ok(())
65}
66
67#[cfg(test)]
68mod tests {
69    use super::{admit_sql_batch, require_sql_listener_session};
70    use uqa_core::CancellationToken;
71    use uqa_sql::parser::ParserSettings;
72    use uqa_sql::SQLError;
73
74    #[test]
75    fn diagnosed_admission_retains_the_original_failing_member() {
76        let token = CancellationToken::new();
77        let error = super::admit_sql_batch_diagnosed(
78            true,
79            ParserSettings::default(),
80            ["SELECT 1", "SELECT )"],
81            &token,
82        )
83        .unwrap_err();
84        assert_eq!(error.statement_index, Some(1));
85        assert_eq!(error.error.sqlstate(), Some("42601"));
86        assert_eq!(error.error.position(), Some(8));
87        let error = super::admit_sql_batch_diagnosed(
88            true,
89            ParserSettings::default(),
90            ["SELECT 1", "LISTEN events"],
91            &token,
92        )
93        .unwrap_err();
94        assert_eq!(error.statement_index, Some(1));
95        assert_eq!(
96            error.error.code(),
97            Some("NOTIFICATION_REQUIRES_SUBSCRIPTION")
98        );
99    }
100
101    #[test]
102    fn api_batch_classifies_commands_without_searching_embedded_sql() {
103        let token = CancellationToken::new();
104        admit_sql_batch(
105            true,
106            ParserSettings::default(),
107            [
108                "SELECT 'LISTEN'",
109                "DO $$ BEGIN EXECUTE 'LISTEN events'; END $$",
110                "NOTIFY events, 'UNLISTEN'",
111            ],
112            &token,
113        )
114        .unwrap();
115        assert!(matches!(
116            admit_sql_batch(
117                true,
118                ParserSettings::default(),
119                ["SELECT nextval('counter')", "UNLISTEN *"],
120                &token
121            ),
122            Err(SQLError::NotificationRequiresSubscription)
123        ));
124        // Ordinary sessions retain their existing parse and execution order.
125        admit_sql_batch(
126            false,
127            ParserSettings::default(),
128            ["SELECT (", "LISTEN events"],
129            &token,
130        )
131        .unwrap();
132        require_sql_listener_session(false).unwrap();
133        let error = require_sql_listener_session(true).unwrap_err();
134        assert_eq!(error.sqlstate(), Some("0A000"));
135        assert_eq!(error.code(), Some("NOTIFICATION_REQUIRES_SUBSCRIPTION"));
136    }
137
138    #[test]
139    fn cancelled_admission_does_not_parse_the_next_message() {
140        let token = CancellationToken::new();
141        token.cancel();
142        assert!(matches!(
143            admit_sql_batch(true, ParserSettings::default(), ["SELECT ("], &token),
144            Err(SQLError::Cancelled(_))
145        ));
146    }
147
148    #[test]
149    fn admission_classifies_strings_under_the_callers_lexical_settings() {
150        let token = CancellationToken::new();
151        let settings = ParserSettings {
152            standard_conforming_strings: false,
153            ..ParserSettings::default()
154        };
155        admit_sql_batch(true, settings, [r"SELECT 'a\'; LISTEN embedded'"], &token).unwrap();
156        assert!(matches!(
157            admit_sql_batch(true, settings, [r"SELECT 'a\'b'; LISTEN actual"], &token),
158            Err(SQLError::NotificationRequiresSubscription)
159        ));
160    }
161}