IRC-kosmi-relay/docs/INTEGRATION.md

Integrating Kosmi Bridge into Full Matterbridge

This document explains how to integrate the Kosmi bridge into the full Matterbridge codebase.

Current Status

The Kosmi bridge has been implemented as a standalone module with the following components:

Implemented Features ✅

1. WebSocket Connection: Full GraphQL-WS protocol implementation
2. Message Reception: Subscribes to Kosmi chat messages and forwards to Matterbridge
3. Message Sending: Sends messages to Kosmi via GraphQL mutations
4. Bridge Registration: Properly registered in the bridgemap
5. Configuration Support: TOML configuration with room URL and server settings

File Structure

bridge/
├── bridge.go           # Bridge interface and config (minimal implementation)
├── config/
│   └── config.go       # Message and channel structures
└── kosmi/
    ├── kosmi.go        # Main bridge implementation
    └── graphql.go      # GraphQL WebSocket client

gateway/
└── bridgemap/
    ├── bridgemap.go    # Bridge factory registry
    └── bkosmi.go       # Kosmi bridge registration

cmd/
└── test-kosmi/
    └── main.go         # Standalone test program

matterbridge.toml       # Example configuration
go.mod                  # Go module dependencies

Integration Steps

To integrate this into the full Matterbridge project:

Option 1: Copy into Existing Matterbridge

1. Copy the Kosmi bridge files:

   # From the matterbridge repository root
   cp -r /path/to/irc-kosmi-relay/bridge/kosmi bridge/kosmi
   cp /path/to/irc-kosmi-relay/gateway/bridgemap/bkosmi.go gateway/bridgemap/
   

2. Update go.mod (if needed):

   go get github.com/gorilla/websocket@v1.5.1
   go mod tidy
   

3. Build Matterbridge:

   go build
   

4. Configure (add to your matterbridge.toml):

   [kosmi.hyperspaceout]
   RoomURL="https://app.kosmi.io/room/@hyperspaceout"
   
   [[gateway]]
   name="kosmi-irc"
   enable=true
   
   [[gateway.inout]]
   account="kosmi.hyperspaceout"
   channel="main"
   
   [[gateway.inout]]
   account="irc.libera"
   channel="#your-channel"
   

5. Run:

   ./matterbridge -conf matterbridge.toml
   

Option 2: Use as Standalone (Current Setup)

The current implementation can work standalone but requires the full Matterbridge gateway logic. To use it standalone:

1. Test the Kosmi connection:

   ./test-kosmi -room "https://app.kosmi.io/room/@hyperspaceout" -debug
   

2. Implement a simple gateway (you would need to add):

   • IRC bridge implementation (or copy from Matterbridge)
   • Gateway routing logic to relay messages between bridges
   • Main program that initializes both bridges

Testing the Bridge

Test 1: Kosmi Connection Only

# Build and run the test program
go build -o test-kosmi ./cmd/test-kosmi
./test-kosmi -room "https://app.kosmi.io/room/@hyperspaceout" -debug

Expected output:

INFO[...] Starting Kosmi bridge test
INFO[...] Room URL: https://app.kosmi.io/room/@hyperspaceout
INFO[...] Connecting to Kosmi...
INFO[...] Connecting to Kosmi GraphQL WebSocket: wss://engine.kosmi.io/gql-ws
INFO[...] WebSocket connection established
INFO[...] Sent connection_init message
INFO[...] Received connection_ack
INFO[...] GraphQL WebSocket handshake completed
INFO[...] Subscribed to messages in room: hyperspaceout
INFO[...] Successfully connected to Kosmi!
INFO[...] Starting message listener
INFO[...] Listening for messages... Press Ctrl+C to exit

When someone sends a message in the Kosmi room, you should see:

INFO[...] Received message: [15:04:05] Username: [Kosmi] <Username> message text

Test 2: Full Integration with IRC

Once integrated into full Matterbridge:

1. Start Matterbridge with Kosmi configured
2. Send a message in Kosmi → Should appear in IRC as [Kosmi] <username> message
3. Send a message in IRC → Should appear in Kosmi as [IRC] <username> message

Reverse Engineering Notes

GraphQL API Details

The Kosmi bridge uses the following GraphQL operations:

Subscription (implemented and tested):

subscription {
  newMessage(roomId: "roomId") {
    body
    time
    user {
      displayName
      username
    }
  }
}

Mutation (implemented but needs testing):

mutation {
  sendMessage(roomId: "roomId", body: "message text") {
    id
  }
}

Potential Issues

1. Message Sending: The sendMessage mutation is based on common GraphQL patterns but may need adjustment based on Kosmi's actual API. If sending doesn't work:

   • Use browser DevTools to capture the actual mutation
   • Update graphql.go SendMessage() method with correct mutation format

2. Room ID Format: The bridge supports both @roomname and roomid formats. If connection fails:

   • Check the actual room ID in browser DevTools
   • Update extractRoomID() function in kosmi.go

3. Authentication: Currently connects anonymously. If Kosmi adds authentication:

   • Add auth token configuration
   • Update Connect() to include auth headers

Browser-Based Testing

To verify the GraphQL API structure:

1. Open Kosmi room in browser
2. Open DevTools → Network tab
3. Filter by WS (WebSocket)
4. Click on the WebSocket connection to engine.kosmi.io
5. View messages to see the exact GraphQL format

Example messages you might see:

// Outgoing subscription
{
  "id": "1",
  "type": "start",
  "payload": {
    "query": "subscription { newMessage(roomId: \"...\") { ... } }"
  }
}

// Incoming message
{
  "type": "next",
  "id": "1",
  "payload": {
    "data": {
      "newMessage": {
        "body": "Hello!",
        "time": 1730349600,
        "user": {
          "displayName": "User",
          "username": "user123"
        }
      }
    }
  }
}

Next Steps

1. Test message sending: Send a test message from the bridge to verify the mutation works
2. Add IRC bridge: Either integrate into full Matterbridge or implement a minimal IRC bridge
3. Test bidirectional relay: Verify messages flow both ways correctly
4. Add error handling: Improve reconnection logic and error recovery
5. Add features:
   • User presence/join/leave events
   • File/image sharing (if supported by Kosmi)
   • Message editing/deletion
   • Typing indicators

Troubleshooting

"Connection refused" or "dial tcp: lookup engine.kosmi.io"

• Check network connectivity
• Verify DNS resolution
• Check firewall rules

"Connection closed unexpectedly"

• Enable debug logging: -debug flag
• Check if Kosmi API has changed
• Verify room ID is correct

"Messages not appearing"

• Check message format in logs
• Verify subscription is active
• Test with browser DevTools to compare

"Cannot send messages"

• The mutation may need adjustment
• Check browser DevTools for actual mutation format
• Update SendMessage() in graphql.go

Contributing

To improve the bridge:

1. Test thoroughly with actual Kosmi rooms
2. Document any API changes you discover
3. Add unit tests for critical functions
4. Improve error handling and logging
5. Add reconnection logic for network issues

License

Same as Matterbridge (Apache 2.0)