protocol#

Communication between client and daemon is composed of two things: standard streams, often referred to as stdio (after the popular C library stdio.h), and JSON-RPC. While this documentation does not aim to give an in-depth explanation of the two, it will cover some basics, in order for you to be able to roll your own client.

standard streams#

Standard streams are a set of preconnected communication channels. Of said channels, there are three: input, output and error. It is quite simple — the client application writes to the daemon’s input channel, and reads from the daemon’s output and error channel.

Any message read from the error channel should be displayed to the user by the client application, just as dendrite.nvim does it.

Standard streams contain unstructured bytes. This places the responsibility of framing and protocol on the application. So in order for dendrite.daemon and any client application to communicate correctly, a framing and protocol must be agreed upon.

Tip: For more information about standard streams the reader is referred to Standard streams.

framing#

To solve the issue of framing messages, there are two popular approaches, content length, and newline delimited framing. The latter is very simple, as each message is simply appended with \n and then written to a given stream. Simple does not necessarily mean better, however, there are pitfalls: any embedded newlines in a message will break the framing, and frame corruption can occur if, for example, the application crashes mid-write.

While this is not a concern right now, based on these known potential issues, the framing is subject to change, and a switch to content length might be implemented at a later point.

JSON-RPC#

JSON-RPC 2.0 is used as the protocol, which is a remote procedure call protocol implemented using JSON. It is simple and lightweight, and all you need after having read a line is a json serializer, which is readily available in every programming language.

Below is an example taken from the JSON-RPC documentation.

--> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

--> {"jsonrpc": "2.0", "method": "subtract", "params": [23, 42], "id": 2}
<-- {"jsonrpc": "2.0", "result": -19, "id": 2}

Tip: For more information about JSON-RPC the reader is referred to JSON-RPC