dIRC Services Overview (dircservices)

The dircservices package is a standalone IRC services daemon — a server-to-server (S2S) peer that links into UnrealIRCd as a U:Lined services host (services.dlan) and spawns 14 pseudoclients services (NickServ, ChanServ, GroupServ, OperServ, Global, HostServ, BotServ, ALIS, GameServ, StatServ, SecureServ, IdleRPGServ, LoveServ, HelpServ). It is the dLAN alternative to Anope/OperStats, written in pure Go with no CGO and no AI dependencies.

Scope note: dircservices builds as a standalone binary (dircservices/cmd/dircservices/) for dev/smoke use, but in production it runs in-process inside the main dLANDiscord monolith, launched non-blocking via dircservices.Start() (commit d336f939) — same process, same crash domain as the Discord bot. It remains explicitly decoupled in responsibility from the dirc client package and the AI assistant system — the dirc client connects as a regular IRC user, while dircservices links as an ircd peer that owns nickname/channel registration, operator tooling, and games.

Origin & Status

Built in three waves starting 2026-07-23 (see docs/dLAN_Services_DevLog.md and docs/dIRC_Analysis.md):

Current state: 14 services operational, lifecycle hardened (panic recovery + auto-reconnect with exponential backoff), SJOIN trailing-member bug fixed, per-service .md docs shipped in 13 EN.*.md files.

Architecture

graph TB
    subgraph ircd[UnrealIRCd irc.dlan:6700]
        UL[U:Lined services.dlan link]
    end

    subgraph dircservices[dircservices binary]
        CFG[config TopLevelConfig]
        ST[store.Store SQLite WAL]
        P[protocol/unreal4 S2S]
        UR[state.UserRegistry]
        CR[state.ChannelRegistry]
        REG[services.Registry]
        ID[pseudoclient.IdentifiedMap]
        SVCS[14 Service pseudoclients]
    end

    UL <--> P
    P --> UR
    P --> CR
    CFG --> ST
    REG --> SVCS
    SVCS --> P
    SVCS --> ST
    SVCS --> UR
    SVCS --> CR
    SVCS --> ID

Package Layout

The 14 Services

Connection & Wire Protocol

