working v1
This commit is contained in:
cottongin
237
QUICK_REFERENCE.md
Normal file
237
QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# Quick Reference Guide
|
||||
|
||||
## Testing the Bridge
|
||||
|
||||
### Build and Run Test Program
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### When Messages Arrive
|
||||
|
||||
```
|
||||
INFO Processing 1 messages from queue
|
||||
INFO Received message: [00:02:51] username: [Kosmi] <username> message text
|
||||
```
|
||||
|
||||
## 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 |
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: "No WebSocket connection detected yet"
|
||||
|
||||
**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"
|
||||
|
||||
## Configuration
|
||||
|
||||
### Minimal Test Configuration
|
||||
|
||||
```toml
|
||||
[kosmi.test]
|
||||
RoomURL="https://app.kosmi.io/room/@hyperspaceout"
|
||||
Debug=true
|
||||
```
|
||||
|
||||
### Full Matterbridge Configuration
|
||||
|
||||
```toml
|
||||
# Kosmi
|
||||
[kosmi.hyperspaceout]
|
||||
RoomURL="https://app.kosmi.io/room/@hyperspaceout"
|
||||
|
||||
# IRC
|
||||
[irc.libera]
|
||||
Server="irc.libera.chat:6667"
|
||||
Nick="kosmi-relay"
|
||||
UseTLS=false
|
||||
|
||||
# Gateway
|
||||
[[gateway]]
|
||||
name="kosmi-irc"
|
||||
enable=true
|
||||
|
||||
[[gateway.inout]]
|
||||
account="kosmi.hyperspaceout"
|
||||
channel="main"
|
||||
|
||||
[[gateway.inout]]
|
||||
account="irc.libera"
|
||||
channel="#your-channel"
|
||||
```
|
||||
|
||||
## Message Format
|
||||
|
||||
### Kosmi → IRC
|
||||
|
||||
```
|
||||
[Kosmi] <username> message text
|
||||
```
|
||||
|
||||
### IRC → Kosmi
|
||||
|
||||
```
|
||||
[IRC] <username> message text
|
||||
```
|
||||
|
||||
## 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 |
|
||||
|
||||
## Key Implementation Details
|
||||
|
||||
### WebSocket Hook Injection
|
||||
|
||||
**MUST** use `page.AddScriptToEvaluateOnNewDocument` to inject **before page load**:
|
||||
|
||||
```go
|
||||
chromedp.ActionFunc(func(ctx context.Context) error {
|
||||
_, err := page.AddScriptToEvaluateOnNewDocument(script).Do(ctx)
|
||||
return err
|
||||
})
|
||||
```
|
||||
|
||||
### Hook Script
|
||||
|
||||
Wraps `window.WebSocket` constructor to intercept all WebSocket connections:
|
||||
|
||||
```javascript
|
||||
window.WebSocket = function(url, protocols) {
|
||||
const socket = new OriginalWebSocket(url, protocols);
|
||||
// ... interception logic ...
|
||||
return socket;
|
||||
};
|
||||
```
|
||||
|
||||
## Debugging Commands
|
||||
|
||||
```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 ./...
|
||||
```
|
||||
|
||||
## Performance Notes
|
||||
|
||||
- **Chrome Startup**: ~1-2 seconds
|
||||
- **Page Load**: ~1-2 seconds
|
||||
- **Message Latency**: ~100-500ms
|
||||
- **Memory Usage**: ~100-200MB (Chrome process)
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- 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 Considerations
|
||||
|
||||
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)
|
||||
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user