How skeptik-io/herald works
Herald is a multi-tenant realtime event transport: backends provision streams and members through HTTP, while clients connect over WebSocket to subscribe, publish, receive acknowledgments, and catch up after reconnects. Its Rust server supplies the transport and optional chat and presence engines; TypeScript SDKs provide browser, chat-state, and React interfaces, alongside generated multi-language admin clients. The graph preserves documented chat and presence capabilities, but their internal server routing is not fully represented because those source excerpts were not sampled.
Main entry points: client.ts WebSocket SDK · handler.rs WebSocket protocol handler · engine.rs Engine extension system · chat-core.ts Chat state machine
Components 22
Herald Server
- Server startup
herald-server/src/main.rs - Engine extension system
herald-server/src/engine.rs - WebSocket protocol handler
herald-server/src/ws/handler.rs - Connection lifecycle
herald-server/src/ws/connection.rs - HTTP API routes
herald-server/src/http - Event buffer
herald-server/src/store/events.rs - Stream membership
herald-server/src/store/members.rs - Read cursors
herald-server/src/store/cursors.rs
Domain Engines
- Chat features
herald-server/src/engines/chat - Presence features
herald-server/src/engines/presence
Client SDKs
- WebSocket SDK
herald-sdk-typescript/src/client.ts - Reconnect transport
herald-sdk-typescript/src/connection.ts - E2EE manager
herald-sdk-typescript/src/e2ee.ts - Chat state machine
herald-chat-core/src/chat-core.ts - React chat UI
herald-chat-react/src/provider.tsx - Chat protocol SDK
herald-chat-sdk-typescript/src/client.ts - Presence protocol SDK
herald-presence-sdk-typescript/src/client.ts
Backend Administration
- Admin SDK
herald-admin-typescript/src/client.ts - Admin HTTP transport
herald-admin-typescript/src/transport.ts - Other language clients
herald-admin-python/herald_admin/client.py
Other components
- Browser client
- Application backend
Connections 18
- Application backend → Admin SDK: manages through
- Admin SDK → Admin HTTP transport: sends requests
- Admin HTTP transport → HTTP API routes: calls HTTP
- Browser client → WebSocket SDK: uses
- WebSocket SDK → Reconnect transport: creates connection
- WebSocket SDK → E2EE manager: encrypts events
- WebSocket SDK → WebSocket protocol handler: exchanges frames
- WebSocket protocol handler → Event buffer: reads and writes
- WebSocket protocol handler → Stream membership: checks membership
- WebSocket protocol handler → Read cursors: reads cursor
- Server startup → Engine extension system: registers engines
- Engine extension system → Chat features: dispatches hooks
- Engine extension system → Presence features: dispatches hooks
- Chat protocol SDK → WebSocket SDK: extends frames
- Presence protocol SDK → WebSocket SDK: extends frames
- Chat state machine → WebSocket SDK: uses transport
- React chat UI → Chat state machine: provides UI for
- Application backend → Other language clients: may use