govuk_personalisation 0.2.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f19f176c2aa1874082e94b2798bc865b4b612ec92682ba41d8b6ed386239543
-  data.tar.gz: 50c849e85a7d2115316c7db368e16f2c15649f82265b1a2c87a787aae49018e1
+  metadata.gz: '08b691342c4c22592162f9eb11e8c8f74b8fea75af5669568c71d15337166626'
+  data.tar.gz: 0e266ec1d1f91a7537ccef2c1a4398e90b4c0435546772d41877cfd34e9df092
 SHA512:
-  metadata.gz: e9ddd7d63d119782c1a8663ba076f233881dbfd04fadd9007d53afaaa68555145a10c30e1a0e2e04f65867d79c13ba662a9febb0e2ba4ba657bf056056efa6f2
-  data.tar.gz: '02950b7e918f99b08f2cbeeec51da89e8aeaaa7be115250c4e918aebf0a06e6fb7768c59cf208f20dc17c11c7edf346fcc2edbe1c4ff9a3c2caabad9673d4941'
+  metadata.gz: 5f265633173eee3b60e436c781ddb4047d849471cc1760d88e8c3e497a79d8a0fd188a4c3908feb33fecf3b8c2b171dbbc1ea7f08ed837fae2d58cfc5658ae35
+  data.tar.gz: d90dc8a74720981e16d7d379939c08072806ead930d012bb40c1a57ac2e90ae3879a10d7fb0bfbe3d874d39c70312952d72c0c9eca452fd757906c253ecb402e

data/CHANGELOG.md

@@ -1,7 +1,26 @@
-## [0.2.0]
+# 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))
+
+# 0.2.0
 
 - Add AccountConcern to extract common account-related functionality ([#3](https://github.com/alphagov/govuk_personalisation/pull/3))
 
-## [0.1.0] - 2021-05-12
+# 0.1.0
 
 - Initial release

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/lib/govuk_personalisation.rb

@@ -1,9 +1,9 @@
 # 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"
 
-module GovukPersonalisation
-  class Error < StandardError; end
-  # Your code goes here...
-end
+module GovukPersonalisation; end

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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: govuk_personalisation
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.6.0
 platform: ruby
 authors:
 - GOV.UK Dev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-06-01 00:00:00.000000000 Z
+date: 2021-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -116,7 +116,10 @@ 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/version.rb
 homepage: https://github.com/alphagov/govuk_personalisation
 licenses:
@@ -137,7 +140,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,55 +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
-      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_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