2.7 KiB
ADR 0003: LSP framework and protocol contract
- Status: accepted
- Date: 2026-09-29
Context
John Slop needs a small stdio language server that reuses the validated
replacement configuration and exact TextEdits from the library. Implementing
JSON-RPC framing and the Language Server Protocol state machine locally would
add protocol risk without improving detection. The original tower-lsp crate's
latest release is 0.20.0, while its maintained community continuation publishes
the same Tower-oriented API as tower-lsp-server.
The dependency review compared the crates' published metadata, documentation,
runtime features, and minimum Rust versions. tower-lsp-server 0.23.0 is the
latest stable release; 0.24.0-rc.1 is a prerelease. Version 0.23.0 requires Rust
1.85, below this project's Rust 1.98.1 baseline, and provides the Tokio stdio
transport, generated LSP types, client notifications, and in-process service
interface needed by the milestone. Its MIT OR Apache-2.0 licensing is compatible
with this project.
Decision
Use tower-lsp-server 0.23 and its Tokio runtime feature. Use Tokio directly
only for the stdio runtime and synchronized in-memory document state. Do not
enable proposed LSP extensions or an alternate URI implementation.
The initial server targets stable LSP 3.17 behavior with these assumptions:
- transport is stdio only, with protocol bytes reserved for stdout;
- document positions are zero-based UTF-16 code-unit offsets;
- clients send full-document synchronization, simplifying authoritative version handling while replacement behavior is established;
- the server owns snapshots of open documents only and never writes their URIs;
- diagnostics and quick fixes cover configured ASCII replacements, not heuristic authorship or aggregate heuristic findings;
- quick fixes use versioned workspace edits and are rejected when the request refers to a stale or unknown document version;
workspace/didChangeConfigurationreloads the same layered configuration used by the CLI and formatter, then republishes diagnostics for open snapshots;- malformed messages and invalid URIs are protocol/input errors, never panics.
Consequences
- The replacement engine remains the single source of edit ranges and text.
- A tested line index converts canonical UTF-8 byte offsets to LSP UTF-16 positions at the adapter boundary.
- Protocol tests can drive
LspServicein process without launching a child process, while a small stdio smoke test protects stream purity. - Incremental synchronization may be added later, but must preserve version and stale-result guarantees before it is advertised.
- Upgrading to the 0.24 line waits for a stable release and a separate API and minimum-Rust review.