rpc-io 0.4.0

JSON-RPC 2.0 engine for LSP, MCP, and service APIs: Content-Length and newline framings, a sans-IO core, blocking and async adapters, bounded non-blocking output, and hostile-input hardening.
Documentation
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
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
# rpc-io — API Reference

> Complete reference for every public item in `rpc-io`; each section has an example.
> **Status: pre-1.0 (0.4.0).** The surface is refined across the 0.x series and
> frozen at `1.0.0`, after lsp-lang and mcp-io have run on it (LexerSketch
> decision D18). See [`../dev/ROADMAP.md`](../dev/ROADMAP.md).

<sub>Copyright &copy; 2026 <strong>James Gober</strong>.</sub>

## Table of contents

- [Overview](#overview)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Concepts](#concepts)
  - [The endpoint's contract](#the-endpoints-contract)
  - [Error codes](#error-codes)
  - [Ids](#ids)
  - [Batches](#batches)
  - [Cancellation](#cancellation-both-ways)
  - [Deadlines](#deadlines)
  - [Output and slow peers](#output-and-slow-peers)
  - [Threads, turns, and panics](#threads-turns-and-panics)
- [`serve`](#serve)
- [`Server`](#server)
- [`Endpoint`](#endpoint)
- [`Flow`, `End`, and `Next`](#flow-end-and-next)
- [`Router`](#router)
- [`Params`](#params)
- [`Context`](#context)
- [`Event`](#event)
- [`Stats`](#stats)
- [`Peer`](#peer)
- [`Call`](#call)
- [`Canceller`](#canceller)
- [`Responder`](#responder)
- [`Notifier`](#notifier)
- [`CancelToken`](#canceltoken)
- [`Progress` and `WorkDone`](#progress-and-workdone)
- [`Config`](#config)
- [`Cancellation`](#cancellation)
- [`Gate`](#gate)
- [`Limits`](#limits)
- [`Sink` and `Framed`](#sink-and-framed)
- [`Queued` and `Outbox`](#queued-and-outbox)
- [Typed params and results (`ToJson` / `FromJson`)](#typed-params-and-results-tojson--fromjson)
- [Typed params and results (`serde`)](#typed-params-and-results-serde)
- [The async adapter (`futures-io`)](#the-async-adapter-futures-io)
- [`Framing`](#framing)
- [`Decoder`](#decoder)
- [`FrameError`](#frameerror)
- [`decode`](#decode)
- [`Incoming` and `Entry`](#incoming-and-entry)
- [`Message`](#message)
- [`Request`, `Notification`, `Response`](#request-notification-response)
- [`Invalid`](#invalid)
- [`write_batch`](#write_batch)
- [`Id`](#id)
- [`Raw`](#raw)
- [`Json`](#json)
- [`ErrorCode`](#errorcode)
- [`ErrorObject`](#errorobject)
- [`Pending`](#pending)
- [`Error`](#error)
- [`CallError`](#callerror)
- [Feature flags](#feature-flags)

## Overview

| Item | Kind | Purpose |
|---|---|---|
| [`serve`](#serve) | fn | Serve a `Router` over a byte stream until it ends. |
| [`Server`](#server), `Stopper`, `Connection` | structs | An accept loop over TCP and Unix sockets, one endpoint per connection (`net`). |
| [`Endpoint`](#endpoint) | struct | One connection, both directions: dispatch, answers, correlation. |
| [`Flow`, `End`, `Next`](#flow-end-and-next) | enums | Whether to go on after a message; why `run` returned; what `next_read` needs. |
| [`Router`](#router) | struct | Request, deferred, and notification handlers, the interceptor, and the event hook. |
| [`Params`](#params) | struct | A call's `params`, parsed on demand. |
| [`Context`](#context) | struct | What a handler can reach: method, id, the peer, `stop`. |
| [`Event`](#event) | enum | What the endpoint handled on its own. |
| [`Stats`](#stats) | struct | A connection's counters and gauges. |
| [`Peer`](#peer) | struct | Send notifications and requests, from any thread. |
| [`Call`](#call), [`Canceller`](#canceller) | structs | One of our requests: await, poll, cancel. |
| [`Responder`](#responder), [`CancelToken`](#canceltoken) | structs | Answer a deferred request once; learn it was cancelled. |
| [`Notifier`](#notifier) | struct | Notifications sent only while their request is in flight. |
| [`Progress`, `WorkDone`](#progress-and-workdone) | structs | MCP `notifications/progress`; LSP `$/progress`. |
| [`Config`](#config), [`Cancellation`](#cancellation), [`Gate`](#gate), [`Limits`](#limits) | structs | Settings, presets, and budgets. |
| [`Sink`](#sink-and-framed), [`Framed`](#sink-and-framed), [`Drain`](#sink-and-framed) | trait, structs | Where outgoing messages go; what closing waits for. |
| [`Queued`, `outbox`, `Outbox`, `OutboxSink`, `QueueLimits`](#queued-and-outbox) | structs, fn | Outgoing queues whose senders do not wait on the peer. |
| [`Framing`](#framing), [`Decoder`](#decoder), [`FrameError`](#frameerror), `READ_CHUNK` | enum, struct, enum, const | Cut bodies out of a byte stream and frame them back. |
| [`decode`](#decode), [`Incoming`, `Entry`](#incoming-and-entry), [`Message`](#message), [`Request`, `Notification`, `Response`](#request-notification-response), [`Invalid`](#invalid), [`write_batch`](#write_batch) | the message model | Read and write JSON-RPC 2.0 messages. |
| [`Id`](#id), [`Raw`](#raw), [`Json`](#json), [`ErrorCode`](#errorcode), [`ErrorObject`](#errorobject) | values | Ids, JSON text, JSON to send, error codes and objects. |
| [`Pending`](#pending) | struct | Outstanding requests by id, with deadlines and a capacity. |
| [`Error`](#error), [`CallError`](#callerror) | enums | Why the connection, or one of our requests, failed. |

## Installation

```toml
[dependencies]
rpc-io = "0.4"   # JSON values through `rpc_io::jsonx` (jsonx-lib, re-exported)

# Framing, messages, and correlation only, without std (alloc only):
# rpc-io = { version = "0.4", default-features = false }

# Integrations, each off by default:
# rpc-io = { version = "0.4", features = ["serde", "futures-io", "tracing", "net"] }
```

## Quick start

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{End, Framing, Router};

    let router = Router::new()
        .request("ping", |_, _, _| Ok("pong"))
        .request("sum", |_, params, _| {
            let p = params.parse()?;
            Ok(p.as_array().map_or(0, |items| items.iter().filter_map(|v| v.as_i64()).sum::<i64>()))
        })
        .notification("exit", |_, _, cx| cx.stop());

    let mut input = Vec::new();
    for body in [r#"{"jsonrpc":"2.0","id":1,"method":"sum","params":[1,2,3]}"#, r#"{"jsonrpc":"2.0","method":"exit"}"#] {
        Framing::ContentLength.encode(body.as_bytes(), &mut input);
    }
    let end = rpc_io::serve(input.as_slice(), std::io::sink(), Framing::ContentLength, router)?;
    assert_eq!(end, End::Stopped);
    Ok(())
}
```

## Concepts

### The endpoint's contract

For any input, an [`Endpoint`](#endpoint):

- answers every request exactly once, and never answers a valid notification;
- answers a malformed message under its own id when the message has a `method` and a valid, unrepeated id, and under `null` otherwise (with no `id` member at all under `Config::omit_null_id`, as MCP's schema has it); never answers a malformed *response* (it ends the call it names with `CallError::InvalidResponse` instead);
- matches answers to our requests by id, and reports answers to ids it is not waiting on as [`Event::Unmatched`](#event);
- contains handler and interceptor panics: the request is answered with `INTERNAL_ERROR`, the session goes on;
- never panics, and holds memory within [`Limits`](#limits), [`QueueLimits`](#queued-and-outbox), and `Config::max_held_bytes`.

### Error codes

| Code | Constant | When the endpoint answers with it |
|---:|---|---|
| `-32700` | `ErrorCode::PARSE_ERROR` | The body is not valid JSON (including invalid UTF-8), or a batch has a syntax error before its limit. Always under `null`. |
| `-32600` | `ErrorCode::INVALID_REQUEST` | Valid JSON but not a valid message: wrong `jsonrpc`, non-string `method`, non-structured `params`, a bad id, a repeated envelope member, an empty or oversized batch, any batch while batches are off, a message over a JSON budget or over `max_message_bytes`, a repeated opening request, an id already in flight (answered under `null`, so the in-flight request's answer stays the only response with that id). |
| `-32601` | `ErrorCode::METHOD_NOT_FOUND` | No request handler for the method. |
| `-32602` | `ErrorCode::INVALID_PARAMS` | Returned by handlers; `Params::parse` and `Params::deserialize` produce it for params that do not parse or fit. |
| `-32603` | `ErrorCode::INTERNAL_ERROR` | A handler or the interceptor panicked, a `Responder` was dropped without answering, or a typed result could not be serialized. |
| `-32000` | `ErrorCode::SERVER_OVERLOADED` | More deferred requests than `Config::max_in_flight` (`Config::overloaded_code`; this is the default, and `Config::mcp()` uses `-32603`, since MCP asks new implementations not to use `-32000..=-32019`). |
| `-32002` | `ErrorCode::SERVER_NOT_INITIALIZED` | A request before the [`Gate`](#gate) opened (the gate's code; this is the default of `Gate::new`, and `Gate::lsp()`'s; `Gate::mcp()` uses `-32600`). |
| `-32800` | `ErrorCode::REQUEST_CANCELLED` | The peer cancelled the request (LSP; the cancellation's code). |
| `-32801`, `-32802`, `-32803` | `CONTENT_MODIFIED`, `SERVER_CANCELLED`, `REQUEST_FAILED` | LSP's codes, for handlers to answer with. |

### Ids

Request ids are strings or integers within `i64`. JSON-RPC 2.0 also allows `null` and fractions, and discourages both; LSP and MCP forbid them, and by default so does this crate: such a request is refused with `-32600` under `null`. Ids compare by value (`7` and `"7"` differ; `-0` reads as `0`, and is echoed as `0`). Our own requests are numbered from 1 upward.

With `Limits::with_lenient_ids(true)` (for generic JSON-RPC services) such requests are accepted: a `null` id is `Id::Null`, and any other number (a fraction, an exponent, an integer outside `i64`) is `Id::RawNumber`, kept as its exact text and echoed back as it was sent (`1.0` and `1.00` are different ids). A response from the peer may then carry a `RawNumber` id too; it matches none of ours. A `null` id names no one request: two `null`-id requests cannot both be in flight (the second is refused as a duplicate), and a cancel notification naming `null` cancels nothing.

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{Config, Endpoint, Limits, Router};

    let router = Router::new().request("m", |_: &mut (), _, _| Ok(true));
    let (tx, rx) = std::sync::mpsc::channel::<String>();
    let config = Config::new().with_limits(Limits::new().with_lenient_ids(true));
    let mut endpoint = Endpoint::new(tx, router, ()).with_config(config);
    endpoint.handle(br#"{"jsonrpc":"2.0","id":2.50,"method":"m"}"#)?;
    assert_eq!(rx.try_recv().ok().as_deref(), Some(r#"{"jsonrpc":"2.0","id":2.50,"result":true}"#));
    Ok(())
}
```

A request that reuses the id of a request still being answered is refused with `-32600` under `null`. This deliberately departs from the letter of JSON-RPC 2.0 §5, which says a response's id must be the request's and keeps `null` for ids that could not be read: answering under the reused id would give the peer two responses with one id, one of them for a request it cannot tell apart. The in-flight request's answer stays the only response with that id.

### Batches

A batch is answered with one array holding one response per request, in the order they were answered, and nothing at all when it holds only notifications and responses. An empty batch, a batch over `Limits::max_batch`, and a batch with a JSON syntax error are each answered with a single error object, not an array. A batch over the limit is refused as soon as it passes the limit, without reading the rest (so its size cannot drive the work done), and with batches off (`max_batch` 0, as MCP's 2025-06-18 revision wants) any batch is refused at its `[`. A batch with deferred requests is sent when its last answer arrives. The [gate](#gate)'s opening request cannot be sent in a batch.

### Cancellation, both ways

[`Cancellation`](#cancellation) says how the protocol spells it. When the peer cancels a deferred request, the request's [`CancelToken`](#canceltoken) is set and the request is answered with the cancellation's code (LSP) or not at all (MCP); a later answer returns `Error::AlreadyAnswered`. When one of our requests is cancelled, times out, or is evicted, the peer is sent the cancel notification. Every race between an answer and a cancellation resolves to one outcome under the endpoint's lock.

### Deadlines

A request gets a deadline from `Peer::request_with_timeout` or `Config::request_timeout`. Deadlines fire on their own: the first request with one starts a timer thread for the connection, which sleeps until the earliest is due, ends it with `CallError::TimedOut`, and sends the peer the cancel notification, even when nothing arrives and nobody waits. The thread holds only a weak reference to the connection and stops when it closes. With `Config::with_timer(false)` there is no thread, and a deadline is enforced when it is next looked at: when the endpoint handles a message, at the next request, in `Call::wait`/`try_wait`, when an awaited `Call` is polled, or by `Endpoint::expire`.

### Output and slow peers

Every outgoing message goes to the endpoint's [`Sink`](#sink-and-framed), with the endpoint's lock held. A sink that blocks (`Framed` writing to a peer that has stopped reading) blocks every sender for as long, the endpoint's own thread included. With [`Queued`](#queued-and-outbox) and [`outbox`](#queued-and-outbox) a send does not wait on the peer: each message is framed into a bounded queue, and a writer thread, or an async task, does the writes. When the peer falls behind past [`QueueLimits`](#queued-and-outbox) (by default 64 MiB or 65,536 messages queued, or a writer that has written nothing for 60 seconds, checked at each send, flush, and close), the queue fails and the connection closes. Closing closes the queue under the lock without waiting; the closing thread then waits for what is queued to be written with the lock released, for at most `close_timeout` (10 s), so other threads see the connection closed at once. [`serve`](#serve) and [`Server`](#server) use `Queued`.

### Threads, turns, and panics

Handlers run on the thread that calls `handle` or `run`, one at a time, in arrival order; that call is a *turn*, and what handlers send during it is flushed once at its end. `Peer`, `Call`, `Canceller`, and `Responder` are `Send` and work from any thread; what they send from another thread goes out at once. The endpoint's lock is held to encode a message and hand it to the sink, never while a handler, the interceptor, or the event hook runs, so handles never deadlock against a handler. A `Sink` must not call back into the endpoint or its handles. Handler, interceptor, event-hook, sink, and writer panics are caught (`panic = "unwind"`, Rust's default, is required).

## `serve`

```rust,ignore
pub fn serve<R: Read, W: Write + Send + 'static>(input: R, output: W, framing: Framing, router: Router<()>) -> Result<End, Error>
```

The one-call server: reads framed messages from `input`, answers them through `output` with the same framing, and returns when the input ends (`End::Eof`) or a handler calls `Context::stop` (`End::Stopped`). Default [`Config`](#config). Output goes through a [`Queued`](#queued-and-outbox) sink with the default limits, and `serve` returns once what is queued has been written, or after `close_timeout` (10 s), or once the writes stop making progress. For state, settings, or sending to the peer, build an [`Endpoint`](#endpoint).

**Errors:** as [`Endpoint::run`](#endpointrun); `Error::Io` if the writer thread cannot start.

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{End, Framing, Router};

    let input: &[u8] = b"{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"ping\"}\n";
    let router = Router::new().request("ping", |_, _, _| Ok("pong"));
    assert_eq!(rpc_io::serve(input, std::io::sink(), Framing::Newline, router)?, End::Eof);
    Ok(())
}
```

## `Server`

With the `net` feature. An accept loop: one [`Endpoint`](#endpoint) per connection, each on its own thread, with output through a `Queued` sink.

| Method | Description |
|---|---|
| `new(framing) -> Self` | Defaults for untrusted peers: `Config::new()` with `Limits::network()` (4 MiB messages), `QueueLimits::new()` with 8 MiB and 4,096 messages, 256 connections, a 30 s message timeout, a 300 s idle timeout. |
| `with_config(self, config)`, `with_queue(self, limits)`, `with_max_connections(self, n)` | Settings for every connection; `max_connections` is at least 1. |
| `with_message_timeout(self, Option<Duration>)`, `with_idle_timeout(self, Option<Duration>)` | How long a message may take to arrive once its first bytes have (and a new connection to send its first message); how long a connection may stay idle: no traffic either way, no request of ours awaiting the peer within its timeout, and no deferred request of the peer's being answered while nothing of ours waits on the peer without a timeout (one of ours sent without a timeout never counts, and suspends the count of the peer's own requests, whose handler may be waiting on its answer: a peer cannot hold a slot by never answering, and a client slower than `idle_timeout` to answer such a request, a slow MCP `sampling/createMessage` for example, is disconnected unless the request has a timeout of its own; long-lived LSP or MCP sessions may want `None`). `None` is no limit. A connection past either is closed. |
| `config(&self) -> &Config`, `queue(&self) -> QueueLimits`, `message_timeout(&self)`, `idle_timeout(&self)` | The settings. |
| `max_connections(&self)`, `connections(&self)` | The bound, and connections served now. |
| `stopper(&self) -> Stopper` | A `Clone + Send + Sync` handle: `stop()`, `is_stopped()`. |
| `serve_tcp(&self, TcpListener, connect)` | Serves until stopped; `connect: FnMut(&Connection) -> (Router<S>, S)` runs once per connection. |
| `serve_unix(&self, UnixListener, connect)` | The same over a Unix domain socket (Unix only). |

At `max_connections` the loop stops accepting (the system queues further connections) until one ends. A connection that leaves a message unfinished past `message_timeout` (a per-message clock, started by the read that brings the message's first bytes and restarted when it completes, so back-to-back streaming is never cut off), or stays idle past `idle_timeout`, is closed, so silent or trickling sockets delay other clients by at most `message_timeout` and cannot lock them out. A read that times out closes the connection; the socket is not read again. Each connection's socket gets the queue's `write_timeout` as its write timeout, and a failed write shuts the connection down. A connection costs a reader thread, a writer thread, and, once a request with a deadline is sent on it, a timer thread. `Stopper::stop` stops accepting, shuts every open connection down (the peers see the stream end), and the serve call returns once every connection's thread has finished. `Connection` (`#[non_exhaustive]`) has `id` (counted from 0) and `addr`; the example below uses it, and the `Stopper`. **Errors:** the I/O error that ended the accept loop. Aborted and reset connections are skipped; running out of descriptors, buffers, or memory pauses the loop (10 ms, doubling to 1 s), and it carries on.

```rust
#[cfg(not(feature = "net"))] fn main() {}
#[cfg(feature = "net")] fn main() -> Result<(), Box<dyn std::error::Error>> {
    use std::{io::{BufRead, BufReader, Write}, net::{TcpListener, TcpStream}};
    use rpc_io::{Framing, Router, Server};

    let listener = TcpListener::bind("127.0.0.1:0")?;
    let addr = listener.local_addr()?;
    let server = Server::new(Framing::Newline).with_max_connections(16);
    let stopper = server.stopper();
    let serving = std::thread::spawn(move || {
        server.serve_tcp(listener, |connection| {
            (Router::new().request("whoami", |id: &mut u64, _, _| Ok(*id)), connection.id)
        })
    });
    let mut client = TcpStream::connect(addr)?;
    client.write_all(b"{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"whoami\"}\n")?;
    let mut line = String::new();
    BufReader::new(&client).read_line(&mut line)?;
    assert_eq!(line, "{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":0}\n");
    stopper.stop();
    assert!(serving.join().is_ok_and(|served| served.is_ok()));
    Ok(())
}
```

## `Endpoint`

```rust,ignore
pub struct Endpoint<S, K: Sink>
```

One JSON-RPC connection: a [`Router`](#router), the state `S` its handlers work on, and a [`Sink`](#sink-and-framed) for outgoing messages. `Send` when `S` is. Dropping it closes it.

| Method | Description |
|---|---|
| `new(sink, router, state) -> Self` | An endpoint with the default `Config`. |
| `with_config(self, config) -> Self` | Applies a [`Config`](#config); call before any traffic. |
| `peer(&self) -> Peer` | A sending handle, for any thread. |
| `state(&self) -> &S`, `state_mut(&mut self) -> &mut S` | The handlers' state. |
| `with_sink(&self, f) -> R` | Runs `f` on the sink under the lock (to inspect a `Framed<Vec<u8>>`). |
| `handle(&mut self, body: &[u8]) -> Result<Flow, Error>` | Handles one unframed body (a message or a batch). |
| `run(&mut self, input: impl Read, framing) -> Result<End, Error>` | Reads and handles framed messages until the input ends or a handler stops. |
| `run_with(&mut self, decoder: &mut Decoder, input) -> Result<End, Error>` | As `run`, with a decoder the caller owns (stream hand-off). |
| `next_read(&mut self, framing) -> Result<Next, Error>`, `commit(&mut self, n)`, `finish(&mut self) -> Result<End, Error>` | `run` taken apart, for async and non-blocking readers: handle what is buffered, read into the returned buffer, commit the count. |
| `run_async(&mut self, input: impl AsyncRead + Unpin, framing)` | `run` for an async stream (`futures-io`; see [the async adapter](#the-async-adapter-futures-io)). |
| `close(&mut self)` | Closes: closes the sink, ends every `Call` with `Closed`, cancels deferred work; then, with the lock released, waits for the sink's [`Drain`](#sink-and-framed) (for `Queued`, at most `close_timeout`). Idempotent. |
| `buffered_input(&self) -> usize` | Bytes read from the stream and held in the endpoint's decoder: part of a message, or read ahead. |
| `is_closed(&self) -> bool` | Whether the connection has ended (read without the lock). |
| `next_deadline(&self) -> Option<Instant>`, `expire(&self)` | The earliest deadline; expire what is due (with the timer off). |
| `stats(&self) -> Stats` | The connection's [counters and gauges](#stats). |

### `Endpoint::handle`

Malformed input is answered, not returned as an error. **Errors:** `Error::Closed` after `close`; `Error::Io` if the sink failed (now or since the last call), which closes the endpoint.

```rust
fn main() -> Result<(), rpc_io::Error> {
    use std::sync::mpsc;
    use rpc_io::{Endpoint, Flow, Router};

    let router = Router::new().notification("exit", |_: &mut (), _, cx| cx.stop());
    let (tx, rx) = mpsc::channel::<String>();
    let mut endpoint = Endpoint::new(tx, router, ());
    assert_eq!(endpoint.handle(b"[]")?, Flow::Continue);
    assert!(rx.try_recv().is_ok_and(|m| m.contains("-32600")));
    assert_eq!(endpoint.handle(br#"{"jsonrpc":"2.0","method":"exit"}"#)?, Flow::Stop);
    Ok(())
}
```

### `Endpoint::run`

A message over `Limits::max_message_bytes` is skipped without being buffered and answered with `-32600` under `null`; the session goes on. When the input ends, the endpoint closes. When a handler stops it, it stays open, and the bytes already read past the stopping message stay in the endpoint: the next `run` handles them first. Interrupted reads are retried. **Errors:** `Error::Frame` for a framing the input broke beyond recovery, `Error::Io`, `Error::Closed`; the endpoint is closed after any of them.

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{End, Endpoint, Framed, Framing, Router};

    let router = Router::new().request("ping", |_: &mut (), _, _| Ok("pong"));
    let mut endpoint = Endpoint::new(Framed::new(Vec::new(), Framing::Newline), router, ());
    let input: &[u8] = b"{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"ping\"}\n";
    assert_eq!(endpoint.run(input, Framing::Newline)?, End::Eof);
    let out = endpoint.with_sink(|s| s.get_ref().clone());
    assert_eq!(out, b"{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":\"pong\"}\n");
    Ok(())
}
```

### `Endpoint::next_read`, `commit`, `finish`

`next_read` handles every complete message already buffered, then returns `Next::Read(buf)` (read the stream into `buf`, then `commit` the count) or `Next::Stopped`. At the end of the stream, `finish` handles what is left (a last line without its `\n`) and closes the endpoint. The read goes straight into the endpoint's decoder.

```rust
fn main() -> Result<(), rpc_io::Error> {
    use std::io::Read;
    use rpc_io::{End, Endpoint, Framed, Framing, Next, Router};

    let router = Router::new().request("ping", |_: &mut (), _, _| Ok("pong"));
    let mut endpoint = Endpoint::new(Framed::new(Vec::new(), Framing::Newline), router, ());
    let mut input: &[u8] = b"{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"ping\"}\n";
    let end = loop {
        let buf = match endpoint.next_read(Framing::Newline)? {
            Next::Read(buf) => buf,
            Next::Stopped => break End::Stopped,
        };
        let n = input.read(buf).map_err(rpc_io::Error::Io)?; // or `.await` on any runtime
        if n == 0 {
            break endpoint.finish()?;
        }
        endpoint.commit(n);
    };
    assert_eq!(end, End::Eof);
    Ok(())
}
```

## `Flow`, `End`, and `Next`

`Flow` (`Continue`, `Stop`) is what `handle` returns: `Stop` after a handler called `Context::stop`. `End` (`#[non_exhaustive]`: `Eof`, `Stopped`) is why `run` returned without an error: the input ended (the endpoint is closed), or a handler stopped it (the endpoint is still open, and keeps what it read ahead). `Next` (`Read(&mut [u8])`, `Stopped`) is what `next_read` needs.

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{End, Endpoint, Flow, Framing, Next, Router};

    let router = Router::new().notification("pause", |_: &mut (), _, cx| cx.stop());
    let (tx, _rx) = std::sync::mpsc::channel::<String>();
    let mut endpoint = Endpoint::new(tx, router, ());
    assert_eq!(endpoint.handle(br#"{"jsonrpc":"2.0","method":"pause"}"#)?, Flow::Stop);
    let input: &[u8] = b"{\"jsonrpc\":\"2.0\",\"method\":\"pause\"}\n";
    assert_eq!(endpoint.run(input, Framing::Newline)?, End::Stopped); // still open
    assert!(matches!(endpoint.next_read(Framing::Newline)?, Next::Read(_)));
    assert_eq!(endpoint.finish()?, End::Eof); // now closed
    assert!(endpoint.is_closed());
    Ok(())
}
```

## `Router`

```rust,ignore
pub struct Router<S>
```

| Method | Description |
|---|---|
| `new()` | No handlers. |
| `request(self, method, FnMut(&mut S, Params, &mut Context) -> Result<J, ErrorObject>)` | Answers with the return value (`J: Into<Json<'static>>`). |
| `deferred(self, method, FnMut(&mut S, Params, &mut Context, Responder))` | Answers through a [`Responder`](#responder), now or later. |
| `notification(self, method, FnMut(&mut S, Params, &mut Context))` | Handles a notification. |
| `request_typed`, `notification_typed` | The same through `serde` types (`serde`; see [typed params](#typed-params-and-results-serde)). |
| `intercept(self, FnMut(&mut S, &str, Option<&Id>, &Params) -> Result<(), ErrorObject>)` | Runs before every routed call; `Err` refuses it. |
| `on_event(self, FnMut(&mut S, &Event))` | Observes [`Event`](#event)s; its panics are contained and ignored. |
| `has_request(&self, method)`, `has_notification(&self, method)` | Lookups. |

Registering a method again replaces its handler. Requests and notifications are registered separately: a request for a method with only a notification handler is `METHOD_NOT_FOUND`, and a notification with no handler is ignored (`Event::UnknownNotification`). A panicking handler may leave the state half-updated; the endpoint does not repair it.

The interceptor runs for each request and notification after the gate and cancellation have had their say, before the handler is looked up: the place for authorization, rate limits, or an audit log. `Err(error)` answers a request with `error` (so an unauthorized caller cannot probe which methods exist) and drops a notification (`Event::Refused`).

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{Endpoint, ErrorCode, ErrorObject, Router};

    #[derive(Default)]
    struct Server { documents: Vec<String>, authorized: bool }

    let router = Router::new()
        .request("auth", |s: &mut Server, _, _| { s.authorized = true; Ok(()) })
        .request("document/count", |s, _, _| Ok(s.documents.len()))
        .notification("document/add", |s, params, _| {
            if let Ok(p) = params.parse() {
                s.documents.push(p["text"].as_str().unwrap_or_default().to_owned());
            }
        })
        .intercept(|s, method, _, _| {
            if s.authorized || method == "auth" {
                Ok(())
            } else {
                Err(ErrorObject::new(ErrorCode(1003), "authenticate first"))
            }
        });
    let (tx, rx) = std::sync::mpsc::channel::<String>();
    let mut endpoint = Endpoint::new(tx, router, Server::default());
    endpoint.handle(br#"{"jsonrpc":"2.0","id":1,"method":"document/count"}"#)?;
    assert!(rx.try_recv().is_ok_and(|m| m.contains("1003")));
    endpoint.handle(br#"{"jsonrpc":"2.0","id":2,"method":"auth"}"#)?;
    endpoint.handle(br#"{"jsonrpc":"2.0","method":"document/add","params":{"text":"a"}}"#)?;
    assert_eq!(endpoint.state().documents, ["a"]);
    Ok(())
}
```

## `Params`

A call's `params`: validated, a slice of the message, parsed only when asked.

| Method | Description |
|---|---|
| `parse(&self) -> Result<Value<'_>, ErrorObject>` | Parses with the endpoint's JSON budgets, duplicate keys refused; `Value::Null` when absent. The error is `INVALID_PARAMS`, ready for `?`. |
| `decode<T: FromJson>(&self) -> Result<T, ErrorObject>` | Into a jsonx-lib `FromJson` type, with the endpoint's budgets and duplicate keys refused; `T` may borrow from the message. Absent params read as `null`. The error is `INVALID_PARAMS` naming the path and offset. |
| `deserialize<T>(&self) -> Result<T, ErrorObject>` | Into a `serde` type (`serde`); absent params read as `null`. |
| `raw(&self) -> Option<&Raw>` | The JSON text. |
| `is_present(&self) -> bool` | Whether params were sent (`"params": null` reads as absent). |
| `progress_token(&self) -> Option<Raw<'_>>` | MCP's `params._meta.progressToken`, a string or an integer. |
| `work_done_token(&self) -> Option<Raw<'_>>` | LSP's `params.workDoneToken`, a string or an integer. |
| `into_raw(self) -> Option<Raw>` | The text, to forward without re-serializing. |
| `into_owned(self) -> Params<'static>` | Copies, to keep beyond the call or move to a thread. |

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{Endpoint, Router};

    let router = Router::new().request("echo", |_: &mut (), params, _| {
        Ok(params.into_raw().map_or(rpc_io::Raw::NULL, rpc_io::Raw::into_owned))
    });
    let (tx, rx) = std::sync::mpsc::channel::<String>();
    Endpoint::new(tx, router, ()).handle(br#"{"jsonrpc":"2.0","id":1,"method":"echo","params":{"a": [1, 2]}}"#)?;
    assert_eq!(rx.try_recv().ok().as_deref(), Some(r#"{"jsonrpc":"2.0","id":1,"result":{"a": [1, 2]}}"#));
    Ok(())
}
```

## `Context`

What a handler can reach while it runs.

| Method | Description |
|---|---|
| `method(&self) -> &str` | The method being handled. |
| `id(&self) -> Option<&Id>` | The request's id; `None` for a notification. |
| `notify(&self, method, params)` | Sends a notification (before this request's response). |
| `request(&self, method, params) -> Result<Call, Error>` | Sends a request. Its `Call` cannot be waited on here (`CallError::WouldDeadlock`): keep it and `try_wait` later, or wait on another thread. |
| `request_with_timeout(&self, method, params, timeout)` | The same with a deadline. |
| `peer(&self) -> Peer` | A `Peer` to keep or move to a thread. |
| `notifier(&self) -> Option<Notifier>` | Notifications bound to this request (see [`Notifier`](#notifier)); `None` for a notification. For a request answered by the handler's return value, it refuses as soon as the handler returns. |
| `progress(&self, &Params) -> Option<Progress>` | MCP progress bound to this request (see [`Progress`](#progress-and-workdone)). |
| `notify_json`, `request_json` | With `ToJson` params (see [typed params](#typed-params-and-results-tojson--fromjson)). |
| `stop(&mut self)` | Stops after this message (`Flow::Stop`, `End::Stopped`); the current response is still sent. |

`ErrorObject: From<Error>` (an `INTERNAL_ERROR`), so `cx.notify(..)?` works in a request handler.

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{Endpoint, Router};

    let router = Router::new().request("work", |_: &mut (), _, cx| {
        cx.notify("$/progress", rpc_io::jsonx::json!({ "token": cx.method() }))?;
        Ok("done")
    });
    let (tx, rx) = std::sync::mpsc::channel::<String>();
    Endpoint::new(tx, router, ()).handle(br#"{"jsonrpc":"2.0","id":1,"method":"work"}"#)?;
    let sent: Vec<String> = rx.try_iter().collect();
    assert_eq!(sent, [
        r#"{"jsonrpc":"2.0","method":"$/progress","params":{"token":"work"}}"#,
        r#"{"jsonrpc":"2.0","id":1,"result":"done"}"#,
    ]);
    Ok(())
}
```

## `Event`

`#[non_exhaustive]`. What the endpoint handled on its own, reported to `Router::on_event` (and, with the `tracing` feature, recorded as an event).

| Variant | Meaning |
|---|---|
| `Panicked { method, message }` | A handler or the interceptor panicked; a request was answered with `INTERNAL_ERROR` (the message stays here). |
| `Invalid { error, answered }` | A malformed message, or a request reusing an in-flight id; answered when request-like, dropped when a broken response. |
| `UnknownNotification { method }` | A notification with no handler. |
| `Dropped { method }` | A notification dropped before the gate opened. |
| `Refused { method, error }` | A notification the interceptor refused. |
| `InvalidParams { method, error }` | A notification whose params did not fit its typed handler (`notification_json`, or `notification_typed` with `serde`). |
| `Unmatched { id }` | A response to an id we are not waiting on. |
| `PeerError { error }` | An error response under `null`: the peer could not read something we sent. |
| `Oversized { error }` | A message over `max_message_bytes`, skipped and answered under `null`. |
| `Cancelled { id }` | The peer cancelled one of its deferred requests. |

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{Endpoint, Event, Router};

    let router = Router::new().on_event(|log: &mut Vec<String>, event| {
        if let Event::Unmatched { id } = event {
            log.push(format!("unmatched {id}"));
        }
    });
    let (tx, _rx) = std::sync::mpsc::channel::<String>();
    let mut endpoint = Endpoint::new(tx, router, Vec::new());
    endpoint.handle(br#"{"jsonrpc":"2.0","id":42,"result":null}"#)?;
    assert_eq!(endpoint.state(), &["unmatched 42"]);
    Ok(())
}
```

## `Stats`

`#[non_exhaustive]`, `Copy`. A snapshot from `Endpoint::stats()` or `Peer::stats()`. The endpoint keeps the counters as plain integers under the lock it takes for every message anyway.

| Field | Kind | Counts | Worth a look |
|---|---|---|---|
| `bodies_in`, `bytes_in` | counter | message bodies handled (a batch counts once) and their bytes | `bytes_in / bodies_in` near `max_message_bytes` |
| `requests_in`, `notifications_in`, `responses_in` | counter | messages from the peer, batch elements included | |
| `invalid_in` | counter | malformed messages and messages skipped as oversized | any growth: a broken or hostile peer |
| `bodies_out`, `bytes_out` | counter | message bodies sent and their bytes | |
| `requests_out`, `notifications_out`, `responses_out` | counter | messages sent, batch elements included | |
| `errors_out` | counter | error responses sent, of `responses_out` | a large share: handlers failing |
| `timed_out`, `evicted`, `cancelled_out` | counter | our requests that ended so | timeouts: a slow or stuck peer; evictions: raise `max_pending` |
| `cancelled_in` | counter | the peer's requests it cancelled | |
| `panics` | counter | handler and interceptor panics contained | any: a bug |
| `pending`, `in_flight`, `held` | gauge | our requests awaiting answers, deferred requests being answered, messages held behind the gate | near their limits |

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{Endpoint, Router};

    let (tx, _rx) = std::sync::mpsc::channel::<String>();
    let mut endpoint = Endpoint::new(tx, Router::<()>::new(), ());
    endpoint.handle(br#"{"jsonrpc":"2.0","id":1,"method":"missing"}"#)?;
    let stats = endpoint.stats();
    assert_eq!((stats.requests_in, stats.errors_out), (1, 1));
    Ok(())
}
```

## `Peer`

`Clone + Send + Sync`. Sends from any thread.

| Method | Description |
|---|---|
| `notify(&self, method, params) -> Result<(), Error>` | `params`: an array, an object, or `()` for none. |
| `request(&self, method, params) -> Result<Call, Error>` | Deadline: `Config::request_timeout`, if set. |
| `request_with_timeout(&self, method, params, timeout) -> Result<Call, Error>` | With its own deadline. |
| `notify_typed`, `request_typed` | With `serde` params (`serde`). |
| `is_closed(&self) -> bool` | Whether the connection has ended. |
| `stats(&self) -> Stats` | The connection's counters and gauges. |

**Errors:** `Error::InvalidParams` for params that are not an array, an object, or null; `Error::Closed`; `Error::Io` (which closes the connection); `Error::Backlog` while the gate is shut and its budget is spent.

```rust
fn main() -> Result<(), rpc_io::Error> {
    use std::time::Duration;
    use rpc_io::{CallError, Endpoint, Router};

    let (tx, rx) = std::sync::mpsc::channel::<String>();
    let endpoint = Endpoint::new(tx, Router::<()>::new(), ());
    let peer = endpoint.peer();
    let call = peer.request_with_timeout("slow", (), Duration::from_millis(10))?;
    assert_eq!(call.wait(), Err(CallError::TimedOut));
    let sent: Vec<String> = rx.try_iter().collect();
    assert_eq!(sent[1], r#"{"jsonrpc":"2.0","method":"$/cancelRequest","params":{"id":1}}"#);
    Ok(())
}
```

## `Call`

One of our requests. Ends in exactly one outcome. Dropping it before its outcome cancels the request (frees its pending slot and tells the peer), so it is `#[must_use]`; `detach()` keeps it outstanding without a waiter instead. A `Future` on any executor (`Output = Result<Raw<'static>, CallError>`), woken when the outcome arrives; polling it again after that returns `CallError::Closed`.

| Method | Description |
|---|---|
| `id(&self) -> u64` | The id on the wire. |
| `deadline(&self) -> Option<Instant>` | The deadline, if any. |
| `wait(self) -> Result<Raw<'static>, CallError>` | Blocks for the outcome, enforcing the deadline. On the endpoint's own thread returns `WouldDeadlock` unless the outcome is already there. |
| `wait_json<T: FromJson>(self) -> Result<T, CallError>` | `wait`, then decodes the result (owned `T`); one that does not fit is `CallError::InvalidResponse`. |
| `wait_typed<T>(self) -> Result<T, CallError>` | `wait`, then deserializes the result (`serde`). |
| `try_wait(self) -> Result<Result<Raw<'static>, CallError>, Call>` | Never blocks; `Err(self)` while outstanding. |
| `cancel(self) -> bool` | Cancels (sends the cancel notification); `false` if already ended. |
| `detach(self)` | Keeps the request outstanding without a waiter: answered (and discarded), timed out, or evicted later. |
| `canceller(&self) -> Canceller` | A handle that cancels from elsewhere. |

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{Endpoint, Router};

    let (tx, _rx) = std::sync::mpsc::channel::<String>();
    let mut endpoint = Endpoint::new(tx, Router::<()>::new(), ());
    let call = endpoint.peer().request("x", ())?;
    let call = match call.try_wait() { Ok(_) => unreachable!(), Err(call) => call };
    endpoint.handle(br#"{"jsonrpc":"2.0","id":1,"result":[42]}"#)?;
    assert_eq!(call.wait().map(|r| r.as_str().to_owned()), Ok("[42]".to_owned()));
    Ok(())
}
```

## `Canceller`

`Clone + Send + Sync`: `cancel(&self) -> bool` (as `Call::cancel`) and `id(&self) -> u64`.

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{CallError, Endpoint, Router};

    let (tx, _rx) = std::sync::mpsc::channel::<String>();
    let endpoint = Endpoint::new(tx, Router::<()>::new(), ());
    let call = endpoint.peer().request("slow", ())?;
    let canceller = call.canceller();
    std::thread::spawn(move || canceller.cancel());
    assert_eq!(call.wait(), Err(CallError::Cancelled));
    Ok(())
}
```

## `Responder`

The right to answer one deferred request, exactly once. `Send`.

| Method | Description |
|---|---|
| `id(&self) -> &Id<'static>` | The request's id. |
| `token(&self) -> CancelToken`, `is_cancelled(&self) -> bool` | The cancellation flag. |
| `peer(&self) -> Peer` | Send progress while working. |
| `respond(self, Result<J, ErrorObject>)`, `ok(self, value)`, `err(self, error)` | Answers. **Errors:** `Error::AlreadyAnswered` (cancelled first), `Error::Closed`, `Error::Io`. |
| `ok_json(self, &T)` | Answers with a `ToJson` value, encoded in a per-thread reused buffer. |
| `ok_typed(self, &T)` | Answers with a `serde` value (`serde`); one that cannot be serialized is answered `INTERNAL_ERROR` and returns `Error::Serialize`. |
| `notifier(&self) -> Notifier` | Notifications bound to this request (see [`Notifier`](#notifier)). |
| `progress(&self, &Params) -> Option<Progress>` | MCP progress bound to this request. |

Dropped without answering, it answers `INTERNAL_ERROR`.

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{Endpoint, Router};

    let router = Router::new().deferred("slow", |_: &mut (), _, _, responder| {
        std::thread::spawn(move || {
            if !responder.is_cancelled() {
                responder.ok("done").ok();
            }
        });
    });
    let (tx, rx) = std::sync::mpsc::channel::<String>();
    let mut endpoint = Endpoint::new(tx, router, ());
    endpoint.handle(br#"{"jsonrpc":"2.0","id":7,"method":"slow"}"#)?;
    let reply = rx.recv_timeout(std::time::Duration::from_secs(5)).ok();
    assert_eq!(reply.as_deref(), Some(r#"{"jsonrpc":"2.0","id":7,"result":"done"}"#));
    Ok(())
}
```

## `Notifier`

Notifications that belong to one request, sent only while it is in flight: `notify(method, params)` and `notify_json(method, &T)` refuse with `Error::AlreadyAnswered` once the request is answered or cancelled by the peer, and `Error::Closed` once the connection closed. The check runs under the lock the response is written under, so no notification can follow the response, or a cancellation the endpoint has handled, on the wire. A notifier is bound to its request, not to the request's id: when the peer reuses the id for a later request, a notifier of the earlier one still refuses. For a stream of notifications tied to a request, such as MCP's `subscriptions/listen`. `Clone + Send + Sync`; from `Responder::notifier` or `Context::notifier`.

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{Config, Endpoint, Error, Router};

    let router = Router::new().deferred("subscriptions/listen", |kept: &mut Vec<rpc_io::Responder>, _, _, responder| {
        kept.push(responder);
    });
    let (tx, rx) = std::sync::mpsc::channel::<String>();
    let mut endpoint = Endpoint::new(tx, router, Vec::new()).with_config(Config::mcp());
    endpoint.handle(br#"{"jsonrpc":"2.0","id":1,"method":"subscriptions/listen"}"#)?;
    let responder = endpoint.state_mut().remove(0);
    let notifier = responder.notifier();
    notifier.notify_json("notifications/resources/updated", &["file:///a"])?;
    responder.ok(())?; // the stream ends with its response
    assert!(matches!(notifier.notify("notifications/resources/updated", ()), Err(Error::AlreadyAnswered)));
    assert_eq!(rx.try_iter().count(), 2);
    Ok(())
}
```

## `CancelToken`

`Clone + Send + Sync + Default`: `new()`, `cancel(&self)`, `is_cancelled(&self) -> bool`. Clones share the flag. The endpoint sets it when the peer cancels the request or the connection closes.

```rust
let token = rpc_io::CancelToken::new();
let seen = token.clone();
token.cancel();
assert!(seen.is_cancelled());
```

## `Progress` and `WorkDone`

`Progress` sends MCP's `notifications/progress` for one progress token, and holds MCP's two rules for it:

- `progress` must increase with every report: `report` refuses a value that does not exceed the last one sent with `Error::ProgressNotIncreasing { last, next }`, and sends nothing. For a handle bound to a request, "the last one sent" is the request's: every handle made for it (each `Context::progress` or `Responder::progress` call, and their clones) shares one history. For a handle bound to nothing (`new`, `from_params`) it is the handle's and its clones'. The check and the send happen under one lock, so reports from several threads reach the wire in increasing order.
- Reports stop when the request completes (and, on stdio, once the peer cancelled it): a handle from `Context::progress(&params)` or `Responder::progress(&params)` is bound to its request and refuses with `Error::AlreadyAnswered` once the request is answered (for a request answered by the handler's return value, as soon as the handler returns) or cancelled, checked under the lock the response is written under, and bound to the request rather than its id, so a later request reusing the id is never reported for; `Error::Closed` once the connection closed. Both return `None` when the request carries no `_meta.progressToken` (and `Context::progress` for a notification).

`new(peer, token)` and `from_params(&params, peer)` make a handle bound to no request: the first rule holds, the second is the caller's. `token()`, and `report(progress: f64, total: Option<f64>, message: Option<&str>)`. Whole numbers are written without a fraction; a number that is not finite is `Error::Serialize`.

`WorkDone` sends LSP's `$/progress` for one work-done token: `new(peer, token)`, `from_params(&params, peer)` (when the request carries `workDoneToken`), `token()`, `begin(title, cancellable, message, percentage)`, `report(message, percentage)`, `end(message)`. Percentages are capped at 100. Both are `Clone`, and send through their `Peer` from any thread.

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{Endpoint, Router, WorkDone};

    let router = Router::new().request("work", |_: &mut (), params, cx| {
        if let Some(progress) = cx.progress(&params) {
            progress.report(50.0, Some(100.0), None)?;
            assert!(progress.report(40.0, None, None).is_err()); // must increase
        }
        if let Some(work) = WorkDone::from_params(&params, cx.peer()) {
            work.begin("Working", false, None, None)?;
            work.end(Some("done"))?;
        }
        Ok(())
    });
    let (tx, rx) = std::sync::mpsc::channel::<String>();
    let mut endpoint = Endpoint::new(tx, router, ());
    endpoint.handle(br#"{"jsonrpc":"2.0","id":1,"method":"work","params":{"_meta":{"progressToken":7}}}"#)?;
    let sent: Vec<String> = rx.try_iter().collect();
    assert_eq!(sent[0], r#"{"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":7,"progress":50,"total":100}}"#);
    endpoint.handle(br#"{"jsonrpc":"2.0","id":2,"method":"work","params":{"workDoneToken":"w"}}"#)?;
    let sent: Vec<String> = rx.try_iter().collect();
    assert_eq!(sent[1], r#"{"jsonrpc":"2.0","method":"$/progress","params":{"token":"w","value":{"kind":"end","message":"done"}}}"#);
    Ok(())
}
```

## `Config`

`#[non_exhaustive]`; start from `Config::new()` (or a preset) and chain `with_*`.

| Field | Default | Meaning |
|---|---|---|
| `limits` | `Limits::new()` | Budgets on incoming messages. |
| `max_pending` | 1024 | Our requests awaiting answers; one more evicts the oldest (`CallError::Evicted`). |
| `max_in_flight` | 1024 | Deferred requests being answered; more are refused with `-32000`. |
| `max_held_bytes` | 4 MiB | Messages this side sends while the gate is shut; more fail with `Error::Backlog`. |
| `request_timeout` | none | Deadline for requests that set none. |
| `cancellation` | `Some(Cancellation::lsp())` | How cancellation is spelled; `None` turns it off (the notification then reaches handlers). |
| `gate` | none | An opening request every other request waits for. |
| `timer` | `true` | Deadlines fire on their own, from a timer thread (see [Deadlines](#deadlines)). |
| `omit_null_id` | `false` | An error for a message whose id could not be read carries `"id": null` (JSON-RPC 2.0); `true` leaves `id` out (MCP). An error response from the peer with either form is read as one under `null`. |
| `overloaded_code` | `-32000` | The code of the refusal past `max_in_flight`. |

Presets:

- `Config::lsp()`: an LSP server. `Limits::lsp()`, `Cancellation::lsp()`, `Gate::lsp()`. A client leaves the gate out (`with_gate(None)`).
- `Config::mcp()`: MCP as of its current revision, 2026-07-28, for a server or a client. `Limits::mcp()` (batches off), `Cancellation::mcp()`, **no gate** (the protocol is stateless: every request carries its protocol version in `_meta`, and there is no `initialize`), `omit_null_id`, and `overloaded_code` `-32603`. This is also the preset of a dual-era server: the specification has such a server pick each request's semantics from the request itself (an `initialize` selects the legacy ones), which belongs to the protocol layer above.
- `Config::mcp_legacy()`: a server for MCP's legacy revisions only (2025-11-25 and earlier): `Config::mcp()` plus `Gate::mcp()`. Modern clients never send `initialize`, so it refuses all their requests.

Before 0.4.0, `Config::mcp()` was the legacy preset, with the `initialize` gate and its `-32002` refusals.

```rust
use std::time::Duration;
use rpc_io::{Cancellation, Config, Gate};

let mcp = Config::new()
    .with_cancellation(Some(Cancellation::mcp()))
    .with_gate(Some(Gate::new("initialize")))
    .with_request_timeout(Some(Duration::from_secs(30)));
assert_eq!(mcp.max_pending, 1024);
assert_eq!(Config::mcp().limits.max_batch, 0);
assert!(Config::mcp().gate.is_none());
assert!(Config::mcp_legacy().gate.is_some());
```

## `Cancellation`

`#[non_exhaustive]` with public fields `method`, `id_member`, `reply: Option<ErrorCode>`. Constructors: `new(method, id_member, reply)`, `lsp()` (`$/cancelRequest {id}`, answered `-32800`), `mcp()` (`notifications/cancelled {requestId}`, no answer). The notification is consumed by the endpoint; it never reaches the router or the interceptor.

```rust
use rpc_io::{Cancellation, ErrorCode};

// A service API of your own: `$/cancel {id}`, answered with error 1005.
let custom = Cancellation::new("$/cancel", "id", Some(ErrorCode(1005)));
assert_eq!(custom.method, "$/cancel");
```

## `Gate`

`#[non_exhaustive]` with public fields `method`, `code` (default `-32002`), `allow` (notifications), `allow_requests`. Constructors: `new(method)`, `lsp()` (`initialize`, `exit` allowed), `mcp()` (MCP's legacy handshake, revisions 2025-11-25 and earlier: `initialize`, the `ping` request allowed, refusals with `-32600`, since MCP used `-32002` for "resource not found" and forbids emitting it since), `allow(self, notification)`, `allow_request(self, request)`, `with_code(self, code)`.

Until the opening request succeeds: other requests are refused with `code`, except those in `allow_requests`; notifications are dropped except those in `allow`; everything this side sends but responses is held, within `Config::max_held_bytes`, and sent in order right after the opening response. If the opening request fails (an error answer, or cancelled under a cancellation with no reply), held traffic is discarded, held requests end `Cancelled`, and the gate shuts again. A held request that times out or is cancelled is never sent; an answer to one is unmatched. A repeated opening request after success, and one in a batch, are refused with `-32600`.

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{Config, Endpoint, Gate, Router};

    let router = Router::new()
        .request("initialize", |_: &mut (), _, _| Ok(rpc_io::jsonx::json!({ "capabilities": {} })))
        .request("hover", |_, _, _| Ok("text"));
    let (tx, rx) = std::sync::mpsc::channel::<String>();
    let mut endpoint = Endpoint::new(tx, router, ())
        .with_config(Config::new().with_gate(Some(Gate::new("initialize").allow("exit"))));
    endpoint.handle(br#"{"jsonrpc":"2.0","id":1,"method":"hover"}"#)?;
    assert!(rx.try_recv().is_ok_and(|m| m.contains("-32002")));
    endpoint.handle(br#"{"jsonrpc":"2.0","id":2,"method":"initialize"}"#)?;
    endpoint.handle(br#"{"jsonrpc":"2.0","id":3,"method":"hover"}"#)?;
    assert_eq!(rx.try_iter().last().as_deref(), Some(r#"{"jsonrpc":"2.0","id":3,"result":"text"}"#));
    Ok(())
}
```

## `Limits`

`#[non_exhaustive]`, `Copy`; `Limits::new()` (also `const`), the presets, and `with_*` for each field.

| Field | Default | Bounds |
|---|---:|---|
| `max_message_bytes` | 64 MiB | One body (a Content-Length body or a line). |
| `max_header_bytes` | 8 KiB | One Content-Length header section, line ends and the terminating blank line included. |
| `max_headers` | 32 | Header lines in one section. |
| `max_batch` | 1024 | Messages in one batch; `0` turns batches off (`without_batches()`). |
| `max_skip_bytes` | `u64::MAX` | The largest announced length of an oversized Content-Length body still skipped; above it the connection closes (`FrameError::TooLargeToSkip`). |
| `json` | `jsonx_lib::Limits::new()` | Depth 128, 16 MiB strings, 1 KiB numbers, 4 Mi values; its `max_input_bytes` is replaced by `max_message_bytes`. |
| `lenient_ids` | `false` | A policy, not a budget: accept `null` and non-`i64` numeric request ids (see [Ids](#ids)); off in every preset. |

| Preset | Messages | Headers | Batch | Skip | JSON depth / strings / numbers / values |
|---|---:|---:|---:|---:|---|
| `new()`, `lsp()` | 64 MiB | 8 KiB, 32 | 1024 | any | 128 / 16 MiB / 1 KiB / 4 Mi |
| `mcp()` | 64 MiB | 8 KiB, 32 | off | any | 128 / 16 MiB / 1 KiB / 4 Mi |
| `network()` | 4 MiB | 4 KiB, 16 | 128 | 64 MiB | 64 / 1 MiB / 128 B / 256 Ki |
| `strict()` | 1 MiB | 2 KiB, 8 | 16 | 4 MiB | 32 / 256 KiB / 64 B / 64 Ki |

A handler that calls `Params::parse` builds a value tree within these budgets, so one 64 MiB array of small numbers can cost several times its size: use `network()` or `strict()` for peers across a network. `parser(&self) -> jsonx_lib::Parser` is the parser these limits configure.

```rust
use rpc_io::Limits;

const SMALL: Limits = Limits::new().with_max_message_bytes(1 << 20).with_max_batch(16);
assert_eq!(SMALL.parser().get_limits().max_input_bytes, 1 << 20);
assert_eq!(Limits::network().max_message_bytes, 4 << 20);
```

## `Sink` and `Framed`

```rust,ignore
pub trait Sink: Send + 'static {
    fn send(&mut self, message: &str) -> io::Result<()>;
    fn flush(&mut self) -> io::Result<()> { Ok(()) }
    fn close(&mut self) -> io::Result<()> { self.flush() }
    fn drain(&mut self) -> Option<Drain> { None }
}
```

Each `send` is one unframed body; `flush` is called at the end of each turn and after each message from another thread; `close` once: when the endpoint closes, or after a send or flush failed. A sink is called with the endpoint's lock held and must not call back into the endpoint; a sink that blocks blocks every sender. `close` should not wait for the peer: a sink with writes still in flight returns a `Drain` from `drain` (asked for once, right after `close`, when the endpoint is closed rather than failed), and the closing thread waits on it after releasing the lock. `Drain::new(impl FnOnce() + Send + 'static)` wraps the wait; `wait(self)` runs it. `Queued` returns one that waits for its writer, for at most `close_timeout`. An error, or a panic, closes the connection. Implemented for `mpsc::Sender<String>` (one string per message), [`Framed<W: Write + Send + 'static>`](#sink-and-framed), [`Queued`](#queued-and-outbox), and [`OutboxSink`](#queued-and-outbox).

`Framed` frames into a reused buffer and writes once per turn, or whenever the flush threshold (64 KiB by default) is waiting, in the sending thread. A buffer grown past twice the threshold by one large message is released after it is written. `Framed` has `new(writer, framing)`, `with_flush_threshold(bytes)`, `flush_threshold()`, `framing()`, `get_ref()`, `get_mut()`, `into_inner()`.

```rust
fn main() -> Result<(), std::io::Error> {
    use rpc_io::{Framed, Framing, Sink};

    let mut framed = Framed::new(Vec::new(), Framing::ContentLength);
    framed.send("{}")?;
    framed.flush()?;
    assert_eq!(framed.get_ref().as_slice(), b"Content-Length: 2\r\n\r\n{}");
    Ok(())
}
```

## `Queued` and `Outbox`

Outgoing queues whose senders do not wait on the peer: messages are framed into a bounded queue under the endpoint's lock, and the slow part, the write to the peer, happens elsewhere, without the lock.

- **`Queued`** (a `Sink`): `new(writer, framing)` and `with_limits(writer, framing, limits)` start a writer thread over any `Write + Send + 'static`, which writes each batch of queued messages in chunks of at most 64 KiB, then one `flush`. `framing()`, `limits()`, `pending_bytes()`, `pending_messages()`. Closing the endpoint closes the queue without waiting, under the lock; its `Drain` then waits, without the lock, for what is queued to be written: until the writer is done, has made no progress for `write_timeout`, or `close_timeout` has passed. Dropping a `Queued` that was never closed does the same. When the writer finishes, the writer is dropped; a writer stuck in a write when the wait gives up ends when that write returns. **Errors:** the I/O error from starting the thread.
- **`outbox(framing, limits) -> (OutboxSink, Outbox)`**: the same queue, drained by an async task. `OutboxSink` goes into the endpoint; `Outbox::poll_chunk(cx)` yields the next framed bytes (an empty chunk at the end), `consume(n)` records how many were written, `pending_bytes()`. With `futures-io`, `Outbox` is an `AsyncRead` and `AsyncBufRead`, and `write_to(writer)` drains it into any `AsyncWrite`. Dropping the `Outbox` fails the sink, which closes the endpoint.
- **`QueueLimits`** (`#[non_exhaustive]`, `Copy`): `max_bytes` (64 MiB), `max_messages` (65,536), `write_timeout` (60 s; `None` waits forever), `close_timeout` (10 s; `Duration::MAX` waits as long as the writes make progress), with `new()` and `with_*`. A message that would take the queue past a limit fails it (one message is always taken when it is empty). `write_timeout` is a no-progress timeout: every byte the peer takes restarts it, so a slow but steady reader is never cut off; it is checked at each send, flush, and close, which then fail. A writer blocked in a write cannot check it itself: give the writer its own write timeout (as `Server` does with its sockets) to have the write fail. A failed queue refuses everything with the same I/O error, which closes the endpoint.

```rust
fn main() -> Result<(), std::io::Error> {
    use std::task::{Context, Poll, Waker};
    use rpc_io::{Endpoint, Framing, QueueLimits, Queued, Router};

    // A thread-written sink for a byte stream:
    let endpoint = Endpoint::new(Queued::new(std::io::sink(), Framing::ContentLength)?, Router::<()>::new(), ());
    endpoint.peer().notify("ready", ()).ok();

    // An async-drained one:
    let (sink, mut outbox) = rpc_io::outbox(Framing::Newline, QueueLimits::new().with_max_bytes(1 << 20));
    let endpoint = Endpoint::new(sink, Router::<()>::new(), ());
    endpoint.peer().notify("ready", ()).ok();
    let Poll::Ready(chunk) = outbox.poll_chunk(&mut Context::from_waker(Waker::noop())) else { panic!() };
    assert_eq!(chunk, b"{\"jsonrpc\":\"2.0\",\"method\":\"ready\"}\n");
    Ok(())
}
```

## Typed params and results (`ToJson` / `FromJson`)

The primary typed API: jsonx-lib's own traits, hand-implemented (no derive, no reflection, no third-party dependency), in every build.

| Item | Description |
|---|---|
| `Router::request_json(method, FnMut(&mut S, P, &mut Context) -> Result<R, ErrorObject>)` | `P: for<'de> FromJson<'de>` (owned), `R: ToJson`. Params that do not decode are `INVALID_PARAMS` without calling the handler. The result is written as for `request_encoded`. |
| `Router::request_encoded(method, FnMut(&mut S, Params, &mut Context) -> Result<R, ErrorObject>)` | `R: ToJson`, written straight into a buffer the endpoint reuses (released after a result over 64 KiB): no `Value` is built, and once the buffer has grown nothing is allocated for the result. With `Params::decode` inside, the way to take params that borrow from the message. |
| `Router::notification_json(method, FnMut(&mut S, P, &mut Context))` | Params that do not decode are reported as `Event::InvalidParams`. |
| `Params::decode::<T>()`, `Raw::decode::<T>()`, `Call::wait_json::<T>()` | Decoding; see [`Params`](#params), [`Raw`](#raw), [`Call`](#call). Errors name what did not fit, the byte offset, and the JSON Pointer path, clipped to 256 bytes (they may quote keys the peer chose). |
| `Peer::notify_json(method, &T)`, `Peer::request_json(method, &T)`, and the same on `Context` | `T: ToJson`, encoded in a per-thread reused buffer (also released after 64 KiB); params must encode to an array, an object, or `null` (`Error::InvalidParams` otherwise). |
| `Responder::ok_json(&T)` | The same, for a deferred answer from any thread. |
| `Json::encode(&T) -> Json<'static>` | Compact JSON, allocated; for error `data` and the like. Infallible. |
| `ToJson` for `Id`, `ErrorCode`, `ErrorObject`, `Raw`, `Json`; `FromJson` for `Id<'de>`, `ErrorCode`, `Raw<'de>` | An id writes as it is sent and decodes strictly (a string, borrowed when it has no escapes, or an `i64` integer); a code is an integer; an error object writes as a response carries it; a `Raw` writes its text and decodes as a value's source text, unparsed. |

Encoding runs outside the endpoint's lock: a `ToJson` impl may itself send through a `Peer` (it gets a fresh buffer), and a panic in one is contained like a handler's (a request is answered with `INTERNAL_ERROR`; a panic while encoding params unwinds to the caller, and the buffer stays usable).

```rust
use rpc_io::jsonx::{DecodeError, FromJson, Reader, ToJson, ValueWriter, Written};
use rpc_io::{Endpoint, Router};

struct Position { line: u64 }
struct Hover { line: u64 }

impl<'de> FromJson<'de> for Position {
    fn from_json(reader: &mut Reader<'de>) -> Result<Self, DecodeError> {
        let mut line = None;
        let mut object = reader.read_object()?;
        while let Some(key) = object.next_key()? {
            if key == "line" {
                object.field(&mut line)?;
            }
        }
        Ok(Position { line: object.required(line, "line")? })
    }
}

impl ToJson for Hover {
    fn to_json(&self, out: ValueWriter<'_>) -> Written {
        out.object(|o| {
            o.member("contents", "markdown");
            o.member("line", &self.line);
        })
    }
}

fn main() -> Result<(), rpc_io::Error> {
    let router = Router::new().request_json("hover", |_: &mut (), p: Position, _| Ok(Hover { line: p.line }));
    let (tx, rx) = std::sync::mpsc::channel::<String>();
    let mut endpoint = Endpoint::new(tx, router, ());
    endpoint.handle(br#"{"jsonrpc":"2.0","id":1,"method":"hover","params":{"line":3}}"#)?;
    assert_eq!(rx.try_recv().ok().as_deref(), Some(r#"{"jsonrpc":"2.0","id":1,"result":{"contents":"markdown","line":3}}"#));
    endpoint.peer().notify_json("log", &["indexed", "a.rs"])?;
    assert_eq!(rx.try_recv().ok().as_deref(), Some(r#"{"jsonrpc":"2.0","method":"log","params":["indexed","a.rs"]}"#));
    Ok(())
}
```

## Typed params and results (`serde`)

The alternative to the traits above. With the `serde` feature, protocol types written against `serde` (`lsp-types`, MCP schema crates, your own `#[derive(Deserialize)]`) go in and out of handlers and calls. Values are read from the text the endpoint has already validated within its JSON budgets, with `serde_json`.

| Item | Description |
|---|---|
| `Router::request_typed(method, FnMut(&mut S, P, &mut Context) -> Result<R, ErrorObject>)` | `P: DeserializeOwned`, `R: Serialize`. Params that do not fit are `INVALID_PARAMS`; a result that cannot be serialized is `INTERNAL_ERROR`. |
| `Router::notification_typed(method, FnMut(&mut S, P, &mut Context))` | Params that do not fit are reported as `Event::InvalidParams`. |
| `Params::deserialize::<T>()`, `Raw::deserialize::<T>()` | `INVALID_PARAMS` saying what did not fit. |
| `Json::serialize(&T) -> Result<Json<'static>, ErrorObject>` | Compact JSON, to send. |
| `Peer::notify_typed(method, &T)`, `Peer::request_typed(method, &T)` | `Error::Serialize` for a value that is not JSON. |
| `Call::wait_typed::<T>()` | A result that does not fit is `CallError::InvalidResponse`. |
| `Responder::ok_typed(&T)` | See [`Responder`](#responder). |
| `Serialize`/`Deserialize` for `Id<'static>` and `ErrorCode` | An integer or a string; an integer. |

```rust
#[cfg(not(feature = "serde"))] fn main() {}
#[cfg(feature = "serde")] fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{Endpoint, Router};
    use serde::{Deserialize, Serialize};

    #[derive(Deserialize)]
    #[serde(rename_all = "camelCase")]
    struct HoverParams { text_document: Document, position: Position }
    #[derive(Deserialize)]
    struct Document { uri: String }
    #[derive(Deserialize, Serialize)]
    struct Position { line: u32, character: u32 }
    #[derive(Serialize)]
    struct Hover { contents: String }

    let router = Router::new().request_typed("textDocument/hover", |_: &mut (), p: HoverParams, _| {
        Ok(Hover { contents: format!("{} line {}", p.text_document.uri, p.position.line) })
    });
    let (tx, rx) = std::sync::mpsc::channel::<String>();
    let mut endpoint = Endpoint::new(tx, router, ());
    endpoint.handle(br#"{"jsonrpc":"2.0","id":1,"method":"textDocument/hover","params":{"textDocument":{"uri":"a.rs"},"position":{"line":3,"character":0}}}"#)?;
    assert_eq!(rx.try_recv().ok().as_deref(), Some(r#"{"jsonrpc":"2.0","id":1,"result":{"contents":"a.rs line 3"}}"#));

    let call = endpoint.peer().request_typed("cursor", &Position { line: 1, character: 2 })?;
    endpoint.handle(br#"{"jsonrpc":"2.0","id":1,"result":{"line":5,"character":6}}"#)?;
    assert_eq!(call.wait_typed::<Position>().map(|p| p.line), Ok(5));
    Ok(())
}
```

## The async adapter (`futures-io`)

Runtime-agnostic: `futures-io`'s `AsyncRead`/`AsyncWrite` are implemented by smol and async-std, and reached from tokio through `tokio-util`'s `compat`. Without the feature, the same loop is a few lines over `Endpoint::next_read` and `Outbox::poll_chunk`.

- `Endpoint::run_async(&mut self, input: impl AsyncRead + Unpin, framing) -> Result<End, Error>`: `run` for an async stream. Handlers run inside the future and must not block; answer slow requests from a deferred handler's worker.
- `Outbox::write_to(&mut self, writer: impl AsyncWrite + Unpin) -> io::Result<()>`: writes everything the outbox yields, flushing after each batch, until the endpoint closes. A writer failure fails the queue, which closes the endpoint.
- `Call` is a `Future` with or without the feature.

```rust
#[cfg(not(feature = "futures-io"))] fn main() {}
#[cfg(feature = "futures-io")] fn main() -> Result<(), rpc_io::Error> {
    use std::{future::Future, pin::pin, sync::Arc, task::{Context, Poll, Wake, Waker}};
    use rpc_io::{End, Endpoint, Framing, QueueLimits, Router};

    // Any executor will do; this one parks the thread between polls.
    fn block_on<F: Future>(future: F) -> F::Output {
        struct Unpark(std::thread::Thread);
        impl Wake for Unpark { fn wake(self: Arc<Self>) { self.0.unpark() } }
        let waker = Waker::from(Arc::new(Unpark(std::thread::current())));
        let mut future = pin!(future);
        loop {
            if let Poll::Ready(out) = future.as_mut().poll(&mut Context::from_waker(&waker)) {
                return out;
            }
            std::thread::park();
        }
    }

    let router = Router::new().request("ping", |_: &mut (), _, _| Ok("pong"));
    let (sink, mut outbox) = rpc_io::outbox(Framing::ContentLength, QueueLimits::new());
    let mut endpoint = Endpoint::new(sink, router, ());
    let input: &[u8] = b"Content-Length: 40\r\n\r\n{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"ping\"}";
    assert_eq!(block_on(endpoint.run_async(input, Framing::ContentLength))?, End::Eof);
    let mut output = Vec::new();
    block_on(outbox.write_to(&mut output)).map_err(rpc_io::Error::Io)?;
    assert!(output.ends_with(br#"{"jsonrpc":"2.0","id":1,"result":"pong"}"#));
    Ok(())
}
```

## `Framing`

`#[non_exhaustive]`: `ContentLength` (LSP's base protocol, and DAP's: `Content-Length: n\r\n\r\n` then `n` bytes; other headers ignored, names case-insensitive, bare `\n` accepted, names must be RFC 9110 tokens; blank lines between messages skipped and not counted against `max_header_bytes`) and `Newline` (MCP stdio, JSON Lines: one message per line, `\r` before `\n` dropped, blank lines skipped; every line, blank or not, counts against `max_message_bytes`). Either way the result does not depend on how the input was split into reads. DAP's messages are not JSON-RPC: the framing cuts them, the endpoint does not serve them.

- `encode(self, body: &[u8], out: &mut Vec<u8>)` appends one framed message. For `Newline`, `\r` and `\n` in the body become spaces: JSON can only hold them as whitespace, so the message means the same and stays on one line.
- `decoder(self, limits: &Limits) -> Decoder`.

`READ_CHUNK` (8 KiB) is the read size the decoder offers by default, and its read-ahead past a message.

```rust
use rpc_io::Framing;

let mut out = Vec::new();
Framing::Newline.encode(b"{\n  \"a\": 1\n}", &mut out);
assert_eq!(out, b"{   \"a\": 1 }\n");
```

## `Decoder`

Sans-IO. Bytes go in through `space` + `commit` (read straight into the buffer) or `feed` (copy); bodies come out of `next_frame` as slices of the buffer. It takes bytes only after `next_frame` returned `Ok(None)`, which keeps it bounded: at most `max(max_message_bytes + 1, max_header_bytes) + read_chunk` bytes (`memory_bound`), a body reserved as it arrives (never from the header's word alone, and geometrically, so a large message costs linear copying), an oversized message skipped as it arrives. Shrink policy: once a buffer of at least four read chunks needs at most a quarter of its size, it is cut down, so memory follows the current message, not the largest one seen.

| Method | Description |
|---|---|
| `new(framing, &limits)`, `framing()` | Construction. |
| `with_read_chunk(self, bytes)`, `read_chunk()` | The bytes offered per read (at least 1; `READ_CHUNK` by default). |
| `space(&mut self) -> &mut [u8]`, `commit(&mut self, n)` | Read into the buffer. `space` is empty until `next_frame` returns `Ok(None)`, and after a fatal error. |
| `feed(&mut self, bytes) -> usize` | Copies what it takes now. |
| `next_frame(&mut self) -> Result<Option<&[u8]>, FrameError>` | The next body; `Ok(None)` when more bytes are needed. |
| `finish(&mut self) -> Result<Option<&[u8]>, FrameError>` | At end of input: a last unterminated line, `Ok(None)` when clean, `Truncated` inside a Content-Length message. |
| `buffered()`, `capacity()`, `memory_bound()` | Bytes held; bytes allocated now; the most it can hold. |

```rust
fn main() -> Result<(), rpc_io::FrameError> {
    use std::io::Read;
    use rpc_io::{Framing, Limits};

    let mut input: &[u8] = b"Content-Length: 2\r\n\r\n{}Content-Length: 4\r\n\r\nnull";
    let mut decoder = Framing::ContentLength.decoder(&Limits::new());
    let mut bodies = Vec::new();
    loop {
        while let Some(body) = decoder.next_frame()? {
            bodies.push(body.to_vec());
        }
        let n = input.read(decoder.space()).unwrap_or(0);
        if n == 0 {
            break;
        }
        decoder.commit(n);
    }
    assert_eq!(decoder.finish()?, None);
    assert_eq!(bodies, [b"{}".to_vec(), b"null".to_vec()]);
    Ok(())
}
```

## `FrameError`

`#[non_exhaustive]`, `Copy`. `is_recoverable()` is true only for `TooLarge`; every other error is final and repeats.

| Variant | Meaning |
|---|---|
| `HeaderTooLarge { limit }` | A header section over `max_header_bytes`. |
| `TooManyHeaders { limit }` | More than `max_headers` lines. |
| `InvalidHeader` | A line that is not `name: value` with a token name (a body that ran into the headers). |
| `MissingContentLength` | No `Content-Length` in a section. |
| `DuplicateContentLength` | More than one, even if equal. |
| `InvalidContentLength` | Not a decimal integer that fits in 64 bits. |
| `TooLarge { length, limit }` | A message over `max_message_bytes`, skipped (recoverable). `length` is the announced Content-Length, and always `None` for newline framing (a line is refused as soon as it outgrows the limit, before its length is known). |
| `TooLargeToSkip { length, limit }` | An announced Content-Length over both `max_message_bytes` and `max_skip_bytes`: too large to read or to skip. |
| `Truncated` | The stream ended inside a Content-Length message. |

```rust
use rpc_io::{FrameError, Framing, Limits};

let mut d = Framing::ContentLength.decoder(&Limits::new().with_max_message_bytes(3));
d.feed(b"Content-Length: 5\r\n\r\nhelloContent-Length: 2\r\n\r\nok");
assert_eq!(d.next_frame(), Err(FrameError::TooLarge { length: Some(5), limit: 3 }));
assert_eq!(d.next_frame(), Ok(Some(&b"ok"[..])));
```

## `decode`

```rust,ignore
pub fn decode<'a>(body: &'a [u8], limits: &Limits) -> Incoming<'a>
```

Decodes one body: a single message or a batch, in one pass of `jsonx-lib`'s pull reader. The body is validated in full first, so a syntax error anywhere is one `PARSE_ERROR`, except in a batch refused early: over `max_batch` (refused as soon as it passes the limit, the rest unread) or while batches are off (refused at its `[`). Rules beyond the specification: `jsonrpc` must be exactly `"2.0"`; unknown members are ignored; a repeated envelope member makes the message invalid; request ids are strings or `i64` integers (any number or `null` with `Limits::lenient_ids`); an error response without `id` (MCP's form) is one under `null`; `"params": null` reads as absent; a message over a JSON budget is `INVALID_REQUEST`, under its id when the id and method were read first. `params`, `result`, and error `data` are slices of `body`.

```rust
use rpc_io::{decode, Incoming, Limits, Message};

let body = br#"{"jsonrpc": "2.0", "id": "a", "method": "add", "params": [2, 3]}"#;
let Incoming::Single(Ok(Message::Request(r))) = decode(body, &Limits::new()) else { panic!() };
assert_eq!(r.params.as_ref().map(|p| p.as_str()), Some("[2, 3]"));
```

## `Incoming` and `Entry`

`Entry<'a> = Result<Message<'a>, Invalid<'a>>`. `Incoming` is `Single(Entry)` or `Batch(Vec<Entry>)` (never empty).

```rust
use rpc_io::{decode, Incoming, Limits};

let Incoming::Batch(entries) = decode(br#"[{"jsonrpc":"2.0","method":"a"}, 7]"#, &Limits::new()) else { panic!() };
assert!(entries[0].is_ok());
assert!(entries[1].as_ref().is_err_and(|invalid| invalid.reply().is_some())); // answered with -32600
```

## `Message`

`Request(Request)`, `Notification(Notification)`, `Response(Response)`. Methods: `id()`, `method()`, `write(&self, out: &mut String)` (compact JSON), `into_owned()`; `Display` writes the JSON.

```rust
use rpc_io::{decode, Incoming, Limits, Message};

let body = br#"{"jsonrpc":"2.0","id":7,"method":"hover"}"#;
let Incoming::Single(Ok(message)) = decode(body, &Limits::new()) else { panic!() };
assert_eq!(message.method(), Some("hover"));
assert_eq!(message.id().and_then(|id| id.as_i64()), Some(7));
let owned: Message<'static> = message.into_owned();
assert_eq!(owned.to_string(), r#"{"jsonrpc":"2.0","id":7,"method":"hover"}"#);
```

## `Request`, `Notification`, `Response`

Structs with public fields: `Request { id: Id, method: Cow<str>, params: Option<Raw> }`, `Notification { method, params }`, `Response { id: Option<Id>, result: Result<Raw, ErrorObject> }` (`id: None` is `null`, only for errors). All three are `#[non_exhaustive]` (since 0.4.0), so a later version can keep more of the envelope without a break: read and change the fields freely, build with the constructors, and add `..` to struct patterns. Constructors: `Request::new(id, method, params)`, `Notification::new(method, params)`, `Response::new(id, result)`, `Response::ok(id, raw)`, `Response::err(id, error)`.

```rust
fn main() -> Result<(), rpc_io::jsonx::Error> {
    use rpc_io::{ErrorObject, Message, Raw, Response};

    let ok = Response::ok(4, Raw::new("true")?);
    assert_eq!(Message::Response(ok).to_string(), r#"{"jsonrpc":"2.0","id":4,"result":true}"#);
    let failed = Response::err(None, ErrorObject::parse_error("bad JSON"));
    assert_eq!(
        Message::Response(failed).to_string(),
        r#"{"jsonrpc":"2.0","id":null,"error":{"code":-32700,"message":"bad JSON"}}"#,
    );
    Ok(())
}
```

## `Invalid`

A body that is not a valid message. `id()` (the id to answer under, or the request a broken response meant), `is_response()` (a broken response: never answered), `error()` (`PARSE_ERROR` or `INVALID_REQUEST`), `reply()` (the response to send, `None` for a broken response), `into_owned()`.

```rust
use rpc_io::{decode, ErrorCode, Incoming, Limits};

let Incoming::Single(Err(invalid)) = decode(br#"{"jsonrpc":"2.0","id":9,"method":"m","params":5}"#, &Limits::new()) else { panic!() };
assert_eq!((invalid.id().and_then(|i| i.as_i64()), invalid.error().code()), (Some(9), ErrorCode::INVALID_REQUEST));
```

## `write_batch`

`write_batch(out: &mut String, messages: &[Message])` appends a JSON array of the messages (`[]` for none, which JSON-RPC forbids sending).

```rust
use rpc_io::{write_batch, Message, Notification};

let ping = Message::Notification(Notification::new("ping", None));
let mut out = String::new();
write_batch(&mut out, &[ping.clone(), ping]);
assert_eq!(out, r#"[{"jsonrpc":"2.0","method":"ping"},{"jsonrpc":"2.0","method":"ping"}]"#);
```

## `Id`

`Number(i64)`, `String(Cow<str>)`, and, read only with lenient ids (see [Ids](#ids)), `RawNumber(Cow<str>)` (any other JSON number, as its text) and `Null`. Exhaustive: those are every id JSON-RPC 2.0 allows. `Ord + Hash`; `as_i64()`, `as_str()`, `is_null()`, `raw_number(&str)` (a `RawNumber`, or a `Number` for an `i64` integer; `None` for text that is not one JSON number), `into_owned()`; `From` `i64`, `i32`, `u32`, `&str`, `String`, `Cow<str>`; `Display` writes the JSON form. With `serde`, `Serialize` (a `RawNumber` through `serde_json::Number`: exact within `u64`, else the nearest `f64`), and `Deserialize` for `Id<'static>` (integers and strings).

```rust
use rpc_io::Id;

assert_eq!(Id::from("a\"b").to_string(), r#""a\"b""#);
assert_eq!(Id::from(7).as_i64(), Some(7));
assert_eq!(Id::raw_number("1e3").map(|id| id.to_string()).as_deref(), Some("1e3"));
```

## `Raw`

One JSON value kept as its exact validated text. `NULL`; `new(&str)` and `new_with(&str, &Parser)` validate (trimming surrounding whitespace); `from_string(String)`; `from_value(&Value)`; `as_str()`; `kind()` (from the first byte); `parse()` and `parse_with(&Parser)`; `decode::<T>()` (a jsonx-lib `FromJson`, borrowing from the text; `jsonx::DecodeError`); `deserialize::<T>()` (`serde`); `into_owned()`. `ToJson` (the text as it is: a `Raw` from a message, `new`, `from_value`, or `Json::encode` holds a jsonx-lib `RawValue`, validated once, and is copied with no second scan; one wrapping `serde` output is validated on the way out) and `FromJson` (a value's source text, borrowed, unparsed).

```rust
fn main() -> Result<(), rpc_io::jsonx::Error> {
    let raw = rpc_io::Raw::new(r#" {"line": 3} "#)?;
    assert_eq!(raw.as_str(), r#"{"line": 3}"#);
    assert_eq!(raw.parse()?["line"], 3);
    Ok(())
}
```

## `Json`

A value to send: `Value(jsonx_lib::Value)` or `Raw(Raw)`. Everything that sends takes `impl Into<Json>`: a `json!` value, anything that converts into a `Value` (numbers, strings, booleans, `()` for `null`, `Vec`s, `Option`s), or a `Raw`. `kind()`, `into_owned()`, `Display`; `Json::serialize(&T)` with `serde`.

```rust
use rpc_io::Json;

assert_eq!(Json::from(rpc_io::jsonx::json!([1, 2])).to_string(), "[1,2]");
assert_eq!(Json::from(()).to_string(), "null");
```

## `ErrorCode`

`ErrorCode(pub i64)` with the constants in [Error codes](#error-codes); `name()` for those, `is_reserved()` for `-32768..=-32000`; `Display` as `"-32601 (method not found)"`. With `serde`, `Serialize` and `Deserialize` as the integer.

```rust
use rpc_io::ErrorCode;

assert_eq!(ErrorCode::METHOD_NOT_FOUND.to_string(), "-32601 (method not found)");
assert_eq!(ErrorCode(-32601), ErrorCode::METHOD_NOT_FOUND);
assert_eq!(ErrorCode(1001).name(), None);
assert!(ErrorCode::SERVER_OVERLOADED.is_reserved() && !ErrorCode(1).is_reserved());
```

## `ErrorObject`

The `error` member: `new(code, message)`, `with_data(impl Into<Json>)`, `parse_error`, `invalid_request`, `method_not_found(method)` (clipped to 128 bytes), `invalid_params`, `internal_error`, `code()`, `message()`, `data()`. `From<jsonx_lib::Error>` gives `INVALID_PARAMS`; `From<Error>` gives `INTERNAL_ERROR` (for `Error::Io`, only "the transport failed": the operating system's text stays on this side). A peer's error message is clipped to 4 KiB.

```rust
use rpc_io::{ErrorCode, ErrorObject};

let e = ErrorObject::new(ErrorCode(1001), "stale version").with_data(rpc_io::jsonx::json!({ "expected": 4 }));
assert_eq!(e.data().map(|d| d.as_str()), Some(r#"{"expected":4}"#));
assert_eq!(e.to_string(), "stale version (code 1001)");
```

## `Pending`

Outstanding requests by id (`no_std`). `new(capacity)`, `capacity()`, `len()`, `is_empty()`, `contains(id)`, `get(id)`, `issue(value, deadline) -> (id, evicted)`, `settle(id) -> Option<T>`, `pop_expired(now)`, `next_deadline()`, `drain()`. Ids start at 1 and count up; at capacity the oldest is evicted; each id settles at most once; deadlines are `Duration`s from an epoch the caller chooses. Every operation is `O(log n)`.

```rust
use std::time::Duration;
use rpc_io::Pending;

let mut pending = Pending::new(2);
let (a, _) = pending.issue("first", None);
let (b, _) = pending.issue("second", Some(Duration::from_secs(5)));
let (_, evicted) = pending.issue("third", None);
assert_eq!(evicted, Some((a, "first")));
assert_eq!(pending.pop_expired(Duration::from_secs(5)), Some((b, "second")));
```

## `Error`

`#[non_exhaustive]`: `Io(io::Error)` (the transport failed; closed), `Frame(FrameError)` (the input lost its framing; closed), `Closed`, `InvalidParams(Kind)` (outgoing params not an array, object, or null; nothing sent), `AlreadyAnswered` (a deferred request was answered or cancelled first; nothing sent), `Backlog` (the gate is shut and `max_held_bytes` is spent; nothing sent, the connection stays open), `Serialize(String)` (a value is not JSON: a non-finite progress number, or a typed send with `serde`; nothing sent). Implements `std::error::Error`.

```rust
use rpc_io::{Endpoint, Error, Router};

let (tx, _rx) = std::sync::mpsc::channel::<String>();
let mut endpoint = Endpoint::new(tx, Router::<()>::new(), ());
assert!(matches!(endpoint.peer().notify("x", 1), Err(Error::InvalidParams(_)))); // params must be structured
endpoint.close();
assert!(matches!(endpoint.peer().notify("x", ()), Err(Error::Closed)));
```

## `CallError`

`#[non_exhaustive]`, why one of our requests produced no result: `Rejected(ErrorObject)` (the peer's error), `InvalidResponse(ErrorObject)` (a broken answer, or one that does not fit `wait_typed`'s type), `TimedOut`, `Cancelled`, `Evicted` (over `max_pending`), `Closed`, `WouldDeadlock` (waited on the endpoint's own thread; the call, consumed by `wait`, is cancelled).

```rust
fn main() -> Result<(), rpc_io::Error> {
    use rpc_io::{CallError, Endpoint, Router};

    let (tx, _rx) = std::sync::mpsc::channel::<String>();
    let mut endpoint = Endpoint::new(tx, Router::<()>::new(), ());
    let call = endpoint.peer().request("x", ())?;
    endpoint.handle(br#"{"jsonrpc":"2.0","id":1,"error":{"code":1,"message":"no"}}"#)?;
    assert!(matches!(call.wait(), Err(CallError::Rejected(e)) if e.message() == "no"));
    Ok(())
}
```

## Feature flags

| Feature | Default | Effect |
|---|---|---|
| `std` | yes | The endpoint and everything it uses (`Endpoint`, `serve`, `Router`, handles, `Config`, `Sink`, `Framed`, `Queued`, `outbox`, `Progress`, `WorkDone`, `Notifier`, `Stats`, `Error`, `CallError`, and the typed handler methods); forwards to `jsonx-lib/std`. Without it, the crate is `no_std` + `alloc`: framing, the message model, `Pending`, `Raw::decode`, `Json::encode`, and the `ToJson`/`FromJson` impls for the crate's values. |
| `serde` | no | Typed params and results (above); adds `serde` and `serde_json`. |
| `futures-io` | no | The async adapter (above); adds `futures-io`. |
| `tracing` | no | A debug span per call (method and id) and events for what the endpoint does on its own, under the `rpc_io` target. Records methods, ids, sizes, error codes and messages, and panic messages; never `params`, results, or error `data` as such. Peer-chosen text is clipped and escaped (`Debug`), and an error message that quotes the peer's input (a `serde` error) is clipped to 256 bytes. Adds `tracing`. Off, the instrumentation compiles to nothing. |
| `net` | no | `Server`, `Stopper`, `Connection`; `std` only. |