tower-lsp

When implementing or using LSP features in tower-lsp, messages are categorized by their direction and type. This determines whether you implement them in the LanguageServer trait or use the Client struct:

• Request (Client to Server): Implemented via the LanguageServer trait.
• Notification (Client to Server): Implemented via the LanguageServer trait.
• Request (Server to Client): Handled using the Client struct.
• Notification (Server to Client): Handled using the Client struct.

tower-lsp is a Language Server Protocol (LSP) implementation for Rust built on the tower framework. It is composed of three primary components:

1. LanguageServer trait: This is where you define the specific behavior and logic of your language server (e.g., how to handle initialization, shutdown, or specific LSP requests).
2. LspService: An asynchronous delegate that wraps your LanguageServer implementation and handles the underlying protocol mechanics.
3. Server: The component responsible for spawning the LspService and managing the transport of requests and responses over stdio or TCP.

By default, tower-lsp is configured to use tokio. If you need to use a different asynchronous runtime, you must disable the default features and enable the runtime-agnostic feature in your Cargo.toml.

[dependencies.tower-lsp]
version = "*"
default-features = false
features = ["runtime-agnostic"]

To access features defined in the LSP Specification version 3.18 that are currently marked as 'proposed', enable the proposed Cargo feature.

Warning: Features enabled via the proposed flag have no semver guarantees and may introduce breaking changes between versions.

The Client struct is a lightweight, clonable handle used by the language server to send requests and notifications to the client (e.g., an IDE or editor). It implements tower::Service, allowing it to be used with middleware.

Key characteristics:

• Cheap to clone: You can pass it around easily across different parts of your server.
• Lifecycle-aware: Most requests and notifications require the server to be in the Initialized or ShutDown state. Sending requests before initialization will return a JSON-RPC error code -32002.

The LspService implements tower::Service<Request>, acting as a bridge between the transport layer and your LanguageServer implementation.

• Input: A JSON-RPC Request.
• Output: An Option<Response>.
  • If the input is a request, the output is Some(Response) containing the result or error.
  • If the input is a notification or a client response, the output is None.
• Lifecycle: The service shuts down and stops serving requests after the exit notification is received. Any subsequent calls to the service will return an ExitedError.

To run a server, you typically use LspService::new to wrap your LanguageServer implementation and then use Server::new to bind it to standard input/output or other transport mechanisms.

Basic pattern:

1. Define your backend struct (which should hold a Client to send notifications back to the client).
2. Use LspService::new(|client| Backend { client }) to create the service.
3. Use Server::new(stdin, stdout, socket).serve(service).await to start the event loop.

    let (service, socket) = LspService::new(|client| Backend { client });
    Server::new(stdin, stdout, socket).serve(service).await;

To provide code completion, implement textDocument/completion. If computing full completion items is expensive, you can implement completionItem/resolve to provide additional information lazily when a user selects a specific item in the UI.

Note: All properties except those explicitly listed in completion_item.resolve_support (like sort_text, filter_text, insert_text, and text_edit) must be provided in the initial textDocument/completion response and cannot be changed during resolution.

async fn completion(&self, params: CompletionParams) -> Result<Option<CompletionResponse>>
async fn completion_resolve(&self, params: CompletionItem) -> Result<CompletionItem>