natsdotnet/Documentation/Protocol/Overview.md

# Protocol Overview

NATS uses a line-oriented, text-based protocol over TCP. All commands are terminated by `\r\n`. This simplicity makes it easy to debug with raw TCP tools and keeps parsing overhead low.

## Command Reference

All commands flow either from server to client (S→C) or client to server (C→S). PING and PONG travel in both directions as part of the keepalive mechanism.

| Command | Direction | Format |
|---------|-----------|--------|
| INFO | S→C | `INFO {json}\r\n` |
| CONNECT | C→S | `CONNECT {json}\r\n` |
| PUB | C→S | `PUB subject [reply] size\r\n[payload]\r\n` |
| HPUB | C→S | `HPUB subject [reply] hdr_size total_size\r\n[headers+payload]\r\n` |
| SUB | C→S | `SUB subject [queue] sid\r\n` |
| UNSUB | C→S | `UNSUB sid [max_msgs]\r\n` |
| MSG | S→C | `MSG subject sid [reply] size\r\n[payload]\r\n` |
| HMSG | S→C | `HMSG subject sid [reply] hdr_size total_size\r\n[headers+payload]\r\n` |
| PING/PONG | Both | `PING\r\n` / `PONG\r\n` |
| +OK/-ERR | S→C | `+OK\r\n` / `-ERR 'msg'\r\n` |

Arguments in brackets are optional. `sid` is the subscription ID string assigned by the client. Commands with a payload body (PUB, HPUB, MSG, HMSG) use a two-line structure: a control line with sizes, then the raw payload bytes, then a terminating `\r\n`.

## Connection Handshake

The handshake is always server-initiated:

1. Client opens TCP connection.
2. Server immediately sends `INFO {json}\r\n` describing itself.
3. Client sends `CONNECT {json}\r\n` with its options.
4. Normal operation begins (PUB, SUB, MSG, PING/PONG, etc.).

If `verbose` is enabled in `ClientOptions`, the server sends `+OK` after each valid client command. If the server rejects the CONNECT (bad credentials, unsupported protocol version, etc.) it sends `-ERR 'message'\r\n` and closes the connection.

## ServerInfo

The `ServerInfo` JSON payload is sent in the initial INFO message. The `ClientId` and `ClientIp` fields are omitted from JSON when not set.

```csharp
public sealed class ServerInfo
{
    [JsonPropertyName("server_id")]
    public required string ServerId { get; set; }

    [JsonPropertyName("server_name")]
    public required string ServerName { get; set; }

    [JsonPropertyName("version")]
    public required string Version { get; set; }

    [JsonPropertyName("proto")]
    public int Proto { get; set; } = NatsProtocol.ProtoVersion;

    [JsonPropertyName("host")]
    public required string Host { get; set; }

    [JsonPropertyName("port")]
    public int Port { get; set; }

    [JsonPropertyName("headers")]
    public bool Headers { get; set; } = true;

    [JsonPropertyName("max_payload")]
    public int MaxPayload { get; set; } = NatsProtocol.MaxPayloadSize;

    [JsonPropertyName("client_id")]
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
    public ulong ClientId { get; set; }

    [JsonPropertyName("client_ip")]
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    public string? ClientIp { get; set; }
}
```

`headers` signals that the server supports HPUB/HMSG. `max_payload` advertises the largest message body the server accepts (default 1 MB). `proto` is the protocol version integer; the current value is `1`.

## ClientOptions

The `ClientOptions` JSON payload is sent by the client in the CONNECT command.

```csharp
public sealed class ClientOptions
{
    [JsonPropertyName("verbose")]
    public bool Verbose { get; set; }

    [JsonPropertyName("pedantic")]
    public bool Pedantic { get; set; }

    [JsonPropertyName("echo")]
    public bool Echo { get; set; } = true;

    [JsonPropertyName("name")]
    public string? Name { get; set; }

    [JsonPropertyName("lang")]
    public string? Lang { get; set; }

    [JsonPropertyName("version")]
    public string? Version { get; set; }

    [JsonPropertyName("protocol")]
    public int Protocol { get; set; }

    [JsonPropertyName("headers")]
    public bool Headers { get; set; }

    [JsonPropertyName("no_responders")]
    public bool NoResponders { get; set; }
}
```

`echo` defaults to `true`, meaning a client receives its own published messages if it has a matching subscription. Setting `echo` to `false` suppresses that. `no_responders` causes the server to send a status message when a request has no subscribers, rather than letting the client time out.

## Protocol Constants

`NatsProtocol` centralises limits and pre-encoded byte arrays to avoid repeated allocations in the hot path.

```csharp
public static class NatsProtocol
{
    public const int MaxControlLineSize = 4096;
    public const int MaxPayloadSize = 1024 * 1024; // 1MB
    public const int DefaultPort = 4222;

    // Pre-encoded protocol fragments
    public static readonly byte[] CrLf = "\r\n"u8.ToArray();
    public static readonly byte[] PingBytes = "PING\r\n"u8.ToArray();
    public static readonly byte[] PongBytes = "PONG\r\n"u8.ToArray();
    public static readonly byte[] OkBytes = "+OK\r\n"u8.ToArray();
    public static readonly byte[] InfoPrefix = "INFO "u8.ToArray();
    public static readonly byte[] MsgPrefix = "MSG "u8.ToArray();
    public static readonly byte[] HmsgPrefix = "HMSG "u8.ToArray();
    public static readonly byte[] ErrPrefix = "-ERR "u8.ToArray();
}
```

`MaxControlLineSize` (4096 bytes) is the maximum length of a command line before the payload. Any control line that exceeds this limit causes the parser to throw `ProtocolViolationException`. `MaxPayloadSize` (1 MB) is the default limit enforced by the parser; it is configurable per server instance.

## Go Reference

The Go implementation of protocol parsing is in `golang/nats-server/server/parser.go`. The .NET implementation follows the same command identification strategy and enforces the same control line and payload size limits.

## Related Documentation

- [Parser](Parser.md)
- [Server Overview](../Server/Overview.md)
- [Configuration Overview](../Configuration/Overview.md)

<!-- Last verified against codebase: 2026-02-22 -->