john-slop/docs/decisions/0003-lsp-framework-and-prot...

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 confidence findings;
  • quick fixes use versioned workspace edits and are rejected when the request refers to a stale or unknown document version;
  • workspace/didChangeConfiguration reloads 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 LspService in 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.