govuk_content_item_loader 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 365987707cc39e8b636dfa88723bf0dd4c94a927b10188e72d2cc1a6db083abf
-  data.tar.gz: 32de377938b8a4c3f7c5ed0ef369f4d18e67a807defb745ef1bf2d348db08266
+  metadata.gz: 947921788377a6a5dd65917c2f546d8baaabbab0183a9673df551a064b422457
+  data.tar.gz: 9aecaf319b535faa6172cf652cd195e89dadc0dd92858db2c25b9737309b9e48
 SHA512:
-  metadata.gz: '068e7bdf5420dac1daaebb68ceef011475c4ddd94b2204793c0e650909d4ae11c6606c8118d31980241e4fffcfdb2002a607cb3cb88ec8fcbced97ad580d8eb8'
-  data.tar.gz: 695b64ce8e808861f42d95fa0e1516b326257dc0518dba887677e6619283d01a9dcdfcb0d59093b21b99a22613a6ac7b5a12c60c37c0ebbb4a8a52972d7cee96
+  metadata.gz: 6f5f426102604ffce580a33b0fead1eb99d623f4500cd308669bf95b4ab49d9239e7d4dab37917ce32a513ec28cc3a8682c09833aca0136bff5cee5b7a443c0a
+  data.tar.gz: ee6e8a19ff172558e8aaa0a86c80c189f41213f09cc1715e00e18b2e0be62d32d7e40a815ec745880c197f97135c7d622b57725050a5ad2120989fe334bb9ebf

data/.github/workflows/autorelease.yml

@@ -6,7 +6,5 @@ on:
 jobs:
   autorelease:
     uses: alphagov/govuk-infrastructure/.github/workflows/autorelease-rubygem.yml@main
-    with:
-      gem_name: content_block_tools
     secrets:
       GH_TOKEN: ${{ secrets.GOVUK_CI_GITHUB_API_TOKEN }}

data/.github/workflows/ci.yml

@@ -38,7 +38,7 @@ jobs:
     - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         ref: ${{ inputs.ref || github.ref }}
-    - uses: ruby/setup-ruby@09a7688d3b55cf0e976497ff046b70949eeaccfd # v1.288.0
+    - uses: ruby/setup-ruby@6ca151fd1bfcfd6fe0c4eb6837eb0584d0134a0c # v1.290.0
       with:
         ruby-version: ${{ matrix.ruby }}
         bundler-cache: true

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.1.0
+
+- Add Content Store fallback for failed Graphql requests
+
+## 1.0.0
+
+- Add GraphQL traffic rates initializer.
+- Add request-level conditional content item loader for GraphQL traffic routing with `load` and `can_load_from_graphql?` methods.
+
 ## 0.1.0
 
 Initial release

data/README.md

@@ -2,6 +2,90 @@
 
 Ruby gem that standardises how GOV.UK frontend apps load content items. It provides configurable GraphQL traffic rates per content schema and a request-level loader that routes requests to the Publishing API via GraphQL or falls back to the Content Store ensuring consistent traffic management across applications.
 
