98 lines
5.4 KiB
Markdown
98 lines
5.4 KiB
Markdown
# Message Schemas
|
||
|
||
JSON Schema definitions (draft 2020-12) for the chat protocol. Messages use
|
||
**IRC command names and numeric reply codes** (RFC 1459/2812) encoded as JSON
|
||
over HTTP.
|
||
|
||
## Envelope
|
||
|
||
Every message is a JSON object with a `command` field. The format maps directly
|
||
to IRC wire format:
|
||
|
||
```
|
||
IRC: :nick PRIVMSG #channel :hello world
|
||
JSON: {"command": "PRIVMSG", "from": "nick", "to": "#channel", "body": ["hello world"]}
|
||
|
||
IRC: :server 353 nick = #channel :user1 @op1 +voice1
|
||
JSON: {"command": "353", "to": "nick", "params": ["=", "#channel"], "body": ["user1 @op1 +voice1"]}
|
||
|
||
Multiline: {"command": "PRIVMSG", "to": "#ch", "body": ["line 1", "line 2"]}
|
||
Structured: {"command": "PUBKEY", "body": {"alg": "ed25519", "key": "base64..."}}
|
||
```
|
||
|
||
Common fields (see `message.json` for full schema):
|
||
|
||
| Field | Type | Description |
|
||
|-----------|----------------|------------------------------------------------------|
|
||
| `id` | string (uuid) | Server-assigned message UUID |
|
||
| `command` | string | IRC command or 3-digit numeric code |
|
||
| `from` | string | Source nick or server name (IRC prefix) |
|
||
| `to` | string | Target: #channel or nick |
|
||
| `params` | string[] | Middle parameters (mainly for numerics) |
|
||
| `body` | array \| object | Structured body — never a raw string (see below) |
|
||
| `ts` | string | ISO 8601 timestamp (server-assigned, not in raw IRC) |
|
||
| `meta` | object | Extensible metadata (signatures, hashes, etc.) |
|
||
|
||
**Structured bodies:** `body` is always an array of strings (for text) or an
|
||
object (for structured data like PUBKEY). Never a raw string. This enables:
|
||
- Multiline messages without escape sequences
|
||
- Deterministic canonicalization via RFC 8785 JCS for signing
|
||
- Structured data where needed
|
||
|
||
## Commands
|
||
|
||
IRC commands used for client↔server and server↔server communication.
|
||
|
||
| Command | File | RFC | Description |
|
||
|-----------|---------------------------|-----------|--------------------------------|
|
||
| `PRIVMSG` | `commands/PRIVMSG.json` | 1459 §4.4.1 | Message to channel or user |
|
||
| `NOTICE` | `commands/NOTICE.json` | 1459 §4.4.2 | Notice (no auto-reply) |
|
||
| `JOIN` | `commands/JOIN.json` | 1459 §4.2.1 | Join a channel |
|
||
| `PART` | `commands/PART.json` | 1459 §4.2.2 | Leave a channel |
|
||
| `QUIT` | `commands/QUIT.json` | 1459 §4.1.6 | User disconnected |
|
||
| `NICK` | `commands/NICK.json` | 1459 §4.1.2 | Change nickname |
|
||
| `TOPIC` | `commands/TOPIC.json` | 1459 §4.2.4 | Get/set channel topic |
|
||
| `MODE` | `commands/MODE.json` | 1459 §4.2.3 | Set channel/user modes |
|
||
| `KICK` | `commands/KICK.json` | 1459 §4.2.8 | Kick user from channel |
|
||
| `PING` | `commands/PING.json` | 1459 §4.6.2 | Keepalive |
|
||
| `PONG` | `commands/PONG.json` | 1459 §4.6.3 | Keepalive response |
|
||
| `PUBKEY` | `commands/PUBKEY.json` | (extension) | Announce/relay signing key |
|
||
|
||
## Numeric Replies
|
||
|
||
Three-digit codes for server responses, per IRC convention.
|
||
|
||
### Success / Informational (0xx–3xx)
|
||
|
||
| Code | Name | File | Description |
|
||
|-------|-------------------|-----------------------|--------------------------------|
|
||
| `001` | RPL_WELCOME | `numerics/001.json` | Welcome after session creation |
|
||
| `002` | RPL_YOURHOST | `numerics/002.json` | Server host info |
|
||
| `003` | RPL_CREATED | `numerics/003.json` | Server creation date |
|
||
| `004` | RPL_MYINFO | `numerics/004.json` | Server info and modes |
|
||
| `322` | RPL_LIST | `numerics/322.json` | Channel list entry |
|
||
| `323` | RPL_LISTEND | `numerics/323.json` | End of channel list |
|
||
| `332` | RPL_TOPIC | `numerics/332.json` | Channel topic |
|
||
| `353` | RPL_NAMREPLY | `numerics/353.json` | Channel member list |
|
||
| `366` | RPL_ENDOFNAMES | `numerics/366.json` | End of NAMES list |
|
||
| `372` | RPL_MOTD | `numerics/372.json` | MOTD line |
|
||
| `375` | RPL_MOTDSTART | `numerics/375.json` | Start of MOTD |
|
||
| `376` | RPL_ENDOFMOTD | `numerics/376.json` | End of MOTD |
|
||
|
||
### Errors (4xx)
|
||
|
||
| Code | Name | File | Description |
|
||
|-------|----------------------|-----------------------|--------------------------------|
|
||
| `401` | ERR_NOSUCHNICK | `numerics/401.json` | No such nick/channel |
|
||
| `403` | ERR_NOSUCHCHANNEL | `numerics/403.json` | No such channel |
|
||
| `433` | ERR_NICKNAMEINUSE | `numerics/433.json` | Nickname already in use |
|
||
| `442` | ERR_NOTONCHANNEL | `numerics/442.json` | Not on that channel |
|
||
| `482` | ERR_CHANOPRIVSNEEDED | `numerics/482.json` | Not channel operator |
|
||
|
||
## Federation (S2S)
|
||
|
||
Server-to-server messages use the same command format. Federated servers relay
|
||
messages with an additional `origin` field in `meta` to track the source server.
|
||
The PING/PONG commands serve as inter-server keepalives. State sync after link
|
||
establishment uses a burst of JOIN, NICK, TOPIC, and MODE commands.
|