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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
//! # rpc-io
//!
//! A JSON-RPC 2.0 engine for the protocols editors and tools speak: LSP
//! (Content-Length framing), MCP over stdio (newline framing), and JSON-RPC
//! service APIs. Build a [`Router`] of handlers, hand it a byte stream, and the
//! crate does the rest: framing, the envelope, batches, id correlation,
//! cancellation, deadlines, and the error codes the specification prescribes,
//! with bounded buffers and no panics on any input. JSON is [`jsonx_lib`], the
//! family's own; the default build has no third-party runtime dependency.
//!
//! The Content-Length framing ([`Framing::ContentLength`], [`Decoder`]) is
//! also the base protocol of the Debug Adapter Protocol and cuts DAP messages
//! as well. DAP's messages themselves (`seq`, `type`, `command`) are not
//! JSON-RPC, so the endpoint does not serve DAP: only the framing applies.
//!
//! ## Quick start
//!
//! ```
//! # #[cfg(not(feature = "std"))] fn main() {}
//! # #[cfg(feature = "std")] fn main() -> Result<(), rpc_io::Error> {
//! use jsonx_lib::json;
//! use rpc_io::{End, Framing, Router};
//!
//! let router = Router::new()
//! .request("add", |_, params, _| {
//! let p = params.parse()?;
//! match (p[0].as_i64(), p[1].as_i64()) {
//! (Some(a), Some(b)) => Ok(json!(a + b)),
//! _ => Err(rpc_io::ErrorObject::invalid_params("expected [a, b]")),
//! }
//! })
//! .notification("exit", |_, _, cx| cx.stop());
//!
//! let input: &[u8] = b"{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"add\",\"params\":[2,3]}\n\
//! {\"jsonrpc\":\"2.0\",\"method\":\"exit\"}\n";
//! // Real servers pass `std::io::stdin().lock()` and `std::io::stdout()`.
//! let end = rpc_io::serve(input, std::io::sink(), Framing::Newline, router)?;
//! assert_eq!(end, End::Stopped);
//! # Ok(())
//! # }
//! ```
//!
//! ## Layers
//!
//! - **Framing** ([`Framing`], [`Decoder`]): cuts message bodies out of a
//! byte stream and frames them back. The decoder is sans-IO, holds at most
//! one message plus a read chunk whatever the peer sends, and gives memory
//! back after a large message.
//! - **Messages** ([`decode`], [`Message`], [`Incoming`], [`Invalid`]):
//! one pass of `jsonx_lib`'s pull reader per body; `params` and `result`
//! stay borrowed slices ([`Raw`]) until a handler parses them.
//! - **Correlation** ([`Pending`]): our outstanding requests by id, with
//! deadlines and a capacity, every operation `O(log n)`.
//! - **Endpoint** (`Endpoint`, `Router`, `Peer`, `Call`, `Responder`): the
//! dispatcher, both directions, with cancellation (`Cancellation`,
//! `CancelToken`), an opening-request `Gate`, self-firing deadlines, an
//! interceptor, and `Stats`. `run` reads a blocking stream; `next_read`,
//! `commit`, and `finish` take it apart for any other kind; `run_async`
//! reads an async one (`futures-io`). `Call` is a `Future`. Needs `std`.
//! - **Output** (`Sink`, `Framed`, `Queued`, `outbox`): where messages go.
//! `Queued` writes from its own thread and `outbox` from an async task,
//! behind `QueueLimits`, so a peer that stops reading blocks no sender
//! while the connection is open; closing waits for the drain outside the
//! endpoint's lock, for at most `QueueLimits::close_timeout`.
//! Needs `std`.
//! - **Serving** (`serve`, and `Server` with the `net` feature): one call
//! over a byte stream, or an accept loop over TCP and Unix sockets.
//!
//! ## Policies
//!
//! - **Every request gets exactly one response; no valid notification gets
//! one.** A malformed message is answered under its own id when that id
//! could be read, and under `null` otherwise, as JSON-RPC 2.0 requires.
//! - **Handler panics are contained.** A request whose handler panics is
//! answered with `INTERNAL_ERROR` (the panic message goes to the event
//! hook, never to the peer), and the endpoint keeps serving. This needs
//! `panic = "unwind"`, Rust's default.
//! - **Ids are strings or integers.** `null`, fractional, and out-of-range
//! request ids are refused as invalid requests (LSP and MCP forbid them).
//!
//! ## Features
//!
//! - `std` (default): the endpoint, its handles, `serve`, the queued and
//! async-drained sinks, and the progress helpers. Without it the crate is
//! `no_std` (needs `alloc`): framing, the message model, and the
//! correlation map.
//! - `serde`: typed params and results ([`Router::request_typed`],
//! `Params::deserialize`, `Peer::request_typed`, `Call::wait_typed`),
//! through `serde` and `serde_json`.
//! - `futures-io`: the async adapter over `futures-io`'s traits
//! (`Endpoint::run_async`, `Outbox::write_to`); runtime-agnostic.
//! - `tracing`: spans for every call and events for what the endpoint does
//! on its own; without it the instrumentation compiles to nothing.
//! - `net`: `Server`, an accept loop over TCP and Unix domain sockets.
//!
//! Every optional feature is off by default, and adds only the crates it
//! names and their own dependencies.
extern crate alloc;
pub use ;
pub use ;
pub use Id;
pub use Limits;
pub use ;
pub use Pending;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use Stats;
/// Compiles and runs the `rust` code blocks in `README.md` and `docs/API.md` as
/// part of `cargo test`, so the published examples cannot drift from the API.
///
/// Present only while collecting doctests (`#[cfg(doctest)]`); it is not part of
/// the public surface and does not appear in the built library or its docs.
;