Skip to main content

qualia_core_db/sparql_library/
sparql_websocket.rs

1//! SPARQL WebSocket Support
2//!
3//! Real-time SPARQL query results via WebSocket using zero-allocation patterns.
4
5use crate::sparql_ast::*;
6use crate::sparql_executor::*;
7use crate::sparql_library::serialisers::sparql_results::ResultFormatter;
8use crate::sparql_parser;
9use crate::sparql_planner::*;
10use crate::NQuin;
11
12use std::collections::HashMap;
13
14/// WebSocket message type
15#[repr(C)]
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub enum WebSocketMessageType {
18    Query,
19    Subscribe,
20    Unsubscribe,
21    Result,
22    Error,
23    Close,
24}
25
26/// WebSocket message
27#[repr(C)]
28#[derive(Debug, Clone, Copy)]
29pub struct WebSocketMessage {
30    pub msg_type: WebSocketMessageType,
31    pub query_id: u64,
32    pub payload_len: u16,
33}
34
35/// WebSocket session
36#[repr(C)]
37#[derive(Debug, Clone, Copy)]
38pub struct WebSocketSession {
39    pub session_id: u64,
40    pub active_query: Option<u64>,
41    pub subscribed: bool,
42}
43
44/// A real-time subscription registered by a WebSocket client.
45///
46/// Each subscription binds a `client_id` (the WebSocket connection identifier)
47/// to a SPARQL query whose results the client wants pushed to it whenever the
48/// underlying data changes.
49#[derive(Debug, Clone)]
50pub struct Subscription {
51    /// Unique subscription identifier (a query-derived token).
52    pub subscription_id: String,
53    /// The WebSocket client that owns this subscription.
54    pub client_id: String,
55    /// The SPARQL query the subscription is watching.
56    pub query: String,
57}
58
59impl Subscription {
60    /// Create a new subscription.
61    pub fn new(subscription_id: String, client_id: String, query: String) -> Self {
62        Self {
63            subscription_id,
64            client_id,
65            query,
66        }
67    }
68}
69
70/// SPARQL WebSocket handler
71pub struct SparqlWebSocketHandler<'a> {
72    pub quins: &'a [NQuin],
73    pub sessions: [Option<WebSocketSession>; 32],
74    pub session_count: u8,
75    /// Active subscriptions keyed by subscription id.
76    pub subscriptions: HashMap<String, Subscription>,
77    /// Whether [`initialize`](Self::initialize) has been called.
78    pub initialized: bool,
79}
80
81impl<'a> SparqlWebSocketHandler<'a> {
82    /// Creates `SparqlWebSocketHandler` with the given state.
83    pub fn new(quins: &'a [NQuin]) -> Self {
84        Self {
85            quins,
86            sessions: [None; 32],
87            session_count: 0,
88            subscriptions: HashMap::new(),
89            initialized: false,
90        }
91    }
92
93    /// Initialize the handler for use. Resets subscription state and marks the
94    /// handler ready. Must be called before subscribing/notifying so downstream
95    /// code can rely on a deterministic start state.
96    pub fn initialize(&mut self) -> Result<(), String> {
97        self.subscriptions.clear();
98        self.initialized = true;
99        Ok(())
100    }
101
102    /// Register a new WebSocket session
103    pub fn register_session(&mut self) -> Result<u64, String> {
104        if self.session_count >= 32 {
105            return Err("Session overflow".to_string());
106        }
107
108        let session_id = self.session_count as u64;
109        self.sessions[self.session_count as usize] = Some(WebSocketSession {
110            session_id,
111            active_query: None,
112            subscribed: false,
113        });
114        self.session_count += 1;
115
116        Ok(session_id)
117    }
118
119    /// Unregister a WebSocket session
120    pub fn unregister_session(&mut self, session_id: u64) -> Result<(), String> {
121        for i in 0..self.session_count as usize {
122            if let Some(session) = self.sessions[i] {
123                if session.session_id == session_id {
124                    self.sessions[i] = None;
125                    return Ok(());
126                }
127            }
128        }
129        Err("Session not found".to_string())
130    }
131
132    /// Handle a WebSocket query, returning formatted output (json or xml).
133    ///
134    /// This is the format-aware, session-scoped variant. The simpler
135    /// [`handle_query`](Self::handle_query) returns serialized JSON bytes.
136    pub fn handle_query_formatted(
137        &self,
138        query: &str,
139        format: &str,
140        _session_id: u64,
141    ) -> Result<String, String> {
142        // Parse query
143        let (sparql_query, ctx) = sparql_parser::parse_sparql(query)?;
144
145        // Plan query
146        let plan = QueryPlanner::plan(&sparql_query, &ctx)?;
147
148        // Execute query
149        let executor = QueryExecutor::new(self.quins);
150        let results = executor.execute(&plan, &ctx)?;
151
152        // Format results
153        match format.to_lowercase().as_str() {
154            "json" => {
155                let mut output = Vec::new();
156                let vars = match &sparql_query {
157                    SparqlQuery::Select(select) => {
158                        select.variables[..select.var_count as usize].to_vec()
159                    }
160                    _ => vec![],
161                };
162                ResultFormatter::format_json(&mut output, &vars, &results, &ctx, None)
163                    .map_err(|e| e.to_string())?;
164                Ok(String::from_utf8(output).unwrap())
165            }
166            "xml" => {
167                let mut output = Vec::new();
168                let vars = match &sparql_query {
169                    SparqlQuery::Select(select) => {
170                        select.variables[..select.var_count as usize].to_vec()
171                    }
172                    _ => vec![],
173                };
174                ResultFormatter::format_xml(&mut output, &vars, &results, &ctx, None)
175                    .map_err(|e| e.to_string())?;
176                Ok(String::from_utf8(output).unwrap())
177            }
178            _ => Err("Unsupported format. Use: xml or json".to_string()),
179        }
180    }
181
182    /// Stream query results in chunks, executing the query and formatting each
183    /// chunk as JSON. This is the query-executing variant. The simpler
184    /// [`stream_results`](Self::stream_results) splits an already-serialized
185    /// byte buffer.
186    pub fn stream_query_results(
187        &self,
188        query: &str,
189        chunk_size: usize,
190        _session_id: u64,
191    ) -> Result<Vec<String>, String> {
192        // Parse and execute query
193        let (sparql_query, ctx) = sparql_parser::parse_sparql(query)?;
194        let plan = QueryPlanner::plan(&sparql_query, &ctx)?;
195        let executor = QueryExecutor::new(self.quins);
196        let results = executor.execute(&plan, &ctx)?;
197
198        // Get variables
199        let vars = match &sparql_query {
200            SparqlQuery::Select(select) => select.variables[..select.var_count as usize].to_vec(),
201            _ => vec![],
202        };
203
204        // Chunk results
205        let mut chunks = Vec::new();
206        for chunk in results.chunks(chunk_size) {
207            let mut output = Vec::new();
208            ResultFormatter::format_json(&mut output, &vars, chunk, &ctx, None)
209                .map_err(|e| e.to_string())?;
210            chunks.push(String::from_utf8(output).unwrap());
211        }
212
213        Ok(chunks)
214    }
215
216    /// Subscribe a session to real-time updates for a query (session-based).
217    ///
218    /// This is the numeric-session variant. The string-keyed
219    /// [`subscribe`](Self::subscribe) is the subscription notification API.
220    pub fn subscribe_session(&mut self, session_id: u64, query: &str) -> Result<u64, String> {
221        // Find session
222        for i in 0..self.session_count as usize {
223            if let Some(session) = self.sessions[i] {
224                if session.session_id == session_id {
225                    // Store query hash as subscription ID
226                    let query_hash = crate::lexicon::generate_60bit_token(query.as_bytes());
227                    self.sessions[i] = Some(WebSocketSession {
228                        session_id,
229                        active_query: Some(query_hash),
230                        subscribed: true,
231                    });
232                    return Ok(query_hash);
233                }
234            }
235        }
236        Err("Session not found".to_string())
237    }
238
239    /// Unsubscribe a session from updates (session-based).
240    pub fn unsubscribe_session(&mut self, session_id: u64) -> Result<(), String> {
241        for i in 0..self.session_count as usize {
242            if let Some(session) = self.sessions[i] {
243                if session.session_id == session_id {
244                    self.sessions[i] = Some(WebSocketSession {
245                        session_id,
246                        active_query: None,
247                        subscribed: false,
248                    });
249                    return Ok(());
250                }
251            }
252        }
253        Err("Session not found".to_string())
254    }
255
256    /// Notify session subscribers of updates (session-based), returning the
257    /// session ids whose active query matches `query_hash`.
258    pub fn notify_session_subscribers(&self, query_hash: u64) -> Vec<u64> {
259        let mut subscribers = Vec::new();
260
261        for i in 0..self.session_count as usize {
262            if let Some(session) = self.sessions[i] {
263                if session.subscribed && session.active_query == Some(query_hash) {
264                    subscribers.push(session.session_id);
265                }
266            }
267        }
268
269        subscribers
270    }
271
272    // ---- Subscription-based API (client_id string keyed) ----
273    //
274    // The methods below use a `client_id: &str` / `subscription_id: &str` model
275    // that is independent of the numeric session slots above. This is the
276    // notification system used by the WebSocket subscription feature.
277
278    /// Register a subscription for a client and return the subscription id.
279    ///
280    /// The subscription id is derived from the query (via
281    /// `generate_60bit_token`) so the same query re-subscribed by the same
282    /// client yields a stable id. The query and client_id are stored in the
283    /// subscriptions map for later notification.
284    pub fn subscribe(&mut self, client_id: &str, query: &str) -> Result<String, String> {
285        let token = crate::lexicon::generate_60bit_token(query.as_bytes());
286        let subscription_id = format!("sub-{}-{}", client_id, token);
287        let subscription = Subscription::new(
288            subscription_id.clone(),
289            client_id.to_string(),
290            query.to_string(),
291        );
292        self.subscriptions
293            .insert(subscription_id.clone(), subscription);
294        Ok(subscription_id)
295    }
296
297    /// Remove a subscription by its id. Returns an error if the subscription
298    /// does not exist.
299    pub fn unsubscribe(&mut self, subscription_id: &str) -> Result<(), String> {
300        if self.subscriptions.remove(subscription_id).is_some() {
301            Ok(())
302        } else {
303            Err("Subscription not found".to_string())
304        }
305    }
306
307    /// List all active subscriptions.
308    pub fn get_subscriptions(&self) -> Vec<&Subscription> {
309        self.subscriptions.values().collect()
310    }
311
312    /// Count active subscriptions.
313    pub fn subscription_count(&self) -> usize {
314        self.subscriptions.len()
315    }
316
317    /// Notify all active subscribers of an event.
318    ///
319    /// For each subscription, returns a `(client_id, notification_message)`
320    /// pair. The notification message is a JSON-like string containing the
321    /// subscription's query and the event data, so a transport layer can push
322    /// it directly to the connected client.
323    pub fn notify_subscribers(&self, event_data: &str) -> Vec<(String, String)> {
324        let mut notifications = Vec::new();
325        for sub in self.subscriptions.values() {
326            let message = format_notification(&sub.subscription_id, &sub.query, event_data);
327            notifications.push((sub.client_id.clone(), message));
328        }
329        notifications
330    }
331
332    /// Execute a SPARQL query and return the results as serialized bytes in a
333    /// simple JSON format. This is the WebSocket query handler entry point.
334    pub fn handle_query(&self, query: &str) -> Result<Vec<u8>, String> {
335        // Parse query
336        let (sparql_query, ctx) = sparql_parser::parse_sparql(query)?;
337
338        // Plan query
339        let plan = QueryPlanner::plan(&sparql_query, &ctx)?;
340
341        // Execute query
342        let executor = QueryExecutor::new(self.quins);
343        let results = executor.execute(&plan, &ctx)?;
344
345        // Serialize results as JSON bytes.
346        let vars = match &sparql_query {
347            SparqlQuery::Select(select) => select.variables[..select.var_count as usize].to_vec(),
348            _ => vec![],
349        };
350        let mut output = Vec::new();
351        ResultFormatter::format_json(&mut output, &vars, &results, &ctx, None)
352            .map_err(|e| e.to_string())?;
353        Ok(output)
354    }
355
356    /// Split a serialized result buffer into chunks for streaming over
357    /// WebSocket frames. Each chunk is at most `chunk_size` bytes (the final
358    /// chunk may be smaller).
359    pub fn stream_results(&self, results: &[u8], chunk_size: usize) -> Vec<Vec<u8>> {
360        if chunk_size == 0 {
361            // A zero chunk size would loop forever; return the whole buffer as
362            // a single chunk instead.
363            return vec![results.to_vec()];
364        }
365        results.chunks(chunk_size).map(|c| c.to_vec()).collect()
366    }
367}
368
369impl<'a> Default for SparqlWebSocketHandler<'a> {
370    fn default() -> Self {
371        Self::new(&[])
372    }
373}
374
375/// Build a JSON-like notification message for a subscription event.
376///
377/// The message is a compact JSON object containing the subscription id, the
378/// subscribed query, and the event payload. It is intentionally simple and
379/// dependency-free so it can be pushed directly over a WebSocket frame.
380fn format_notification(subscription_id: &str, query: &str, event_data: &str) -> String {
381    format!(
382        "{{\"subscriptionId\":\"{}\",\"query\":\"{}\",\"event\":{}}}",
383        escape_json_string(subscription_id),
384        escape_json_string(query),
385        event_data
386    )
387}
388
389/// Escape a string for inclusion inside a JSON string literal. Handles the
390/// characters that are most likely to appear in subscription ids / queries.
391fn escape_json_string(s: &str) -> String {
392    let mut out = String::with_capacity(s.len());
393    for c in s.chars() {
394        match c {
395            '"' => out.push_str("\\\""),
396            '\\' => out.push_str("\\\\"),
397            '\n' => out.push_str("\\n"),
398            '\r' => out.push_str("\\r"),
399            '\t' => out.push_str("\\t"),
400            c if (c as u32) < 0x20 => out.push_str(&format!("\\u{:04x}", c as u32)),
401            c => out.push(c),
402        }
403    }
404    out
405}
406
407#[cfg(test)]
408mod tests {
409    use super::*;
410
411    #[test]
412    fn test_websocket_handler_creation() {
413        let quins = vec![];
414        let handler = SparqlWebSocketHandler::new(&quins);
415        assert_eq!(handler.session_count, 0);
416    }
417
418    #[test]
419    fn test_register_session() {
420        let quins = vec![];
421        let mut handler = SparqlWebSocketHandler::new(&quins);
422
423        let session_id = handler.register_session().unwrap();
424        assert_eq!(session_id, 0);
425        assert_eq!(handler.session_count, 1);
426    }
427
428    #[test]
429    fn test_unregister_session() {
430        let quins = vec![];
431        let mut handler = SparqlWebSocketHandler::new(&quins);
432
433        let session_id = handler.register_session().unwrap();
434        handler.unregister_session(session_id).unwrap();
435    }
436
437    #[test]
438    fn test_subscribe_session() {
439        let quins = vec![];
440        let mut handler = SparqlWebSocketHandler::new(&quins);
441
442        let session_id = handler.register_session().unwrap();
443        let query_hash = handler
444            .subscribe_session(session_id, "SELECT ?s WHERE ?s ?p ?o")
445            .unwrap();
446
447        assert!(query_hash > 0);
448    }
449
450    // ---- Subscription-based API tests ----
451
452    #[test]
453    fn test_handler_initialize() {
454        let quins = vec![];
455        let mut handler = SparqlWebSocketHandler::new(&quins);
456        assert!(!handler.initialized);
457        handler.initialize().unwrap();
458        assert!(handler.initialized);
459        assert_eq!(handler.subscription_count(), 0);
460    }
461
462    #[test]
463    fn test_subscribe_client_returns_id() {
464        let quins = vec![];
465        let mut handler = SparqlWebSocketHandler::new(&quins);
466
467        let sub_id = handler
468            .subscribe("client-1", "SELECT ?s WHERE { ?s ?p ?o }")
469            .unwrap();
470        assert!(sub_id.starts_with("sub-client-1-"));
471        assert_eq!(handler.subscription_count(), 1);
472    }
473
474    #[test]
475    fn test_subscribe_client_stores_query_and_client() {
476        let quins = vec![];
477        let mut handler = SparqlWebSocketHandler::new(&quins);
478
479        let sub_id = handler
480            .subscribe("client-1", "SELECT ?s WHERE { ?s ?p ?o }")
481            .unwrap();
482        let subs = handler.get_subscriptions();
483        assert_eq!(subs.len(), 1);
484        assert_eq!(subs[0].subscription_id, sub_id);
485        assert_eq!(subs[0].client_id, "client-1");
486        assert_eq!(subs[0].query, "SELECT ?s WHERE { ?s ?p ?o }");
487    }
488
489    #[test]
490    fn test_subscribe_same_query_same_client_stable_id() {
491        let quins = vec![];
492        let mut handler = SparqlWebSocketHandler::new(&quins);
493
494        let id1 = handler
495            .subscribe("client-1", "SELECT ?s WHERE { ?s ?p ?o }")
496            .unwrap();
497        let id2 = handler
498            .subscribe("client-1", "SELECT ?s WHERE { ?s ?p ?o }")
499            .unwrap();
500        // Same client + same query → same id (overwrites the previous entry).
501        assert_eq!(id1, id2);
502        assert_eq!(handler.subscription_count(), 1);
503    }
504
505    #[test]
506    fn test_subscribe_different_clients_separate_subscriptions() {
507        let quins = vec![];
508        let mut handler = SparqlWebSocketHandler::new(&quins);
509
510        handler
511            .subscribe("client-1", "SELECT ?s WHERE { ?s ?p ?o }")
512            .unwrap();
513        handler
514            .subscribe("client-2", "SELECT ?s WHERE { ?s ?p ?o }")
515            .unwrap();
516        assert_eq!(handler.subscription_count(), 2);
517    }
518
519    #[test]
520    fn test_unsubscribe_client_removes_subscription() {
521        let quins = vec![];
522        let mut handler = SparqlWebSocketHandler::new(&quins);
523
524        let sub_id = handler
525            .subscribe("client-1", "SELECT ?s WHERE { ?s ?p ?o }")
526            .unwrap();
527        assert_eq!(handler.subscription_count(), 1);
528
529        handler.unsubscribe(&sub_id).unwrap();
530        assert_eq!(handler.subscription_count(), 0);
531        assert!(handler.get_subscriptions().is_empty());
532    }
533
534    #[test]
535    fn test_unsubscribe_client_unknown_id_errors() {
536        let quins = vec![];
537        let mut handler = SparqlWebSocketHandler::new(&quins);
538        let err = handler.unsubscribe("does-not-exist").unwrap_err();
539        assert!(err.contains("not found"));
540    }
541
542    #[test]
543    fn test_subscription_lifecycle() {
544        let quins = vec![];
545        let mut handler = SparqlWebSocketHandler::new(&quins);
546        handler.initialize().unwrap();
547
548        // Subscribe two clients.
549        let id1 = handler
550            .subscribe("client-1", "SELECT ?s WHERE { ?s ?p ?o }")
551            .unwrap();
552        let id2 = handler
553            .subscribe("client-2", "SELECT ?s WHERE { ?s ?p ?o }")
554            .unwrap();
555        assert_eq!(handler.subscription_count(), 2);
556
557        // Notify both.
558        let notifications = handler.notify_subscribers("{\"type\":\"update\"}");
559        assert_eq!(notifications.len(), 2);
560        let client_ids: Vec<&str> = notifications.iter().map(|(c, _)| c.as_str()).collect();
561        assert!(client_ids.contains(&"client-1"));
562        assert!(client_ids.contains(&"client-2"));
563        for (_, msg) in &notifications {
564            assert!(msg.contains("\"query\":\"SELECT ?s WHERE { ?s ?p ?o }\""));
565            assert!(msg.contains("\"event\":{\"type\":\"update\"}"));
566        }
567
568        // Unsubscribe client-1; only client-2 remains.
569        handler.unsubscribe(&id1).unwrap();
570        assert_eq!(handler.subscription_count(), 1);
571        let notifications = handler.notify_subscribers("{\"type\":\"update\"}");
572        assert_eq!(notifications.len(), 1);
573        assert_eq!(notifications[0].0, "client-2");
574
575        // Unsubscribe client-2; none remain.
576        handler.unsubscribe(&id2).unwrap();
577        assert_eq!(handler.subscription_count(), 0);
578        assert!(handler.notify_subscribers("event").is_empty());
579    }
580
581    #[test]
582    fn test_notify_subscribers_message_format() {
583        let quins = vec![];
584        let mut handler = SparqlWebSocketHandler::new(&quins);
585        handler
586            .subscribe("client-1", "SELECT ?s WHERE { ?s ?p ?o }")
587            .unwrap();
588
589        let notifications = handler.notify_subscribers("{\"data\":42}");
590        assert_eq!(notifications.len(), 1);
591        let (_client, msg) = &notifications[0];
592        assert!(msg.starts_with("{\"subscriptionId\":\""));
593        assert!(msg.contains("\"query\":\"SELECT ?s WHERE { ?s ?p ?o }\""));
594        assert!(msg.contains("\"event\":{\"data\":42}"));
595    }
596
597    #[test]
598    fn test_handle_query_bytes_returns_json() {
599        let quins = vec![];
600        let handler = SparqlWebSocketHandler::new(&quins);
601        let bytes = handler
602            .handle_query("SELECT ?s WHERE { ?s ?p ?o }")
603            .unwrap();
604        // ResultFormatter produces a JSON document.
605        let text = String::from_utf8(bytes).unwrap();
606        assert!(text.contains("head") || text.contains("results") || text.contains('{'));
607    }
608
609    #[test]
610    fn test_handle_query_bytes_parse_error() {
611        let quins = vec![];
612        let handler = SparqlWebSocketHandler::new(&quins);
613        let err = handler.handle_query("not sparql").unwrap_err();
614        assert!(!err.is_empty());
615    }
616
617    #[test]
618    fn test_stream_results_bytes_chunks() {
619        let quins = vec![];
620        let handler = SparqlWebSocketHandler::new(&quins);
621        let data: Vec<u8> = (0..25u8).collect();
622        let chunks = handler.stream_results(&data, 10);
623        assert_eq!(chunks.len(), 3);
624        assert_eq!(chunks[0].len(), 10);
625        assert_eq!(chunks[1].len(), 10);
626        assert_eq!(chunks[2].len(), 5);
627        // Reassemble and verify round-trip.
628        let reassembled: Vec<u8> = chunks.into_iter().flatten().collect();
629        assert_eq!(reassembled, data);
630    }
631
632    #[test]
633    fn test_stream_results_bytes_empty() {
634        let quins = vec![];
635        let handler = SparqlWebSocketHandler::new(&quins);
636        let chunks = handler.stream_results(&[], 10);
637        assert!(chunks.is_empty());
638    }
639
640    #[test]
641    fn test_stream_results_bytes_zero_chunk_size() {
642        let quins = vec![];
643        let handler = SparqlWebSocketHandler::new(&quins);
644        let data: Vec<u8> = (0..5u8).collect();
645        // Zero chunk size must not panic; returns a single chunk.
646        let chunks = handler.stream_results(&data, 0);
647        assert_eq!(chunks.len(), 1);
648        assert_eq!(chunks[0], data);
649    }
650
651    #[test]
652    fn test_format_notification_escapes_quotes() {
653        let msg = format_notification("sub-1", "SELECT \"x\"", "{}");
654        assert!(msg.contains("\\\"x\\\""));
655        assert!(msg.contains("\"event\":{}"));
656    }
657
658    #[test]
659    fn test_escape_json_string() {
660        assert_eq!(escape_json_string("a\"b"), "a\\\"b");
661        assert_eq!(escape_json_string("a\\b"), "a\\\\b");
662        assert_eq!(escape_json_string("a\nb"), "a\\nb");
663        assert_eq!(escape_json_string("plain"), "plain");
664    }
665}