# Custom protocol framework LspCpp is not limited to Language Server Protocol servers. The LSP layer is built on top of a reusable JSON-RPC message framework, so you can define your own protocol methods and use the same transport, framing, dispatch, cancellation, and typed serialization infrastructure. Use this mode when you want: - A private JSON-RPC protocol between two C++ processes. - An editor-like plugin protocol that is not the standard LSP. - A test harness, daemon, or tool server with typed request/response messages. - LSP-compatible framing over stdio, TCP, WebSocket, or custom streams without using LSP method names. ## Layers you can reuse The project has two useful layers: | Layer | Main types | Use when | |-------|------------|----------| | LSP convenience layer | `lsp::LanguageSession`, `lsp::ProtocolJsonHandler` | You are building a normal LSP server or extending LSP. | | Generic JSON-RPC layer | `MessageJsonHandler`, `GenericEndpoint`, `RemoteEndPoint` | You want to define your own protocol methods and message types. | `LanguageSession` creates a `ProtocolJsonHandler`, which pre-registers many LSP methods. For a clean custom protocol, construct `RemoteEndPoint` yourself with a plain `MessageJsonHandler`. ## Minimal custom protocol server This example defines a request named `tool/echo` and a notification named `tool/exit`. It does not depend on any LSP request or capability types. ```cpp #include "LibLsp/JsonRpc/Condition.h" #include "LibLsp/JsonRpc/Endpoint.h" #include "LibLsp/JsonRpc/NotificationInMessage.h" #include "LibLsp/JsonRpc/RemoteEndPoint.h" #include "LibLsp/JsonRpc/RequestInMessage.h" #include "LibLsp/JsonRpc/stream.h" #include #include struct EchoParams { std::string text; MAKE_SWAP_METHOD(EchoParams, text); }; MAKE_REFLECT_STRUCT(EchoParams, text); struct EchoResult { std::string text; MAKE_SWAP_METHOD(EchoResult, text); }; MAKE_REFLECT_STRUCT(EchoResult, text); DEFINE_REQUEST_RESPONSE_TYPE(Echo, EchoParams, EchoResult, "tool/echo"); struct ExitParams { bool requested = true; MAKE_SWAP_METHOD(ExitParams, requested); }; MAKE_REFLECT_STRUCT(ExitParams, requested); DEFINE_NOTIFICATION_TYPE(Notify_ToolExit, ExitParams, "tool/exit"); int main() { lsp::NullLog log; auto json_handler = std::make_shared(); auto local_endpoint = std::make_shared(log); RemoteEndPoint endpoint(json_handler, local_endpoint, log); Condition exit_requested; endpoint.registerHandler( [](Echo::request const& req) { Echo::response rsp; rsp.id = req.id; rsp.result.text = req.params.text; return rsp; }); endpoint.registerHandler( [&](Notify_ToolExit::notify const&) { exit_requested.notify(std::make_unique(true)); }); endpoint.startProcessingMessages(lsp::make_stdin_stream(), lsp::make_stdout_stream()); exit_requested.wait(); endpoint.stop(); } ``` `registerHandler()` installs both the message handler and the JSON parser for unknown custom methods. You do not need to manually populate `MessageJsonHandler` for simple custom request and notification types. ## Wire format The default `JSONStreamStyle::Standard` transport uses LSP-style `Content-Length` framing, but the JSON-RPC payload can be your own protocol: ```text Content-Length: 72 {"jsonrpc":"2.0","id":1,"method":"tool/echo","params":{"text":"hello"}} ``` The response uses the result type declared in `DEFINE_REQUEST_RESPONSE_TYPE`: ```text Content-Length: 52 {"jsonrpc":"2.0","id":1,"result":{"text":"hello"}} ``` ## Send custom messages Use `RemoteEndPoint` the same way for outbound messages: ```cpp auto req = endpoint.createRequest(); req.params.text = "ping"; auto future = endpoint.send(req); future.wait(); auto result = future.get(); if (!result.IsError()) { auto echoed = result.response.result.text; } ``` Notifications do not need request ids: ```cpp Notify_ToolExit::notify notify; endpoint.send(notify); ``` ## Use different transports The generic layer can use the same transports as the LSP layer: - stdio: `endpoint.startProcessingMessages(lsp::make_stdin_stream(), lsp::make_stdout_stream())` - custom streams: pass your own `std::shared_ptr` and `std::shared_ptr` - TCP: build around `lsp::TcpServer` and register handlers on `server.point` - WebSocket: use the existing WebSocket server support when `LSPCPP_BUILD_WEBSOCKETS=ON` The message types do not need to be LSP types. Only the JSON-RPC envelope and framing need to match what both sides expect. ## When to use `LanguageSession` instead Use `lsp::LanguageSession` when your protocol is still mostly LSP: - You need standard LSP methods such as `initialize`, `shutdown`, `textDocument/hover`, or diagnostics. - You want built-in LSP request and notification parsers. - You are writing a language server for an editor. Use `RemoteEndPoint` with a plain `MessageJsonHandler` when you want a protocol that is independent from LSP. ## Design guidelines - Pick stable method names, for example `tool/echo`, `daemon/build`, or `$/progress`. - Keep request params and response results small and explicit. - Version your custom protocol in an initialization request if clients and servers may be upgraded independently. - Treat `Content-Length` framing as part of the transport contract; both peers must send complete JSON-RPC frames. - If you later add standard LSP support, switch to `lsp::ProtocolJsonHandler` or `lsp::LanguageSession` and keep your custom methods alongside the LSP ones. ## Related docs - [Advanced customization](advanced-customization.md) - [Transport options](transport.md) - [Protocol types](../developer/protocol-types.md) .