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
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
//! # 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, re-exported as [`jsonx`]; 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 rpc_io::jsonx::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
//! (with no `id` at all under [`Config::omit_null_id`], as MCP has it).
//! - **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 by default.** `null`, fractional, and
//! out-of-range request ids are refused as invalid requests (LSP and MCP
//! forbid them); [`Limits::with_lenient_ids`] accepts them and echoes them
//! back as sent, for generic JSON-RPC services.
//! - **Repeated envelope members are refused.** A message with two
//! `method`s (or `id`s, `params`, ...) is invalid, so no reader can see one
//! method and run another.
//!
//! ## 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 through `serde` and `serde_json`
//! (`Router::request_typed`, `Params::deserialize`, `Peer::request_typed`,
//! `Call::wait_typed`), an alternative to the typed API every build has:
//! jsonx-lib's `FromJson` and `ToJson` ([`Router::request_json`],
//! [`Params::decode`], [`Peer::notify_json`], [`Call::wait_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;
/// jsonx-lib, the JSON this crate is built on, re-exported: its types are
/// part of this crate's API ([`Raw::parse`] returns a [`jsonx::Value`],
/// [`Json`] converts from one, typed handlers take [`jsonx::ToJson`]), so a
/// crate on top (an LSP or MCP server) uses them through `rpc_io::jsonx` and
/// always gets the same jsonx-lib version as this crate, with no dependency
/// of its own to keep in step. `rpc_io::jsonx::json!` builds values.
///
/// # Examples
///
/// ```
/// use rpc_io::jsonx::{self, json};
///
/// let value = json!({ "line": 3 });
/// assert_eq!(jsonx::to_string(&value), r#"{"line":3}"#);
/// assert_eq!(rpc_io::Raw::from_value(&value).as_str(), r#"{"line":3}"#);
/// ```
pub use jsonx_lib as jsonx;
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.
;