Real-Time (WebSocket)
The realtime library provides WebSocket-based real-time communication
with JWT authentication, message routing, and topic-based pub/sub.
Connection lifecycle
-
Client connects with JWT:
ws://host/ws?token=<jwt> -
Server verifies JWT via
IJWTVerifieradapter -
Connection record created and registered
-
Client sends and receives messages
-
On disconnect: cleanup registry, unsubscribe from all topics
Message routing types
| Type | Target | Use case |
|---|---|---|
|
All connections |
System announcements |
|
Specific user-id |
Direct messages |
|
Users with a specific role |
Admin notifications |
|
Specific connection-id |
Job progress updates |
Sending messages
(require '[boundary.realtime.ports :as ports])
;; Broadcast to all
(ports/send-to-all service {:type :announcement :text "System maintenance in 5 minutes"})
;; Send to specific user
(ports/send-to-user service user-id {:type :notification :data {...}})
;; Send to all users with a role
(ports/send-to-role service :admin {:type :alert :data {...}})
;; Send to specific connection
(ports/send-to-connection service conn-id {:type :progress :percent 75})Topic-based pub/sub
;; Subscribe connection to a topic
(ports/subscribe-to-topic pubsub-mgr conn-id "order:123")
;; Publish to all topic subscribers
(ports/publish-to-topic service "order:123" {:type :order-updated :payload {...}})
;; Unsubscribe
(ports/unsubscribe-from-topic pubsub-mgr conn-id "order:123")Integrant configuration
:boundary/realtime-service
{:jwt-verifier #ig/ref :boundary/jwt-verifier
:db #ig/ref :boundary/db} ; optional, for persistenceSee realtime library for the full reference.