rpc_io/config.rs
1//! [`Config`]: how an endpoint behaves, with [`Gate`] and [`Cancellation`].
2
3use std::{borrow::Cow, time::Duration};
4
5use crate::{error_object::ErrorCode, limits::Limits};
6
7/// An endpoint's settings.
8///
9/// | Setting | Default | Meaning |
10/// |---|---|---|
11/// | `limits` | [`Limits::new`] | budgets on incoming messages |
12/// | `max_pending` | 1024 | our requests awaiting answers; one more evicts the oldest |
13/// | `max_in_flight` | 1024 | deferred requests being answered; more are refused with `overloaded_code` |
14/// | `max_held_bytes` | 4 MiB | messages this side sends while the gate is shut, held until it opens |
15/// | `max_batch_bytes` | 16 MiB | answers held until the rest of their batch is answered, over all open batches |
16/// | `request_timeout` | none | deadline for our requests that set none themselves |
17/// | `cancellation` | [`Cancellation::lsp`] | the cancel notification, both ways; `None` turns cancellation off |
18/// | `gate` | none | an opening request every other request must wait for |
19/// | `timer` | `true` | deadlines fire on their own, from a helper thread |
20/// | `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) |
21/// | `overloaded_code` | `SERVER_OVERLOADED` (`-32000`) | the code of the refusal past `max_in_flight` |
22///
23/// `#[non_exhaustive]`: start from [`Config::new`] and chain `with_*`.
24///
25/// # Examples
26///
27/// ```
28/// use std::time::Duration;
29/// use rpc_io::{Cancellation, Config, Gate};
30///
31/// let lsp = Config::new()
32/// .with_gate(Some(Gate::new("initialize").allow("exit")))
33/// .with_request_timeout(Some(Duration::from_secs(30)));
34/// let mcp = Config::new().with_cancellation(Some(Cancellation::mcp()));
35/// assert_eq!(lsp.max_pending, 1024);
36/// assert_eq!(mcp.cancellation.map(|c| c.id_member), Some("requestId".into()));
37/// ```
38#[derive(Clone, Debug, PartialEq, Eq)]
39#[non_exhaustive]
40pub struct Config {
41 /// Budgets on incoming messages.
42 pub limits: Limits,
43 /// Most of our requests awaiting an answer at once (at least one).
44 pub max_pending: usize,
45 /// Most deferred requests being answered at once.
46 pub max_in_flight: usize,
47 /// Most bytes of messages held back while the [`Gate`] is shut. A send
48 /// past it fails with [`Error::Backlog`](crate::Error::Backlog) and is
49 /// not held.
50 pub max_held_bytes: usize,
51 /// Most bytes of answers held for open batches. A batch is answered as
52 /// one array, so the answers to its other members wait while one of
53 /// them is deferred. An answer that would take the held bytes past this
54 /// is replaced by a short `overloaded_code` error under its id. A new
55 /// batch that arrives while the budget is spent, or while a batch with
56 /// such a replaced answer is still open, is refused whole with one
57 /// `overloaded_code` error under `null`, unhandled. So the held answers
58 /// stay within this budget plus one short error per member of a batch.
59 pub max_batch_bytes: usize,
60 /// The deadline for our requests that do not set their own.
61 pub request_timeout: Option<Duration>,
62 /// How cancellation is spelled, or `None` for none.
63 pub cancellation: Option<Cancellation>,
64 /// The opening request, if the protocol has one.
65 pub gate: Option<Gate>,
66 /// Whether our requests' deadlines fire on their own. On (the default),
67 /// the first request with a deadline starts a timer thread for the
68 /// connection, which ends each due request with
69 /// [`CallError::TimedOut`](crate::CallError::TimedOut) and sends the
70 /// peer the cancel notification even while nothing arrives; it sleeps
71 /// between deadlines and stops when the connection closes. Off, a
72 /// deadline is enforced only when it is next looked at: when the endpoint
73 /// handles a message, at the next request, in
74 /// [`Call::wait`](crate::Call::wait) and
75 /// [`try_wait`](crate::Call::try_wait), when an awaited `Call` is polled,
76 /// or by [`Endpoint::expire`](crate::Endpoint::expire).
77 pub timer: bool,
78 /// Whether an error answering a message whose id could not be read
79 /// leaves `id` out (`true`, as MCP's schema has it: `id?: RequestId`,
80 /// never `null`) or writes `"id": null` (`false`, as JSON-RPC 2.0
81 /// requires). Either form from the peer is read as the same answer.
82 pub omit_null_id: bool,
83 /// The error code a request past `max_in_flight` is refused with.
84 pub overloaded_code: ErrorCode,
85}
86
87impl Config {
88 /// The defaults in the table above.
89 ///
90 /// # Examples
91 ///
92 /// ```
93 /// assert!(rpc_io::Config::new().gate.is_none());
94 /// ```
95 #[must_use]
96 pub fn new() -> Self {
97 Self {
98 limits: Limits::new(),
99 max_pending: 1024,
100 max_in_flight: 1024,
101 max_held_bytes: 4 * 1024 * 1024,
102 max_batch_bytes: 16 * 1024 * 1024,
103 request_timeout: None,
104 cancellation: Some(Cancellation::lsp()),
105 gate: None,
106 timer: true,
107 omit_null_id: false,
108 overloaded_code: ErrorCode::SERVER_OVERLOADED,
109 }
110 }
111
112 /// Sets `limits`.
113 ///
114 /// # Examples
115 ///
116 /// ```
117 /// use rpc_io::{Config, Limits};
118 ///
119 /// let c = Config::new().with_limits(Limits::new().with_max_batch(4));
120 /// assert_eq!(c.limits.max_batch, 4);
121 /// ```
122 #[must_use]
123 pub fn with_limits(mut self, limits: Limits) -> Self {
124 self.limits = limits;
125 self
126 }
127
128 /// Sets `max_pending`.
129 ///
130 /// # Examples
131 ///
132 /// ```
133 /// assert_eq!(rpc_io::Config::new().with_max_pending(8).max_pending, 8);
134 /// ```
135 #[must_use]
136 pub fn with_max_pending(mut self, count: usize) -> Self {
137 self.max_pending = count;
138 self
139 }
140
141 /// Sets `max_in_flight`.
142 ///
143 /// # Examples
144 ///
145 /// ```
146 /// assert_eq!(rpc_io::Config::new().with_max_in_flight(8).max_in_flight, 8);
147 /// ```
148 #[must_use]
149 pub fn with_max_in_flight(mut self, count: usize) -> Self {
150 self.max_in_flight = count;
151 self
152 }
153
154 /// Sets `max_batch_bytes`.
155 ///
156 /// # Examples
157 ///
158 /// ```
159 /// assert_eq!(rpc_io::Config::new().with_max_batch_bytes(1 << 20).max_batch_bytes, 1 << 20);
160 /// ```
161 #[must_use]
162 pub fn with_max_batch_bytes(mut self, bytes: usize) -> Self {
163 self.max_batch_bytes = bytes;
164 self
165 }
166
167 /// Sets `max_held_bytes`.
168 ///
169 /// # Examples
170 ///
171 /// ```
172 /// assert_eq!(rpc_io::Config::new().with_max_held_bytes(1 << 10).max_held_bytes, 1 << 10);
173 /// ```
174 #[must_use]
175 pub fn with_max_held_bytes(mut self, bytes: usize) -> Self {
176 self.max_held_bytes = bytes;
177 self
178 }
179
180 /// Sets `request_timeout`.
181 ///
182 /// # Examples
183 ///
184 /// ```
185 /// use std::time::Duration;
186 ///
187 /// let c = rpc_io::Config::new().with_request_timeout(Some(Duration::from_secs(5)));
188 /// assert_eq!(c.request_timeout, Some(Duration::from_secs(5)));
189 /// ```
190 #[must_use]
191 pub fn with_request_timeout(mut self, timeout: Option<Duration>) -> Self {
192 self.request_timeout = timeout;
193 self
194 }
195
196 /// Sets `cancellation`.
197 ///
198 /// # Examples
199 ///
200 /// ```
201 /// assert!(rpc_io::Config::new().with_cancellation(None).cancellation.is_none());
202 /// ```
203 #[must_use]
204 pub fn with_cancellation(mut self, cancellation: Option<Cancellation>) -> Self {
205 self.cancellation = cancellation;
206 self
207 }
208
209 /// Sets `gate`.
210 ///
211 /// # Examples
212 ///
213 /// ```
214 /// use rpc_io::{Config, Gate};
215 ///
216 /// let c = Config::new().with_gate(Some(Gate::new("initialize")));
217 /// assert_eq!(c.gate.map(|g| g.method), Some("initialize".into()));
218 /// ```
219 #[must_use]
220 pub fn with_gate(mut self, gate: Option<Gate>) -> Self {
221 self.gate = gate;
222 self
223 }
224
225 /// Sets `timer`.
226 ///
227 /// # Examples
228 ///
229 /// ```
230 /// assert!(!rpc_io::Config::new().with_timer(false).timer);
231 /// ```
232 #[must_use]
233 pub fn with_timer(mut self, timer: bool) -> Self {
234 self.timer = timer;
235 self
236 }
237
238 /// Sets `omit_null_id`: whether an error for a message whose id could
239 /// not be read leaves `id` out instead of writing `"id": null`.
240 ///
241 /// # Examples
242 ///
243 /// ```
244 /// use rpc_io::{Config, Endpoint, Router};
245 ///
246 /// let (tx, rx) = std::sync::mpsc::channel::<String>();
247 /// let config = Config::new().with_omit_null_id(true);
248 /// Endpoint::new(tx, Router::<()>::new(), ()).with_config(config).handle(b"{")?;
249 /// let reply = rx.try_recv().unwrap_or_default();
250 /// assert!(reply.starts_with(r#"{"jsonrpc":"2.0","error":{"code":-32700"#), "{reply}");
251 /// # Ok::<(), rpc_io::Error>(())
252 /// ```
253 #[must_use]
254 pub fn with_omit_null_id(mut self, omit: bool) -> Self {
255 self.omit_null_id = omit;
256 self
257 }
258
259 /// Sets `overloaded_code`, the code of the refusal past
260 /// `max_in_flight`.
261 ///
262 /// # Examples
263 ///
264 /// ```
265 /// use rpc_io::{Config, ErrorCode};
266 ///
267 /// let config = Config::new().with_overloaded_code(ErrorCode::INTERNAL_ERROR);
268 /// assert_eq!(config.overloaded_code, ErrorCode::INTERNAL_ERROR);
269 /// ```
270 #[must_use]
271 pub fn with_overloaded_code(mut self, code: ErrorCode) -> Self {
272 self.overloaded_code = code;
273 self
274 }
275}
276
277impl Config {
278 /// An LSP server: [`Limits::lsp`] (batches off), [`Cancellation::lsp`], and
279 /// [`Gate::lsp`]. A client leaves the gate out (`with_gate(None)`): the
280 /// gate belongs on the side that receives `initialize`.
281 ///
282 /// # Examples
283 ///
284 /// ```
285 /// let config = rpc_io::Config::lsp();
286 /// assert_eq!(config.gate.map(|g| g.method), Some("initialize".into()));
287 /// assert_eq!(config.cancellation.map(|c| c.method), Some("$/cancelRequest".into()));
288 /// ```
289 #[must_use]
290 pub fn lsp() -> Self {
291 Self::new()
292 .with_limits(Limits::lsp())
293 .with_cancellation(Some(Cancellation::lsp()))
294 .with_gate(Some(Gate::lsp()))
295 }
296
297 /// MCP as its current revision (2026-07-28) has it, for a server or a
298 /// client: [`Limits::mcp`] (batches off), [`Cancellation::mcp`], and no
299 /// gate. The protocol is stateless: every request carries its protocol
300 /// version in `_meta`, and there is no `initialize` to wait for. Errors
301 /// for unreadable messages are written without `id` (MCP's schema has
302 /// no `null` id), and requests past `max_in_flight` are refused with
303 /// `INTERNAL_ERROR` (`-32603`), since MCP asks new implementations not to
304 /// use `-32000..=-32019`.
305 ///
306 /// This is also the preset of a dual-era server (one that serves legacy
307 /// clients too): the specification has such a server pick each
308 /// request's semantics from the request itself (an `initialize` selects
309 /// the legacy ones), which belongs to the protocol layer above. A server
310 /// for legacy clients only takes [`Config::mcp_legacy`].
311 ///
312 /// # Examples
313 ///
314 /// ```
315 /// use rpc_io::{Config, ErrorCode};
316 ///
317 /// let config = Config::mcp();
318 /// assert_eq!(config.limits.max_batch, 0);
319 /// assert!(config.gate.is_none());
320 /// assert!(config.omit_null_id);
321 /// assert_eq!(config.overloaded_code, ErrorCode::INTERNAL_ERROR);
322 /// assert_eq!(config.cancellation.map(|c| c.id_member), Some("requestId".into()));
323 /// ```
324 #[must_use]
325 pub fn mcp() -> Self {
326 Self::new()
327 .with_limits(Limits::mcp())
328 .with_cancellation(Some(Cancellation::mcp()))
329 .with_omit_null_id(true)
330 .with_overloaded_code(ErrorCode::INTERNAL_ERROR)
331 }
332
333 /// A server for MCP's legacy revisions only (2025-11-25 and earlier),
334 /// which open with an `initialize` handshake: [`Config::mcp`] plus
335 /// [`Gate::mcp`]. Modern clients never send `initialize`, so this
336 /// preset refuses every request of theirs: use it only where no modern
337 /// client can connect. A client leaves the gate out (`with_gate(None)`).
338 ///
339 /// # Examples
340 ///
341 /// ```
342 /// let config = rpc_io::Config::mcp_legacy();
343 /// assert_eq!(config.gate.map(|g| g.method), Some("initialize".into()));
344 /// assert!(config.omit_null_id);
345 /// ```
346 #[must_use]
347 pub fn mcp_legacy() -> Self {
348 Self::mcp().with_gate(Some(Gate::mcp()))
349 }
350}
351
352impl Default for Config {
353 fn default() -> Self {
354 Self::new()
355 }
356}
357
358/// How a protocol spells request cancellation: a notification naming the id
359/// of the request to cancel.
360///
361/// Both directions use it. When the peer sends it for one of our deferred
362/// requests, the request's [`CancelToken`](crate::CancelToken) is set and, if
363/// `reply` is set, the request is answered at once with that error code (LSP:
364/// a cancelled request still gets exactly one response); with `reply: None`
365/// it gets no response at all (MCP: the receiver "SHOULD NOT send a response
366/// for the cancelled request"), and a reply the handler sends later is
367/// dropped. When one of our requests times out, is evicted, or is cancelled,
368/// the peer is sent this notification.
369///
370/// The cancel notification is consumed by the endpoint; it never reaches the
371/// [`Router`](crate::Router).
372///
373/// # Examples
374///
375/// ```
376/// use rpc_io::{Cancellation, ErrorCode};
377///
378/// let lsp = Cancellation::lsp();
379/// assert_eq!((lsp.method.as_ref(), lsp.id_member.as_ref()), ("$/cancelRequest", "id"));
380/// assert_eq!(lsp.reply, Some(ErrorCode::REQUEST_CANCELLED));
381///
382/// // A service API of your own: `$/cancel {id}`, answered with error 1005.
383/// let custom = Cancellation::new("$/cancel", "id", Some(ErrorCode(1005)));
384/// assert_eq!(custom.reply, Some(ErrorCode(1005)));
385/// ```
386#[derive(Clone, Debug, PartialEq, Eq, Hash)]
387#[non_exhaustive]
388pub struct Cancellation {
389 /// The notification's method.
390 pub method: Cow<'static, str>,
391 /// The `params` member holding the request id.
392 pub id_member: Cow<'static, str>,
393 /// The error code a cancelled request is answered with, or `None` to send
394 /// no response.
395 pub reply: Option<ErrorCode>,
396}
397
398impl Cancellation {
399 /// A cancellation spelled `method {id_member: <id>}`.
400 ///
401 /// # Examples
402 ///
403 /// ```
404 /// let c = rpc_io::Cancellation::new("cancel", "target", None);
405 /// assert_eq!(c.id_member, "target");
406 /// ```
407 #[must_use]
408 pub fn new(
409 method: impl Into<Cow<'static, str>>,
410 id_member: impl Into<Cow<'static, str>>,
411 reply: Option<ErrorCode>,
412 ) -> Self {
413 Self {
414 method: method.into(),
415 id_member: id_member.into(),
416 reply,
417 }
418 }
419
420 /// LSP: `$/cancelRequest {id}`, answered with `RequestCancelled`
421 /// (`-32800`).
422 ///
423 /// # Examples
424 ///
425 /// ```
426 /// assert_eq!(rpc_io::Cancellation::lsp().method, "$/cancelRequest");
427 /// ```
428 #[must_use]
429 pub fn lsp() -> Self {
430 Self::new("$/cancelRequest", "id", Some(ErrorCode::REQUEST_CANCELLED))
431 }
432
433 /// MCP: `notifications/cancelled {requestId}`, and no response for the
434 /// cancelled request.
435 ///
436 /// # Examples
437 ///
438 /// ```
439 /// assert_eq!(rpc_io::Cancellation::mcp().reply, None);
440 /// ```
441 #[must_use]
442 pub fn mcp() -> Self {
443 Self::new("notifications/cancelled", "requestId", None)
444 }
445}
446
447/// An opening request that must succeed before anything else is served (LSP's
448/// `initialize`, MCP's `initialize`, a service's own `auth`).
449///
450/// Until the opening request has been answered successfully:
451///
452/// - other requests are answered with `code` (default
453/// [`SERVER_NOT_INITIALIZED`](ErrorCode::SERVER_NOT_INITIALIZED)), except
454/// the methods in `allow_requests` (MCP's `ping`);
455/// - notifications are dropped (reported as [`Event::Dropped`](crate::Event)),
456/// except the methods in `allow` (LSP's `exit`);
457/// - everything this side sends other than responses (notifications and
458/// requests, from handlers or other threads) is held back, then sent in
459/// order right after the opening response; if the opening request fails,
460/// what was held is discarded and held requests end with
461/// [`CallError::Cancelled`](crate::CallError::Cancelled). A held request
462/// that times out or is cancelled is simply never sent, and an "answer" to
463/// one is treated as unmatched: the peer has never seen it.
464///
465/// The opening request fails when it is answered with an error, and also when
466/// the peer cancels it under a [`Cancellation`] that sends no reply; the gate
467/// then shuts again and a new opening request is served. Afterwards (once it
468/// succeeded) a repeated opening request is answered with `INVALID_REQUEST`,
469/// as is an opening request inside a batch. A gate belongs on the side that
470/// receives the opening request; on the side that sends it, it would hold that
471/// side's own messages forever.
472///
473/// Held messages are bounded by [`Config::max_held_bytes`]: a send that would
474/// take them past it fails with [`Error::Backlog`](crate::Error::Backlog)
475/// (and a request that fails so is not outstanding). Held requests also count
476/// against [`Config::max_pending`].
477///
478/// # Examples
479///
480/// ```
481/// use rpc_io::{ErrorCode, Gate};
482///
483/// let gate = Gate::new("initialize").allow("exit");
484/// assert_eq!(gate.code, ErrorCode::SERVER_NOT_INITIALIZED);
485/// assert_eq!(gate.allow, ["exit"]);
486/// ```
487#[derive(Clone, Debug, PartialEq, Eq, Hash)]
488#[non_exhaustive]
489pub struct Gate {
490 /// The opening request's method.
491 pub method: Cow<'static, str>,
492 /// The error code for requests that arrive before the gate opens.
493 pub code: ErrorCode,
494 /// Notifications delivered even before the gate opens.
495 pub allow: Vec<Cow<'static, str>>,
496 /// Requests served even before the gate opens (MCP's `ping`).
497 pub allow_requests: Vec<Cow<'static, str>>,
498}
499
500impl Gate {
501 /// A gate opened by a successful `method` request.
502 ///
503 /// # Examples
504 ///
505 /// ```
506 /// assert!(rpc_io::Gate::new("auth").allow.is_empty());
507 /// ```
508 #[must_use]
509 pub fn new(method: impl Into<Cow<'static, str>>) -> Self {
510 Self {
511 method: method.into(),
512 code: ErrorCode::SERVER_NOT_INITIALIZED,
513 allow: Vec::new(),
514 allow_requests: Vec::new(),
515 }
516 }
517
518 /// LSP's: `initialize`, with `exit` let through (a client may end a
519 /// server it never initialized).
520 ///
521 /// # Examples
522 ///
523 /// ```
524 /// assert_eq!(rpc_io::Gate::lsp().allow, ["exit"]);
525 /// ```
526 #[must_use]
527 pub fn lsp() -> Self {
528 Self::new("initialize").allow("exit")
529 }
530
531 /// MCP's legacy handshake (revisions 2025-11-25 and earlier; the
532 /// 2026-07-28 revision has none): `initialize`, with the `ping` request
533 /// served before it (those revisions allow pings at any time), and
534 /// early requests refused with `INVALID_REQUEST` (`-32600`). Not
535 /// `SERVER_NOT_INITIALIZED`: MCP used `-32002` for "resource not found"
536 /// in those revisions and forbids emitting it since.
537 ///
538 /// # Examples
539 ///
540 /// ```
541 /// use rpc_io::{ErrorCode, Gate};
542 ///
543 /// assert_eq!(Gate::mcp().allow_requests, ["ping"]);
544 /// assert_eq!(Gate::mcp().code, ErrorCode::INVALID_REQUEST);
545 /// ```
546 #[must_use]
547 pub fn mcp() -> Self {
548 Self::new("initialize")
549 .allow_request("ping")
550 .with_code(ErrorCode::INVALID_REQUEST)
551 }
552
553 /// Serves the request `method` before the gate opens.
554 ///
555 /// # Examples
556 ///
557 /// ```
558 /// let gate = rpc_io::Gate::new("auth").allow_request("version");
559 /// assert_eq!(gate.allow_requests, ["version"]);
560 /// ```
561 #[must_use]
562 pub fn allow_request(mut self, method: impl Into<Cow<'static, str>>) -> Self {
563 self.allow_requests.push(method.into());
564 self
565 }
566
567 /// Whether the request `method` is served before the gate opens.
568 pub(crate) fn allows_request(&self, method: &str) -> bool {
569 self.allow_requests.iter().any(|m| m == method)
570 }
571
572 /// Lets the notification `method` through before the gate opens.
573 ///
574 /// # Examples
575 ///
576 /// ```
577 /// let gate = rpc_io::Gate::new("initialize").allow("exit").allow("$/logTrace");
578 /// assert_eq!(gate.allow.len(), 2);
579 /// ```
580 #[must_use]
581 pub fn allow(mut self, method: impl Into<Cow<'static, str>>) -> Self {
582 self.allow.push(method.into());
583 self
584 }
585
586 /// Sets the error code for requests before the gate opens.
587 ///
588 /// # Examples
589 ///
590 /// ```
591 /// use rpc_io::{ErrorCode, Gate};
592 ///
593 /// assert_eq!(Gate::new("auth").with_code(ErrorCode(1010)).code, ErrorCode(1010));
594 /// ```
595 #[must_use]
596 pub fn with_code(mut self, code: ErrorCode) -> Self {
597 self.code = code;
598 self
599 }
600
601 /// Whether the notification `method` passes before the gate opens.
602 pub(crate) fn allows(&self, method: &str) -> bool {
603 self.allow.iter().any(|m| m == method)
604 }
605}