govuk_personalisation 0.3.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfc2b7eaa63dff171682233c9a9aeb902e2e888b1ad3bba5bb6a1f0556d1c1e1
-  data.tar.gz: a8641359718d30bc54f193cdf902108c1de52b3167e7028c972ba228383807d9
+  metadata.gz: 5ba6e9b0f0533ecc545582e031f6faf0f734d727e42478ffea40ddac7635986e
+  data.tar.gz: '0974635ac43c8dfacb6894787db3d36b2608438117b41640364bfd40dcecb125'
 SHA512:
-  metadata.gz: 84c745bb3cd6b4b7d0e9ea6c420d4e9fb233e2be8342fe9a95d4afa47194d9b5686ffa783012a45ec48e976e52893ef3f2c091105659bf390f851604909a3939
-  data.tar.gz: b314b9488c92e1fce28082af10b876b47bfbad0e5f589fc33c301882af12a0a3cbf2cb61dfdf8273b4bbdc92b17fe1cebf790e15f50574d07985c521841d5411
+  metadata.gz: 0fdb4622d551eae409978cac47ea4dfc78205a33d6e6b324b0a4eae4ab97eb5730571cd038a49ae9d74167a50093771aa96e60062a8fadfe33dc9b57206da2a1
+  data.tar.gz: f11fc215ac0ab1bb8147c973398b1bba72a1f58a7ea838473ea05f305a2ac169bd527fb61e8eb7e5676be14fb02fde5ef821800868488b6250b0591e64e6aab0

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+# 0.7.0
+
+- Add `GovukPersonalisation::Urls` module ([#14](https://github.com/alphagov/govuk_personalisation/pull/14) [#16](https://github.com/alphagov/govuk_personalisation/pull/16))
+
+# 0.6.0
+
+- Add `GovukPersonalisation::Flash` and helper methods to the concern ([#9](https://github.com/alphagov/govuk_personalisation/pull/9))
+- Ensure every method has RDoc ([#10](https://github.com/alphagov/govuk_personalisation/pull/10))
+- Remove unused `GovukPersonalisation::Error` class ([#10](https://github.com/alphagov/govuk_personalisation/pull/10))
+- BREAKING: Rename `GovukPersonalisation::AccountConcern` to `GovukPersonalisation::ControllerConcern` ([#11](https://github.com/alphagov/govuk_personalisation/pull/11))
+
+# 0.5.0
+
+- Rename header name constants ([#7](https://github.com/alphagov/govuk_personalisation/pull/7))
+
+# 0.4.0
+
+- Add ability to set GOVUK-Account-Session ([#6](https://github.com/alphagov/govuk_personalisation/pull/6))
+
 # 0.3.0
 
 - Always set `Vary: GOVUK-Account-Session` response header ([#4](https://github.com/alphagov/govuk_personalisation/pull/4))

data/README.md

@@ -1,6 +1,6 @@
-# GovukPersonalisation
+# GOV.UK Personalisation
 
-A gem to hold shared code which other GOV.UK apps will use to implement
+A gem to hold shared code which other GOV.UK apps use to implement
 accounts-related functionality.
 
 ## Installation
@@ -17,13 +17,64 @@ And then execute:
 $ bundle install
 ```
 
-## Technical documentation
+## Usage
 
-<!-- TODO -->...
+### Rails concern
 
-### Testing
+Include the concern into a controller:
 
-<!-- TODO -->...
+```ruby
+include GovukPersonalisation::AccountConcern
+```
+
+And it will add `before_action` methods to:
+
+- fetch the account session identifier from the request headers, making it available as `account_session_header`
+- set a `Vary` response header, to ensure responses for different users are cached differently by the CDN
+
+The following functions are available:
+
+- `logged_in?` - check if there is an account session header
+- `set_account_session_header` - replace the current session value, and set the response header the CDN uses to update the user's cookie
+- `logout!` - clear the session value, and set the response header the CDN uses to remove the user's cookie
+
+When run in development mode (`RAILS_ENV=development`), a cookie on
+`dev.gov.uk` is used instead of custom headers.
+
+### Test helpers
+
+There are test helpers for both request and feature specs to log the
+user in.  Include the relevant helper:
+
+```ruby
+include GovukPersonalisation::TestHelpers::Requests
+```
+
+*or*
+
+```ruby
+include GovukPersonalisation::TestHelpers::Features
+```
+
+And then log the user in:
+
+```ruby
+before do
+  mock_logged_in_session
+end
+```
+
+If you need a specific session identifier, for example to match
+against it in WebMock stubs or with the [gds-api-adapters][] test
+helpers, you can pass it as an argument:
+
+```ruby
+before do
+  mock_logged_in_session("your-session-identifier-goes-here")
+end
+```
+
+[gds-api-adapters]: https://github.com/alphagov/gds-api-adapters
 
 ## License
 

data/govuk_personalisation.gemspec

@@ -25,9 +25,11 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = %w[lib]
 
+  spec.add_dependency "plek", ">= 1.9.0"
   spec.add_dependency "rails", "~> 6"
 
   spec.add_development_dependency "bundler"
+  spec.add_development_dependency "climate_control"
   spec.add_development_dependency "pry-byebug"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec-rails"

data/lib/govuk_personalisation/controller_concern.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module GovukPersonalisation
+  module ControllerConcern
+    extend ActiveSupport::Concern
+
+    ACCOUNT_SESSION_INTERNAL_HEADER_NAME = "HTTP_GOVUK_ACCOUNT_SESSION"
+    ACCOUNT_SESSION_HEADER_NAME = "GOVUK-Account-Session"
+    ACCOUNT_END_SESSION_HEADER_NAME = "GOVUK-Account-End-Session"
+    ACCOUNT_SESSION_DEV_COOKIE_NAME = "govuk_account_session"
+
+    included do
+      before_action :fetch_account_session_header
+      before_action :set_account_vary_header
+      attr_accessor :account_session_header
+      attr_reader :account_flash
+    end
+
+    # Read the `GOVUK-Account-Session` request header and set the
+    # `@account_session_header` and `@account_flash` variables.  Also
+    # sets a response header with an empty flash if there is a flash
+    # in the request.
+    #
+    # This is called as a `before_action`
+    #
+    # This should not be called after either of the
+    # `@govuk_account_session` or flash to return to the user have
+    # been changed, as those changes will be overwritten.
+    def fetch_account_session_header
+      session_with_flash =
+        if request.headers[ACCOUNT_SESSION_INTERNAL_HEADER_NAME]
+          request.headers[ACCOUNT_SESSION_INTERNAL_HEADER_NAME].presence
+        elsif Rails.env.development?
+          cookies[ACCOUNT_SESSION_DEV_COOKIE_NAME]
+        end
+
+      @account_session_header, flash = GovukPersonalisation::Flash.decode_session(session_with_flash)
+      @account_flash = (flash || []).index_with { |_| true }
+      @new_account_flash = {}
+
+      set_account_session_header unless @account_flash.empty?
+    end
+
+    # Set the `Vary: GOVUK-Account-Session` response header.
+    #
+    # This is called as a `before_action`, to ensure that pages
+    # rendered using one user's session are not served to another by
+    # our CDN.  You should only skip this action if you are certain
+    # that the response does not include any personalisation, or if
+    # you prevent caching in some other way (for example, with
+    # `Cache-Control: no-store`).
+    def set_account_vary_header
+      response.headers["Vary"] = [response.headers["Vary"], ACCOUNT_SESSION_HEADER_NAME].compact.join(", ")
+    end
+
+    # Check if the user has a session.
+    #
+    # This does not call account-api to verify that the session is
+    # valid, but an invalid session would not allow a user to access
+    # any personal data anyway.
+    #
+    # @return [true, false] whether the user has a session
+    def logged_in?
+      account_session_header.present?
+    end
+
+    # Set a new session header.
+    #
+    # This should be called after any API call to account-api which
+    # returns a new session value.  This is called automatically after
+    # updating the flash with `account_flash_add` or
+    # `account_flash_keep`
+    #
+    # Calling this after calling `logout!` will not prevent the user
+    # from being logged out.
+    #
+    # @param govuk_account_session [String, nil] the new session identifier
+    def set_account_session_header(govuk_account_session = nil)
+      @account_session_header = govuk_account_session if govuk_account_session
+
+      session_with_flash = GovukPersonalisation::Flash.encode_session(@account_session_header, @new_account_flash.keys)
+
+      response.headers[ACCOUNT_SESSION_HEADER_NAME] = session_with_flash
+      if Rails.env.development?
+        cookies[ACCOUNT_SESSION_DEV_COOKIE_NAME] = {
+          value: session_with_flash,
+          domain: "dev.gov.uk",
+        }
+      end
+    end
+
+    # Clear the `@account_session_header` and set the logout response
+    # header.
+    def logout!
+      response.headers[ACCOUNT_END_SESSION_HEADER_NAME] = "1"
+      @account_session_header = nil
+      if Rails.env.development?
+        cookies[ACCOUNT_SESSION_DEV_COOKIE_NAME] = {
+          value: "",
+          domain: "dev.gov.uk",
+          expires: 1.second.ago,
+        }
+      end
+    end
+
+    # Add a message to the flash to return to the user.  This does not
+    # change `account_flash`
+    #
+    # @param message [String] the message to add
+    #
+    # @return [true, false] whether the message is valid (and so has been added)
+    def account_flash_add(message)
+      return false unless GovukPersonalisation::Flash.valid_message? message
+
+      @new_account_flash[message] = true
+      set_account_session_header
+      true
+    end
+
+    # Copy all messages from the `account_flash` into the flash to
+    # return to the user.
+    def account_flash_keep
+      @new_account_flash = @account_flash.merge(@new_account_flash)
+      set_account_session_header
+    end
+  end
+end

data/lib/govuk_personalisation/flash.rb

@@ -0,0 +1,50 @@
+# frozen_string-literal: true
+
+module GovukPersonalisation::Flash
+  SESSION_SEPARATOR = "$$"
+  MESSAGE_SEPARATOR = ","
+  MESSAGE_REGEX = /\A[a-zA-Z0-9._\-]+\z/.freeze
+
+  # Splits the session header into a session value (suitable for using
+  # in account-api calls) and flash messages.
+  #
+  # @param encoded_session [String] the value of the `GOVUK-Account-Session` header
+  #
+  # @return [Array(String, Array<String>), nil] the session value and the flash messages
+  def self.decode_session(encoded_session)
+    session_bits = encoded_session&.split(SESSION_SEPARATOR)
+    return if session_bits.blank?
+
+    if session_bits.length == 1
+      [session_bits[0], []]
+    else
+      [session_bits[0], session_bits[1].split(MESSAGE_SEPARATOR)]
+    end
+  end
+
+  # Encodes the session value and a list of flash messages into a
+  # session header which can be returned to the user.
+  #
+  # @param session [String]        the session value
+  # @param flash   [Array<String>] the flash messages, which must all be `valid_message?`
+  #
+  # @return [String] the encoded session header value
+  def self.encode_session(session, flash)
+    if flash.blank?
+      session
+    else
+      "#{session}#{SESSION_SEPARATOR}#{flash.join(MESSAGE_SEPARATOR)}"
+    end
+  end
+
+  # Check if a string is valid as a flash message.
+  #
+  # @param message [String, nil] the flash message
+  #
+  # @return [true, false] whether the message is valid or not.
+  def self.valid_message?(message)
+    return false if message.nil?
+
+    message.match? MESSAGE_REGEX
+  end
+end

data/lib/govuk_personalisation/test_helpers/features.rb

@@ -0,0 +1,14 @@
+module GovukPersonalisation
+  module TestHelpers
+    module Features
+      # Set the `GOVUK-Account-Session` request header in the page
+      # driver.
+      #
+      # @param session_id [String]             the session identifier
+      # @param flash      [Array<String>, nil] the flash messages
+      def mock_logged_in_session(session_id = "placeholder", flash = nil)
+        page.driver.header("GOVUK-Account-Session", GovukPersonalisation::Flash.encode_session(session_id, flash))
+      end
+    end
+  end
+end

data/lib/govuk_personalisation/test_helpers/requests.rb

@@ -0,0 +1,13 @@
+module GovukPersonalisation
+  module TestHelpers
+    module Requests
+      # Set the `GOVUK-Account-Session` request header.
+      #
+      # @param session_id [String]             the session identifier
+      # @param flash      [Array<String>, nil] the flash messages
+      def mock_logged_in_session(session_id = "placeholder", flash = nil)
+        request.headers["GOVUK-Account-Session"] = GovukPersonalisation::Flash.encode_session(session_id, flash)
+      end
+    end
+  end
+end

data/lib/govuk_personalisation/urls.rb

@@ -0,0 +1,87 @@
+require "plek"
+
+module GovukPersonalisation::Urls
+  # Find the GOV.UK URL for the "sign in" page
+  #
+  # @return [String] the URL
+  def self.sign_in
+    find_govuk_url(var: "SIGN_IN", application: "frontend", path: "/sign-in")
+  end
+
+  # Find the GOV.UK URL for the "sign out" page
+  #
+  # @return [String] the URL
+  def self.sign_out
+    find_govuk_url(var: "SIGN_OUT", application: "frontend", path: "/sign-out")
+  end
+
+  # Find the GOV.UK URL for the "your account" page
+  #
+  # @return [String] the URL
+  def self.your_account
+    find_govuk_url(var: "YOUR_ACCOUNT", application: "frontend", path: "/account/home")
+  end
+
+  # Find the external URL for the "manage" page
+  #
+  # @return [String] the URL
+  def self.manage
+    find_external_url(var: "MANAGE", application: "account-manager", path: "/account/manage")
+  end
+
+  # Find the external URL for the "security" page
+  #
+  # @return [String] the URL
+  def self.security
+    find_external_url(var: "SECURITY", application: "account-manager", path: "/account/security")
+  end
+
+  # Find the external URL for the "feedback" page
+  #
+  # @return [String] the URL
+  def self.feedback
+    find_external_url(var: "FEEDBACK", application: "account-manager", path: "/feedback")
+  end
+
+  # Finds a URL on www.gov.uk.  This method is used so we can have
+  # links which work both in production (where the website root is
+  # returned) and in local development (where an application URL is
+  # returned).
+  #
+  # If `GOVUK_PERSONALISATION_#{var}_URI` is in the environment, that
+  # will be returned.
+  #
+  # Otherwise, a `www.gov.uk` URL will be returned (a `dev.gov.uk`
+  # domain in development mode)
+  #
+  # @param var         [String] the name of the variable to look up
+  # @param application [String] the name of the frontend application, passed to Plek, to use in development mode (if the env var is set, this is ignored)
+  # @param path        [String] the path to use (if the env var is set this is ignored)
+  #
+  # @return [String] the URL
+  def self.find_govuk_url(var:, application:, path:)
+    value_from_env_var = ENV["GOVUK_PERSONALISATION_#{var}_URI"]
+    if value_from_env_var
+      value_from_env_var
+    else
+      plek_application_uri = Rails.env.development? ? Plek.find(application) : Plek.new.website_root
+      "#{plek_application_uri}#{path}"
+    end
+  end
+
+  # Finds a URL outside www.gov.uk
+  #
+  # If `GOVUK_PERSONALISATION_#{var}_URI` is in the environment, that
+  # will be returned.
+  #
+  # Otherwise, an application URL generated by Plek will be returned.
+  #
+  # @param var         [String] the name of the variable to look up
+  # @param application [String] the name of the frontend application, passed to Plek (if the env var is set, this is ignored)
+  # @param path        [String] the path to use (if the env var is set this is ignored)
+  #
+  # @return [String] the URL
+  def self.find_external_url(var:, application:, path:)
+    ENV.fetch("GOVUK_PERSONALISATION_#{var}_URI", "#{Plek.find(application)}#{path}")
+  end
+end

data/lib/govuk_personalisation/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GovukPersonalisation
-  VERSION = "0.3.0"
+  VERSION = "0.7.0"
 end

data/lib/govuk_personalisation.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 require "govuk_personalisation/version"
-require "govuk_personalisation/account_concern"
+require "govuk_personalisation/controller_concern"
+require "govuk_personalisation/flash"
+require "govuk_personalisation/test_helpers/features"
+require "govuk_personalisation/test_helpers/requests"
+require "govuk_personalisation/urls"
 
-module GovukPersonalisation
-  class Error < StandardError; end
-  # Your code goes here...
-end
+module GovukPersonalisation; end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: govuk_personalisation
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.7.0
 platform: ruby
 authors:
 - GOV.UK Dev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-06-02 00:00:00.000000000 Z
+date: 2021-08-31 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: plek
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.9.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.9.0
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -38,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !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: pry-byebug
   requirement: !ruby/object:Gem::Requirement
@@ -116,7 +144,11 @@ files:
 - bin/setup
 - govuk_personalisation.gemspec
 - lib/govuk_personalisation.rb
-- lib/govuk_personalisation/account_concern.rb
+- lib/govuk_personalisation/controller_concern.rb
+- lib/govuk_personalisation/flash.rb
+- lib/govuk_personalisation/test_helpers/features.rb
+- lib/govuk_personalisation/test_helpers/requests.rb
+- lib/govuk_personalisation/urls.rb
 - lib/govuk_personalisation/version.rb
 homepage: https://github.com/alphagov/govuk_personalisation
 licenses:
@@ -137,7 +169,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: A gem to hold shared code which other GOV.UK apps will use to implement accounts-related

data/lib/govuk_personalisation/account_concern.rb

@@ -1,60 +0,0 @@
-# frozen_string_literal: true
-
-require "active_support/concern"
-
-module GovukPersonalisation
-  module AccountConcern
-    extend ActiveSupport::Concern
-
-    ACCOUNT_SESSION_REQUEST_HEADER_NAME = "HTTP_GOVUK_ACCOUNT_SESSION"
-    ACCOUNT_SESSION_RESPONSE_HEADER_NAME = "GOVUK-Account-Session"
-    ACCOUNT_END_SESSION_RESPONSE_HEADER_NAME = "GOVUK-Account-End-Session"
-    ACCOUNT_SESSION_DEV_COOKIE_NAME = "govuk_account_session"
-
-    included do
-      before_action :fetch_account_session_header
-      before_action :set_account_vary_header
-      attr_accessor :account_session_header
-    end
-
-    def logged_in?
-      account_session_header.present?
-    end
-
-    def fetch_account_session_header
-      @account_session_header =
-        if request.headers[ACCOUNT_SESSION_REQUEST_HEADER_NAME]
-          request.headers[ACCOUNT_SESSION_REQUEST_HEADER_NAME].presence
-        elsif Rails.env.development?
-          cookies[ACCOUNT_SESSION_DEV_COOKIE_NAME]
-        end
-    end
-
-    def set_account_vary_header
-      response.headers["Vary"] = [response.headers["Vary"], ACCOUNT_SESSION_RESPONSE_HEADER_NAME].compact.join(", ")
-    end
-
-    def set_account_session_header(govuk_account_session = nil)
-      @account_session_header = govuk_account_session if govuk_account_session
-      response.headers[ACCOUNT_SESSION_RESPONSE_HEADER_NAME] = @account_session_header
-      if Rails.env.development?
-        cookies[ACCOUNT_SESSION_DEV_COOKIE_NAME] = {
-          value: @account_session_header,
-          domain: "dev.gov.uk",
-        }
-      end
-    end
-
-    def logout!
-      response.headers[ACCOUNT_END_SESSION_RESPONSE_HEADER_NAME] = "1"
-      @account_session_header = nil
-      if Rails.env.development?
-        cookies[ACCOUNT_SESSION_DEV_COOKIE_NAME] = {
-          value: "",
-          domain: "dev.gov.uk",
-          expires: 1.second.ago,
-        }
-      end
-    end
-  end
-end