+## Installation
+
+Install the gem
+
+    `gem install govuk_content_item_loader`
+
+or add it to your Gemfile
+
+    `gem "govuk_content_item_loader"`
+
+## GraphQL traffic rates
+
+Provides a canonical way for frontend apps to configure GraphQL traffic rates for relevant content schemas. It sets the following application configuration:
+
+* `Rails.application.config.graphql_allowed_schemas` - array of schema names that are eligible to be served via GraphQL.
+* `Rails.application.config.graphql_traffic_rates` - hash mapping schema names to traffic percentages (as floats between 0 and 1.0).
+
+Traffic rates for individual schemas are set in `govuk-helm-charts` repository as environment variables, with the following format `GRAPHQL_RATE_<SCHEMA_NAME>`.
+
+### Usage
+
+To enable this functionality, create a file `config/initializers/govuk_graphql_traffic_rates.rb` in the app containing:
+
+```ruby
+GovukGraphqlTrafficRates.configure
+```
+
+## Conditional Content Item Loader
+
+This class acts as a traffic-splitting content loader that decides, per request, whether to fetch a content item from the **Publishing API via GraphQL** or fall back to the **Content Store**, based on request parameters and configured traffic-shaping rules based on content schemas.
+
+**In practice, it:**
+
+* Chooses between GraphQL (Publishing API) and the Content Store when loading a content item
+* Always disables GraphQL on draft hosts
+* Allows GraphQL to be explicitly forced on or off via the `graphql` request parameter
+* Falls back to the Content Store unless the content item’s schema is explicitly allow-listed
+* Uses a per-schema traffic rate to probabilistically route a percentage of requests to GraphQL
+* Records GraphQL success, error status codes and timeouts in Prometheus request labels
+* Propagates GdsApi errors
+
+### Usage 
+
+#### Prerequisites
+
+1. Ensure application configuration sets list of schema names that are eligible to be served via GraphQL and hash mapping schema names to traffic percentages via `GovukGraphqlTrafficRates` described above.
+
+2. Ensure the `PLEK_SERVICE_PUBLISHING_API_URI` environment variable is set in **govuk-helm-charts** for the live app (draft stack is handled via [`PLEK_HOSTNAME_PREFIX`](https://github.com/alphagov/plek/blob/main/CHANGELOG.md#410)), across all relevant environments, so the Publishing API (GraphQL) can be correctly resolved at runtime:
+
+  ```yaml
+  - name: PLEK_SERVICE_PUBLISHING_API_URI
+    value: "http://publishing-api-read-replica"
+  ```
+
+3. (Assumed true for all frontend apps) Ensure the application has Content Store connection configuration.
+
+#### Using the loader
+
+`GovukConditionalContentItemLoader` is intended to be used at the point where a request needs to load a content item, and where traffic may be conditionally routed to GraphQL instead of the Content Store.
+
+At its simplest, you initialise the loader with the current request and call load:
+```
+loader = GovukConditionalContentItemLoader.new(request: request)
+content_item = loader.load
+```
+
+By default, the loader uses:
+* `GdsApi.content_store` to fetch content from the Content Store
+* `GdsApi.publishing_api` to fetch content via GraphQL
+
+These defaults make it suitable for use in production code without additional configuration.
+
+*Passing custom clients*
+For testing or specialised use cases, you can explicitly pass in the API clients:
+```
+loader = GovukGraphql::ConditionalContentItemLoader.new(
+  request: request,
+  content_store_client: content_store_client,
+  publishing_api_client: publishing_api_client,
+)
+```
+
+The decision logic is also exposed via `can_load_from_graphql?`, allowing applications to make the routing decision themselves and implement custom fallback or error-handling behaviour if needed.
+
 ## Licence
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/docs/adr/01-new-gem-for-conditional-content-loading.md

@@ -0,0 +1,73 @@
+# ADR 1: Create a dedicated gem for conditional GraphQL content loading
+Status: Accepted
+Date: 2026-02-17
+
+## Context
+As part of the migration to GraphQL-backed content retrieval [RFC-172](https://github.com/alphagov/govuk-rfcs/blob/main/rfc-172-graphql-for-govuk.md), we are introducing a temporary (medium-term) ConditionalContentItemLoader that determines whether a request should load content from:
+* The Content Store (REST), or
+* The Publishing API via GraphQL
+
+This decision is made at request time and depends on:
+* Request parameters
+* Environment state (e.g. draft host)
+* Allow-list configuration
+* Probabilistic traffic splitting
+
+It includes Prometheus metrics labelling for monitoring and alerting.
+
+The loader is required across seven frontend applications.
+
+## Problem
+We need a centralised implementation to:
+* Avoid duplication and divergence across multiple apps
+* Maintain clear architectural boundaries
+* Keep configuration and routing logic co-located
+
+## Decision
+We will create a Ruby gem to encapsulate the conditional content loader and its configuration, with minimal dependencies.
+
+## Rationale
+1. Shared across multiple applications
+One gem ensures consistent behaviour and easier rollout coordination.
+
+1. Maintenance burden is acceptable
+The gem is small, with few dependencies.
+
+1. Not a good fit for `gds-api-adapters`
+`gds-api-adapters` is designed around a clear architectural pattern:
+* Each adapter corresponds to a single external API
+* Adapter methods map directly to HTTP endpoints
+* Namespaces reflect a 1:1 relationship with APIs
+
+The conditional loader does not fit this model as it's a higher-level orchestration layer, not a client abstraction. Adding it to gds-api-adapters would:
+* Blur architectural boundaries
+* Violate separation of concerns
+* Break the established software design pattern of the gem
+
+1. Not a good fit for `govuk_app_config`
+That library is intended for generic application configuration, not behaviour orchestration used by a subset of apps.
+
+1. Explicitly not using `govuk_ab_testing`
+`govuk_ab_testing` was considered. This is not a generic A/B test or experiment framework use case. Embedding this logic in govuk_ab_testing would conflate experimentation infrastructure with migration routing logic.
+
+1. Co-location with configuration
+The loader depends on configuration established via GovukGraphqlTrafficRates.configure which would fit in govuk_app_config. However, keeping it in the same gem reduces complexity and risk of misconfiguration. 
+
+## Alternatives considered
+- Duplicate in each app – rejected due to divergence risk.
+- Add to `gds-api-adapters` – rejected; violates separation of concerns.
+- Add to `govuk_app_config` – rejected; not just application configuration.
+- Add to `govuk_ab_testing` – rejected; not experimentation logic.
+
+## Consequences
+
+### Positive
+* Consistent behaviour across multiple applications
+* Clean architectural separation
+* Centralised rollout
+* Clear ownership of GraphQL migration logic
+* Versioned upgrades
+
+### Negative
+* One additional gem to maintain
+* Increase in dependency management overhead

data/govuk_content_item_loader.gemspec

@@ -20,7 +20,10 @@ Gem::Specification.new do |spec|
   spec.require_paths = %w[lib]
 
   spec.add_dependency "gds-api-adapters", ">= 99.3"
+  spec.add_dependency "railties", ">= 7.2"
 
+  spec.add_development_dependency "climate_control"
+  spec.add_development_dependency "ostruct"
   spec.add_development_dependency "rails", ">= 7.2"
   spec.add_development_dependency "rake", ">= 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"

data/lib/govuk_content_item_loader/govuk_conditional_content_item_loader.rb

@@ -0,0 +1,76 @@
+class GovukConditionalContentItemLoader
+  attr_reader :content_store_client, :publishing_api_client, :request, :base_path
+
+  def initialize(request:, content_store_client: GdsApi.content_store, publishing_api_client: GdsApi.publishing_api)
+    @content_store_client = content_store_client
+    @publishing_api_client = publishing_api_client
+    @request = request
+    @base_path = request&.path
+  end
+
+  def load
+    return content_item_from_content_store unless can_load_from_graphql?
+
+    content_item_from_graphql || content_item_from_content_store
+  end
+
+  def can_load_from_graphql?
+    return false unless request
+
+    return false if draft_host?
+
+    return force_graphql_param unless force_graphql_param.nil?
+
+    schema_name = content_item_from_content_store["schema_name"]
+    return false unless graphql_schema_allowed?(schema_name)
+
+    within_graphql_traffic_rate?(schema_name)
+  end
+
+private
+
+  def content_item_from_graphql
+    set_prometheus_labels
+    publishing_api_client.graphql_live_content_item(base_path)
+  rescue GdsApi::HTTPErrorResponse => e
+    set_prometheus_labels(graphql_status_code: e.code)
+    false
+  rescue GdsApi::TimedOutException
+    set_prometheus_labels(graphql_api_timeout: true)
+    false
+  end
+
+  def content_item_from_content_store
+    @content_item_from_content_store ||= content_store_client.content_item(base_path)
+  end
+
+  def set_prometheus_labels(graphql_status_code: 200, graphql_api_timeout: false)
+    prometheus_labels = request.env.fetch("govuk.prometheus_labels", {})
+
+    hash = {
+      "graphql_status_code" => graphql_status_code,
+      "graphql_api_timeout" => graphql_api_timeout,
+    }
+
+    request.env["govuk.prometheus_labels"] = prometheus_labels.merge(hash)
+  end
+
+  def draft_host?
+    ENV["PLEK_HOSTNAME_PREFIX"] == "draft-"
+  end
+
+  def force_graphql_param
+    return true if request.params["graphql"] == "true"
+
+    false if request.params["graphql"] == "false"
+  end
+
+  def graphql_schema_allowed?(schema_name)
+    Rails.application.config.graphql_allowed_schemas&.include?(schema_name) || false
+  end
+
+  def within_graphql_traffic_rate?(schema_name)
+    graphql_traffic_rate = Rails.application.config.graphql_traffic_rates&.dig(schema_name) || 0
+    Random.rand(1.0) < graphql_traffic_rate
+  end
+end

data/lib/govuk_content_item_loader/govuk_graphql_traffic_rates.rb

@@ -0,0 +1,15 @@
+module GovukGraphqlTrafficRates
+  def self.configure
+    rates = graphql_rates_from_env
+
+    Rails.application.config.graphql_traffic_rates = rates
+    Rails.application.config.graphql_allowed_schemas = rates.keys
+  end
+
+  def self.graphql_rates_from_env
+    ENV
+      .select { |key, _| key.start_with?("GRAPHQL_RATE_") }
+      .transform_keys { |key| key.delete_prefix("GRAPHQL_RATE_").downcase }
+      .transform_values(&:to_f)
+  end
+end

data/lib/govuk_content_item_loader/version.rb

@@ -1,3 +1,3 @@
 module GovukContentItemLoader
-  VERSION = "0.1.0".freeze
+  VERSION = "1.1.0".freeze
 end

data/lib/govuk_content_item_loader.rb

@@ -1 +1,3 @@
+require "govuk_content_item_loader/govuk_graphql_traffic_rates"
+require "govuk_content_item_loader/govuk_conditional_content_item_loader"
 require "govuk_content_item_loader/version"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: govuk_content_item_loader
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.1.0
 platform: ruby
 authors:
 - GOV.UK Dev
@@ -23,6 +23,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '99.3'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: climate_control
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -115,8 +157,11 @@ files:
 - LICENCE
 - README.md
 - Rakefile
+- docs/adr/01-new-gem-for-conditional-content-loading.md
 - govuk_content_item_loader.gemspec
 - lib/govuk_content_item_loader.rb
+- lib/govuk_content_item_loader/govuk_conditional_content_item_loader.rb
+- lib/govuk_content_item_loader/govuk_graphql_traffic_rates.rb
 - lib/govuk_content_item_loader/version.rb
 homepage: https://github.com/alphagov/govuk_content_item_loader
 licenses:
@@ -136,7 +181,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.7
 specification_version: 4
 summary: Provides a standardised content item loader for GOV.UK frontend apps with
   configurable GraphQL traffic routing and automatic fallback to the Content Store