Websocket Development

WebSocket Development

Quick reference for WebSocket development in the Lupin project.

Architecture Overview

Lupin uses a dual-session WebSocket design:

Key Principle: User-centric routing - events routed by user identity, not just session.

Authentication

All connections require auth_request with Bearer token:

// Token format
Bearer mock_token_email_{email}

// Example auth message
{
  "type": "auth_request",
  "token": "Bearer mock_token_email_user@example.com"
}

Session ID Format

Session IDs use "adjective noun" format for human-readability:

• wise penguin
• clever dolphin
• swift falcon

Stored in localStorage for persistence across page reloads.

Quick Debugging Checklist

Development Tips

1. Enable debug mode: Set app_debug = true in lupin-app.ini (5s vs 60s updates)
2. Monitor traffic: Browser DevTools → Network → WS tab
3. Check auth: Console shows success/failure messages
4. Configuration: All settings under websocket_* keys in lupin-app.ini

Event Subscription

Clients subscribe to specific event types to filter unwanted events:

// Subscribe to events
{
  "type": "subscribe",
  "events": ["queue_update", "notification", "time_update"]
}

Detailed References

For comprehensive documentation:

• Architecture - Full dual-session design
• Configuration - All config options
• Events - Complete event catalog
• Troubleshooting - Debug procedures

Anti-Patterns

• Don't hardcode session IDs - use localStorage persistence
• Don't skip auth_request - connections will be rejected
• Don't forget both WebSockets for audio features
• Don't ignore subscription filtering - causes event spam

Converted and distributed by TomeVault — claim your Tome and manage your conversions.