Add Controllers::AutoRefreshingToken concern

This can optionally be included into your controller to automatically
use the user's refresh token to obtain a new access token when the old
one expires. It adds a before action to the target controller which
automatically calls `OauthClient#refresh_credentials!` if the user is
signed in and their access token has expired.

Again this has been substantially copied from `code-club-frontend`:
- `app/controllers/application_controller.rb` [1]
- `spec/requests/refresh_credentials_spec.rb` [2]

Some things that I've changed:
- Moved functionality from `ApplicationController` into an `RpiAuth`
  namespaced concern which can be included into the controller in the
  Rails app.
- Make `AutoRefreshingToken#refresh_credentials_if_needed` private since
  it's not a controller action.
- Use the home page in the dummy app in the request spec instead of the
  home page in `code-club-frontend`.
- Construct a user directly in the request spec; there's no user factory
  in the `rpi_auth` gem.
- Set `RpiAuth.configuration.user_model = 'User'` in the `before` block
  as per the other request specs.

I'm slightly concerned about a few details of the implementation of
`AutoRefreshingToken#refresh_credentials_if_needed`:
- Rescuing all `ArgumentError` exceptions seems risky, because it's
  quite a common exception. It would be better to be more specific.
- Even rescuing all `OAuth2::Error` exceptions seems a bit broad,
  although I haven't investigated what this encompasses.
- While resetting the session in the event of an exception seems OK
  security-wise, it probably doesn't result in a great user experience.
  It would be better to redirect and/or display an error message to the
  user to explain what's happened.

[1]: https://github.com/RaspberryPiFoundation/code-club-frontend/blob/f7e965798d910584fed0d1eb7867f32a899f9ce8/app/controllers/application_controller.rb#L8
[2]: https://github.com/RaspberryPiFoundation/code-club-frontend/blob/f7e965798d910584fed0d1eb7867f32a899f9ce8/spec/requests/refresh_credentials_spec.rb

Author: floehopper

lib/rpi_auth/controllers/auto_refreshing_token.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'oauth2/error'
+
+module RpiAuth
+  module Controllers
+    module AutoRefreshingToken
+      extend ActiveSupport::Concern
+
+      include CurrentUser
+
+      included do
+        before_action :refresh_credentials_if_needed
+      end
+
+      private
+
+      def refresh_credentials_if_needed
+        return unless current_user
+
+        return if Time.now.to_i < current_user.expires_at
+
+        current_user.refresh_credentials!
+        self.current_user = current_user
+      rescue OAuth2::Error, ArgumentError
+        reset_session
+      end
+    end
+  end
+end

spec/dummy/app/controllers/application_controller.rb

@@ -1,4 +1,7 @@
 require 'rpi_auth/controllers/current_user'
+require 'rpi_auth/controllers/auto_refreshing_token'
+
 class ApplicationController < ActionController::Base
   include RpiAuth::Controllers::CurrentUser
+  include RpiAuth::Controllers::AutoRefreshingToken
 end

spec/dummy/spec/requests/refresh_credentials_spec.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+require 'oauth2/error'
+
+RSpec.describe 'Refreshing the auth token', type: :request do
+  include ActiveSupport::Testing::TimeHelpers
+
+  subject(:request) { get root_path }
+
+  let(:logged_in_text) { 'Log out' }
+  let(:stub_oauth_client) { instance_double(RpiAuth::OauthClient) }
+
+  before do
+    freeze_time
+    allow(RpiAuth::OauthClient).to receive(:new).and_return(stub_oauth_client)
+    allow(stub_oauth_client).to receive(:refresh_credentials).with(any_args)
+    RpiAuth.configuration.user_model = 'User'
+  end
+
+  after do
+    unfreeze_time
+  end
+
+  shared_examples 'there is no attempt to renew the token' do
+    it 'calls refresh_credentials on the oauth client' do
+      request
+      expect(stub_oauth_client).not_to have_received(:refresh_credentials)
+    end
+  end
+
+  shared_examples 'there is an attempt to renew the token' do
+    it 'does not call refresh_credentials on the oauth client' do
+      request
+      expect(stub_oauth_client).to have_received(:refresh_credentials)
+    end
+  end
+
+  shared_examples 'the user is logged in' do
+    it do
+      request
+      expect(response.body).to include(logged_in_text)
+    end
+  end
+
+  shared_examples 'the user is logged out' do
+    it do
+      request
+      expect(response.body).not_to include(logged_in_text)
+    end
+  end
+
+  context 'when not logged in' do
+    it_behaves_like 'the user is logged out'
+    it_behaves_like 'there is no attempt to renew the token'
+  end
+
+  context 'when logged in' do
+    let(:user) { User.new(expires_at:) }
+
+    before do
+      log_in(user:)
+    end
+
+    context 'when the access token has not expired' do
+      let(:expires_at) { 10.seconds.from_now }
+
+      it_behaves_like 'the user is logged in'
+      it_behaves_like 'there is no attempt to renew the token'
+    end
+
+    context 'when the access token has expired' do
+      let(:expires_at) { 10.seconds.ago }
+
+      before do
+        allow(stub_oauth_client).to receive(:refresh_credentials).with(any_args).and_return({ access_token: 'foo',
+                                                                                              refresh_token: 'bar',
+                                                                                              expires_at: 10.minutes.from_now })
+      end
+
+      it_behaves_like 'the user is logged in'
+      it_behaves_like 'there is an attempt to renew the token'
+
+      context 'when an OAuth error is raised' do
+        before do
+          allow(stub_oauth_client).to receive(:refresh_credentials).with(any_args).and_raise(OAuth2::Error.new('blargh'))
+        end
+
+        it_behaves_like 'the user is logged out'
+        it_behaves_like 'there is an attempt to renew the token'
+      end
+    end
+  end
+end