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

291
docs/setup/TEST_INSTRUCTIONS.md
View File

@@ -1,255 +1,126 @@
# Message Relay Testing Instructions
**Bridge Status**: ✅ **ACTIVE AND READY**
Both Kosmi and IRC are connected. The gateway is relaying messages.
## Current Configuration
- **Kosmi Room**: https://app.kosmi.io/room/@hyperspaceout
- **IRC Server**: irc.zeronode.net:6697
- **IRC Channel**: #cottongin
- **Status**: Both bridges connected and relaying
- **Kosmi Room**: Configured via `RoomURL` in `matterbridge.toml`
- **IRC Server**: Configured via `Server` in `matterbridge.toml`
- **IRC Channel**: Configured via gateway `[[gateway.inout]]`
## Test 1: Kosmi → IRC
## Test 1: Kosmi --> IRC
### Steps:
1. Open the Kosmi room in your browser: https://app.kosmi.io/room/@hyperspaceout
2. Type a message in the chat (e.g., "Test message from Kosmi 🚀")
### Steps
1. Open your Kosmi room in a browser
2. Type a test message (e.g., "Test message from Kosmi")
3. Press Enter to send
### Expected Result:
- The message should appear in IRC channel #cottongin
- The logs will show:
```
level=info msg="📨 Received message from Kosmi: ..." prefix=kosmi
level=info msg="Relaying message from kosmi to irc"
```
### Expected Logs
### How to Verify:
Connect to IRC and join #cottongin:
```bash
# Using an IRC client (e.g., irssi, weechat, hexchat)
/connect irc.zeronode.net 6697
/join #cottongin
```
INFO Received message from Kosmi: [<timestamp>] username: message text
DEBUG Forwarding to Matterbridge channel=main account=kosmi.hyperspaceout
```
Or watch the Docker logs:
```bash
docker-compose logs -f | grep -E "(Received|Relaying|Sent)"
### Verification
The message should appear in your IRC channel with the configured `RemoteNickFormat`, typically:
```
[kosmi] <username> Test message from Kosmi
```
---
## Test 2: IRC --> Kosmi
## Test 2: IRC → Kosmi
### Steps
### Steps:
1. Connect to IRC: `irc.zeronode.net:6697`
2. Join channel: `/join #cottongin`
3. Send a message: "Test message from IRC 👋"
1. Connect to your IRC server and join the configured channel
2. Send a test message (e.g., "Test message from IRC")
### Expected Result:
- The message should appear in the Kosmi chat room
- The logs will show:
```
level=info msg="Received message from IRC: ..." prefix=irc
level=info msg="Relaying message from irc to kosmi"
level=info msg="✅ Sent message via Playwright-assisted WebSocket: ..." prefix=kosmi
```
### Expected Logs
### How to Verify:
- Open Kosmi room in browser: https://app.kosmi.io/room/@hyperspaceout
- Check if your IRC message appears in the chat
```
DEBUG <= Sending message from #channel on irc.account to gateway
DEBUG => Sending message to Kosmi
```
---
### Verification
## Watch Logs in Real-Time
The message should appear in the Kosmi room with the configured format, typically:
```
[irc] <username> Test message from IRC
```
## Test 3: Jackbox Vote Detection (if enabled)
### Steps
1. In IRC or Kosmi, type: `thisgame++`
2. Check bot logs
### Expected Logs
```
DEBUG Detected vote from username: up (ticker="")
```
## Test 4: IRC Commands
### Steps
1. In IRC, type: `!votes`
2. Check for broadcast response
### Expected Response (if active session)
```
🗳️ Game Title • Today: X👍 Y👎 (Score: Z) • All-time: X👍 Y👎 (Score: Z)
```
## Watching Logs
```bash
# All logs
docker-compose logs -f
# Only message-related logs
docker-compose logs -f | grep -E "(message|Message|Received|Sent|Relaying)"
# Message-related logs only
docker-compose logs -f | grep -E "(Received|Sending|Forwarding|Detected)"
# Last 50 lines
docker-compose logs --tail=50
```
---
## Success Criteria
## Quick IRC Connection Methods
### Method 1: Web IRC Client
1. Go to: https://web.libera.chat/
2. Connect to: irc.zeronode.net (port 6697, SSL)
3. Join: #cottongin
### Method 2: Command-Line (irssi)
```bash
# Install irssi (if not installed)
brew install irssi # macOS
# or
apt-get install irssi # Linux
# Connect
irssi -c irc.zeronode.net -p 6697
/join #cottongin
```
### Method 3: Command-Line (nc for quick test)
```bash
# Simple netcat connection (read-only)
openssl s_client -connect irc.zeronode.net:6697
# Then type:
NICK testuser
USER testuser 0 * :Test User
JOIN #cottongin
```
---
## What You Should See
### In Docker Logs (Normal Operation):
```
✅ WebSocket established and ready!
✅ Native client fully connected!
Successfully connected to Kosmi
Connection succeeded (IRC)
irc.libera: joining #cottongin
Gateway(s) started successfully. Now relaying messages
```
### When a Message is Relayed (Kosmi → IRC):
```
level=info msg="📨 Received message from Kosmi: username: message text" prefix=kosmi
level=info msg="Handling message from kosmi.hyperspaceout" prefix=router
level=info msg="Relaying message to irc.libera" prefix=router
level=info msg="Sent message to #cottongin" prefix=irc
```
### When a Message is Relayed (IRC → Kosmi):
```
level=info msg="Received message from #cottongin: username: message text" prefix=irc
level=info msg="Handling message from irc.libera" prefix=router
level=info msg="Relaying message to kosmi.hyperspaceout" prefix=router
level=info msg="✅ Sent message via Playwright-assisted WebSocket: message text" prefix=kosmi
```
---
1. Messages sent in Kosmi appear in IRC
2. Messages sent in IRC appear in Kosmi
3. Usernames are displayed correctly with bridge prefix
4. Messages appear within 1-2 seconds
5. No errors in logs during normal relay
## Troubleshooting
### No Messages Appearing
1. **Check bridge is running**:
```bash
docker-compose ps
```
Should show `kosmi-irc-relay` as "Up"
2. **Check logs for errors**:
```bash
docker-compose logs --tail=100
```
3. **Verify connections**:
```bash
docker-compose logs | grep -E "(Connected|connected|joined)"
```
Should show both Kosmi WebSocket and IRC connected
4. **Restart if needed**:
```bash
docker-compose restart
docker-compose logs -f
```
1. Check the container is running: `docker-compose ps`
2. Check for errors: `docker-compose logs --tail=100`
3. Verify both bridges are connected (look for success messages)
4. Restart if needed: `docker-compose restart`
### Messages Only Going One Direction
- **If Kosmi → IRC works but IRC → Kosmi doesn't**:
- Check Kosmi WebSocket is still connected: `docker-compose logs | grep WebSocket`
- The native client might have disconnected
- Restart: `docker-compose restart`
- **If IRC → Kosmi works but Kosmi → IRC doesn't**:
- Check IRC connection: `docker-compose logs | grep irc`
- Verify IRC authentication
- **Kosmi --> IRC works, IRC --> Kosmi doesn't**: Check Kosmi WebSocket is connected
- **IRC --> Kosmi works, Kosmi --> IRC doesn't**: Check IRC connection status
### Message Formatting Issues
Messages are formatted as:
```
<username> message text
```
Message format is controlled by `RemoteNickFormat` in each bridge's config section. Default: `[{PROTOCOL}] <{NICK}> `
This is configurable in `matterbridge.toml` under the gateway settings.
---
## Success Criteria
✅ **Full Success** means:
1. Message sent in Kosmi appears in IRC #cottongin
2. Message sent in IRC #cottongin appears in Kosmi room
3. Usernames are preserved/displayed correctly
4. Messages appear within 1-2 seconds
5. No errors in logs
---
## Next Steps After Testing
Once both directions work:
1. **Monitor stability** - Let it run for a few hours
2. **Check memory usage**: `docker stats kosmi-irc-relay`
3. **Review message formatting** - Adjust in `matterbridge.toml` if needed
4. **Set up log rotation** - For long-term operation
5. **Consider adding more channels** - Edit `matterbridge.toml`
---
## Quick Commands Reference
## Quick Commands
```bash
# Start in background
docker-compose up -d
# Follow logs
docker-compose logs -f
# Stop
docker-compose down
# Restart
docker-compose restart
# Rebuild
docker-compose up --build -d
# Check status
docker-compose ps
# View resource usage
docker stats kosmi-irc-relay
docker-compose up -d # Start
docker-compose logs -f # Follow logs
docker-compose down # Stop
docker-compose restart # Restart
docker-compose ps # Status
docker stats kosmi-irc-relay # Resource usage
```
---
## Ready to Test!
The bridge is **running and connected**. You can start testing immediately:
1. 🌐 Open: https://app.kosmi.io/room/@hyperspaceout
2. 💬 Send a test message
3. 👀 Watch the logs: `docker-compose logs -f`
4. 🔗 Connect to IRC and verify the message appeared
5. 🔄 Send a message from IRC and check Kosmi
Good luck! 🎉