rspade_system/app/RSpade/Core/Realtime/CLAUDE.md

Realtime WebSocket System

Architecture

PHP (authority) → Redis pub/sub → Node.js relay → WebSocket → Browser

• PHP: Issues HMAC-signed tokens, checks permissions, publishes events
• Node: Validates tokens, routes messages, stores last-message. Zero business logic
• Browser: Connects, subscribes, receives notifications, fetches fresh data via Ajax

Key Files

• Realtime.php — Static API: connection_token(), subscribe_token(), publish()
• Realtime_Topic_Abstract.php — Base class for topic permission checks
• Realtime_Controller.php — Ajax endpoints for browser token requests
• /system/bin/realtime-server.js — Node.js WebSocket server
• /system/app/RSpade/Core/Js/Rsx_Realtime.js — Client manager

Security Model

1. Connection token: HMAC-signed with APP_KEY, contains user_id + site_id + session_id, expires in 60s
2. Subscribe token: Per-topic, HMAC-signed, checks Topic::can_subscribe() before issuing
3. Site scoping: Messages only route to connections with matching site_id
4. No confidential data: Messages are notifications only — clients fetch data through Ajax

Token Format

base64(json_payload).hmac_sha256_hex

Connection: {user_id, site_id, session_id, exp} Subscribe: {topic, filter, site_id, exp}

Redis Channels

• Pattern: rsx_rt:{site_id}
• Message: {topic, data, site_id, ts}

Configuration

.env:

REALTIME_ENABLED=false
REALTIME_WS_PORT=6200
REALTIME_PUBLIC_URL=ws://localhost:6200