From 476b94967eddfec862ac3a30d783588a0bd1f82e Mon Sep 17 00:00:00 2001 From: user Date: Sun, 15 Feb 2026 13:11:40 +0100 Subject: [PATCH] docs: document debounced oper detection on JOIN Co-Authored-By: Claude Opus 4.6 --- docs/CHEATSHEET.md | 3 ++- docs/USAGE.md | 16 +++++++++++++++- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/CHEATSHEET.md b/docs/CHEATSHEET.md index 2864b25..8eaeab2 100644 --- a/docs/CHEATSHEET.md +++ b/docs/CHEATSHEET.md @@ -85,7 +85,8 @@ make logs # Follow logs admins = ["*!~user@trusted.host", "ops!*@*.ops.net"] ``` -IRC operators are auto-detected via WHO. Hostmask patterns use fnmatch. +IRC operators are auto-detected via WHO on connect and on user JOIN +(debounced 2s to handle netsplit floods). Hostmask patterns use fnmatch. ## Channel Management (admin) diff --git a/docs/USAGE.md b/docs/USAGE.md index 2a6ff67..b9464d6 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -206,7 +206,7 @@ Default format is `"text"` (human-readable, same as before). Commands marked as `admin` require elevated permissions. Admin access is granted via: -1. **IRC operator status** -- detected automatically via `WHO` on channel join +1. **IRC operator status** -- detected automatically via `WHO` 2. **Hostmask patterns** -- configured in `[bot] admins`, fnmatch-style ```toml @@ -220,6 +220,20 @@ admins = [ Empty by default -- only IRC operators get admin access unless patterns are configured. +### Oper Detection + +IRC operators are detected via the `*` flag in `WHO` replies. Detection +happens at two points: + +- **On connect** -- `WHO #channel` for each configured channel +- **On user JOIN** -- debounced `WHO #channel` (2-second window) + +The debounce prevents flooding the server during netsplit recovery: many +rapid JOINs produce a single `WHO` per channel. Note that the first +command after joining may not yet have oper status -- the debounced WHO +fires after a 2-second delay. Users who `QUIT` are removed from the oper +set automatically. + | Command | Description | |---------|-------------| | `!whoami` | Show your hostmask and admin status |