Real-Time Updates

FeatureSignals propagates flag changes to all connected SDKs in real-time. Multiple mechanisms work together to ensure every SDK has the latest flag configuration — from instant WebSocket push to reliable polling fallback, backed by PG-driven cache invalidation across all server instances.

How an Update Flows

When someone toggles a flag in the Flag Engine, API, or via SDK, here's what happens:

Mutation committed. The flag change is written to PostgreSQL in a transaction. A NOTIFY event fires on the flag_changes channel.
All API server instances receive the notification. Each instance's PG listener picks up the event and invalidates the affected Redis cache key.
WebSocket/SSE push. Each API server pushes a change event to all SDKs connected via WebSocket or SSE. The event payload includes the flag key, project ID, and environment key.
SDK invalidates and re-fetches. The SDK marks the stale flag in its local cache and schedules a re-fetch. For WebSocket clients, this is immediate. For polling clients, it happens on the next poll cycle.
Evaluation continues uninterrupted. If the re-fetch fails, the SDK keeps using the last known good configuration — it never returns stale errors to the application.

Latency Guarantees

Mechanism	Typical End-to-End Latency	Failure Mode
WebSocket	< 500ms	Falls back to polling
SSE	< 1s	Falls back to polling
Polling	Up to configured interval (30–60s)	Exponential backoff on failure
PG LISTEN/NOTIFY	< 100ms (server-side cache invalidation)	Redis cache has TTL fallback

Update Mechanisms

WebSocket Streaming

< 500ms end-to-end

SDKs establish a persistent WebSocket connection to the FeatureSignals API. When a flag is created, updated, or toggled, the server pushes a change event to all connected SDKs. The SDK invalidates its local cache and re-fetches the affected ruleset.

Polling Fallback

Up to poll interval (30–60s configurable)

For environments where WebSockets are blocked (firewalls, proxies) or for SDKs that don't support persistent connections, SDKs fall back to periodic polling. The poll interval is configurable — typically 30 seconds for server SDKs, 60 seconds for client SDKs.

PG LISTEN/NOTIFY (Server-Side)

< 100ms for cache invalidation across all instances

When a flag is mutated, PostgreSQL emits a NOTIFY event on a dedicated channel. Every API server instance listens on this channel. Upon receiving a notification, each instance invalidates the relevant Redis cache entry. This ensures all instances stay synchronized without a centralized cache coordinator.

SSE (Server-Sent Events)

< 1s end-to-end

For browser-based SDKs that can't use raw WebSockets, FeatureSignals supports Server-Sent Events. The browser opens a one-way stream from the API, receiving flag change events as they happen. SSE is simpler than WebSockets and works through most corporate firewalls.

SDK Configuration

Each SDK exposes configuration for real-time updates. The exact API varies by language, but the concepts are consistent:

Option	Default	Description
`updateMode`	`websocket`	Transport: `websocket`, `sse`, or `polling`
`pollIntervalMs`	30000	Poll interval in milliseconds (when using polling mode or as fallback)
`cacheTtlMs`	60000	Maximum age of cached flag data before a forced refresh
`reconnectBackoffMs`	1000	Initial backoff for WebSocket/SSE reconnection (exponential with jitter)

Graceful Degradation

SDKs never return errors due to stale data

If the WebSocket disconnects, the SDK uses the last known configuration. If polling fails, it uses the cached ruleset. If the cache expires during an outage, the SDK returns the fallback value you provide in your code. Your application keeps running normally regardless of connectivity to FeatureSignals.