IRC-kosmi-relay/TEST_INSTRUCTIONS.md

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

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 🚀")
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"
  

How to Verify:

Connect to IRC and join #cottongin:

# Using an IRC client (e.g., irssi, weechat, hexchat)
/connect irc.zeronode.net 6697
/join #cottongin

Or watch the Docker logs:

docker-compose logs -f | grep -E "(Received|Relaying|Sent)"

---

Test 2: IRC → Kosmi

Steps:

1. Connect to IRC: irc.zeronode.net:6697
2. Join channel: /join #cottongin
3. Send a message: "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
  

How to Verify:

• Open Kosmi room in browser: https://app.kosmi.io/room/@hyperspaceout
• Check if your IRC message appears in the chat

---

Watch Logs in Real-Time

# All logs
docker-compose logs -f

# Only message-related logs
docker-compose logs -f | grep -E "(message|Message|Received|Sent|Relaying)"

# Last 50 lines
docker-compose logs --tail=50

---

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)

# 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)

# 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

---

Troubleshooting

No Messages Appearing

1. Check bridge is running:

   docker-compose ps
   

   Should show kosmi-irc-relay as "Up"

2. Check logs for errors:

   docker-compose logs --tail=100
   

3. Verify connections:

   docker-compose logs | grep -E "(Connected|connected|joined)"
   

   Should show both Kosmi WebSocket and IRC connected

4. Restart if needed:

   docker-compose restart
   docker-compose logs -f
   

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

Message Formatting Issues

Messages are formatted as:

<username> message text

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

# 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

---

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! 🎉