tower-lsp-server

To create a language server, implement the LanguageServer trait for your backend struct. You must provide implementations for initialize, initialized, and shutdown. Use the LspService::new constructor to create a service that instantiates your backend with a Client for sending messages back to the client. Finally, use Server::new with your transport handles (like stdin and stdout) to serve the service.

use tower_lsp_server::jsonrpc::Result;
use tower_lsp_server::gen_lsp_types::*;
use tower_lsp_server::{Client, LanguageServer, LspService, Server};

#[derive(Debug)]
struct Backend {
    client: Client,
}

impl LanguageServer for Backend {
    async fn initialize(&self, _: InitializeParams) -> Result<InitializeResult> {
        Ok(InitializeResult::default())
    }

    async fn initialized(&self, _: InitializedParams) {
        self.client
            .log_message(MessageType::INFO, "server initialized!")
            .await;
    }

    async fn shutdown(&self) -> Result<()> {
        Ok(())
    }
}

#[tokio::main]
async fn main() {
    let stdin = tokio::io::stdin();
    let stdout = tokio::io::stdout();

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

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

Lifecycle and State

• Initialization: The service remains in an Initializing state until the initialize request is processed. During this time, poll_ready returns Poll::Pending.
• Shutdown: Once the exit notification is received, the service enters the Exited state. Subsequent calls to poll_ready or call will return an ExitedError.
• Cancellation: Pending requests can be canceled by the client issuing a $/cancelRequest notification. The service handles this by returning a JSON-RPC error response to the pending request.

Request/Response Mapping

• Requests: Incoming JSON-RPC requests result in an Option<Response>. If the handler returns a value, it is wrapped in Some(Response). If the handler is a notification (returns ()), the result is None.
• Error Handling: If a client sends a request for a method that does not exist (and it is not a standard $/ extension method), the service automatically handles the MethodNotFound error logic.

Progress reporting follows a builder pattern to emit $/progress notifications to the client. The workflow consists of three main stages:

1. Creation: Use Client::progress(token, title) to create a Progress builder. By default, progress is unbounded and not cancellable.
2. Configuration: Use builder methods to define the progress behavior:
   • .with_percentage(start_percentage: u32): Transitions the stream from Unbounded to Bounded (0-100%).
   • .with_cancel_button(): Transitions the stream from NotCancellable to Cancellable.
   • .with_message(message: M): Sets an initial detailed message.
3. Execution: Call .begin().await on the builder. This sends the initial notification and returns an OngoingProgress handle.
4. Updates: Use the OngoingProgress handle to call .report(...) or .report_with_message(...) to update the UI.
5. Completion: Call .finish().await or .finish_with_message(message).await to signal the operation is complete.

Note: Progress is not reported to the client until .begin() is called.

// Conceptual workflow
let progress = client.progress(token, "Indexing project")
    .with_percentage(0)
    .with_cancel_button()
    .with_message("Starting...");

let ongoing = progress.begin().await;

// Update progress
ongoing.report_with_message("Scanning files...", 50, None).await;

// Finish
ongoing.finish().await;

To create a language server, use LspService::build or LspService::build_with_lifecycle_methods. These return an LspServiceBuilder which you can customize before calling .finish() to obtain the LspService and a ClientSocket for server-to-client communication.

• LspService::build(init): Registers all default methods from the LanguageServer trait. Use this for standard LSP servers.
• LspService::build_with_lifecycle_methods(init): Registers only the essential LSP lifecycle methods (initialize, initialized, shutdown, exit, and $/cancelRequest). This is ideal for reducing binary size when implementing only a subset of LSP.

The init argument is a closure that takes a Client and returns your server backend S (which must implement LanguageServer).

use tower_lsp_server::{LanguageServer, LspService};

struct MyServer;

#[async_trait::async_trait]
impl LanguageServer for MyServer {
    // ... implement required methods
}

let (service, socket) = LspService::build(|client| MyServer)
    .finish();

This reference lists the availability of specific LSP methods for older versions of the protocol. Use this to determine if your required functionality (like progress reporting or workspace configuration) is implemented in the version of the server you are targeting.

### [3.15.0] - 2020-01-14

| Method Name | Message Type | Supported |
| :--- | :---: | :---: |
| `$/progress` | ↔ | 🔴 |
| `window/workDoneProgress/create` | ↪ | 🔴 |
| `window/workDoneProgress/cancel` | ↔ | 🔴 |
| `textDocument/selectionRange` | ↩ | 🟢 |

### [3.14.0] - 2018-12-13

| Method Name | Message Type | Supported |
| :--- | :---: | :---: |
| `textDocument/declaration` | ↩ | 🟢 |

### [3.12.0] - 2018-08-23

| Method Name | Message Type | Supported |
| :--- | :---: | :---: |
| `textDocument/prepareRename` | ↩ | 🟢 |

### [3.10.0] - 2018-07-23

| Method Name | Message Type | Supported |
| :--- | :---: | :---: |
| `textDocument/foldingRange` | ↩ | 🟢 |

### [3.6.0] - 2018-02-22

| Method Name | Message Type | Supported |
| :--- | :---: | :---: |
| `workspace/workspaceFolders` | ↪ | 🟢 |
| `workspace/didChangeWorkspaceFolders` | ↔ | 🟢 |
| `workspace/configuration` | ↪ | 🟢 |
| `textDocument/typeDefinition` | ↩ | 🟢 |
| `textDocument/implementation` | ↩ | 🟢 |
| `textDocument/documentColor` | ↩ | 🟢 |
| `textDocument/colorPresentation` | ↩ | 🟢 |