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:
```bash
# Using an IRC client (e.g., irssi, weechat, hexchat)
/connect irc.zeronode.net 6697
/join #cottongin
```

Or watch the Docker logs:
```bash
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

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

---

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

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

```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
```

---

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