api_adaptor 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15a3973e6718c891d082915a0306fec878eaadbaaad013a25dcaba91ce0cb92f
-  data.tar.gz: d8da61b6f522276dcd74d569673bb6d4a0dd899ab43f9cb1ad85a85eec303c28
+  metadata.gz: ec2d6e2bc7c54d07e88bee9945a772f952076ba24b3f1fdf176e951bae3f8dad
+  data.tar.gz: c0d9d319cd02061d462eaba8bdc8cfd5a8dda94df5973e7ba8ef78fc3dada248
 SHA512:
-  metadata.gz: 24586320847f202c0913f4612a246c2e9e8fef9a380090b773101a8c9fd2204811051c9551fbd7a9c76ab6e25cea655185c213735f937e7a9278b30e120fbc54
-  data.tar.gz: 8c884ad4796aa32f2623c07d58aa15b8727f5b8dc22549fac2e7a9e2d61849643ce9059fb56edc3cc42c0f8ae0d19389377b20083d34afdf301e72f263c2f899
+  metadata.gz: 7ac1bd16754ce9ae420ad5ba9d3fc9d92ad280f896afcb5312688b880b228c179ca75a8edb6a16811064f6c3d71805045aae22312137b325b067a0339c801acf
+  data.tar.gz: 9dd42bfacca8f947ac4977c3f1a4970db143118dd101c851b61ecae8a4462cde109f4157e542020e57f147f01cc83973c11de3a8e9d0093dd7991241b1669485

data/.rubocop.yml

@@ -1,5 +1,7 @@
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.2
+  NewCops: disable
+  SuggestExtensions: false
 
 Style/StringLiterals:
   Enabled: true
@@ -10,4 +12,10 @@ Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
 
 Layout/LineLength:
-  Max: 120
+  Enabled: false
+
+Metrics:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false

data/CHANGELOG.md

@@ -1,4 +1,17 @@
-## [Unreleased]
+## [0.1.0] - 2025-31-01
+
+- Improvements to 307, 308 redirect behaviour
+- Greater configuration over redirect behaviour
+- Add CI/CD to Rubygems
+- Test against Ruby v4.0
+
+## [0.0.2] - 2024-14-01
+
+- Improvements to CI/CD
+  - Enable CodeQL
+  - Enable Dependabot
+  - Enable Rubocop Testing
+  - Enable unit testing against Ruby v3.2, v3.3, v3.4
 
 ## [0.0.1] - 2023-06-01
 

data/Gemfile.lock

@@ -1,75 +1,96 @@
 PATH
   remote: .
   specs:
-    api_adaptor (0.0.0)
+    api_adaptor (0.1.0)
       addressable (~> 2.8)
+      base64 (~> 0.3)
+      bigdecimal (>= 3.3, < 5.0)
+      link_header (~> 0.0.8)
+      logger (>= 1.6, < 2.0)
       rest-client (~> 2.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.4)
-      public_suffix (>= 2.0.2, < 6.0)
-    ast (2.4.2)
-    crack (0.4.5)
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    crack (1.0.1)
+      bigdecimal
       rexml
-    diff-lcs (1.5.0)
-    domain_name (0.5.20190701)
-      unf (>= 0.0.5, < 1.0.0)
-    hashdiff (1.0.1)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    domain_name (0.6.20240107)
+    hashdiff (1.2.1)
     http-accept (1.7.0)
     http-cookie (1.0.5)
       domain_name (~> 0.5)
-    json (2.6.3)
-    mime-types (3.4.1)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    link_header (0.0.8)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    mime-types (3.5.2)
       mime-types-data (~> 3.2015)
-    mime-types-data (3.2023.0218.1)
+    mime-types-data (3.2023.1205)
     netrc (0.11.0)
-    parallel (1.23.0)
-    parser (3.2.2.1)
+    parallel (1.27.0)
+    parser (3.3.10.1)
       ast (~> 2.4.1)
-    public_suffix (5.0.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.2)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.0.6)
-    regexp_parser (2.8.0)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
     rest-client (2.1.0)
       http-accept (>= 1.7.0, < 2.0)
       http-cookie (>= 1.0.2, < 2.0)
       mime-types (>= 1.16, < 4.0)
       netrc (~> 0.8)
