caelix_socketio/lib.rs
1#![deny(missing_docs)]
2#![deny(rustdoc::broken_intra_doc_links)]
3
4//! Socket.IO support for Caelix's Axum runtime.
5//!
6//! This crate intentionally has no Actix dependency. It is exposed through
7//! `caelix::socket_io` only when the `socketio` feature selects Axum.
8
9use caelix_core::{Container, HttpException, Result};
10use serde::Serialize;
11
12/// Re-exported public API.
13pub use socketioxide::layer::SocketIoLayer;
14/// Re-exported public API.
15pub use socketioxide::{
16 SocketIo,
17 extract::{AckSender, Data, SocketRef},
18};
19
20/// The Socket.IO server handle registered as a first-class Caelix provider by
21/// `caelix_axum::Application::with_socket_io`.
22#[derive(Clone)]
23/// Public Caelix type `SocketIoHandle`.
24pub struct SocketIoHandle {
25 io: SocketIo,
26}
27
28impl SocketIoHandle {
29 /// Builds the Tower layer and its matching injectable handle exactly once.
30 pub fn build() -> (SocketIoLayer, Self) {
31 let (layer, io) = SocketIo::builder().build_layer();
32 (layer, Self { io })
33 }
34
35 /// Runs the `io` public API operation.
36 pub fn io(&self) -> &SocketIo {
37 &self.io
38 }
39}
40
41/// Implemented by `#[gateway("/namespace")]` for Socket.IO gateways.
42#[doc(hidden)]
43pub trait SocketIoGateway: Send + Sync + 'static {
44 /// Public Caelix API.
45 fn register_socket_io(io: &SocketIo, container: &Container) -> Result<()>;
46}
47
48/// Serializable failure payload used for both acknowledgement replies and the
49/// mandatory `"error"` event emitted for failed handlers.
50#[derive(Serialize)]
51/// Public Caelix type `SocketIoError`.
52pub struct SocketIoError {
53 /// The `error` value.
54 pub error: String,
55 /// The `message` value.
56 pub message: String,
57}
58
59impl From<HttpException> for SocketIoError {
60 fn from(exception: HttpException) -> Self {
61 Self {
62 error: exception.error.to_owned(),
63 message: exception.message,
64 }
65 }
66}