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
//! # rpc-io
//!
//! A JSON-RPC 2.0 engine for the protocols editors and tools speak: LSP and
//! DAP (Content-Length framing), MCP over stdio (newline framing), and 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,
//! and the error codes the specification prescribes, with bounded buffers and
//! no panics on any input. JSON is [`jsonx_lib`], the family's own; there are
//! no third-party runtime dependencies.
//!
//! ## 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 and holds at
//! most one message plus a read chunk, whatever the peer sends.
//! - **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`) and an opening-request `Gate`. Needs `std`.
//!
//! ## Policies
//!
//! - **Every request gets exactly one response; no 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, and the blocking adapter.
//! Without it the crate is `no_std` (needs `alloc`): framing, the message
//! model, and the correlation map.
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 ;
/// 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.
;