-    rexml (3.2.5)
-    rspec (3.12.0)
-      rspec-core (~> 3.12.0)
-      rspec-expectations (~> 3.12.0)
-      rspec-mocks (~> 3.12.0)
-    rspec-core (3.12.2)
-      rspec-support (~> 3.12.0)
-    rspec-expectations (3.12.3)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-mocks (3.12.5)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-support (3.12.0)
-    rubocop (1.51.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    rubocop (1.84.0)
       json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
-      parser (>= 3.2.0.0)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.28.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.28.1)
-      parser (>= 3.2.1.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
     ruby-progressbar (1.13.0)
-    timecop (0.9.6)
-    unf (0.1.4)
-      unf_ext
-    unf_ext (0.0.8.2)
-    unicode-display_width (2.4.2)
-    webmock (3.18.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
+    timecop (0.9.10)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    webmock (3.26.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
@@ -82,6 +103,7 @@ DEPENDENCIES
   rake (~> 13.0)
   rspec (~> 3.0)
   rubocop (~> 1.21)
+  simplecov (~> 0.22)
   timecop (~> 0.9)
   webmock (~> 3.18)
 

data/README.md

@@ -7,90 +7,198 @@ Intended to bootstrap the quick writing of Adaptors for specific APIs, without h
 
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add api_adaptor
+```shell
+bundle add api_adaptor
+```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install api_adaptor
+```shell
+gem install api_adaptor
+```
+
+## Releasing
+
+Publishing is handled by GitHub Actions when you push a version tag.
+
+- RubyGems publishing uses **Trusted Publishing (OIDC)** via `rubygems/release-gem`
+- Ensure `api_adaptor` is configured on RubyGems.org with this repository/workflow as a trusted publisher.
+- Bump `ApiAdaptor::VERSION` in `lib/api_adaptor/version.rb`.
+- Tag the release as `vX.Y.Z` (must match `ApiAdaptor::VERSION`) and push the tag:
+
+```shell
+git tag v0.1.1
+git push origin v0.1.1
+```
 
 ## Usage
 
 Use the ApiAdaptor as a base class for your API wrapper, for example:
 
-```
-  class MyApi < ApiAdaptor::Base
-    def base_url
-      endpoint
-    end
-  end
+```ruby
+  class MyApi < ApiAdaptor::Base; end
 ```
 
 Use your new class to create a client that can make HTTP requests to JSON APIs for:
 
-### GET JSON
-
-```
-    client = MyApi.new
-    response = client.get_json("http://some.endpoint/json")
+```ruby
+client = MyApi.new
+client.get_json("http://some.endpoint/json")
+client.post_json("http://some.endpoint/json", { "foo": "bar" })
+client.put_json("http://some.endpoint/json", { "foo": "bar" })
+client.patch_json("http://some.endpoint/json", { "foo": "bar" })
+client.delete_json("http://some.endpoint/json", { "foo": "bar" })
 ```
 
-### POST JSON
+You can also get a raw response from the API
 
-```
-    client = MyApi.new
-    response = client.post_json("http://some.endpoint/json", { "foo": "bar" })
+```ruby
+client.get_raw("http://some.endpoint/json")
 ```
 
-### PUT JSON
+### Redirects (3xx)
 
-```
-    client = MyApi.new
-    response = client.put_json("http://some.endpoint/json", { "foo": "bar" })
-```
+Some APIs return a `3xx` response (commonly `307`/`308`) with a `Location` header that points to the “real” URL.
+`ApiAdaptor::JsonClient` follows these redirects in a controlled way so callers consistently receive a final JSON response.
+
+#### Defaults
+
+- Redirects are followed for `GET`/`HEAD` when the status is `301`, `302`, `303`, `307`, or `308`.
+- `max_redirects` defaults to `3`.
+- Cross-origin redirects (scheme/host/port change) are allowed by default, but credentials are **not** forwarded.
+- Non-GET requests (`POST`, `PUT`, `PATCH`, `DELETE`) do **not** follow redirects by default.
+
+#### Configuration
 
-### PATCH JSON
+You can configure redirect behaviour by passing options into your `ApiAdaptor::Base` subclass (they are forwarded to `ApiAdaptor::JsonClient`):
 
+```ruby
+client = MyApi.new(
+  "https://example.com",
+  max_redirects: 3,
+  allow_cross_origin_redirects: true,
+  forward_auth_on_cross_origin_redirects: false,
+  follow_non_get_redirects: false
+)
+
+client.get_json("https://example.com/some/endpoint.json")
 ```
-    client = MyApi.new
-    response = client.patch_json("http://some.endpoint/json", { "foo": "bar" })
+
+Or, if you are using `ApiAdaptor::JsonClient` directly:
+
+```ruby
+client = ApiAdaptor::JsonClient.new(
+  bearer_token: "SOME_BEARER_TOKEN",
+  max_redirects: 3,
+  allow_cross_origin_redirects: true,
+  forward_auth_on_cross_origin_redirects: false
+)
+
+client.get_json("https://example.com/some/endpoint.json")
 ```
 
-### DELETE JSON
+#### Security: auth and cross-origin redirects
+
+Following redirects across origins can accidentally leak credentials (for example `Authorization` bearer tokens) to an unexpected host.
+To reduce risk:
+
+- By default, when the redirect target is cross-origin, `Authorization` is stripped and basic auth is not applied.
+- To completely prevent cross-origin redirects, set `allow_cross_origin_redirects: false`.
+- Only set `forward_auth_on_cross_origin_redirects: true` if you fully trust the redirect target.
 
+#### Non-GET redirects (risk of replay)
+
+Redirects for non-GET requests are risky because they may cause a request to be replayed (and potentially create duplicate side effects).
+For that reason, redirect-following is disabled for non-GET requests by default.
+
+If you do want to follow `307`/`308` for non-GET requests, you can opt in:
+
+```ruby
+client = MyApi.new(
+  "https://example.com",
+  follow_non_get_redirects: true
+)
+
+client.post_json("https://example.com/some/endpoint.json", { "a" => 1 })
 ```
-    client = MyApi.new
-    response = client.delete_json("http://some.endpoint/json", { "foo": "bar" })
+
+#### Handling redirect failures
+
+You can rescue these redirect-specific exceptions:
+
+- `ApiAdaptor::TooManyRedirects` (exceeded `max_redirects`)
+- `ApiAdaptor::RedirectLocationMissing` (a redirect response without a usable `Location`)
+
+Example:
+
+```ruby
+begin
+  client.get_json("https://example.com/some/endpoint.json")
+rescue ApiAdaptor::TooManyRedirects, ApiAdaptor::RedirectLocationMissing => e
+  # handle / log / retry / surface a friendly message
+  raise e
+end
 ```
 
-### GET raw requests
+### Conventional usage
 
-you can also get a raw response from the API
+An example of how to use this repository to bootstrap an API can be found in the [WikiData REST adaptor](https://github.com/huwd/wikidata_adaptor) it was built for.
 
+A REST API module can be created with:
+
+```ruby
+module MyApiAdaptor
+  # Wikidata REST API class
+  class RestApi < ApiAdaptor::Base
+    def get_foo(foo_id)
+      get_json("#{endpoint}/foo/#{CGI.escape(foo_id)}")
+    end
+  end
+end
 ```
-    client = MyApi.new
-    response = client.get_raw("http://some.endpoint/json")
+
+and can be wrapped in a top level module:
+
+```ruby
+module MyApiAdaptor
+  class Error < StandardError; end
+
+  def self.rest_endpoint
+    ENV["MYAPI_REST_ENDPOINT"] || "https://example.com"
+  end
+
+  def self.rest_api
+    MyApiAdaptor::RestApi.new(rest_endpoint)
+  end
+end
 ```
 
+The intended convention is to have test helpers ship alongside the actual Adaptor code.
+See [WikiData examples here](https://github.com/huwd/wikidata_adaptor/blob/main/lib/wikidata_adaptor/test_helpers/rest_api.rb).
+This allows other applications that integrate the API Adaptor to easily mock out calls and receive representative data back.
+
 ## Environment variables
 
 User Agent is populated with a default string.
 See .env.example.
 
 For instance if you provide:
-```
+
+```bash
 APP_NAME=test_app
 APP_VERSION=1.0.0
 APP_CONTACT=contact@example.com
 ```
 
 User agent would read
-```
+
+```text
 test_app/1.0.0 (contact@example.com)
 ```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/huwd/api_adaptor. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/huwd/api_adaptor/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at <https://github.com/huwd/api_adaptor>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/huwd/api_adaptor/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 

data/fixtures/v1/integration/foo.json

@@ -0,0 +1,3 @@
+{
+  "foo": "bar"
+}

data/lib/api_adaptor/base.rb

@@ -1,86 +1,90 @@
+# frozen_string_literal: true
+
 require_relative "json_client"
 require "cgi"
 require_relative "null_logger"
 require_relative "list_response"
 
-class ApiAdaptor::Base
-  class InvalidAPIURL < StandardError
-  end
+module ApiAdaptor
+  class Base
+    class InvalidAPIURL < StandardError
+    end
 
-  extend Forwardable
+    extend Forwardable
 
-  def client
-    @client ||= create_client
-  end
+    def client
+      @client ||= create_client
+    end
 
-  def create_client
-    ApiAdaptor::JsonClient.new(options)
-  end
+    def create_client
+      ApiAdaptor::JsonClient.new(options)
+    end
 
-  def_delegators :client,
-                 :get_json,
-                 :post_json,
-                 :put_json,
-                 :patch_json,
-                 :delete_json,
-                 :get_raw,
-                 :get_raw!,
-                 :put_multipart,
-                 :post_multipart
-
-  attr_reader :options
-
-  class << self
-    attr_writer :logger
-    attr_accessor :default_options
-  end
+    def_delegators :client,
+                   :get_json,
+                   :post_json,
+                   :put_json,
+                   :patch_json,
+                   :delete_json,
+                   :get_raw,
+                   :get_raw!,
+                   :put_multipart,
+                   :post_multipart
+
+    attr_reader :options
+
+    class << self
+      attr_writer :logger
+      attr_accessor :default_options
+    end
 
-  def self.logger
-    @logger ||= ApiAdaptor::NullLogger.new
-  end
+    def self.logger
+      @logger ||= ApiAdaptor::NullLogger.new
+    end
 
-  def initialize(endpoint_url, options = {})
-    options[:endpoint_url] = endpoint_url
-    raise InvalidAPIURL unless endpoint_url =~ URI::RFC3986_Parser::RFC3986_URI
+    def initialize(endpoint_url = nil, options = {})
+      options[:endpoint_url] = endpoint_url
+      raise InvalidAPIURL if !endpoint_url.nil? && endpoint_url !~ URI::RFC3986_Parser::RFC3986_URI
 
-    base_options = { logger: ApiAdaptor::Base.logger }
-    default_options = base_options.merge(ApiAdaptor::Base.default_options || {})
-    @options = default_options.merge(options)
-    self.endpoint = options[:endpoint_url]
-  end
+      base_options = { logger: ApiAdaptor::Base.logger }
+      default_options = base_options.merge(ApiAdaptor::Base.default_options || {})
+      @options = default_options.merge(options)
+      self.endpoint = options[:endpoint_url]
+    end
 
-  def url_for_slug(slug, options = {})
-    "#{base_url}/#{slug}.json#{query_string(options)}"
-  end
+    def url_for_slug(slug, options = {})
+      "#{base_url}/#{slug}.json#{query_string(options)}"
+    end
 
-  def get_list(url)
-    get_json(url) do |r|
-      ApiAdaptor::ListResponse.new(r, self)
+    def get_list(url)
+      get_json(url) do |r|
+        ApiAdaptor::ListResponse.new(r, self)
+      end
     end
-  end
 
-private
+    private
 
-  attr_accessor :endpoint
+    attr_accessor :endpoint
 
-  def query_string(params)
-    return "" if params.empty?
+    def query_string(params)
+      return "" if params.empty?
 
-    param_pairs = params.sort.map { |key, value|
-      case value
-      when Array
-        value.map do |v|
-          "#{CGI.escape("#{key}[]")}=#{CGI.escape(v.to_s)}"
+      param_pairs = params.sort.map do |key, value|
+        case value
+        when Array
+          value.map do |v|
+            "#{CGI.escape("#{key}[]")}=#{CGI.escape(v.to_s)}"
+          end
+        else
+          "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
         end
-      else
-        "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
-      end
-    }.flatten
+      end.flatten
 
-    "?#{param_pairs.join('&')}"
-  end
+      "?#{param_pairs.join("&")}"
+    end
 
-  def uri_encode(param)
-    Addressable::URI.encode(param.to_s)
+    def uri_encode(param)
+      Addressable::URI.encode(param.to_s)
+    end
   end
-end
+end

data/lib/api_adaptor/exceptions.rb

@@ -1,7 +1,13 @@
+# frozen_string_literal: true
+
 module ApiAdaptor
   # Abstract error class
   class BaseError < StandardError; end
 
+  class TooManyRedirects < BaseError; end
+
+  class RedirectLocationMissing < BaseError; end
+
   class EndpointNotFound < BaseError; end
 
   class TimedOutException < BaseError; end
@@ -41,6 +47,8 @@ module ApiAdaptor
 
   class HTTPUnprocessableEntity < HTTPClientError; end
 
+  class HTTPUnprocessableContent < HTTPClientError; end
+
   class HTTPBadRequest < HTTPClientError; end
 
   class HTTPTooManyRequests < HTTPIntermittentClientError; end
@@ -102,4 +110,4 @@ module ApiAdaptor
       end
     end
   end
-end
+end

data/lib/api_adaptor/headers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ApiAdaptor
   class Headers
     class << self
@@ -6,18 +8,18 @@ module ApiAdaptor
       end
 
       def headers
-        header_data.reject { |_k, v| (v.nil? || v.empty?) }
+        header_data.reject { |_k, v| v.nil? || v.empty? }
       end
 
       def clear_headers
         Thread.current[:headers] = {}
       end
 
-    private
+      private
 
       def header_data
         Thread.current[:headers] ||= {}
       end
     end
   end
-end
+end

data/lib/api_adaptor/json_client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "exceptions"
 require_relative "variables"
 require_relative "null_logger"
@@ -13,9 +15,7 @@ module ApiAdaptor
     attr_accessor :logger, :options
 
     def initialize(options = {})
-      if options[:disable_timeout] || options[:timeout].to_i.negative?
-        raise "It is no longer possible to disable the timeout."
-      end
+      raise "It is no longer possible to disable the timeout." if options[:disable_timeout] || options[:timeout].to_i.negative?
 
       @logger = options[:logger] || NullLogger.new
       @options = options
@@ -24,7 +24,7 @@ module ApiAdaptor
     def self.default_request_headers
       {
         "Accept" => "application/json",
-        "User-Agent" => "#{Variables.app_name}/#{Variables.app_version} (#{Variables. app_contact}",
+        "User-Agent" => "#{Variables.app_name}/#{Variables.app_version} (#{Variables.app_contact})"
       }
     end
 
@@ -34,11 +34,12 @@ module ApiAdaptor
 
     def self.json_body_headers
       {
-        "Content-Type" => "application/json",
+        "Content-Type" => "application/json"
       }
     end
 
     DEFAULT_TIMEOUT_IN_SECONDS = 4
+    DEFAULT_MAX_REDIRECTS = 3
 
     def get_raw!(url)
       do_raw_request(:get, url)
@@ -78,7 +79,7 @@ module ApiAdaptor
       Response.new(r)
     end
 
-  private
+    private
 
     def do_raw_request(method, url, params = nil)
       do_request(method, url, params)
@@ -94,9 +95,7 @@ module ApiAdaptor
     #                  from the Net::HTTPResponse
     def do_json_request(method, url, params = nil, additional_headers = {}, &create_response)
       begin
-        if params
-          additional_headers.merge!(self.class.json_body_headers)
-        end
+        additional_headers.merge!(self.class.json_body_headers) if params
         response = do_request(method, url, (params.to_json if params), additional_headers)
       rescue RestClient::Exception => e
         # Attempt to parse the body as JSON if possible
@@ -119,25 +118,24 @@ module ApiAdaptor
       if @options[:bearer_token]
         headers = method_params[:headers] || {}
         method_params.merge(headers: headers.merge(
-          "Authorization" => "Bearer #{@options[:bearer_token]}",
+          "Authorization" => "Bearer #{@options[:bearer_token]}"
         ))
       elsif @options[:basic_auth]
         method_params.merge(
           user: @options[:basic_auth][:user],
-          password: @options[:basic_auth][:password],
+          password: @options[:basic_auth][:password]
         )
       else
         method_params
       end
     end
 
-
     # Take a hash of parameters for Request#execute; return a hash of
     # parameters with timeouts included
     def with_timeout(method_params)
       method_params.merge(
         timeout: options[:timeout] || DEFAULT_TIMEOUT_IN_SECONDS,
-        open_timeout: options[:timeout] || DEFAULT_TIMEOUT_IN_SECONDS,
+        open_timeout: options[:timeout] || DEFAULT_TIMEOUT_IN_SECONDS
       )
     end
 
@@ -146,57 +144,184 @@ module ApiAdaptor
         headers: default_headers
           .merge(method_params[:headers] || {})
           .merge(ApiAdaptor::Headers.headers)
-          .merge(additional_headers),
+          .merge(additional_headers)
       )
     end
 
     def with_ssl_options(method_params)
       method_params.merge(
         # This is the default value anyway, but we should probably be explicit
-        verify_ssl: OpenSSL::SSL::VERIFY_NONE,
+        verify_ssl: OpenSSL::SSL::VERIFY_NONE
       )
     end
 
-    def do_request(method, url, params = nil, additional_headers = {})
-      loggable = { request_uri: url, start_time: Time.now.to_f }
-      start_logging = loggable.merge(action: "start")
-      logger.debug start_logging.to_json
+    def max_redirects
+      value = options.fetch(:max_redirects, DEFAULT_MAX_REDIRECTS)
+      value = value.to_i
+      value.negative? ? 0 : value
+    end
 
-      method_params = {
-        method: method,
-        url: url,
-      }
+    def follow_non_get_redirects?
+      options.fetch(:follow_non_get_redirects, false)
+    end
+
+    def allow_cross_origin_redirects?
+      options.fetch(:allow_cross_origin_redirects, true)
+    end
+
+    def forward_auth_on_cross_origin_redirects?
+      options.fetch(:forward_auth_on_cross_origin_redirects, false)
+    end
+
+    def redirect_status_code?(code)
+      code.to_i >= 300 && code.to_i <= 399
+    end
+
+    def follow_redirect_code?(method, code)
+      code = code.to_i
+      return false unless redirect_status_code?(code)
+      return false if code == 304
+      return false if [305, 306].include?(code)
+
+      if %i[get head].include?(method)
+        [301, 302, 303, 307, 308].include?(code)
+      else
+        return true if follow_non_get_redirects? && [307, 308].include?(code)
 
-      method_params[:payload] = params
-      method_params = with_timeout(method_params)
-      method_params = with_headers(method_params, self.class.default_request_headers, additional_headers)
-      method_params = with_auth_options(method_params)
-      if URI.parse(url).is_a? URI::HTTPS
-        method_params = with_ssl_options(method_params)
+        false
       end
+    end
 
-      ::RestClient::Request.execute(method_params)
-    rescue Errno::ECONNREFUSED => e
-      logger.error loggable.merge(status: "refused", error_message: e.message, error_class: e.class.name, end_time: Time.now.to_f).to_json
-      raise ApiAdaptor::EndpointNotFound, "Could not connect to #{url}"
-    rescue RestClient::Exceptions::Timeout => e
-      logger.error loggable.merge(status: "timeout", error_message: e.message, error_class: e.class.name, end_time: Time.now.to_f).to_json
-      raise ApiAdaptor::TimedOutException, e.message
-    rescue URI::InvalidURIError => e
-      logger.error loggable.merge(status: "invalid_uri", error_message: e.message, error_class: e.class.name, end_time: Time.now.to_f).to_json
-      raise ApiAdaptor::InvalidUrl, e.message
-    rescue RestClient::Exception => e
-      # Log the error here, since we have access to loggable, but raise the
-      # exception up to the calling method to deal with
-      loggable.merge!(status: e.http_code, end_time: Time.now.to_f, body: e.http_body)
-      logger.warn loggable.to_json
-      raise
-    rescue Errno::ECONNRESET => e
-      logger.error loggable.merge(status: "connection_reset", error_message: e.message, error_class: e.class.name, end_time: Time.now.to_f).to_json
-      raise ApiAdaptor::TimedOutException, e.message
-    rescue SocketError => e
-      logger.error loggable.merge(status: "socket_error", error_message: e.message, error_class: e.class.name, end_time: Time.now.to_f).to_json
-      raise ApiAdaptor::SocketErrorException, e.message
+    def response_location(response)
+      return nil unless response
+
+      headers = response.headers || {}
+      headers[:location] || headers["location"] || headers["Location"]
+    end
+
+    def resolve_location(current_url, location)
+      URI.join(current_url, location.to_s).to_s
+    rescue URI::Error
+      location.to_s
+    end
+
+    def origin_for(url)
+      uri = URI.parse(url)
+      [uri.scheme, uri.host, uri.port]
+    end
+
+    def do_request(method, url, params = nil, additional_headers = {})
+      current_method = method
+      current_url = url
+      current_params = params
+      redirects_followed = 0
+
+      initial_origin = begin
+        origin_for(url)
+      rescue URI::InvalidURIError => e
+        raise ApiAdaptor::InvalidUrl, e.message
+      end
+
+      loop do
+        loggable = { request_uri: current_url, start_time: Time.now.to_f }
+        start_logging = loggable.merge(action: "start")
+        logger.debug start_logging.to_json
+
+        method_params = {
+          method: current_method,
+          url: current_url,
+          max_redirects: 0
+        }
+        method_params[:payload] = current_params
+        method_params = with_timeout(method_params)
+        method_params = with_headers(method_params, self.class.default_request_headers, additional_headers)
+
+        begin
+          current_origin = origin_for(current_url)
+          cross_origin = current_origin != initial_origin
+          include_auth = !cross_origin || forward_auth_on_cross_origin_redirects?
+          method_params = with_auth_options(method_params) if include_auth
+          unless include_auth
+            if method_params[:headers]
+              method_params[:headers].delete("Authorization")
+              method_params[:headers].delete("Proxy-Authorization")
+            end
+            method_params.delete(:user)
+            method_params.delete(:password)
+          end
+
+          method_params = with_ssl_options(method_params) if URI.parse(current_url).is_a? URI::HTTPS
+          return ::RestClient::Request.execute(method_params)
+        rescue RestClient::ExceptionWithResponse => e
+          if e.is_a?(RestClient::Exceptions::Timeout)
+            logger.error loggable.merge(status: "timeout", error_message: e.message, error_class: e.class.name,
+                                        end_time: Time.now.to_f).to_json
+            raise ApiAdaptor::TimedOutException, e.message
+          end
+
+          status_code = (e.http_code || e.response&.code).to_i
+
+          raise ApiAdaptor::TimedOutException, e.message if status_code == 408
+
+          if follow_redirect_code?(current_method.to_sym, status_code)
+            location = response_location(e.response)
+            raise ApiAdaptor::RedirectLocationMissing, "Redirect response missing Location header for #{current_url}" if location.to_s.strip.empty?
+
+            next_url = resolve_location(current_url, location)
+            begin
+              next_origin = origin_for(next_url)
+            rescue URI::InvalidURIError => e
+              logger.error loggable.merge(status: "invalid_uri", error_message: e.message, error_class: e.class.name,
+                                          end_time: Time.now.to_f).to_json
+              raise ApiAdaptor::InvalidUrl, e.message
+            end
+            if next_origin != initial_origin && !allow_cross_origin_redirects?
+              loggable.merge!(status: status_code, end_time: Time.now.to_f, body: e.http_body)
+              logger.warn loggable.to_json
+              raise
+            end
+
+            raise ApiAdaptor::TooManyRedirects, "Too many redirects (max #{max_redirects}) while requesting #{url}" if redirects_followed >= max_redirects
+
+            redirects_followed += 1
+            current_url = next_url
+
+            next
+          end
+
+          loggable.merge!(status: status_code, end_time: Time.now.to_f, body: e.http_body)
+          logger.warn loggable.to_json
+          raise
+        rescue Errno::ECONNREFUSED => e
+          logger.error loggable.merge(status: "refused", error_message: e.message, error_class: e.class.name,
+                                      end_time: Time.now.to_f).to_json
+          raise ApiAdaptor::EndpointNotFound, "Could not connect to #{current_url}"
+        rescue Timeout::Error => e
+          logger.error loggable.merge(status: "timeout", error_message: e.message, error_class: e.class.name,
+                                      end_time: Time.now.to_f).to_json
+          raise ApiAdaptor::TimedOutException, e.message
+        rescue RestClient::Exceptions::Timeout => e
+          logger.error loggable.merge(status: "timeout", error_message: e.message, error_class: e.class.name,
+                                      end_time: Time.now.to_f).to_json
+          raise ApiAdaptor::TimedOutException, e.message
+        rescue URI::InvalidURIError => e
+          logger.error loggable.merge(status: "invalid_uri", error_message: e.message, error_class: e.class.name,
+                                      end_time: Time.now.to_f).to_json
+          raise ApiAdaptor::InvalidUrl, e.message
+        rescue RestClient::Exception => e
+          loggable.merge!(status: e.http_code, end_time: Time.now.to_f, body: e.http_body)
+          logger.warn loggable.to_json
+          raise
+        rescue Errno::ECONNRESET => e
+          logger.error loggable.merge(status: "connection_reset", error_message: e.message, error_class: e.class.name,
+                                      end_time: Time.now.to_f).to_json
+          raise ApiAdaptor::TimedOutException, e.message
+        rescue SocketError => e
+          logger.error loggable.merge(status: "socket_error", error_message: e.message, error_class: e.class.name,
+                                      end_time: Time.now.to_f).to_json
+          raise ApiAdaptor::SocketErrorException, e.message
+        end
+      end
     end
   end
 end

data/lib/api_adaptor/list_response.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "json"
 require "api_adaptor/response"
 require "link_header"
@@ -24,7 +26,7 @@ module ApiAdaptor
       to_hash["results"]
     end
 
-    def has_next_page?
+    def next_page?
       !page_link("next").nil?
     end
 
@@ -33,20 +35,16 @@ module ApiAdaptor
       # avoid us making multiple requests for the same page, but we shouldn't
       # allow the data to change once it's already been loaded, so long as we
       # retain a reference to any one page in the sequence
-      @next_page ||= if has_next_page?
-                       @api_client.get_list page_link("next").href
-                     end
+      @next_page ||= (@api_client.get_list page_link("next").href if next_page?)
     end
 
-    def has_previous_page?
+    def previous_page?
       !page_link("previous").nil?
     end
 
     def previous_page
       # See the note in `next_page` for why this is memoised
-      @previous_page ||= if has_previous_page?
-                           @api_client.get_list(page_link("previous").href)
-                         end
+      @previous_page ||= (@api_client.get_list(page_link("previous").href) if previous_page?)
     end
 
     # Transparently get all results across all pages. Compare this with #each
@@ -70,13 +68,11 @@ module ApiAdaptor
     def with_subsequent_pages
       Enumerator.new do |yielder|
         each { |i| yielder << i }
-        if has_next_page?
-          next_page.with_subsequent_pages.each { |i| yielder << i }
-        end
+        next_page.with_subsequent_pages.each { |i| yielder << i } if next_page?
       end
     end
 
-  private
+    private
 
     def link_header
       @link_header ||= LinkHeader.parse @http_response.headers[:link]

data/lib/api_adaptor/response.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "json"
 require "forwardable"
 
@@ -8,13 +10,12 @@ module ApiAdaptor
   # API endpoints should return absolute URLs so that they make sense outside of the
   # domain context. However on systems within an API we want to present relative URLs.
   # By specifying a base URI, this will convert all matching web_urls into relative URLs
-  # This is useful on non-canonical frontends, such as those in staging environments.
   #
   # Example:
   #
-  #   r = Response.new(response, web_urls_relative_to: "https://www.gov.uk")
+  #   r = Response.new(response, web_urls_relative_to: "https://www.example.com")
   #   r['results'][0]['web_url']
-  #   => "/bank-holidays"
+  #   => "/foo"
   class Response
     extend Forwardable
     include Enumerable
@@ -58,12 +59,12 @@ module ApiAdaptor
       def reverse_max_age
         self["r-maxage"].to_i if key?("r-maxage")
       end
-      alias_method :r_maxage, :reverse_max_age
+      alias r_maxage reverse_max_age
 
       def shared_max_age
         self["s-maxage"].to_i if key?("r-maxage")
       end
-      alias_method :s_maxage, :shared_max_age
+      alias s_maxage shared_max_age
 
       def to_s
         directives = []
@@ -152,7 +153,7 @@ module ApiAdaptor
       false
     end
 
-  private
+    private
 
     def transform_parsed(value)
       return value if @web_urls_relative_to.nil?
@@ -180,4 +181,4 @@ module ApiAdaptor
       end
     end
   end
-end
+end

data/lib/api_adaptor/variables.rb

@@ -1,15 +1,17 @@
-  module ApiAdaptor
-    module Variables
-      def self.app_name
-        ENV['APP_NAME'] || "Ruby ApiAdaptor App"
-      end
+# frozen_string_literal: true
 
-      def self.app_version
-        ENV['APP_VERSION'] || "Version not stated"
-      end
+module ApiAdaptor
+  module Variables
+    def self.app_name
+      ENV["APP_NAME"] || "Ruby ApiAdaptor App"
+    end
+
+    def self.app_version
+      ENV["APP_VERSION"] || "Version not stated"
+    end
 
-      def self.app_contact
-        ENV['APP_CONTACT'] || "Contact not stated"
-      end
+    def self.app_contact
+      ENV["APP_CONTACT"] || "Contact not stated"
     end
-  end
+  end
+end

data/lib/api_adaptor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ApiAdaptor
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

metadata

@@ -1,43 +1,62 @@
 --- !ruby/object:Gem::Specification
 name: api_adaptor
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Huw Diprose
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-06-02 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rest-client
+  name: addressable
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.8'
 - !ruby/object:Gem::Dependency
-  name: addressable
+  name: base64
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.8'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.8'
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: link_header
   requirement: !ruby/object:Gem::Requirement
@@ -53,33 +72,39 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 0.0.8
 - !ruby/object:Gem::Dependency
-  name: webmock
+  name: logger
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.18'
-  type: :development
+        version: '1.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.18'
+        version: '1.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: timecop
+  name: rest-client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
-  type: :development
+        version: '2.1'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -122,6 +147,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
 description: A basic adaptor to send HTTP requests and parse the responses. Intended
   to bootstrap the quick writing of Adaptors for specific APIs, without having to
   write the same old JSON request and processing time and time again.
@@ -141,6 +208,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- fixtures/v1/integration/foo.json
 - lib/api_adaptor.rb
 - lib/api_adaptor/base.rb
 - lib/api_adaptor/exceptions.rb
@@ -160,7 +228,6 @@ metadata:
   homepage_uri: https://github.com/huwd/api_adaptor
   source_code_uri: https://github.com/huwd/api_adaptor
   changelog_uri: https://github.com/huwd/api_adaptor/blob/main/CHANGELOG.md
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -168,15 +235,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.13
-signing_key: 
+rubygems_version: 4.0.3
 specification_version: 4
 summary: A basic adaptor to send HTTP requests and parse the responses.
 test_files: []