Merge pull request #1371 from NHSDigital/spike-open-feature

Implement 'open feature' feature flagging

Author: gpeng

Dockerfile

@@ -53,6 +53,7 @@ COPY --from=python_builder --chown=${CONTAINER_USER}:${CONTAINER_GROUP} ${VIRTUA
 COPY --chown=${CONTAINER_USER}:${CONTAINER_GROUP} ./manage_breast_screening /app/manage_breast_screening
 COPY --from=node_builder --chown=${CONTAINER_USER}:${CONTAINER_GROUP} /app/manage_breast_screening/assets/compiled /app/manage_breast_screening/assets/compiled
 COPY --chown=${CONTAINER_USER}:${CONTAINER_GROUP} manage.py ./
+COPY --chown=${CONTAINER_USER}:${CONTAINER_GROUP} --chmod=444 flags*.yml ./
 COPY --chown=root:root --chmod=755 scripts/docker/entrypoint.sh /app/entrypoint.sh
 
 # Run django commands

docs/feature-flags.md

@@ -0,0 +1,68 @@
+# Feature flags
+
+Feature flags are implemented using [OpenFeature](https://openfeature.dev/) with an `InMemoryProvider`. Flags are declared in YAML files and loaded at startup.
+
+## Flag files
+
+Each environment has its own flag file. The application selects the file based on the `DEPLOYED_TO` environment variable, falling back to `flags.yml` for local development where `DEPLOYED_TO` is not set.
+
+| Environment                  | File                   |
+| ---------------------------- | ---------------------- |
+| dev                          | `flags.dev.yml`        |
+| review                       | `flags.review.yml`     |
+| preprod                      | `flags.preprod.yml`    |
+| production                   | `flags.production.yml` |
+| local (no `DEPLOYED_TO` set) | `flags.yml`            |
+
+## Adding a flag
+
+**1. Declare the flag in each environment's file.**
+
+Add an entry to all five flag files (`flags.yml`, `flags.dev.yml`, `flags.review.yml`, `flags.preprod.yml`, `flags.production.yml`). Set the value to `true` to enable or `false` to disable in that environment.
+
+```yaml
+flags:
+  my_flag: false
+```
+
+**2. Check the flag in application code.**
+
+```python
+from manage_breast_screening.core.feature_flags import FeatureFlag
+
+if FeatureFlag.is_enabled("my_flag"):
+    # feature is enabled
+```
+
+`FeatureFlag.is_enabled` returns `False` if the flag is missing or the provider is unavailable. If a flag name is not found in the YAML file, OpenFeature silently returns the fallback rather than raising an error — so a typo in a flag name will return `False` without any indication something is wrong.
+
+## Enabling a flag in tests
+
+Use the `with_flag_enabled` fixture to turn a flag on for the duration of a single test:
+
+```python
+def test_something(with_flag_enabled):
+    with_flag_enabled("my_flag")
+    # flag is enabled for this test only
+```
+
+Multiple flags can be enabled by calling it more than once:
+
+```python
+def test_something(with_flag_enabled):
+    with_flag_enabled("my_flag")
+    with_flag_enabled("another_flag")
+```
+
+In class-based tests the fixture must be relayed via an `autouse` fixture so it is accessible to helper methods:
+
+```python
+@pytest.fixture(autouse=True)
+def flags(self, with_flag_enabled):
+    self.with_flag_enabled = with_flag_enabled
+
+def and_my_flag_is_enabled(self):
+    self.with_flag_enabled("my_flag")
+```
+
+After each test the flags are reset to the defaults from the YAML file.

docs/infrastructure/environment-variables.md

@@ -114,6 +114,17 @@ Postgres server port. Defaults to 5432. Required for review apps as each databas
 
 Database server admin user name. When using a managed identity, name of the managed identity.
 
+## DEPLOYED_TO
+
+Describes the environment the application is running in.
+
+**Values:**
+
+- `dev`
+- `review`
+- `preprod`
+- `production`
+
 ## DJANGO_ENV
 
 Specifies the Django environment configuration. This variable controls environment-specific behaviour throughout the application. It's primarily for ensuring non-production code is not run or made available in production.

flags.dev.yml

@@ -0,0 +1,2 @@
+flags:
+  gateway_images: false

flags.preprod.yml

@@ -0,0 +1,2 @@
+flags:
+  gateway_images: false

flags.production.yml

@@ -0,0 +1,2 @@
+flags:
+  gateway_images: false

flags.review.yml

@@ -0,0 +1,2 @@
+flags:
+  gateway_images: false

flags.yml

@@ -0,0 +1,2 @@
+flags:
+  gateway_images: false

infrastructure/environments/dev/variables.yml

@@ -1,3 +1,4 @@
+DEPLOYED_TO: dev
 BASE_URL: https://dev.manage-breast-screening.non-live.screening.nhs.uk
 BASIC_AUTH_ENABLED: True
 CIS2_SERVER_METADATA_URL: https://am.nhsint.auth-ptl.cis2.spineservices.nhs.uk/openam/oauth2/realms/root/realms/NHSIdentity/realms/Healthcare/.well-known/openid-configuration

infrastructure/environments/preprod/variables.yml

@@ -1,3 +1,4 @@
+DEPLOYED_TO: preprod
 BASE_URL: https://preprod.manage-breast-screening.nhs.uk
 BASIC_AUTH_ENABLED: True
 CIS2_SERVER_METADATA_URL: https://am.nhsint.auth-ptl.cis2.spineservices.nhs.uk/openam/oauth2/realms/root/realms/NHSIdentity/realms/Healthcare/.well-known/openid-configuration