Skip to main content

Crate weavatrix_lsp_client

Crate weavatrix_lsp_client 

Source
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 from ClientLimits or from a per-call override. An elapsed deadline completes the request with RequestError::Timeout and 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_bytes and 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_tail and ShutdownReport::stderr_tail each 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 from Drop, 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 as Drop does; a SIGKILLed client or a panic = "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.

FieldDefaultCeilingBounds
max_outbound_messages25665 536Ordinary lane item count
max_outbound_bytes8 MiB256 MiBOrdinary lane retained body bytes
max_control_messages324 096Reserved lane item count
max_control_bytes1 MiB64 MiBReserved lane retained body bytes
max_inbound_messages25665 536Server-initiated item count
max_inbound_bytes8 MiB256 MiBServer-initiated retained payload bytes
max_pending_requests12816 384Requests awaiting a response
max_tombstones25665 536Retained late-response tombstones
max_stderr_bytes64 KiB4 MiBChild stderr ring buffer
wedge_timeout_streak31 024Consecutive deadlines that end a session
request_timeout30 s1 hPer-request deadline from submission
shutdown_grace5 s5 minWait before the forced tree kill
wireLimits::default()256 MiBHeader, 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 at max_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 to REQUEST_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 as cancellations_dropped rather 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 at i32::MAX and skipping anything still pending or tombstoned.
  • Dropping a PendingRequest does 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§

ChildConfig
The child command plus the three base-protocol method names the engine emits on its own behalf.
ClientLimits
Every bound the client engine enforces, in one validated value.
MetricsSnapshot
A consistent-per-field snapshot of engine counters and queue occupancy.
PendingRequest
A submitted request that has not yet produced its single outcome.
Session
One owned language-server subprocess and its bounded request engine.
ShutdownReport
What a completed shutdown observed.

Enums§

ClientLimitsError
An invalid crate::ClientLimits configuration.
Inbound
One server-initiated message delivered to the caller.
RecvError
Receiving server-initiated traffic failed.
RequestError
A submitted request did not complete with a server response.
Response
The server’s answer to one client request.
SessionError
Starting or controlling a child session failed.
SubmitError
A message could not be accepted for transmission.
TerminationReason
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.