patter

A modern Rust library for IRC + IRCv3 — parsing, connection, state.

The published Rust IRC crate of record was written in 2019 and stops at RFC 1459. patter-irc picks up where that left off: comprehensive IRCv3 support, modern async (tokio), TLS by default (rustls), and an ergonomic command/event API designed to be the protocol layer behind any frontend — TUIs, bots, bridges, mobile clients, GUI clients.

[dependencies]
patter-irc = "0.1"

use patter_irc::{Client, ClientCommand, ClientEvent, ServerConfig};
use tokio::sync::mpsc;

let config = ServerConfig {
    host: "irc.libera.chat".into(),
    port: 6697,
    tls: true,
    nick: "patterbot".into(),
    ..Default::default()
};

let (event_tx, mut event_rx) = mpsc::unbounded_channel();
let (cmd_tx, cmd_rx) = mpsc::unbounded_channel();

let client = Client::connect(config, event_tx, cmd_rx).await?;
tokio::spawn(client.run());

while let Some(event) = event_rx.recv().await {
    if let ClientEvent::Registered { .. } = event {
        cmd_tx.send(ClientCommand::Join { channel: "#patter".into() })?;
    }
}

A runnable echo-bot example lives at crates/patter-irc/examples/echo_bot.rs.

What's in the box

• Wire format: RFC 1459 + IRCv3 message-tags, parsed into typed values. Round-trips clean — the parser is paired with a Display impl that re-emits valid wire format.
• Connection: TLS by default via rustls + webpki-roots, with TrustOnFirstUse cert pinning, configurable verifier modes, and token-bucket flood protection on user-originated PRIVMSGs.
• High-level client: Client::connect returns a handle. You send ClientCommands, receive ClientEvents. Capability negotiation, SASL (PLAIN + EXTERNAL), keepalive PINGs, and reconnection ride underneath; you don't have to spell them.
• State: per-channel members, modes, topic, scrollback ring, IRCv3-aware tracking (msgids, batch boundaries, away states).

IRCv3 capabilities

Capability	Status
message-tags	✓
server-time	✓
away-notify	✓
chathistory (BATCH)	✓
labeled-response	✓
multi-prefix	✓
sasl (PLAIN, EXTERNAL)	✓
draft/typing (6s TTL)	✓
draft/react	✓
draft/reply	✓
draft/read-marker	✓
account-notify	planned
batch (general)	planned
bot mode	planned
cap-notify	planned
chghost	planned
echo-message	planned
extended-join	planned
invite-notify	planned
Monitor	planned
multiline	planned
setname	planned
Standard Replies	planned
userhost-in-names	planned
WHOX	planned

The "planned" set tracks what Halloy negotiates internally — the goal is to publish parity-or-better as a reusable crate, since their protocol layer is private to their workspace.

Why a new crate?

The existing irc-proto dates from 2019 and predates most IRCv3 specs that matter today (message-tags, BATCH, labeled-response, chathistory, draft/typing, draft/react, draft/reply, MARKREAD). Halloy has a strong internal protocol layer but doesn't publish it. There's no good "I want to write an IRC bot or bridge in 2026" choice on crates.io. patter-irc fills that gap.

Reference frontend

patter-desktop is a native IRC desktop client built on patter-irc + egui. It exists primarily to dogfood the library on a non-trivial UI; it's a real working client, not a toy.

Build and run:

cargo run -p patter-desktop

For accessibility (VoiceOver, AT-SPI, UIA) the binary needs to run from inside a .app bundle on macOS. See docs/BUNDLING.md for a minimal recipe.

Workspace

• crates/patter-irc — the library (this is the published crate)
• crates/patter-desktop — reference egui frontend, dogfood demo

Stability

Pre-1.0. The high-level Client API is the most stable surface. message and command modules may evolve as IRCv3 specs land. Breaking changes will be called out in CHANGELOG.md and follow semver.

License

AGPL-3.0-only.