README.md — sigil-irc

1# sigil-irc

The canonical IRC protocol library for the [Sigil](https://codeberg.org/sigil/sigil) ecosystem. Covers both client and server flows for modern IRCv3 (Tier 1 ratified caps + Tier 2 high-value drafts), plus a convenience client API with TLS and cooperative I/O.

5## Features

7### Wire layer

9- **IRC line parser** — handles RFC 1459/2812 prefix/command/params/trailing

10- **IRCv3 message tags** — full `@key=value;…` parsing/serialization with escape handling (`\:` `\s` `\\` `\r` `\n`)

- **Identity type** — fully-qualified `<nick>@<server-domain>` with display + canonical accessors (federation-ready from day one)

- **Numeric reply constants** — named bindings for the 50+ relevant IRC numerics (welcome, MOTD, errors, SASL, MONITOR)

14### Capability negotiation (both directions)

16- **CAP state machines** — `cap-client-state` and `cap-server-state` advance values with no I/O

- **Tier 1 caps** — `sasl`, `message-tags`, `server-time`, `account-tag`, `account-notify`, `extended-join`, `userhost-in-names`, `multi-prefix`, `away-notify`, `chghost`, `invite-notify`, `setname`, `batch`, `labeled-response`, `echo-message`, `cap-notify`

18- **Tier 2 caps** — `draft/chathistory`, `draft/read-marker`, `MONITOR`

20### SASL (both directions)

22- **PLAIN** — `authzid \0 authcid \0 password`

23- **EXTERNAL** — TLS client cert

- **SCRAM-SHA-256** — RFC 5802 / RFC 7677 challenge-response (requires sigil-crypto v0.15.0+ for `pbkdf2-sha256` + `hmac-sha256-bytes`)

25- **Chunked AUTHENTICATE** — full base64 chunking per the IRCv3 spec

27### IRCv3 features

29- **BATCH** — start/end line builders, reftag generator, batch-tag tracking

30- **CHATHISTORY** — query parsing (BEFORE/AFTER/LATEST/AROUND/BETWEEN/TARGETS) + serialization

31- **MARKREAD (`draft/read-marker`)** — query/set parsing + line builders

32- **MONITOR** — subcommand parsing + numeric reply builders (730–734)

33- **Server-time, msgid, account, batch, label, +draft/reply, +typing** — typed tag accessors

35### Convenience client (legacy)

The `(sigil irc connection)` module retains a high-level client convenience API with TLS, SASL, channel tracking, NickServ identify, and an event loop — backwards compatible with prior sigil-irc releases.

39### IRC over WebSocket

The sibling `sigil-irc-websocket` package provides `(sigil irc websocket)`, composing the public `sigil-websocket` client API with the IRC message parser for browser/WASM use. It avoids adding a WebSocket dependency to the core `sigil-irc` package used by native/desktop IRC clients.

43## Usage

45### Client (high-level convenience)

47```scheme

48(import (sigil irc)

49 (sigil irc websocket))

51(define conn (make-irc-connection

52 server: "irc.libera.chat"

53 port: 6697

54 nick: "mybot"

55 tls: #t))

57(irc-on conn 'PRIVMSG

58 (lambda (msg)

59 (irc-privmsg conn (irc-message-target msg) "Hello!")))

61(irc-connect conn)

62(irc-join conn "#mychannel")

63(irc-run conn)

64```

66### Browser/WASM IRC over WebSocket

68```scheme

69(import (sigil irc))

71(define session

72 (irc-ws-connect

73 url: "wss://enclave.example/irc"

74 nick: "web-client"))

76(irc-ws-register session)

77(irc-ws-privmsg session "#sigil" "hello")

79(let ((msg (irc-ws-receive session)))

80 (when (irc-message? msg)

81 (display (irc-message-command msg))

82 (newline)))

83```

85### Server (consumer drives I/O)

87```scheme

88(import (sigil irc message)

89 (sigil irc cap-negotiation)

90 (sigil irc capability)

91 (sigil irc sasl)

92 (sigil irc numerics))

94;; Build per-connection state

95(define cap (make-cap-server-state

96 server-name: "enclave.example"

97 supported: (list (make-cap CAP-SASL value: "PLAIN,EXTERNAL")

98 (make-cap CAP-MESSAGE-TAGS)

99 (make-cap CAP-SERVER-TIME)

100 (make-cap CAP-BATCH)

101 (make-cap CAP-LABELED-RESPONSE))))

102

103(define sasl-state

104 (make-sasl-server-state

105 supported-mechanisms: (list SASL-PLAIN SASL-EXTERNAL)

106 server-name: "enclave.example"

107 verify: my-password-checker))

108

109;; Inside your accept fiber, on each line:

110(let* ((msg (parse-irc-message line))

111 (cap-out (cap-server-advance cap msg client-nick: nick))

112 (sasl-out (sasl-server-advance sasl-state msg client-prefix: nick)))

113 (for-each write-line cap-out)

114 (for-each write-line sasl-out))

115```

116

117### Identity is per-server from day one

118

119```scheme

120(import (sigil irc identity))

121

122(define alice (make-irc-identity "alice" "enclave.example"))

123(irc-identity->canonical alice) ; => "[email protected]"

124(irc-identity->display alice) ; => "alice" (default: nick only)

125(irc-identity->display alice show-server?: #t)

126 ; => "[email protected]"

127```

128

129

This is a federation-readiness constraint: future CrafterNet sovereign-per-server federation hinges on identities being qualified from day one. Local-display helpers strip the suffix for UX; storage and protocol always use the canonical form.

130

131## Modules

132

133| Module | Purpose |

134|--------|---------|

135| `(sigil irc)` | Top-level re-exports |

136| `(sigil irc message)` | Line parsing/serialization, IRCv3 tags |

137| `(sigil irc tags)` | Typed tag accessors (server-time, account, batch, label, …) |

138| `(sigil irc identity)` | Qualified `nick@server` identity |

139| `(sigil irc numerics)` | Numeric reply constants |

140| `(sigil irc capability)` | Capability descriptors, Tier 1+2 names |

141| `(sigil irc cap-negotiation)` | CAP state machines (client + server) |

142| `(sigil irc sasl)` | SASL state machines (PLAIN, EXTERNAL, mechanism dispatch) |

143| `(sigil irc sasl-scram)` | SCRAM-SHA-256 driver (RFC 5802/7677) |

144| `(sigil irc batch)` | BATCH command + tag helpers |

145| `(sigil irc chathistory)` | CHATHISTORY query parser/serializer |

146| `(sigil irc read-marker)` | `draft/read-marker` (MARKREAD) helpers |

147| `(sigil irc monitor)` | MONITOR command + numeric reply builders |

148| `(sigil irc connection)` | High-level client convenience API (TLS, event loop) |

149

150## Dependencies

151

152- sigil-socket (TCP)

153- sigil-tls (TLS for the convenience client)

154- sigil-crypto v0.15.0+ (base64, HMAC, PBKDF2 — SCRAM needs the v0.15 SHA-256 byte primitives)

155The optional `sigil-irc-websocket` package also depends on:

156

157- sigil-irc

158- sigil-websocket

159

160## Building / testing

161

162```bash

163sigil deps install

164sigil test

165```

166

167

For development against unreleased sibling packages, use a `dev-redirects.sgl` and run `sigil test --redirects ./dev-redirects.sgl`.

168

169## License

170

171BSD-3-Clause