• Uplink: irc.dlan:6700 (LAN plaintext; ircd set::plaintext-policy::server allow), services SID 00X, server name services.dlan (U:Lined)
• Handshake order (UnrealIRCd requires this exact sequence): PASS → PROTOCTL NOQUIT TOKEN SSJ3 ... PROTOCOL=1202 → PROTOCTL EAUTH=services.dlan → PROTOCTL SID=00X → PROTOCTL TS=<unix> → SERVER services.dlan 1 :dLAN IRC Services → peer SERVER + EOS marks sync (Unreal uses EOS, not Anope's SVINFO)
• Read loop: Run() bool — returns true on read error, false on clean stop (Close()). Either outcome ends the current runOnce() cycle; the outer loop in run() waits 60s then re-dials and re-bursts every pseudoclient from scratch (no partial reconnect).
• Pseudoclient intro: :00X UID NickServ 1 1234567890 services services.dlan 00XAAAAAA 0 +BioS * * * :dLAN Nickname Service — UID is 9 chars total (3-char SID + 6-char base62 suffix, per UnrealIRCd's UID command spec). A prior bug generated 6-char UIDs (3+3): the SERVER link still came up fine, but UnrealIRCd silently dropped every introduced pseudoclient — /MAP showed the link with 0 users and /whois NickServ returned "No such nick", with no error anywhere in our own logs. Fixed in protocol/unreal4/uid.go's encodeUID.

SQLite Store

• Driver: modernc.org/sqlite (pure-Go, no CGO)
• DSN: WAL mode + foreign_keys=ON + busy_timeout=5000 + MaxOpenConns=1 (serial)
• Startup: integrity_check → if fail, restoreFromBackup() (newest OK .db from data/backups/) or reinit
• ~40 tables across all services + 21 hot indexes; schema_version row, INSERT OR IGNORE
• Background tickers: wal_checkpoint(TRUNCATE) every 5m + snapshot VACUUM INTO services-YYYYMMDD-HHMM.db every 24h, prune keep N (default 7)
• Known gotcha: group_members.group renamed to group_name because group is a SQLite reserved word (commit ae91b304)
• OperServ UPDATE calls store.ForceBackup() (snapshot + prune immediately)

Build & Run

go build -o dircservices ./dircservices/cmd/dircservices/
./dircservices    # reads dircservices/config.example.json (or ../config.example.json)
go test ./dircservices/...   # 4 unreal4 tests (dispatch/parse round-trip)

Configuration: dircservices/config.example.json (mirrors §7 of docs/dLAN_Services_Plan.md, LAN-only creds shipped in tree). DefaultConfig() fallback if no file found.

Lifecycle & Robustness

• Panic recovery: every pseudoclient dispatch() wraps handler with defer recover() → logs [PANIC] + replies "Internal error" (no goroutine death)
• Cycle-level panic: runOnce()'s defer recover() logs [FATAL], clears the published status snapshot, and closes the protocol connection — it does not close the shared store.Store or call os.Exit, since dircservices runs as a goroutine inside the main dLANDiscord process (same shared-fate risk as dmud) and exiting the process would take the whole Discord bot down with it. The outer run() loop then re-dials after 60s.
• Reconnect: any link loss (read error) or OperServ SHUTDOWN/RESTART/QUIT ends the current runOnce() cycle; run()'s outer loop rebuilds everything from scratch next pass — fresh Protocol, fresh registries, fresh 14-service UID burst + EOS. No partial-resume: UnrealIRCd forgets our pseudoclients the moment the S2S link drops, so a bare TCP re-dial without a fresh burst would leave services silently ghosted on the network.
• Shutdown: OperServ SHUTDOWN/RESTART/QUIT signals stopCh → registry.StopAll() (reverse order) ends the cycle → outer loop sleeps 60s and re-links (in-process module, never os.Exits itself). The standalone cmd/dircservices/main.go wrapper additionally listens for SIGINT/SIGTERM, but only logs and returns — it does not call registry.StopAll()/store.Close() first, so a signaled standalone process skips graceful teardown.
• File logging: cfg.Log.Target → log dir creation, rotate rename to .bak if older than LogAgeDays, io.MultiWriter(stdout + file)

Integration with the dIRC Client

Explicitly decoupled: dirc (the IRC client package) connects as a regular IRC user, while dircservices is the S2S services peer. The dev work that touched dirc for this effort was a pre-M1 fix (c0f7683e): default SASL off + Anope-compatible NickServ flow for UnrealIRCd — to make the Unreal link behave well alongside services.

See: Features/dircservices/services-suite.md for per-service deep-dive · Key-Packages/dirc/overview.md for the IRC client

Dashboard (dircserviceweb)

dircserviceweb (separate package, dircserviceweb/) is a read-only HTTP dashboard on :16667 — a nod to the classic IRC client port (6667), not an IRC listener itself; it's plain HTTP on the bot host, launched non-blocking (go dircserviceweb.Start() in main.go, right after dircservices.Start()). Plain :6667 doesn't work as an HTTP port: Chrome/Firefox/Edge all block http:// requests to the 6660-6669 + 6697 range (their built-in "unsafe ports" list, a legacy cross-protocol-attack defense) — 16667 dodges that. It has no dependency on the ircd — it reads dircservices.Status(), a Snapshot published by runOnce() after each successful burst (dircservices/status.go), covering:

• Link state, uplink host/SID, registered service list
• Live user/channel counts + listings from UserRegistry/ChannelRegistry (network-wide, since we're U:Lined — not just our own pseudoclients)
• Registration stats pulled straight from store.Store each request: registered nicks/channels/groups, vhosts assigned, active AKILLs
• SecureServ's persisted lifetime event counts: DNSBL hits, clone events, flood events, proxy detections
• StatServ's most recent snapshot: top 5 channels/users by activity (empty until the snapshot loop has run once, default every 5m)

GET / renders the HTML view (auto-refresh every 10s); GET /status.json exposes the same Snapshot as JSON. No auth — matches the existing LAN single-admin trust model (see config.example.json's shipped plaintext link password), so don't expose :16667 outside the LAN without adding one first.

Guidance for AI Agents

• No AI integration: dircservices deliberately excludes all assistant/ imports — any "smart" IRC behavior still goes through the dirc client + assistant pipeline, not the services daemon.
• Schema edits: DB is not yet in production deployment — schema changes can use clean CREATE TABLE (no migration). Once deployed, add ALTER paths.
• New service: implement Service interface in services/<name>/<name>.go, add doc docs/EN.<Name>.md, register in main.go, document here.
• Event wiring: services hook OnPrivmsg/OnUIDIntroduce/etc. via proto.On* setters — the protocol appends multiple subscribers safely (RLock + snapshot copy).
• Oper gate: pseudoclient.IsOper(cfg, nick, identified) requires BOTH a nick match against cfg.Opers AND identified (the caller's UID present in the shared IdentifiedMap, i.e. they IDENTIFY'd with NickServ) — nickname alone is not proof of identity, since anyone can /nick into an oper's name before enforcement reclaims it. Every service exposing oper-only commands wires SetIdentifiedMap.
• Channel presence (2026-07-25): cfg.OpersChannel (default #Opers) is auto-joined by every pseudoclient inside Pseudoclient.Register() — one config knob, all 13 services idle there for opers to see at a glance. protocol.JoinChannel (self-introducing SJOIN) now always includes the @ op-status prefix, since a services pseudoclient sitting in a channel unopped can't enforce anything there; SVSJoin (forcing an existing UID — human or another pseudoclient like an assigned BotServ bot) still grants no status by design, so callers that need the target opped (e.g. BotServ.joinBot) follow it with an explicit MODE +o.
• Speaking as a pseudoclient in a channel: use pc.ReplyChannel(channel, text) / proto.PrivmsgAs(uid, target, text), not PrivmsgUID/NoticeUID — those two always send from the bare server SID, which isn't a channel member and isn't who should visibly be talking.

Cross-References

• dircserviceweb/ — HTTP dashboard package (:16667), reads dircservices.Status()
• Features/dircservices/services-suite.md — per-service command reference
• Key-Packages/dirc/overview.md — IRC client (separate from services daemon)
• Recent-Changes-and-Evolution.md — July 2026 entry
• docs/dLAN_Services_DevLog.md — chronological build log
• docs/dLAN_Services_Plan.md — original spec (~20 commands per service, schema, milestones)
• docs/dIRC_Analysis.md — dirc/Anope analysis that motivated the rewrite