feat: implement ADR-0008 event stream support in OpenAPI spec

[jonathannorris]

Summary

• Implements the OpenAPI spec changes defined in ADR-0008
• Bumps OpenAPI version from 3.1.0 to 3.2.0 for text/event-stream / itemSchema support
• Bumps OFREP version from 0.2.0 to 0.3.0
• Adds eventStreams to both evaluation success responses, flagConfigEtag / flagConfigLastModified query parameters to both eval endpoints, and new schemas for event stream connections and event payloads
• Adds a webhook documenting the text/event-stream content type using OAS 3.2.0 conventions

Notes

• The eventStream schema enforces mutual exclusivity between url and endpoint using oneOf + not clauses
• endpoint provides structured origin + requestUri for proxied deployments that need to override the origin cleanly while preserving the request target
• Query parameter descriptions use generic "event stream" / "change notification" language rather than SSE-specific terms, since eventStreams is designed to be extensible beyond SSE

Related Issues

• Implements: ADR-0008
• Relates to: docs: add ADR for SSE bulk evaluation change notifications #63

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the OpenFeature Remote Evaluation Protocol (OFREP) by integrating event stream support, aligning with ADR-0008. It updates the OpenAPI specification to version 3.2.0 and the OFREP version to 0.3.0, enabling real-time change notifications for flag configurations. This allows providers to subscribe to event streams for immediate updates, moving beyond traditional polling mechanisms for detecting changes.

Highlights

• ADR-0008 Implementation: Implemented event stream support in the OpenAPI specification as defined in ADR-0008, enabling real-time change notifications for flag configurations.
• OpenAPI Version Update: Updated the OpenAPI specification version from 3.1.0 to 3.2.0 to support text/event-stream and itemSchema.
• OFREP Version Bump: Bumped the OpenFeature Remote Evaluation Protocol (OFREP) version from 0.2.0 to 0.3.0.
• Event Stream Integration: Introduced an eventStreams property to both single and bulk evaluation success responses, providing connection details for change notifications.
• New Query Parameters: Added flagConfigEtag and flagConfigLastModified query parameters to evaluation endpoints, allowing for change-triggered re-fetches with cache validation metadata.
• New Schemas Defined: Defined new schemas for event stream connections (eventStream, eventStreamEndpoint) and Server-Sent Event (SSE) payloads (sseEvent, sseEventData).
• Webhook Documentation: Included a webhook definition for flagConfigChanged to document the text/event-stream content type using OAS 3.2.0 conventions.
• Spectral Rule Disabled: Disabled the oas3-schema rule in .spectral.yaml due to current Spectral limitations with OpenAPI 3.2.0 support.

Changelog

• .spectral.yaml
  • Disabled oas3-schema rule.
• service/openapi.yaml
  • Updated OpenAPI version from 3.1.0 to 3.2.0.
  • Updated OFREP version from 0.2.0 to 0.3.0.
  • Added flagConfigEtag query parameter to /evaluate endpoint.
  • Added flagConfigLastModified query parameter to /evaluate endpoint.
  • Added eventStreams property to the successful evaluation response example for /evaluate.
  • Added flagConfigEtag query parameter to /evaluate/batch endpoint.
  • Added flagConfigLastModified query parameter to /evaluate/batch endpoint.
  • Added eventStreams property to the successful bulk evaluation response example for /evaluate/batch.
  • Introduced webhooks section with flagConfigChanged for SSE documentation.
  • Added eventStreams property to bulkEvaluationSuccess schema.
  • Added eventStreams property to serverEvaluationSuccess schema.
  • Defined new eventStream schema, including type, url, endpoint, and inactivityDelaySec properties, with oneOf for url or endpoint.
  • Defined new eventStreamEndpoint schema with origin and requestUri.
  • Defined new sseEvent schema for Server-Sent Events, including data, event, id, and retry.
  • Defined new sseEventData schema for SSE event payloads, including type, etag, and lastModified.

Activity

• No human activity (comments, reviews, etc.) has occurred on this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request successfully implements ADR-0008 by adding event stream support to the OpenAPI specification. The changes are well-structured, including the version bump to OpenAPI 3.2.0, the addition of new schemas for event streams, and new query parameters. My review includes a few suggestions to enhance maintainability and schema precision by reducing parameter duplication and adding more specific constraints to the new schemas.

I am having trouble creating individual review comments. Click here to see my feedback.

service/openapi.yaml (57-90)

To improve maintainability and reduce duplication, consider defining the flagConfigEtag and flagConfigLastModified parameters as reusable components under components.parameters. You can then reference them in both the /ofrep/v1/evaluate/flags/{key} and /ofrep/v1/evaluate/flags paths using $ref. This ensures consistency and simplifies future updates.

service/openapi.yaml (453-459)

The description states that currently only sse is a defined type. To make the schema more precise and self-documenting for the current version, consider constraining this field to the known value using enum.

        type:
          type: string
          enum: ["sse"]
          description: |
            The connection type identifying the push mechanism to use.
            Currently only `sse` is defined. Providers must ignore entries
            with unknown types for forward compatibility.
          example: "sse"

service/openapi.yaml (474-485)

The description mentions that providers should default to 120 seconds for inactivityDelaySec if the value is not present. It's a good practice to explicitly define this default in the schema using the default keyword. This makes the API contract clearer for consumers.

        inactivityDelaySec:
          type: integer
          minimum: 1
          default: 120
          description: |
            Number of seconds of client inactivity (e.g., browser tab hidden,
            mobile app backgrounded) after which the connection should be closed
            to conserve resources. The client must reconnect and perform a full
            unconditional re-fetch when activity resumes. When determining the
            effective inactivity timeout, providers should use a client-side
            override if configured; otherwise use this value when present;
            otherwise default to 120 seconds.
          example: 120

service/openapi.yaml (524-529)

The description states that the SSE event type is always message. To enforce this and make the schema more strict, you can add an enum with the single allowed value.

        event:
          type: string
          enum: ["message"]
          description: |
            The SSE event type. Always `message` for OFREP events. Providers
            must inspect `data.type` rather than this field for event routing.
          example: "message"

service/openapi.yaml (550-555)

The description mentions that currently only refetchEvaluation is defined for the event type. To make the schema more precise for this version of the API, you can constrain this field to the known value using enum.

        type:
          type: string
          enum: ["refetchEvaluation"]
          description: |
            The OFREP event type. Currently only `refetchEvaluation` is defined.
            Providers must ignore unknown values for forward compatibility.
          example: "refetchEvaluation"

[beeme1mr]

Should the example use both single and double quotes?