IRC-kosmi-relay/QUICK_REFERENCE.md

Quick Reference Guide

Testing the Bridge

Build and Run Test Program

cd /Users/erikfredericks/dev-ai/HSO/irc-kosmi-relay
go build -o test-kosmi ./cmd/test-kosmi
./test-kosmi -room "https://app.kosmi.io/room/@hyperspaceout" -debug

Expected Output (Success)

INFO Launching headless Chrome for Kosmi connection
INFO Injecting WebSocket interceptor (runs before page load)...
INFO Navigating to Kosmi room: https://app.kosmi.io/room/@hyperspaceout
INFO ✓ WebSocket hook confirmed installed
INFO Status: WebSocket connection intercepted
INFO Successfully connected to Kosmi via Chrome
INFO Listening for messages... Press Ctrl+C to exit

When Messages Arrive

INFO Processing 1 messages from queue
INFO Received message: [00:02:51] username: [Kosmi] <username> message text

Key Status Indicators

Status Message	Meaning	Action
✓ WebSocket hook confirmed installed	Hook script is active	✅ Good
Status: WebSocket connection intercepted	WebSocket is being captured	✅ Good
Status: No WebSocket connection detected yet	Hook missed the WebSocket	❌ Check injection timing
Processing N messages from queue	Messages are being captured	✅ Good

Common Issues

Issue: "No WebSocket connection detected yet"

Cause: WebSocket hook was injected too late

Fix: Verify injectWebSocketHookBeforeLoad() uses page.AddScriptToEvaluateOnNewDocument

Issue: "Chrome not found"

Cause: Chrome/Chromium not installed or not in PATH

Fix:

# macOS
brew install --cask google-chrome

# Ubuntu/Debian
sudo apt install chromium-browser

# Verify installation
which google-chrome chromium chromium-browser

Issue: Messages not appearing

Cause: Multiple possibilities

Debug:

1. Check for "✓ WebSocket hook confirmed installed" ✓
2. Check for "Status: WebSocket connection intercepted" ✓
3. Enable debug logging: -debug flag
4. Send a test message in the Kosmi room
5. Look for "Processing N messages from queue"

Configuration

Minimal Test Configuration

[kosmi.test]
RoomURL="https://app.kosmi.io/room/@hyperspaceout"
Debug=true

Full Matterbridge Configuration

# Kosmi
[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@hyperspaceout"

# IRC
[irc.libera]
Server="irc.libera.chat:6667"
Nick="kosmi-relay"
UseTLS=false

# Gateway
[[gateway]]
name="kosmi-irc"
enable=true

[[gateway.inout]]
account="kosmi.hyperspaceout"
channel="main"

[[gateway.inout]]
account="irc.libera"
channel="#your-channel"

Message Format

Kosmi → IRC

[Kosmi] <username> message text

IRC → Kosmi

[IRC] <username> message text

File Locations

File	Purpose
bridge/kosmi/kosmi.go	Main bridge implementation
bridge/kosmi/chromedp_client.go	Headless Chrome client
bridge/kosmi/graphql.go	GraphQL structures (legacy)
cmd/test-kosmi/main.go	Standalone test program
matterbridge.toml	Configuration file

Key Implementation Details

WebSocket Hook Injection

MUST use page.AddScriptToEvaluateOnNewDocument to inject before page load:

chromedp.ActionFunc(func(ctx context.Context) error {
    _, err := page.AddScriptToEvaluateOnNewDocument(script).Do(ctx)
    return err
})

Hook Script

Wraps window.WebSocket constructor to intercept all WebSocket connections:

window.WebSocket = function(url, protocols) {
    const socket = new OriginalWebSocket(url, protocols);
    // ... interception logic ...
    return socket;
};

Debugging Commands

# Test Chrome installation
which google-chrome chromium chromium-browser

# Test network connectivity
curl -I https://app.kosmi.io

# Build with verbose output
go build -v -o test-kosmi ./cmd/test-kosmi

# Run with debug logging
./test-kosmi -room "https://app.kosmi.io/room/@hyperspaceout" -debug

# Check for linter errors
go vet ./...

Performance Notes

• Chrome Startup: ~1-2 seconds
• Page Load: ~1-2 seconds
• Message Latency: ~100-500ms
• Memory Usage: ~100-200MB (Chrome process)

Security Considerations

• Bridge runs Chrome in headless mode (no GUI)
• No credentials stored (anonymous access)
• WebSocket traffic is intercepted in memory only
• Messages are not logged to disk (unless debug logging enabled)

Production Deployment

systemd Service Example

[Unit]
Description=Kosmi-IRC Relay
After=network.target

[Service]
Type=simple
User=matterbridge
WorkingDirectory=/opt/matterbridge
ExecStart=/opt/matterbridge/matterbridge -conf /etc/matterbridge/matterbridge.toml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Docker Considerations

When running in Docker, ensure:

• Chrome/Chromium is installed in the container
• --no-sandbox flag may be needed for Chrome
• Sufficient memory allocation (512MB minimum)

Resources

• Documentation: See README.md, QUICKSTART.md, LESSONS_LEARNED.md
• Integration Guide: See INTEGRATION.md
• Implementation Details: See IMPLEMENTATION_SUMMARY.md
• ChromeDP Guide: See CHROMEDP_IMPLEMENTATION.md

Support

For issues:

1. Check this quick reference
2. Review LESSONS_LEARNED.md for common patterns
3. Enable debug logging for detailed output
4. Check Chrome console logs in debug mode