IRC Client Foundations Supplement

Version: 1.0 Status: Ready for implementation Companion to: docs/pdf.md (feature PRD) Purpose: Build-from-scratch decisions for the embeddable rabbot-irc gem

How to use this document

The main PRD (pdf.md) covers mIRC/Ibis feature parity, phased deliverables, services caveats, and the Fandom companion bot. This supplement covers everything needed before rails new or gem scaffolding: packaging, auth, schema, workers, embed API, formatter spec, dialog triage, deployment, and tests.

Decisions locked in for v1:

• Gem, not monorepo app — embeddable IRC chat usable in any Rails app

• Optional Rails accounts — anonymous connect works; accounts unlock persistence + companion bot

• Embeddable UI — mount into any DOM element, not only full-screen

14. Gem packaging and embed API

14.1 Gem name and repos

rabbot-irc depends on rabbot-core and ircinch. Host apps add gem "rabbot-irc" and mount or embed.

14.2 Engine structure

rabbot-irc/
  lib/rabbot/irc/
    engine.rb                    # Rails::Engine, isolated namespace Rabbot::Irc
    version.rb
  app/channels/irc_channel.rb
  app/controllers/rabbot/irc/
  app/javascript/controllers/irc_chat_controller.js
  app/views/rabbot/irc/chat/     # partials: log, nicklist, input, status
  app/services/rabbot/irc/
  config/routes.rb
  lib/generators/rabbot/irc/install/

14.3 Host app integration

Full-page mount (optional):

# config/routes.rb
mount Rabbot::Irc::Engine => "/irc"

Embed in any view:

<div id="sidebar"
     data-controller="irc-chat"
     data-irc-chat-layout-value="compact"
     data-irc-chat-session-url-value="<%= rabbot_irc_session_path %>">
</div>

Generator:

rails generate rabbot:irc:install
rails db:migrate

Copies migrations for irc_* tables; adds importmap/Stimulus pin for irc_chat_controller.

14.4 Embed contract

14.5 Architecture diagram

HostApp (any Rails app)
  ├── mount Rabbot::Irc::Engine => "/irc"     [optional full page]
  └── embed <div data-controller="irc-chat">  [any DOM element]
           │
           ▼
      irc_chat_controller (Stimulus)
           │
           ▼
      ActionCable (IrcChannel)
           │
           ▼
      IrcWorker process (bin/irc_worker)
           │
           ▼
      Cinch (ircinch) ↔ IRC server

15. Auth and sessions

15.1 Two tiers

Anonymous users get live chat while the tab is open. Creating an account (or signing in) unlocks saved network profiles, IrcEventStore replay, and companion bot settings.

15.2 Session model

• IrcSession — ephemeral record tying browser tab(s) to one IRC worker connection or catch-up cursor

• User — host-app model (Devise, etc.); gem provides Rabbot::Irc::Authenticatable concern

• ActionCable auth — IrcChannel rejects subscribe without valid signed_session_id (Rails.application.message_verifier(:irc_session))

• Multi-tab — same IrcSession id → shared stream; last_event_id in server session + localStorage backup per channel

15.3 Anonymous limits

• No IrcEventStore replay beyond the current live connection

• No companion bot

• No saved IrcNetworkProfile (form fields may use session only)

• Disconnect when last tab unsubscribes and session expires

15.4 Account unlocks

• Persisted network profiles and encrypted credentials

• Companion bot (§13 in main PRD)

• Cross-device cursor sync via user_id

• Channel/query log download (Phase 2)

16. Data model

Host app runs engine migrations via rails rabbot:irc:install:migrations.

16.1 Tables

16.2 irc_events schema (key fields)

Index: (user_id, monotonic_id), (user_id, network, channel, monotonic_id).

16.3 Retention

Defaults (configurable via Rabbot::Irc.configure):

• 7 days or 50,000 events per user (whichever limit hit first)

• Compaction job (IrcEventCompactionJob) runs nightly; see §21

16.4 Database

Web platform (rabbot-irc):

• Production: PostgreSQL required (concurrent workers, jsonb, partitioning, read replicas)

• Development: SQLite acceptable for a single local worker

Legacy Rabbot personas:

