From 1577068ab0d6a363707624b9e03b89968adf69a4 Mon Sep 17 00:00:00 2001 From: Jamie Sinn Date: Thu, 27 Aug 2026 11:23:15 -0400 Subject: [PATCH 1/3] chore: Clarify ADR-0008's handling for cache headers in addition to the query params This was an unclear gap that I ran into when implementing https://github.com/open-feature/flagd/pull/2036 This basically states that the `flagConfigEtag` is the "winner", but only in the truth case of 200 vs 304. It must never downgrade a 200 to a 304 from any other cache control headers. Signed-off-by: Jamie Sinn --- service/adrs/0008-sse-for-bulk-evaluation-changes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/service/adrs/0008-sse-for-bulk-evaluation-changes.md b/service/adrs/0008-sse-for-bulk-evaluation-changes.md index fb5129d..9155576 100644 --- a/service/adrs/0008-sse-for-bulk-evaluation-changes.md +++ b/service/adrs/0008-sse-for-bulk-evaluation-changes.md @@ -163,6 +163,7 @@ Provider implementation guidelines: - If `eventStreams` is present and the URL set has changed, close existing connections then connect to the new URLs. 7. Providers SHOULD coalesce concurrent `refetchEvaluation` events into a single re-fetch request (e.g., via in-flight deduplication or a short debounce window) to avoid amplifying load on the flag management system when multiple connections fire simultaneously. 8. Shared, extensible provider implementations may allow the SSE payload parsing to be overridden (see [Customizable payload parsing](#customizable-payload-parsing)); this is optional and not required of providers targeting endpoints that emit the OFREP payload directly. The default parses string `data` as JSON and passes non-string `data` through unchanged; an override lets integrations with vendors that wrap the payload (e.g., Ably's `data.data` envelope) or use non-JSON formats extract the OFREP event object before `type` / `etag` / `lastModified` are read. +9. In cases where the provider sends to the OFREP server an `If-None-Match`, or other cache headers in addition to the `flagConfigEtag` query parameter, the query parameter MUST NOT downgrade a 200 based on these to a 304. For example: A would be 200 from SSE `flagConfigEtag` being different must not be downgraded to a 304 because the `If-None-Match` HTTP ETag matched and would have returned a 304 based on the response being the same. ### OpenAPI Schema Additions From ad850fcc8425ea5b1cfc41726530a6ac6371da93 Mon Sep 17 00:00:00 2001 From: Jamie Sinn Date: Thu, 27 Aug 2026 11:29:33 -0400 Subject: [PATCH 2/3] reword based on coderabbit Signed-off-by: Jamie Sinn --- service/adrs/0008-sse-for-bulk-evaluation-changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/service/adrs/0008-sse-for-bulk-evaluation-changes.md b/service/adrs/0008-sse-for-bulk-evaluation-changes.md index 9155576..bce0f6c 100644 --- a/service/adrs/0008-sse-for-bulk-evaluation-changes.md +++ b/service/adrs/0008-sse-for-bulk-evaluation-changes.md @@ -163,7 +163,7 @@ Provider implementation guidelines: - If `eventStreams` is present and the URL set has changed, close existing connections then connect to the new URLs. 7. Providers SHOULD coalesce concurrent `refetchEvaluation` events into a single re-fetch request (e.g., via in-flight deduplication or a short debounce window) to avoid amplifying load on the flag management system when multiple connections fire simultaneously. 8. Shared, extensible provider implementations may allow the SSE payload parsing to be overridden (see [Customizable payload parsing](#customizable-payload-parsing)); this is optional and not required of providers targeting endpoints that emit the OFREP payload directly. The default parses string `data` as JSON and passes non-string `data` through unchanged; an override lets integrations with vendors that wrap the payload (e.g., Ably's `data.data` envelope) or use non-JSON formats extract the OFREP event object before `type` / `etag` / `lastModified` are read. -9. In cases where the provider sends to the OFREP server an `If-None-Match`, or other cache headers in addition to the `flagConfigEtag` query parameter, the query parameter MUST NOT downgrade a 200 based on these to a 304. For example: A would be 200 from SSE `flagConfigEtag` being different must not be downgraded to a 304 because the `If-None-Match` HTTP ETag matched and would have returned a 304 based on the response being the same. +9. When a differing SSE `flagConfigEtag` selects a 200 response, the server MUST NOT downgrade that response to 304 because `If-None-Match` or another HTTP conditional validator would otherwise produce 304. When this condition does not occur, normal HTTP conditional-cache handling applies. ### OpenAPI Schema Additions From bb31e712cb009690d2a2440d4d431a713fc5b75a Mon Sep 17 00:00:00 2001 From: Jamie Sinn Date: Thu, 27 Aug 2026 11:37:30 -0400 Subject: [PATCH 3/3] Update service/adrs/0008-sse-for-bulk-evaluation-changes.md Co-authored-by: Todd Baert Signed-off-by: Jamie Sinn --- service/adrs/0008-sse-for-bulk-evaluation-changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/service/adrs/0008-sse-for-bulk-evaluation-changes.md b/service/adrs/0008-sse-for-bulk-evaluation-changes.md index bce0f6c..cc9c2dd 100644 --- a/service/adrs/0008-sse-for-bulk-evaluation-changes.md +++ b/service/adrs/0008-sse-for-bulk-evaluation-changes.md @@ -163,7 +163,7 @@ Provider implementation guidelines: - If `eventStreams` is present and the URL set has changed, close existing connections then connect to the new URLs. 7. Providers SHOULD coalesce concurrent `refetchEvaluation` events into a single re-fetch request (e.g., via in-flight deduplication or a short debounce window) to avoid amplifying load on the flag management system when multiple connections fire simultaneously. 8. Shared, extensible provider implementations may allow the SSE payload parsing to be overridden (see [Customizable payload parsing](#customizable-payload-parsing)); this is optional and not required of providers targeting endpoints that emit the OFREP payload directly. The default parses string `data` as JSON and passes non-string `data` through unchanged; an override lets integrations with vendors that wrap the payload (e.g., Ably's `data.data` envelope) or use non-JSON formats extract the OFREP event object before `type` / `etag` / `lastModified` are read. -9. When a differing SSE `flagConfigEtag` selects a 200 response, the server MUST NOT downgrade that response to 304 because `If-None-Match` or another HTTP conditional validator would otherwise produce 304. When this condition does not occur, normal HTTP conditional-cache handling applies. +9. When a differing SSE `flagConfigEtag` dictates a 200 response, the server MUST NOT downgrade that response to 304 because `If-None-Match` or another HTTP conditional validator would otherwise produce 304. When this condition does not occur, normal HTTP conditional-cache handling applies. ### OpenAPI Schema Additions