govuk_content_item_loader 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 365987707cc39e8b636dfa88723bf0dd4c94a927b10188e72d2cc1a6db083abf
-  data.tar.gz: 32de377938b8a4c3f7c5ed0ef369f4d18e67a807defb745ef1bf2d348db08266
+  metadata.gz: 2a533cf2cd72d38cfd19f7ef5555bb14c93156638ff6220d1dd494d92550a390
+  data.tar.gz: a1e9a897b7b82e747d81434c1d5965d550507edaa3a2a5ae4abde20df63e62ac
 SHA512:
-  metadata.gz: '068e7bdf5420dac1daaebb68ceef011475c4ddd94b2204793c0e650909d4ae11c6606c8118d31980241e4fffcfdb2002a607cb3cb88ec8fcbced97ad580d8eb8'
-  data.tar.gz: 695b64ce8e808861f42d95fa0e1516b326257dc0518dba887677e6619283d01a9dcdfcb0d59093b21b99a22613a6ac7b5a12c60c37c0ebbb4a8a52972d7cee96
+  metadata.gz: 85e6a82e33eb3fab62a93bfda0eeff17314f6ac79b4a6e9f2f09b138cbfa5c9c3812557b0638a5d294d9f28c790ee5f6b2e24293b28bd7042699e17c13b037b3
+  data.tar.gz: 7fd62a7aecc2bd6a214a92c6576a0469b3766d548ba699326f9798f7330d2f7b8fa5a219fca55fdac83e064aff2bd5a0e3ffe664ac1518ac6c8b36fe22af35f1

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 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/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,74 @@
+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
+    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)
+    raise e
+  rescue GdsApi::TimedOutException => e
+    set_prometheus_labels(graphql_api_timeout: true)
+    raise e
+  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.0.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.0.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
@@ -117,6 +159,8 @@ files:
 - Rakefile
 - 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: