HyperSpaceOut/IRC-kosmi-relay
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: comprehensive documentation overhaul

Browse Source 
Rewrite README.md and all setup guides to reflect the current native
GraphQL WebSocket architecture (replacing stale headless Chrome/WebSocket
interception descriptions). Add new docs/IRC.md with complete IRC command
reference, vote syntax, and ticker symbol table.

Archive pre-edit docs to docs/archive/setup-backup-2026-05-10/ and move
historical development notes from docs/ root into docs/archive/.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cottongin
2026-05-12 22:01:25 -04:00
parent 4188ae29af
commit c88b75f30d
57 changed files with 4530 additions and 1994 deletions
Download Patch File Download Diff File Expand all files Collapse all files

293
docs/setup/QUICK_REFERENCE.md
View File

@@ -1,237 +1,204 @@
# Quick Reference Guide
## Testing the Bridge
## Running the Bridge
### Build and Run Test Program
### Build and Run Locally
```bash
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
go build -o matterbridge .
./matterbridge -conf matterbridge.toml
```
### Run with Docker
```bash
docker-compose up -d
docker-compose logs -f
```
### 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
INFO Connecting to Kosmi
INFO Extracted room ID: @yourroom
INFO No credentials provided, using anonymous access
INFO Successfully connected to Kosmi
INFO Connection succeeded (IRC)
INFO Gateway(s) started successfully. Now relaying messages
```
### When Messages Arrive
If using email/password authentication:
```
INFO Processing 1 messages from queue
INFO Received message: [00:02:51] username: [Kosmi] <username> message text
INFO Authenticating with email/password...
INFO ✅ Authentication successful
INFO Successfully connected to Kosmi
```
## 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 |
| Log Message | Meaning |
|-------------|---------|
| `Successfully connected to Kosmi` | Native WebSocket connection established |
| `Connection succeeded (IRC)` | IRC bridge is connected |
| `Gateway(s) started successfully` | All bridges up, relay is active |
| `✅ Using cached token` | Reusing saved JWT (no browser needed) |
| `✅ Authentication successful` | Browser login completed |
| `Kosmi connection lost unexpectedly` | WebSocket dropped, auto-reconnect triggered |
## Common Issues
## IRC Commands
### Issue: "No WebSocket connection detected yet"
| Command | Action |
|---------|--------|
| `!kreconnect` | Reconnect Kosmi bridge |
| `!jreconnect` | Reconnect Jackbox WebSocket |
| `!reconnect` | Reconnect all non-IRC services |
| `!votes` | Show current game vote tally |
**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**:
```bash
# 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"
See [IRC.md](../IRC.md) for full details including vote syntax and ticker symbols.
## Configuration
### Minimal Test Configuration
### Minimal Configuration
```toml
[kosmi.test]
RoomURL="https://app.kosmi.io/room/@hyperspaceout"
Debug=true
```
[kosmi.myroom]
RoomURL="https://app.kosmi.io/room/@yourroom"
### Full Matterbridge Configuration
```toml
# Kosmi
[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@hyperspaceout"
# IRC
[irc.libera]
Server="irc.libera.chat:6667"
[irc.myserver]
Server="irc.libera.chat:6697"
Nick="kosmi-relay"
UseTLS=false
UseTLS=true
# Gateway
[[gateway]]
name="kosmi-irc"
enable=true
[[gateway.inout]]
account="kosmi.hyperspaceout"
account="kosmi.myroom"
channel="main"
[[gateway.inout]]
account="irc.libera"
account="irc.myserver"
channel="#your-channel"
```
### With Authentication
```toml
[kosmi.myroom]
RoomURL="https://app.kosmi.io/room/@yourroom"
Email="your-email@example.com"
Password="your-password"
```
### With Jackbox Integration
```toml
[jackbox]
Enabled=true
APIURL="https://your-jackbox-api.example.com"
AdminPassword="your_password"
UseWebSocket=true
EnableRoomCodeImage=true
```
## Message Format
### Kosmi → IRC
### Kosmi --> IRC
```
[Kosmi] <username> message text
[kosmi] <username> message text
```
### IRC → Kosmi
### IRC --> Kosmi
```
[IRC] <username> message text
[irc] <username> message text
```
Format is controlled by `RemoteNickFormat` in each bridge's config section.
## 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 |
| `bridge/kosmi/kosmi.go` | Main Kosmi bridge |
| `bridge/kosmi/graphql_ws_client.go` | Native GraphQL WebSocket client |
| `bridge/kosmi/auth.go` | Anonymous login |
| `bridge/kosmi/browser_auth.go` | Chromedp browser login |
| `bridge/kosmi/token_cache.go` | JWT token caching |
| `bridge/irc/handlers.go` | IRC commands and vote detection |
| `bridge/jackbox/client.go` | Jackbox API client |
| `bridge/jackbox/votes.go` | Vote detection logic |
| `matterbridge.toml` | Runtime configuration |
## Key Implementation Details
## Common Issues
### WebSocket Hook Injection
### Kosmi connection fails
**MUST** use `page.AddScriptToEvaluateOnNewDocument` to inject **before page load**:
1. Verify `RoomURL` is correct and the room exists
2. Check network connectivity: `curl -I https://app.kosmi.io`
3. Enable debug logging: `-debug` flag
4. Check logs for WebSocket handshake errors
```go
chromedp.ActionFunc(func(ctx context.Context) error {
_, err := page.AddScriptToEvaluateOnNewDocument(script).Do(ctx)
return err
})
```
### Authentication fails
### Hook Script
1. Verify Chrome/Chromium is installed: `which chromium chromium-browser google-chrome`
2. Check credentials are correct
3. Delete cached token to force fresh login: `rm data/kosmi_token_cache.json`
4. Check for Kosmi UI changes that may break browser automation
Wraps `window.WebSocket` constructor to intercept all WebSocket connections:
### Messages not appearing
```javascript
window.WebSocket = function(url, protocols) {
const socket = new OriginalWebSocket(url, protocols);
// ... interception logic ...
return socket;
};
```
1. Confirm both bridges are connected (check logs)
2. Verify gateway config: Kosmi channel must be `"main"`, IRC channel must have `#`
3. Enable debug logging to trace message routing
4. Check for `RemoteNickFormat` issues
## Debugging Commands
### Jackbox votes not registering
1. Verify Jackbox integration is enabled in config
2. Check that an active session exists with games played
3. Confirm messages don't start with `[irc]` or `[kosmi]` prefix (relayed messages skip vote detection)
## CLI Flags
```bash
# 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 ./...
./matterbridge -conf matterbridge.toml # Specify config file
./matterbridge -debug # Enable debug logging
./matterbridge -muted # Start with Jackbox announcements muted
./matterbridge -version # Show version info
```
## Performance Notes
## Mute Toggle
- **Chrome Startup**: ~1-2 seconds
- **Page Load**: ~1-2 seconds
- **Message Latency**: ~100-500ms
- **Memory Usage**: ~100-200MB (Chrome process)
Toggle Jackbox announcements at runtime:
## Security Considerations
```bash
# Local
kill -SIGUSR1 $(pgrep matterbridge)
- 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
```ini
[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
docker kill -s SIGUSR1 kosmi-irc-relay
```
### Docker Considerations
## Docker Commands
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)
```bash
docker-compose up -d # Start
docker-compose down # Stop
docker-compose restart # Restart
docker-compose logs -f # Follow logs
docker-compose logs --tail=100 # Last 100 lines
docker-compose build --no-cache # Rebuild
```
## 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
## Further Reading
- [README.md](../../README.md) -- Project overview and architecture
- [IRC.md](../IRC.md) -- IRC command and voting reference
- [DOCKER_QUICKSTART.md](DOCKER_QUICKSTART.md) -- 5-minute Docker setup
- [JACKBOX_INTEGRATION.md](JACKBOX_INTEGRATION.md) -- Jackbox Game Picker setup
- [BROWSER_AUTH_GUIDE.md](BROWSER_AUTH_GUIDE.md) -- Email/password authentication
- [MUTE_CONTROL.md](MUTE_CONTROL.md) -- Mute toggle guide