[OFREP] Add SSE event stream support #31

Context

ADR-0008 defines Server-Sent Events (SSE) as an optional real-time change notification mechanism for OFREP. The OpenAPI spec PR adds the corresponding eventStreams field to the bulk evaluation success response.

The OFREP provider currently uses polling (default 5m) to detect flag configuration changes. SSE support would allow the provider to receive change notifications in real-time and re-fetch only when the underlying flag configuration has actually changed, reducing unnecessary polling traffic and improving responsiveness.

Scope

Parse the optional eventStreams array from the POST /ofrep/v1/evaluate/flags response and connect to any entries with type: "sse". On receiving a refetchEvaluation event, re-fetch the bulk evaluation.

1. Parse eventStreams from bulk evaluation response (High)

• After a successful bulk evaluation, check for an eventStreams array in the response
• For each entry with type: "sse", resolve the connection URL from either url or endpoint.origin + endpoint.requestUri
• Ignore entries with unknown types for forward compatibility

2. SSE connection lifecycle (High)

• Connect to the resolved SSE URL(s) after a successful bulk evaluation
• On receiving an event with data.type: "refetchEvaluation", re-fetch via POST /ofrep/v1/evaluate/flags
• If the event includes etag, send it as the flagConfigEtag query parameter on the re-fetch
• If the event includes lastModified, send it as the flagConfigLastModified query parameter on the re-fetch
• flagConfigEtag and flagConfigLastModified should only be included on re-fetches directly triggered by an SSE event
• On SSE connection failure, fall back to polling if polling is enabled; otherwise continue SSE reconnection attempts

3. Inactivity timeout (Medium)

• Apply an effective inactivityDelaySec: use a client-side override if configured, otherwise use the response value if present, otherwise default to 120 seconds
• On Android, use ProcessLifecycleOwner or Activity lifecycle callbacks to detect app backgrounding
• After the inactivity timeout fires, close the SSE connection
• On resume, reconnect and perform a full unconditional re-fetch without flagConfigEtag or flagConfigLastModified

4. Context change handling (Medium)

• On onContextChange, re-fetch bulk evaluation without SSE query metadata
• Update SSE connections based on the new response (new URLs may differ)
• Close any existing SSE connections before opening new ones

5. Event coalescing (Low)

• If multiple SSE events arrive in rapid succession, coalesce them into a single re-fetch to avoid redundant requests

References

• ADR-0008
• OpenAPI spec changes
• Static context provider guideline
• launchdarkly/okhttp-eventsource — recommended SSE client library for JVM/Android