# Writing a language server This guide covers the main API patterns for implementing an LSP server with LspCpp. ## Two API levels LspCpp offers two ways to wire up a server: | API | Header | When to use | |-----|--------|-------------| | **`LanguageSession`** | `LibLsp/LspCpp.h` | Recommended for new code. Thin wrapper around `RemoteEndPoint`. | | **`RemoteEndPoint`** | `LibLsp/JsonRpc/RemoteEndPoint.h` | Lower-level control; used in older examples. | Both use the same handler registration model. `LanguageSession` is an alias-friendly entry point: ```cpp lsp::LanguageServer server; // alias for LanguageSession ``` ## Registering handlers Handlers are registered with `on()` (LanguageSession) or `registerHandler()` (RemoteEndPoint). The compiler deduces the LSP method from the handler's parameter type. ### Request handlers ```cpp server.on([](td_initialize::request const& req) -> lsp::ResponseOrError { td_initialize::response rsp; rsp.id = req.id; rsp.result.capabilities.hoverProvider = true; return rsp; }); ``` Return `lsp::ResponseOrError` to send either a success response or a JSON-RPC error. You can also return the response type directly; the library wraps it automatically in many cases. Set `rsp.id = req.id` so the client can correlate the response. ### Request handlers with cancellation Long-running requests can accept a `CancelMonitor`: ```cpp server.on([](td_definition::request const& req, CancelMonitor const& monitor) -> lsp::ResponseOrError { if (monitor && monitor()) { Rsp_Error err; err.error.code = lsErrorCodes::RequestCancelled; err.error.message = "cancelled"; return err; } td_definition::response rsp; rsp.id = req.id; // ... return rsp; }); ``` ### Async request handlers Long-running requests can return `lsp::future` or `lsp::future>`. The library waits for the future on a background path and sends the response without blocking the dispatch worker: ```cpp server.on([](td_hover::request const& req) -> lsp::future { auto promise = std::make_shared>(); auto future = promise->get_future(); std::thread([promise, id = req.id]() { td_hover::response rsp; rsp.id = id; // ... promise->set_value(std::move(rsp)); }).detach(); return future; }); ``` Cancellable async handlers use the same second `CancelMonitor const&` parameter. ### Returning errors with RequestError In addition to returning `lsp::ResponseOrError` or `Rsp_Error` explicitly, you can throw `lsp::RequestError` and the library converts it to a JSON-RPC error response: ```cpp #include "LibLsp/JsonRpc/RequestError.h" server.on([](td_initialize::request const&) -> td_initialize::response { throw lsp::RequestError(lsErrorCodes::InvalidParams, "invalid initialize params"); }); ``` `ResponseOrError` remains the explicit, non-exception alternative. ### Notification handlers Notifications have no response. Register them the same way: ```cpp server.on([](Notify_Exit::notify const&) { // handle exit }); server.on([](Notify_TextDocumentDidOpen::notify const& n) { // textDocument/didOpen }); ``` ## LSP lifecycle A well-behaved server follows this sequence: ``` Client Server |---- initialize -----------> | |<--- InitializeResult ------| |---- initialized ---------> | (notification, no response) |---- ... requests ... ----> | |---- shutdown ------------> | |<--- null ------------------| |---- exit -----------------> | | | stop() ``` Implement at minimum: ```cpp server.on([](td_initialize::request const& req) { /* return capabilities */ }); server.on([](td_shutdown::request const& req) { td_shutdown::response rsp; rsp.id = req.id; return rsp; }); server.on([&](Notify_Exit::notify const&) { exit_requested.notify(std::make_unique(true)); }); ``` Until `initialize` completes, the server should reject other requests (LspCpp enforces protocol parsing; your handlers should not assume documents are open before initialization). ## Declaring capabilities Capabilities are returned in the `initialize` response: ```cpp server.on([](td_initialize::request const& req) { td_initialize::response rsp; rsp.id = req.id; lsTextDocumentSyncOptions sync; sync.openClose = true; sync.change = lsTextDocumentSyncKind::Full; rsp.result.capabilities.textDocumentSync = std::make_pair(optional(), optional(sync)); lsCompletionOptions completion; completion.triggerCharacters = std::vector { "." }; rsp.result.capabilities.completionProvider = completion; rsp.result.capabilities.hoverProvider = true; WorkDoneProgressOptions definition_options; rsp.result.capabilities.definitionProvider = std::make_pair(optional(true), optional(definition_options)); return rsp; }); ``` Only advertise features you actually implement. Clients use this list to decide which requests to send. Several server capability fields mirror LSP union types. In this codebase those fields are represented as `std::pair, optional<...>>`; the first slot is usually the simple boolean/kind form and the second slot is the detailed options object. ## Sending outbound messages Use `server.endpoint()` to send notifications or requests to the client: ```cpp // Log to the client's output panel Notify_LogMessage::notify log; log.params.type = lsMessageType::Log; log.params.message = "indexing complete"; session.endpoint().send(log); // Publish diagnostics Notify_TextDocumentPublishDiagnostics::notify diag; diag.params.uri.raw_uri_ = "file:///path/to/file.lang"; diag.params.diagnostics = { /* lsDiagnostic entries */ }; session.endpoint().send(diag); ``` ## Tracking open documents LspCpp provides `WorkingFiles` to maintain in-memory buffers synchronized with LSP document events: ```cpp #include "LibLsp/lsp/working_files.h" WorkingFiles files; server.on([&](Notify_TextDocumentDidOpen::notify const& n) { files.OnOpen(n.params.textDocument); }); server.on([&](Notify_TextDocumentDidChange::notify const& n) { files.OnChange(n.params); }); server.on([&](Notify_TextDocumentDidClose::notify const& n) { files.OnClose(n.params.textDocument); }); ``` `WorkingFile` stores buffer content and precomputed line offsets for converting LSP positions to byte offsets. ## Logging Pass a custom `Log` implementation to `LanguageSession` for diagnostics during development: ```cpp lsp::StderrLog log; lsp::LanguageSession server(log); ``` Use `NullLog` (the default) in production if you do not need stderr output. ## Optional clangd-style helpers (opt-in) These headers are additive; existing `LanguageSession`, `RemoteEndPoint`, `WorkingFiles`, and `ProtocolJsonHandler` defaults are unchanged. ### Request cancellation (`LibLsp/JsonRpc/RequestCancellation.h`) Install a cancelable task scope around long-running work and poll cancellation from ambient `Context`: ```cpp #include "LibLsp/JsonRpc/RequestCancellation.h" server.on([](td_definition::request const& req) -> lsp::ResponseOrError { if (auto monitor = lsp::getCancelledMonitor(req.id)) { if (lsp::isCancellationRequested(*monitor)) { throw lsp::makeRequestCancelledError(); } } // ... }); ``` `BindLspHandlerWithMonitor` and `BindLspAsyncHandlerWithMonitor` in `LibLsp/lsp/BindLspHandler.h` pass a `CancelMonitor` directly. Async binders preserve the handler's exact `lsp::future` return type, including `lsp::future>`. ### Error helpers (`LibLsp/JsonRpc/Error.h`) Helpers for LSP-specific error codes such as `RequestCancelled (-32800)` and `ContentModified (-32801)`: ```cpp #include "LibLsp/JsonRpc/Error.h" throw lsp::makeRequestCancelledError(); throw lsp::makeContentModifiedError("buffer changed"); return lsp::makeRequestCancelledResponse(req.id); ``` **Malformed parameters** must still use `RequestError(lsErrorCodes::InvalidParams, ...)`. Cancellation and content-modified helpers do not replace `InvalidParams` handling. ### Request context (`LibLsp/lsp/request_context.h`) Opt-in ambient offset encoding and path mapping for handler code: ```cpp #include "LibLsp/lsp/request_context.h" lsp::WithContext scope(lsp::withOffsetEncodingContext(lsp::OffsetEncoding::Utf8)); int offset = lsp::GetOffsetForPositionInContext(position, buffer); ``` UTF-16 remains the default when no context is installed. ## Custom request parsing Override the built-in JSON parser for a method when you need non-standard parameter handling. The parser must return the same concrete request type accepted by the handler for that method: ```cpp server.overrideRequestParser( td_initialize::request::kMethodInfo, [](Reader& visitor) { return td_initialize::request::ReflectReader(visitor); }); ``` Or use the template shortcut: ```cpp server.overrideRequestParser(); ``` For custom request/notification types, vendor extensions, and replacing built-in message shapes, see [Advanced customization](advanced-customization.md). ## Finding LSP type headers Request and notification types follow a naming convention: | Pattern | Example | LSP method | |---------|---------|------------| | `td_::request` | `td_definition::request` | `textDocument/definition` | | `td_::response` | `td_definition::response` | (response struct) | | `Notify_::notify` | `Notify_Exit::notify` | `exit` | Headers are organized under `include/LibLsp/lsp/` by domain: - `general/` — initialize, shutdown, exit - `textDocument/` — completion, hover, rename, etc. - `workspace/` — symbols, configuration, applyEdit See [Protocol types](../developer/protocol-types.md) for how these types are generated and extended. ## Examples in the repository | Example | Description | |---------|-------------| | `MinimalStdIOServerExample.cpp` | Smallest stdio server (no Boost) | | `StdIOServerExample.cpp` | stdio with capabilities, definition handler, cancellation | | `ProcessClientExample.cpp` | Lightweight client that launches a server with `lsp::Process` over stdio | | `TcpServerExample.cpp` | TCP server on a configurable port | | `WebsocketExample.cpp` | WebSocket server | | `StdIOClientExample.cpp` | Boost.Process-based client JSON-RPC over stdio | Build all examples with `-DLSPCPP_BUILD_EXAMPLES=ON` (requires Boost; `ProcessClientExample` only needs the in-tree `lsp::Process` helper). ## Launching a server process from a client LSP clients usually spawn the language server and talk over stdio. Use `lsp::Process` (`LibLsp/JsonRpc/Process.h`): ```cpp #include "LibLsp/JsonRpc/Process.h" lsp::Process process = lsp::Process::start("/path/to/language-server", {"--stdio"}); RemoteEndPoint point(json_handler, endpoint, log); point.startProcessingMessages(process.input(), process.output()); // send initialize, handle responses... Notify_Exit::notify exit_notify; point.send(exit_notify); point.stop(); process.wait(); ``` See `examples/ProcessClientExample.cpp` for a full walkthrough. With examples enabled, CTest runs: ```bash ProcessClientExample --execPath StdIOServerExample ``` .