The model
Four layers, each usable on its own:
- Framing.
Framingnames the wire format; aDecodercuts message bodies out of a byte stream (sans-IO: you read, it buffers at most one message) andFraming::encodeframes them back. - Messages.
decodereads a body intoMessages (Request,Notification,Response), a batch, or anInvalidthat says how to answer it.paramsandresultstay borrowedRawslices of the body until a handler parses them. - Correlation.
Pendingmaps our outstanding request ids to waiters, with deadlines and a capacity; every operation isO(log n). - Endpoint. An
Endpointroutes the peer's calls to aRouter's handlers and settles answers to our own requests, sent through aPeerfrom any thread.serveis the one-call server.
What it guarantees, and how each guarantee is checked:
| Guarantee | How it is held |
|---|---|
| Every request gets exactly one response; no notification ever gets one. | A property test sends random batches mixing requests (answered at once, later, by a panicking handler, for a missing method, or cancelled), notifications, malformed elements, and stray responses, and checks the reply holds each request id exactly once with the right code. |
Malformed messages get the specification's codes (-32700, -32600, -32601, -32602, -32603), under their own id when it can be read. |
Every example in section 7 of the JSON-RPC 2.0 specification is a test, verbatim; a property test checks envelope classification against a reference built on a full parse. |
| Every message shape survives encoding and decoding, through either framing. | Property tests over random requests, notifications, results, and errors (any id, any string, any JSON), fed through the decoder in random chunk sizes. |
| No input makes it panic, and memory stays bounded. | Property tests feed arbitrary and JSON-shaped bytes to the decoder, the message decoder, and a live endpoint; the decoder's buffer is checked against its documented bound after every step. |
| A handler panic is contained. | Tests panic in request, deferred, and notification handlers, in batches, in the event hook, and in the sink, and check the answers and that the session goes on (or, for the sink, closes cleanly). |
| Cancellation races resolve to one outcome. | Tests race worker answers against peer cancellations, and our cancellations against the peer's answers, hundreds of times each. |
| No quadratic paths. | Tripwire tests: 4 MiB bodies and lines fed a byte at a time, 100,000 messages through one endpoint, a full batch of cancelled deferred requests, 50,000 forged answers while 50,000 requests are held. |
Installation
[]
= "0.2"
= "0.2" # to build and read JSON values
The framing, message, and correlation layers without the standard library:
[]
= { = "0.2", = false }
Quick start
A server on stdin and stdout is one call. This one takes newline-delimited messages, as MCP's stdio transport does; LSP and DAP use Framing::ContentLength:
use json;
use ;
let router = new
.request
.notification;
// A real server passes `std::io::stdin().lock()` and `std::io::stdout()`.
let input: & = b"{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"add\",\"params\":[2,3]}\n\
{\"jsonrpc\":\"2.0\",\"method\":\"exit\"}\n";
let end = serve?;
assert_eq!;
# Ok::
State, and calls in the other direction
An Endpoint carries state for its handlers and sends requests of its own. Answers are matched to calls by id, and a Call can be waited on from any thread but the endpoint's:
use mpsc;
use json;
use ;
let router = new.notification;
let = ; // any `Sink`: a framed stdout, a socket, a channel
let mut endpoint = new;
endpoint.handle?;
assert_eq!;
let call = endpoint.peer.request?;
endpoint.handle?;
assert_eq!;
# Ok::
Long work, answered later and cancellable
A deferred handler gets a Responder it can keep or move to a worker. If the peer cancels ($/cancelRequest in LSP, notifications/cancelled in MCP), the responder's token is set and the request is answered as the protocol says; a late answer is refused:
use mpsc;
use ;
let router = new.deferred;
let = ;
let mut endpoint = new;
endpoint.handle?;
endpoint.handle?;
let reply = rx.try_recv.unwrap_or_default;
assert!;
let responder = endpoint.state_mut.pop;
assert!;
# Ok::
The lower layers
use ;
let mut decoder = ContentLength.decoder;
decoder.feed;
let body = decoder.next_frame?.unwrap_or_default;
let Single = decode else ;
assert_eq!;
# Ok::
Examples
Runnable programs in examples/:
| Example | What it shows |
|---|---|
stdio_echo |
A server on stdin and stdout, newline framing (MCP) or --content-length (LSP, DAP): echo '{"jsonrpc":"2.0","id":1,"method":"ping"}' | cargo run --example stdio_echo |
pipe_pair |
A client and a server over an in-memory pipe, each on its own thread: concurrent requests correlated by id, a deferred answer with progress notifications, and a cancelled request. |
Performance
Decoding is one pass of jsonx-lib's pull reader over each body: the envelope members are read as raw slices, so params and result are validated once and never copied or decoded unless a handler asks. Method names and string ids borrow from the body when they have no escapes. Messages are written into a reused buffer and framed with one write and one flush per turn, however many messages a handler sends. The decoder reads straight into its own buffer, searches for line ends eight bytes at a time, and resumes each search where the last one stopped.
Measured with the benchmarks in benches/, x86_64 Windows, Rust stable, release profile, on LSP-shaped textDocument/hover requests (about 160 bytes each):
| Benchmark | What it measures | Windows |
|---|---|---|
framing/decode_100k_ContentLength |
Cut 100,000 Content-Length frames out of one 19 MiB stream. | ~5.1 GiB/s (3.6 ms) |
framing/decode_100k_Newline |
The same with newline framing. | ~7.6 GiB/s (2.2 ms) |
framing/encode_100k_* |
Frame 100,000 bodies (Content-Length / newline). | ~2.6 / ~2.0 GiB/s |
messages/decode_100k_requests |
Decode 100,000 requests: envelope, id, method, params validated. |
~2.3 M/s (~440 ns each) |
messages/decode_batch_1024 |
Decode a full batch of 1,024 requests. | ~320 µs |
messages/decode_and_write_100k_responses |
Decode 100,000 responses and write each back. | ~2.6 M/s |
endpoint/handle_100k_requests |
The whole server path, 100,000 times: decode, route, parse params, build a result, encode, frame, write. |
~615 K/s (~1.6 µs each) |
endpoint/run_100k_framed_requests |
The same, read from one Content-Length stream by run. |
~560 K/s |
pending/issue_then_settle_100k_out_of_order |
Issue 100,000 requests with deadlines, settle them in scrambled order. | ~1.8 M pairs/s |
Criterion writes per-benchmark reports to target/criterion/. Numbers vary by CPU; use the trend across runs, not a single absolute.
Design notes
- Exactly one response. A deferred request is tracked until answered; a
Responderdropped without answering (a worker returned early, a panic unwound through it) answersINTERNAL_ERRORitself. A cancelled request is answered by the endpoint (-32800for LSP) or not at all (MCP), and a late answer from the worker returnsError::AlreadyAnsweredinstead of reaching the wire. - Ids. Request ids are strings or integers within
i64.null, fractions, and other values are refused as invalid requests, as LSP and MCP require. A request whose id is still being answered by a deferred handler is refused rather than given a second response under the same id. Our own ids are positive integers counted from 1; answers to ids we are not waiting on are reported and dropped. - Malformed messages. A message with a
methodis answered under its own id when that id is valid and appears once; anything unreadable is answered undernull, as the specification requires. A broken response is never answered (an error under its id would read as an answer to one of the peer's requests); it ends the call it names instead. - Budgets.
Limitscaps message bytes (64 MiB), header bytes (8 KiB), header lines (32), batch size (1024), and every JSON budget ofjsonx-lib(depth 128 by default). An oversized message is skipped as it arrives, never buffered, and answered; a broken frame ends the connection, since no reliable boundary is left. - Panics. Handler and event-hook panics are caught; so are panics in a
Sink, which close the connection as an I/O error. This needspanic = "unwind", Rust's default. - Threads. Handlers run on the endpoint's thread, one at a time, in arrival order.
Peer,Call,Responder, andCancellerareSendand work from any thread; the endpoint's lock is held only to encode a message and hand it to the sink, never while user code runs. A message sent from a worker goes out at once, even while a handler runs.
Testing
tests/properties.rs holds the crate to independent references: a classifier built on a full jsonx-lib parse decides what every random envelope should decode to, and random batches check one response per request id. tests/endpoint.rs runs section 7 of the JSON-RPC 2.0 specification verbatim, tests/framing.rs runs the framings against malformed and hostile streams, tests/session.rs covers cancellation, timeouts, the gate, a client and server over a pipe, and races, and tests/adversarial.rs holds one regression test per finding of the adversarial review. Every rust example in this README and in docs/API.md is compiled and run as a doctest.
Cross-platform support
- Linux (x86_64, aarch64)
- macOS (x86_64, Apple Silicon)
- Windows (x86_64)
The crate uses only std's threads, channels, and clocks, and no platform-specific code.
Contributing
See REPS.md for the engineering standards every change is held to, dev/DIRECTIVES.md for the definition of done, and dev/ROADMAP.md for what comes next. Before a PR: cargo fmt --all, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all-features must be clean.