Expand description
§weavatrix-lsp-client
weavatrix-lsp-client is a protocol-neutral, standard-library threaded request
engine for a language server running as a child process. It layers directly on
weavatrix-lsp-wire and stays below any
crate that knows concrete LSP method types.
There is no Tokio, no futures, and no async runtime: one reader thread, one
writer thread, one stderr thread, one supervisor, and std channels and locks.
Memory, time, concurrency, and process behavior are part of the public
contract, not internal tuning.
§Guarantees
- Dual-bounded outbound queue. Every lane is bounded by message count and
by retained body bytes at the same time. Overflow returns a typed
SubmitError; the engine never silently drops an accepted message and never lets a queue grow past its bound. Bodies are encoded at submission, so backpressure reaches the caller instead of accumulating behind a slow child. The charge is the whole allocation a body retains, not just its encoded length: the bounded JSON-RPC writer grows geometrically and does not shrink, so charging length alone would bound the wrong number and leave resident memory at up to twice the configured budget. - Reserved control lane. Shutdown, exit, and cancellation traffic use a separate lane with its own bounds and strict priority in the writer, so ordinary request backlog can never starve them.
- Capped pending requests with real deadlines. Every request carries a
monotonic deadline that starts at submission and is clamped to
REQUEST_TIMEOUT_CEILING, whether it comes fromClientLimitsor from a per-call override. An elapsed deadline completes the request withRequestError::Timeoutand installs a tombstone. A request the writer has already sent gets exactly one cancellation notification; one still sitting in the queue is retracted instead, because the reserved lane’s strict priority would otherwise deliver the cancellation before the request it cancels. - Tombstoned late replies. A response that arrives after its deadline is
recognised by the bounded tombstone set, counted in
MetricsSnapshot::late_responses, and discarded. It can neither be mistaken for a live request nor leak the identifier. - Exactly-once completion. A request completes only for the thread that removes its slot from the pending table under the table lock. The reader, the deadline sweep, and an explicit cancel all race through that one removal, so a deadline firing while a response is being decoded still yields exactly one outcome.
- Bounded inbound queue. Server-initiated requests and notifications land
in a queue bounded by items and by
JsonRpcMessage::retained_payload_bytes. Overflow applies transport-level backpressure: the reader blocks inside the framing callback, which stops draining the child’s stdout and lets the OS pipe absorb the excess. - Bounded stderr. A dedicated thread drains the child’s stderr into a ring
buffer allocated once at
max_stderr_bytesand never grown: eviction happens before each append, so the allocation figure matches the documented bound instead of settling at the next power of two above it. A flood evicts old bytes, is counted, and never blocks request traffic.Session::stderr_tailandShutdownReport::stderr_taileach return an owned copy of the retained window, which is the caller’s memory, not the engine’s. - Owned process tree. Graceful shutdown sends the shutdown request, waits,
sends the exit notification, closes stdin, and waits again — then ends the
whole tree, on both the graceful and the forced path, before joining the
engine threads. Grandchildren are covered: a descendant that inherited the
child’s stdout or stderr keeps those pipes open after the server itself
exits, so the tree has to go first or the reader would block on an EOF that
never comes. Windows uses a job object with
JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE; Unix uses a dedicated process group. Both run fromDrop, so an unwinding panic still tears the tree down — but the two are not equivalent as a last resort, and the difference is stated rather than smoothed over. The Windows job is kernel-enforced: the tree dies when the last handle closes, including when the client is killed outright, aborts, or panics while already panicking. A POSIX process group has no equivalent, so on Unix the guarantee reaches exactly as far asDropdoes; aSIGKILLed client or apanic = "abort"profile leaves the tree resident. - No resynchronisation after corruption. A framing error or truncated EOF from the child poisons the wire decoder, which is terminal for the session. The client reports it and tears down rather than guessing a resume point.
§Usage
use std::time::Duration;
use weavatrix_lsp_client::{ChildConfig, ClientLimits, Response, Session};
let limits = ClientLimits::default()
.with_max_pending_requests(64)?
.with_request_timeout(Duration::from_secs(10))?;
let config = ChildConfig::new("my-language-server").arg("--stdio");
let session = Session::spawn(&config, limits)?;
// Build params through the codec: wire types do not implement `Serialize`.
let params = session.codec().value_from_string("{}".to_owned())?;
let pending = session.request("initialize", Some(params.try_into().unwrap()))?;
match pending.wait()? {
Response::Success(result) => println!("initialize: {}", result.as_str()),
Response::Failure(error) => eprintln!("server error {}: {}", error.code, error.message),
}
let report = session.shutdown();
assert!(report.graceful || report.forced);§Limits
Every bound lives in one ClientLimits value with a conservative default and
an absolute compiled-in ceiling that no configuration can exceed.
| Field | Default | Ceiling | Bounds |
|---|---|---|---|
max_outbound_messages | 256 | 65 536 | Ordinary lane item count |
max_outbound_bytes | 8 MiB | 256 MiB | Ordinary lane retained body bytes |
max_control_messages | 32 | 4 096 | Reserved lane item count |
max_control_bytes | 1 MiB | 64 MiB | Reserved lane retained body bytes |
max_inbound_messages | 256 | 65 536 | Server-initiated item count |
max_inbound_bytes | 8 MiB | 256 MiB | Server-initiated retained payload bytes |
max_pending_requests | 128 | 16 384 | Requests awaiting a response |
max_tombstones | 256 | 65 536 | Retained late-response tombstones |
max_stderr_bytes | 64 KiB | 4 MiB | Child stderr ring buffer |
wedge_timeout_streak | 3 | 1 024 | Consecutive deadlines that end a session |
request_timeout | 30 s | 1 h | Per-request deadline from submission |
shutdown_grace | 5 s | 5 min | Wait before the forced tree kill |
wire | Limits::default() | 256 MiB | Header, line, field, body, outbound bytes |
with_wire is fallible like every other setter: its two allocating fields,
max_body_bytes and max_outbound_bytes, are checked against
WIRE_BYTES_CEILING. weavatrix_lsp_wire::Limits itself enforces minimums but
no maximum, so an infallible setter here would be the one field able to disarm
every inbound allocation bound above it.
Three allocations are additive to the queue budgets and are stated here rather than implied:
- Decoding one frame. While a frame is decoded synchronously inside the
wire callback, frame body plus decoded payload text is at most
2 * wire.max_body_bytes(). - One oversized inbound message. A server-initiated message larger than the
whole inbound byte budget is admitted alone rather than deadlocking the
stream, so the inbound queue’s real high-water mark is
max(max_inbound_bytes, wire.max_body_bytes). The overshoot is capped at one message: the next push blocks. - Retained response payloads. A response completes its request handle
instead of entering the inbound queue, so it is not charged to
max_inbound_bytes. The payload stays resident in the handle until the handle is dropped, bounding retained response bytes atmax_pending_requests * wire.max_body_bytes— 2 GiB at the defaults. Lower either field to lower that product.
§Deliberate decisions
The architecture document bounds the queues but does not fix every disposition. These are the choices this crate makes, and they are public contract:
- Inbound overflow blocks the reader rather than dropping or coalescing.
- Deadlines start at submission and use
Instant; time behind a full outbound queue counts. A per-call timeout is clamped toREQUEST_TIMEOUT_CEILING. - The deadline wins any race it reaches first; the tombstone makes that observable rather than silent.
- A timeout or cancel that catches its own request still queued retracts the
body and sends nothing, counted as
unsent_requests_discarded. A cancellation the reserved lane cannot accept is counted ascancellations_droppedrather than being silently lost. - A response arriving after its deadline clears the wedge streak: it is late, but it is still evidence the child is answering.
- Tombstones are bounded by count with FIFO eviction. A reply whose tombstone
was already evicted is counted as
unmatched_responses, not as an error. - Identifiers are
i32, allocated by the client, wrapping ati32::MAXand skipping anything still pending or tombstoned. - Dropping a
PendingRequestdoes not cancel it; the deadline still applies. - A panic in any engine thread terminates the session and fails every pending request, so exactly-once completion holds under panic.
§Unsafe
The workspace forbids unsafe. This crate downgrades that to
#![deny(unsafe_code)] because owned process-tree termination requires the
Win32 job-object and POSIX kill(2) contracts. Every unsafe block lives in
src/process/windows.rs or src/process/unix.rs, each carries its own
narrowly scoped #[allow(unsafe_code)], and each states its safety argument
against the platform contract. No other module may use unsafe.
§Conformance harness
The crate ships a weavatrix-lsp-fake-server binary that can be driven into
each pathology the integration tests need: correct, fragmented, and coalesced
frames, delayed and out-of-order replies, server-initiated traffic, JSON-RPC
error responses, stderr floods, notification floods, a child that never reads
its stdin, hangs, early exit, oversized frames, malformed framing, an ignored
shutdown, and a long-lived grandchild that inherits the client’s stdio. Unit
tests alone do not establish subprocess or process-tree conformance, so the
suite drives a real child on every supported platform.
The grandchild modes inherit the child’s stdout and stderr on purpose. That is
what a real language server’s helper process does, and it is what makes the
tests deterministic: both exit paths join the reader and stderr threads, each of
which returns only on EOF, so a completed shutdown or kill is itself proof
that every descendant holding those pipes was terminated. No test in the suite
uses a fixed sleep as synchronisation.
§Performance
Pending. No benchmark has been run for this crate and no numbers are claimed. A
competitor harness comparable to the one recorded for weavatrix-lsp-wire will
be added separately and measured on a quiet machine.
Re-exports§
pub use weavatrix_lsp_wire as wire;
Structs§
- Child
Config - The child command plus the three base-protocol method names the engine emits on its own behalf.
- Client
Limits - Every bound the client engine enforces, in one validated value.
- Metrics
Snapshot - A consistent-per-field snapshot of engine counters and queue occupancy.
- Pending
Request - A submitted request that has not yet produced its single outcome.
- Session
- One owned language-server subprocess and its bounded request engine.
- Shutdown
Report - What a completed shutdown observed.
Enums§
- Client
Limits Error - An invalid
crate::ClientLimitsconfiguration. - Inbound
- One server-initiated message delivered to the caller.
- Recv
Error - Receiving server-initiated traffic failed.
- Request
Error - A submitted request did not complete with a server response.
- Response
- The server’s answer to one client request.
- Session
Error - Starting or controlling a child session failed.
- Submit
Error - A message could not be accepted for transmission.
- Termination
Reason - The single recorded cause of session termination.
Constants§
- CONTROL_
BYTES_ CEILING - Absolute ceiling for
crate::ClientLimits::max_control_bytes. - CONTROL_
MESSAGES_ CEILING - Absolute ceiling for
crate::ClientLimits::max_control_messages. - DEFAULT_
CANCEL_ METHOD - The default cancellation method sent on timeout and explicit cancel.
- DEFAULT_
EXIT_ METHOD - The default exit notification method.
- DEFAULT_
SHUTDOWN_ METHOD - The default graceful-shutdown request method.
- INBOUND_
BYTES_ CEILING - Absolute ceiling for
crate::ClientLimits::max_inbound_bytes. - INBOUND_
MESSAGES_ CEILING - Absolute ceiling for
crate::ClientLimits::max_inbound_messages. - OUTBOUND_
BYTES_ CEILING - Absolute ceiling for
crate::ClientLimits::max_outbound_bytes. - OUTBOUND_
MESSAGES_ CEILING - Absolute ceiling for
crate::ClientLimits::max_outbound_messages. - PENDING_
REQUESTS_ CEILING - Absolute ceiling for
crate::ClientLimits::max_pending_requests. - REQUEST_
TIMEOUT_ CEILING - Absolute ceiling for
crate::ClientLimits::request_timeout. - SHUTDOWN_
GRACE_ CEILING - Absolute ceiling for
crate::ClientLimits::shutdown_grace. - STDERR_
BYTES_ CEILING - Absolute ceiling for
crate::ClientLimits::max_stderr_bytes. - TOMBSTONES_
CEILING - Absolute ceiling for
crate::ClientLimits::max_tombstones. - WEDGE_
TIMEOUT_ STREAK_ CEILING - Absolute ceiling for
crate::ClientLimits::wedge_timeout_streak. - WIRE_
BYTES_ CEILING - Absolute ceiling for the allocating fields of
crate::ClientLimits::wire.