Real-Time Updates

Flipswitch uses Server-Sent Events (SSE) to push flag changes to connected clients instantly.

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Dashboard     │     │   Flipswitch    │     │   Your App      │
│                 │     │     Server      │     │   (SDK)         │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │  Toggle flag "dark-mode"                      │
         │──────────────────────>│                       │
         │                       │                       │
         │                       │  SSE: flag-change     │
         │                       │──────────────────────>│
         │                       │                       │
         │                       │  Invalidate cache     │
         │                       │                       │
         │                       │  Next evaluation      │
         │                       │<──────────────────────│
         │                       │                       │
         │                       │  Fresh flag value     │
         │                       │──────────────────────>│
         │                       │                       │

1. You toggle a flag in the dashboard
2. Server broadcasts a flag-change event to all connected SDKs
3. SDKs invalidate their local cache
4. Next flag evaluation fetches the fresh value

The result: flag changes propagate in milliseconds, not minutes.

Why SSE?

Instant updates. Polling can take 30-60 seconds to detect changes. SSE delivers them immediately.

Kill switches that work. When something breaks, you need to disable features now, not "whenever the next poll happens."

Lower server load. One long-lived connection per client vs. constant polling requests.

Simple protocol. SSE is HTTP with a text/event-stream content type. Works through proxies, load balancers, and firewalls that understand HTTP.

SDK Behavior

All official SDKs support SSE by default:

// SSE enabled by default
const provider = new FlipswitchProvider({
  apiKey: 'YOUR_API_KEY',
  enableRealtime: true  // default
});

When the SSE connection receives a flag-change event:

1. The local cache is invalidated
2. OpenFeature emits a PROVIDER_CONFIGURATION_CHANGED event
3. If using React, useFlag hooks re-render automatically

Connection Status

SDKs track connection state:

const status = provider.getSseStatus();
// 'connecting' | 'connected' | 'disconnected' | 'error'

Reconnection

SDKs automatically reconnect with exponential backoff:

• Initial delay: 1 second
• Maximum delay: 30 seconds
• Backoff multiplier: 2x

While disconnected, the SDK continues working with cached values. When reconnected, it fetches fresh data.

Disabling SSE

If you don't need real-time updates:

const provider = new FlipswitchProvider({
  apiKey: 'YOUR_API_KEY',
  enableRealtime: false,
  pollingInterval: 60000  // Poll every 60 seconds instead
});

Proxy Considerations

SSE requires long-lived HTTP connections. Some proxies and load balancers may close connections after a timeout.

If you see frequent disconnections:

• Configure your proxy to allow longer connection timeouts
• Check for intermediate proxies (CDNs, API gateways) that may buffer responses
• Ensure Transfer-Encoding: chunked is supported