Skip to main content

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}