How it works

When you call canary.init(), the SDK opens an SSE (Server-Sent Events) connection to the CanaryGate API. This connection stays open and automatically receives events when flags change.

SDK → init() → HTTP fetch (initial flag load)
             ↓
          SSE stream (persistent connection)
             ↓
     dashboard change → SSE event → SDK updates local cache

From dashboard to client: latency

When you change a flag in the dashboard:

1. The change is saved in the database
2. An event is published to Redis Pub/Sub
3. The SSE server receives the event and broadcasts it to all connected clients
4. The client SDK receives it and updates the local cache

Typical latency: < 500ms from the dashboard change to the client receiving it.

Automatic reconnection

The native EventSource reconnects automatically in case of a network drop. The SDK also detects when the connection expires and reconnects — you do not need to manage this manually.

Checking whether data is fresh

// Check if data might be stale
if (canary.isStale()) {
  // The SSE connection has been interrupted for longer than X time
  // You may want to reload or show a warning to the user
}
 
// Last successful sync
const lastSync = canary.getLastSyncAt()
console.log('Data synchronized at:', lastSync)

Offline behavior

If the SSE connection is lost:

• Flags return the last known values (local cache)
• isStale() returns true after the configured timeout
• Reconnection is automatic when the network comes back

Disconnecting

// Important: disconnect when you no longer need the SDK
// (e.g., component unmount, server shutdown)
canary.disconnect()