1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
//! Typed, ergonomic [Socket.IO v4][spec] client for Rust.
//!
//! # What is Socket.IO?
//!
//! [Socket.IO][spec] is a real-time, bidirectional event-based communication
//! protocol built on top of [Engine.IO][eio-spec]. It adds **namespaces**
//! (multiplexed channels on a single connection), **typed events** (named
//! messages with structured payloads), **acknowledgements** (request/response
//! over events), and **binary attachments** to the underlying transport.
//!
//! # Crate overview
//!
//! This crate is the main entry point for users. It re-exports the wire-level
//! types from `sioc-socket` and layers typed, compile-time–checked events and
//! acknowledgements on top.
//!
//! ```text
//! ┌──────────────────────────────────────────────┐
//! │ sioc (this crate) │
//! │ • derive macros: EventType, AckType, │
//! │ SerializePayload, DeserializePayload, EventRouter │
//! │ • typed Event / Ack / AckHandle │
//! │ • marker traits: BinaryMarker, AckMarker │
//! ├──────────────────────────────────────────────┤
//! │ sioc-socket — protocol logic │
//! │ • Manager: routing, ack tracking, binary │
//! │ reassembly │
//! │ • Signal / Directive / Packet │
//! ├──────────────────────────────────────────────┤
//! │ sioc-engine — Engine.IO v4 transport │
//! │ • HTTP long-polling & WebSocket │
//! │ • heartbeat, ping/pong │
//! └──────────────────────────────────────────────┘
//! ```
//!
//! # Quick start
//!
//! ```rust,no_run
//! use sioc::prelude::*;
//!
//! #[derive(Debug, EventType, SerializePayload, DeserializePayload)]
//! #[sioc(event(name = "greeting"))]
//! struct Greeting { text: String }
//!
//! #[derive(Debug, EventType, SerializePayload, DeserializePayload)]
//! #[sioc(event(name = "reply"))]
//! struct Reply { text: String }
//!
//! # async fn run() -> sioc::error::Result<()> {
//! // 1. Connect to the server and open the default namespace.
//! let url: url::Url = "http://localhost:3000".parse().unwrap();
//! let client = ClientBuilder::new(url).open()?;
//! let (ns, mut rx) = client.connect("/").await?;
//!
//! // 2. Wait for the server to confirm the connection.
//! let Some(Signal::Connect(info)) = rx.recv().await else {
//! panic!("connection rejected");
//! };
//! println!("connected with sid={}", info.sid);
//!
//! // 3. Receive events and respond.
//! while let Some(packet) = rx.recv().await {
//! if let Signal::Event(event) = packet.cast::<Event<Greeting>>()? {
//! println!("got: {}", event.payload.text);
//!
//! let reply = Reply { text: "hello back".into() };
//! ns.emit(reply).await?;
//! }
//! }
//! # Ok(())
//! # }
//! ```
//!
//! # Key concepts
//!
//! | Concept | Type | Description |
//! |---------|------|-------------|
//! | **Event** | [`EventType`](event::EventType) | Named message: wire format `["name", arg0, …]`. Derive with `#[derive(EventType)]`. |
//! | **Ack** | [`AckType`](ack::AckType) | Response to an event: wire format `[arg0, …]`. Derive with `#[derive(AckType)]`. |
//! | **Namespace** | [`SocketSender`](client::SocketSender) / [`SocketReceiver`](client::SocketReceiver) | Multiplexed channel on a single connection (e.g. `"/"`, `"/chat"`). |
//! | **Binary** | [`HasBinary`](marker::HasBinary) / [`NoBinary`](marker::NoBinary) | Compile-time marker for packets with or without binary attachments. |
//! | **Ack policy** | [`HasAck`](marker::HasAck) / [`NoAck`](marker::NoAck) | Compile-time marker for packets that do or don't expect an acknowledgement. |
//!
//! # Features
//!
//! - Fully async, built on [Tokio](https://tokio.rs).
//! - Derive macros for zero-boilerplate event and ack definitions.
//! - Compile-time enforcement of binary attachment and acknowledgement policies.
//! - Zero-copy packet parsing via [`bytestring::ByteString`] and [`bytes::Bytes`].
//!
//! [spec]: https://socket.io/docs/v4/socket-io-protocol/
//! [eio-spec]: https://socket.io/docs/v4/engine-io-protocol/