KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

loqui

★ 221 Open GitHub ↗

RPC Transport Layer - with minimal bullshit.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# This project is no longer maintained

The gRPC ecosystem has advanced since we've written this project, and we've moved to using gRPC instead.

# Loqui
Loqui is a transport that implements a very simple framing protocol over a raw socket. The framing protocol is similar
to http2, except that we've chosen deliberately to not implement a bunch of stuff, like flow control.
Instead, the RPC implements very simple request and response semantics. For our purposes, requests and responses are both adequately small so we can just send the entire payload in one frame, instead of having streams (like http2 does).

The RPC protocol does not care how you encode your data - treating all data passed through it as opaque binaries. However,
the protocol does support encoding negotiation, and compression where the client sends the server a list of encodings it can speak and compression algos it can use, and the server picks the encoding and compression it wants to use. Compression can be toggled on a per frame basis with frame flags.

# The protocol
The protocol is 9 opcodes, with a binary frame format.

Each frame starts with the opcode as an unsigned 8 bit integer (`uint8`). The opcodes are:

| Name              | Value | Client or Server | Has Payload ? |
| ----------------- | ----- | ---------------- | ------------- |
| `HELLO`           | `1`   | Client           | Yes           |
| `HELLO_ACK`       | `2`   | Server           | Yes           |
| `PING`            | `3`   | Both             | No            |
| `PONG`            | `4`   | Both             | No            |
| `REQUEST`         | `5`   | Client           | Yes           |
| `RESPONSE`        | `6`   | Server           | Yes           |
| `PUSH`            | `7`   | Both             | Yes           |
| `GOAWAY`          | `8`   | Server           | Yes           |
| `ERROR`           | `9`   | Server           | Yes           |

Following the opcode is the frame header - and then if applicable - the payload.
All integers are encoded in `Big Endian` format.

## `Hello`
The hello opcode is sent by the client to the server upon connecting. It advertises the client's Loqui version and a payload containing a a list of connection settings. Settings are in order and split by `|`and a specific setting can have a list of values split by `,`. In our current version the 2 settings are **supported encodings** and **supported compressions**.

| Offset | Type    | Description     |
| ------ | ------- | --------------- |
| `0`    | uint8   | opcode          |
| `1`    | uint8   | flags           |
| `2`    | uint8   | Loqui Version   |
| `3`    | uint32  | Payload Size    |
| `7`    | binary  | Payload Data    |

## `HelloAck`
The helloAck opcode is sent by the server upon receiving hello from the client. It contains the interval in which the server will ping (and that it expects the client to ping the server) - and the supported encodings within the payload data, contains the **encoding** and **compression** separated by `|`.

| Offset | Type    | Description       |
| ------ | ------- | ----------------- |
| `0`    | uint8   | opcode            |
| `1`    | uint8   | flags             |
| `2`    | uint32  | Ping Interval(ms) |
| `6`    | uint32  | Payload Size      |
| `10`   | binary  | Payload Data      |

## `Ping/Pong`
Ping and pong are sent back between the client and server. Either end can initiate a ping - and both ends are expected
to reply to a ping with a pong, with the seq that the remote end pinged with.

| Offset | Type     | Description      |
| ------ | -------- | -----------------|
| `0`    | uint8    | opcode           |
| `1`    | uint8    | flags            |
| `2`    | uint32   | Sequence Num     |

## `Request/Response`
The client can send requests to the server. The server is expected to reply with a `RESPONSE` payload with the sequence set to
request sequence.

| Offset | Type     | Description      |
| ------ | -------- | -----------------|
| `0`    | uint8    | opcode           |
| `1`    | uint8    | flags            |
| `2`    | uint32   | Sequence Num     |
| `6`    | uint32   | Payload Size     |
| `10`   | binary   | Payload Data     |

## `Push`
The client and server can send pushes to their remote connection. These are good for one off messages to
the service that do not need to be acknowledged.

| Offset | Type     | Description      |
| ------ | -------- | -----------------|
| `0`    | uint8    | opcode           |
| `1`    | uint8    | flags            |
| `2`    | uint32   | Payload Size     |
| `6`    | binary   | Payload Data     |

## `Go Away`
The server is getting ready to shut down the connection. It sends this opcode to tell the client end to finish sending
requests and to disconnect. The payload data can be empty, or a string with an error message. Or whatever else you want it to be.

| Offset | Type     | Description      |
| ------ | -------- | -----------------|
| `0`    | uint8    | opcode           |
| `1`    | uint8    | flags            |
| `2`    | uint16   | close code       |
| `4`    | uint32   | Payload Size     |
| `8`    | binary   | Payload Data     |

## `Error`
The server had an internal error processing a given request for a specific seq.

| Offset | Type     | Description      |
| ------ | -------- | -----------------|
| `0`    | uint8    | opcode           |
| `1`    | uint8    | flags            |
| `2`    | uint32   | Sequence Num     |
| `6`    | uint16   | error code       |
| `8`    | uint32   | Payload Size     |
| `12`   | binary   | Payload Data     |

loqui

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README