• Keep SQLite per bot (data/rabbot.db, data/bots/*.db) for plugin state (games, AI, autoop, etc.)

• Do not migrate bot SQLite to Postgres unless cross-bot queries are needed

Shared boundary (Postgres only):

• users, irc_events, irc_sessions, irc_companion_profiles, and companion sync data

• Companion bots write replay events to the web Postgres store, not their local SQLite files

17. IRC worker architecture

17.1 Library

Use Cinch (ircinch) — same as existing Rabbot. Do not use Net::IRC or EventMachine for the web client worker.

17.2 Process model

IrcReadJob is for short tasks only (parse MOTD, probe capabilities) — not holding IRC sockets inside Solid Queue workers.

17.3 Worker loop

1. IrcWorker polls irc_connections for pending / stop commands (DB row or Redis list)

2. Spawns Cinch bot per active irc_connection

3. On IRC event → format → broadcast ActionCable + optionally append irc_events

4. On disconnect → update state; apply reconnect policy from IrcReconnectGuard patterns (lib/irc_reconnect_guard.rb): throttle floor, drone floor, connect stagger

17.4 Connection lifecycle by phase

17.5 Duplicate event rule

When the user’s web session is online (active Cinch connection), log events from that connection only. Companion bot appends to irc_events only when the user connection is absent (tab closed, invisible bouncer mode). Prevents duplicate lines on reconnect.

18. Routes, UI map, and Turbo structure

Engine routes (under mount prefix, e.g. /irc):

18.1 Turbo layout (inside mount element)

[data-controller="irc-chat"]
  turbo-frame#irc-channel-list
  turbo-frame#irc-main
    turbo-frame#irc-log
    turbo-frame#irc-nicklist
  turbo-frame#irc-status
  form#irc-input → POST /messages

18.2 Input routing

19. style.ibis formatter spec (Phase 1)

Map reference/stuff/style.ibis to Rabbot::Irc::EventFormatter. Colour variables from vars.ibis / identifiers1.ibis become IrcClientConfig defaults (mIRC indices 0–98).

19.1 Event templates

19.2 Web-specific mapping

19.3 Golden tests

Add test/fixtures/irc/style_ibis_events.yml with input IRC hashes + expected HTML/mIRC formatted output. Reuse existing IrcFormat test patterns from rabbot-core.

20. Dialog priority matrix

Legacy scan found 20 dialogs; most are not worth porting.

21. Deployment and environment

21.1 Processes

21.2 Environment variables

RABBOT_IRC_WORKER_COUNT=2
RABBOT_IRC_EVENT_RETENTION_DAYS=7
RABBOT_IRC_EVENT_RETENTION_MAX=50000
RABBOT_IRC_ACTION_CABLE_ADAPTER=redis
RABBOT_IRC_COMPANION_ENABLED=true
RABBOT_THROTTLE_RECONNECT_FLOOR=6
RABBOT_DRONE_RECONNECT_FLOOR=8
RABBOT_MESH_HOST=127.0.0.1

21.3 Secrets

• IRC passwords and SASL secrets: Active Record Encryption on irc_credentials

• Never log PASS, IDENTIFY, or raw SASL payloads (main PRD §7)

• Fandom URL fetch: allowlist *.fandom.com only (SSRF guard for profile generator)

21.4 Health check

GET /irc/health returns JSON:

{ "workers_alive": 2, "active_connections": 14, "oldest_ping_sec": 3 }

22. Test plan

22.1 Companion bot tests

• Invisible mode: simulate tab close (session unsubscribe) → worker continues → GET /sync?since= returns missed events

• Visible mode (Phase 3): bot JOIN mirrors user channel set

• Disable companion: assert Cinch QUIT within 10s; no ghost nick after 60s

22.2 Embed tests

• Mount irc-chat in non-full-page div; assert channel list and log render inside host bounds

• layout=compact hides nick list until toggled

23. Scale and data plane (later phases)

Not required for MVP. Documented for growth toward large user counts.

23.1 Data stores

23.2 Application boundaries

• Rust (rabbot-irc-core): IRC parse, connection multiplexer, WebSocket gateway when Ruby density limits hit

• Rails: UI, auth, settings, companion profile generation

• Sharding: by user_id; regional worker pools; own ircd leaf at 100k+ concurrent users

• Public IRC: not 1:1 connections at millions of users — product needs own network or pooled bouncers

23.3 Deferred infrastructure

• Proxmox / VM HA: defer until service boundaries are stable; IRC TCP sessions require app-level reconnect regardless of hypervisor failover

• Bot SQLite: remains for persona plugins; only web/shared data moves to Postgres

24. Federated capacity (mesh donate)

Optional community capacity — extends the spirit of DirectchatMesh, with a new control plane.

24.1 Model

• Rabbot operators opt in to donate connection slots plus CPU/memory caps (absolute limits, not percentage alone)

• Central scheduler assigns web users to volunteer workers

• Volunteers run standard worker images; no primary Postgres on volunteer nodes

• Trust tiers; scoped tokens; invisible bouncer default

24.2 Non-goals

• Open P2P with long-lived IRC passwords on arbitrary nodes

• Volunteers as source of truth for user data

• Replacing owned Redis/Postgres infrastructure

End of foundations supplement. Feature scope remains in pdf.md. Script inventory: ibis-script-reference.md.