govuk_personalisation 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7494e4a43a49be9a654d9b95ad2a2884575c3d46b8b6e5487b9c472575705ada
-  data.tar.gz: 4321076a89efdcc1289d3dccb23eb7c26a87dd877dc63764d1d6da796f18c128
+  metadata.gz: '08b691342c4c22592162f9eb11e8c8f74b8fea75af5669568c71d15337166626'
+  data.tar.gz: 0e266ec1d1f91a7537ccef2c1a4398e90b4c0435546772d41877cfd34e9df092
 SHA512:
-  metadata.gz: 3d772b13491114187dc74f38ceb5959721da4e9df7caa46384fea1e5b7e2f0bdc96486b9e11e1f07a40da625371bfd219f10024d801f417fe23da75ec32ce435
-  data.tar.gz: 1e68f1eeb364957909271666d19a12af06c3f64f47744c9e34d7850a99282b67685cace40b997d5b56a4245b1b7501fc8d03e4c2eaec61b8eddd91957604783f
+  metadata.gz: 5f265633173eee3b60e436c781ddb4047d849471cc1760d88e8c3e497a79d8a0fd188a4c3908feb33fecf3b8c2b171dbbc1ea7f08ed837fae2d58cfc5658ae35
+  data.tar.gz: d90dc8a74720981e16d7d379939c08072806ead930d012bb40c1a57ac2e90ae3879a10d7fb0bfbe3d874d39c70312952d72c0c9eca452fd757906c253ecb402e

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# 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))

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,11 +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

@@ -1,8 +1,13 @@
 module GovukPersonalisation
   module TestHelpers
     module Features
-      def mock_logged_in_session(value = "placeholder")
-        page.driver.header("GOVUK-Account-Session", value)
+      # 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

data/lib/govuk_personalisation/test_helpers/requests.rb

@@ -1,8 +1,12 @@
 module GovukPersonalisation
   module TestHelpers
     module Requests
-      def mock_logged_in_session(value = "placeholder")
-        request.headers["GOVUK-Account-Session"] = value
+      # 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

data/lib/govuk_personalisation/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GovukPersonalisation
-  VERSION = "0.5.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.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - GOV.UK Dev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-06-09 00:00:00.000000000 Z
+date: 2021-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -116,7 +116,8 @@ 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

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_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
-    end
-
-    def logged_in?
-      account_session_header.present?
-    end
-
-    def fetch_account_session_header
-      @account_session_header =
-        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
-    end
-
-    def set_account_vary_header
-      response.headers["Vary"] = [response.headers["Vary"], ACCOUNT_SESSION_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_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_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