api_adaptor 0.0.2 → 1.0.0

data/lib/api_adaptor/json_client.rb

@@ -9,11 +9,68 @@ require_relative "response"
 require "rest-client"
 
 module ApiAdaptor
+  # HTTP client for JSON APIs with comprehensive redirect handling and authentication support.
+  #
+  # JSONClient provides a low-level interface for making HTTP requests to JSON APIs. It handles
+  # automatic JSON parsing, configurable redirect following, authentication (bearer token and basic auth),
+  # timeout management, and comprehensive error handling.
+  #
+  # @example Basic usage with bearer token
+  #   client = JSONClient.new(bearer_token: "abc123")
+  #   response = client.get_json("https://api.example.com/users")
+  #   users = response["data"]
+  #
+  # @example Custom timeout and redirect configuration
+  #   client = JSONClient.new(
+  #     timeout: 10,
+  #     max_redirects: 5,
+  #     follow_non_get_redirects: true
+  #   )
+  #
+  # @example With basic authentication
+  #   client = JSONClient.new(
+  #     basic_auth: { user: "username", password: "password" }
+  #   )
+  #
+  # @example Disable cross-origin redirects for security
+  #   client = JSONClient.new(
+  #     allow_cross_origin_redirects: false
+  #   )
+  #
+  # @see Base for a higher-level API client framework
   class JsonClient
     include ApiAdaptor::ExceptionHandling
 
+    # @return [Logger] Logger instance for request/response logging
+    # @return [Hash] Client configuration options
     attr_accessor :logger, :options
 
+    # Initializes a new JSON HTTP client
+    #
+    # @param options [Hash] Configuration options
+    # @option options [String] :bearer_token Bearer token for Authorization header
+    # @option options [Hash] :basic_auth Basic authentication credentials with :user and :password keys
+    # @option options [Integer] :timeout Request timeout in seconds (default: 4)
+    # @option options [Integer] :max_redirects Maximum number of redirects to follow (default: 3)
+    # @option options [Boolean] :allow_cross_origin_redirects Allow redirects to different origins (default: true)
+    # @option options [Boolean] :forward_auth_on_cross_origin_redirects Forward auth headers on cross-origin redirects (default: false, security risk if enabled)
+    # @option options [Boolean] :follow_non_get_redirects Follow redirects for POST/PUT/PATCH/DELETE (default: false, only 307/308 supported)
+    # @option options [Logger] :logger Custom logger instance (default: NullLogger)
+    #
+    # @raise [RuntimeError] If disable_timeout or negative timeout is provided
+    #
+    # @example Default configuration
+    #   client = JSONClient.new
+    #   # timeout: 4s, max_redirects: 3, only GET/HEAD follow redirects
+    #
+    # @example Full configuration
+    #   client = JSONClient.new(
+    #     bearer_token: "secret",
+    #     timeout: 10,
+    #     max_redirects: 5,
+    #     allow_cross_origin_redirects: false,
+    #     logger: Logger.new($stdout)
+    #   )
     def initialize(options = {})
       raise "It is no longer possible to disable the timeout." if options[:disable_timeout] || options[:timeout].to_i.negative?
 
@@ -21,6 +78,9 @@ module ApiAdaptor
       @options = options
     end
 
+    # Returns default HTTP headers for all requests
+    #
+    # @return [Hash] Default headers including Accept and User-Agent
     def self.default_request_headers
       {
         "Accept" => "application/json",
@@ -28,51 +88,161 @@ module ApiAdaptor
       }
     end
 
+    # Returns default headers for requests with JSON body
+    #
+    # @return [Hash] Default headers plus Content-Type: application/json
     def self.default_request_with_json_body_headers
       default_request_headers.merge(json_body_headers)
     end
 
+    # Returns Content-Type header for JSON requests
+    #
+    # @return [Hash] Content-Type header
     def self.json_body_headers
       {
         "Content-Type" => "application/json"
       }
     end
 
+    # Default request timeout in seconds
     DEFAULT_TIMEOUT_IN_SECONDS = 4
 
+    # Default maximum number of redirects to follow
+    DEFAULT_MAX_REDIRECTS = 3
+
+    # Performs a GET request and returns the raw response
+    #
+    # @param url [String] The URL to request
+    #
+    # @return [RestClient::Response] Raw HTTP response
+    #
+    # @raise [HTTPClientError, HTTPServerError] On HTTP errors
+    # @raise [TimedOutException] On timeout
+    # @raise [EndpointNotFound] On connection refused
+    # @raise [InvalidUrl] On invalid URI
+    # @raise [TooManyRedirects] When max_redirects is exceeded
+    # @raise [RedirectLocationMissing] When redirect lacks Location header
     def get_raw!(url)
       do_raw_request(:get, url)
     end
 
+    # Performs a GET request and returns the raw response (alias for get_raw!)
+    #
+    # @param url [String] The URL to request
+    #
+    # @return [RestClient::Response] Raw HTTP response
+    #
+    # @see #get_raw!
     def get_raw(url)
       get_raw!(url)
     end
 
+    # Performs a GET request and parses the JSON response
+    #
+    # @param url [String] The URL to request
+    # @param additional_headers [Hash] Additional HTTP headers to include
+    # @yield [response] Optional block to create custom response object
+    # @yieldparam response [RestClient::Response] The raw HTTP response
+    # @yieldreturn [Object] Custom response object
+    #
+    # @return [Response, Object] Response object or custom object from block
+    #
+    # @raise [HTTPClientError, HTTPServerError] On HTTP errors
+    # @raise [TimedOutException] On timeout
+    #
+    # @example Basic usage
+    #   response = client.get_json("https://api.example.com/users")
+    #   users = response["data"]
+    #
+    # @example With custom response class
+    #   users = client.get_json("https://api.example.com/users") do |r|
+    #     UserListResponse.new(r)
+    #   end
     def get_json(url, additional_headers = {}, &create_response)
       do_json_request(:get, url, nil, additional_headers, &create_response)
     end
 
+    # Performs a POST request with JSON body
+    #
+    # @param url [String] The URL to request
+    # @param params [Hash] Data to send as JSON in request body (default: {})
+    # @param additional_headers [Hash] Additional HTTP headers to include
+    #
+    # @return [Response] Response object with parsed JSON
+    #
+    # @raise [HTTPClientError, HTTPServerError] On HTTP errors
+    #
+    # @example
+    #   response = client.post_json("https://api.example.com/users", {
+    #     name: "Alice",
+    #     email: "alice@example.com"
+    #   })
     def post_json(url, params = {}, additional_headers = {})
       do_json_request(:post, url, params, additional_headers)
     end
 
+    # Performs a PUT request with JSON body
+    #
+    # @param url [String] The URL to request
+    # @param params [Hash] Data to send as JSON in request body
+    # @param additional_headers [Hash] Additional HTTP headers to include
+    #
+    # @return [Response] Response object with parsed JSON
+    #
+    # @raise [HTTPClientError, HTTPServerError] On HTTP errors
     def put_json(url, params, additional_headers = {})
       do_json_request(:put, url, params, additional_headers)
     end
 
+    # Performs a PATCH request with JSON body
+    #
+    # @param url [String] The URL to request
+    # @param params [Hash] Data to send as JSON in request body
+    # @param additional_headers [Hash] Additional HTTP headers to include
+    #
+    # @return [Response] Response object with parsed JSON
+    #
+    # @raise [HTTPClientError, HTTPServerError] On HTTP errors
     def patch_json(url, params, additional_headers = {})
       do_json_request(:patch, url, params, additional_headers)
     end
 
+    # Performs a DELETE request with optional JSON body
+    #
+    # @param url [String] The URL to request
+    # @param params [Hash] Optional data to send as JSON in request body (default: {})
+    # @param additional_headers [Hash] Additional HTTP headers to include
+    #
+    # @return [Response] Response object with parsed JSON
+    #
+    # @raise [HTTPClientError, HTTPServerError] On HTTP errors
     def delete_json(url, params = {}, additional_headers = {})
       do_json_request(:delete, url, params, additional_headers)
     end
 
+    # Performs a POST request with multipart/form-data
+    #
+    # @param url [String] The URL to request
+    # @param params [Hash] Multipart form data (may include file uploads)
+    #
+    # @return [Response] Response object
+    #
+    # @example Uploading a file
+    #   client.post_multipart("https://api.example.com/upload", {
+    #     file: File.open("image.jpg", "rb"),
+    #     description: "Profile photo"
+    #   })
     def post_multipart(url, params)
       r = do_raw_request(:post, url, params.merge(multipart: true))
       Response.new(r)
     end
 
+    # Performs a PUT request with multipart/form-data
+    #
+    # @param url [String] The URL to request
+    # @param params [Hash] Multipart form data (may include file uploads)
+    #
+    # @return [Response] Response object
     def put_multipart(url, params)
       r = do_raw_request(:put, url, params.merge(multipart: true))
       Response.new(r)
@@ -141,9 +311,9 @@ module ApiAdaptor
     def with_headers(method_params, default_headers, additional_headers)
       method_params.merge(
         headers: default_headers
-          .merge(method_params[:headers] || {})
-          .merge(ApiAdaptor::Headers.headers)
-          .merge(additional_headers)
+                 .merge(method_params[:headers] || {})
+                 .merge(ApiAdaptor::Headers.headers)
+                 .merge(additional_headers)
       )
     end
 
@@ -154,49 +324,173 @@ module ApiAdaptor
       )
     end
 
+    def max_redirects
+      value = options.fetch(:max_redirects, DEFAULT_MAX_REDIRECTS)
+      value = value.to_i
+      value.negative? ? 0 : value
+    end
+
+    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)
+
+        false
+      end
+    end
+
+    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 = {})
-      loggable = { request_uri: url, start_time: Time.now.to_f }
-      start_logging = loggable.merge(action: "start")
-      logger.debug start_logging.to_json
+      current_method = method
+      current_url = url
+      current_params = params
+      redirects_followed = 0
 
-      method_params = {
-        method: method,
-        url: url
-      }
+      initial_origin = begin
+        origin_for(url)
+      rescue URI::InvalidURIError => e
+        raise ApiAdaptor::InvalidUrl, e.message
+      end
 
-      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)
-      method_params = with_ssl_options(method_params) if URI.parse(url).is_a? URI::HTTPS
-
-      ::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
+      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

@@ -5,31 +5,66 @@ require "api_adaptor/response"
 require "link_header"
 
 module ApiAdaptor
-  # Response class for lists of multiple items.
+  # Response wrapper for paginated API results.
   #
-  # This expects responses to be in a common format, with the list of results
-  # contained under the `results` key. The response may also have previous and
-  # subsequent pages, indicated by entries in the response's `Link` header.
+  # ListResponse handles paginated responses using Link headers (RFC 5988) for navigation.
+  # It expects responses to have a "results" array and provides methods to navigate through pages.
+  #
+  # @example Basic usage
+  #   response = client.get_list("/posts?page=1")
+  #   response.results       # => Array of items on current page
+  #   response.next_page?    # => true
+  #   response.next_page     # => ListResponse for page 2
+  #
+  # @example Iterating over current page
+  #   response.each do |item|
+  #     puts item["title"]
+  #   end
+  #
+  # @example Fetching all pages
+  #   response.with_subsequent_pages.each do |item|
+  #     puts item["title"]  # Automatically fetches additional pages
+  #   end
   class ListResponse < Response
-    # The ListResponse is instantiated with a reference back to the API client,
-    # so it can make requests for the subsequent pages
+    # Initializes a new ListResponse with API client reference for pagination
+    #
+    # @param response [RestClient::Response] The raw HTTP response
+    # @param api_client [Base] API client instance for fetching additional pages
+    # @param options [Hash] Configuration options (see Response#initialize)
     def initialize(response, api_client, options = {})
       super(response, options)
       @api_client = api_client
     end
 
-    # Pass calls to `self.each` to the `results` sub-object, so we can iterate
-    # over the response directly
+    # @!method each(&block)
+    #   Iterate over results on the current page only
+    #   @yield [Hash] Each result item
+    #   @see #with_subsequent_pages for iterating across all pages
+    #
+    # @!method to_ary
+    #   Convert results to array
+    #   @return [Array] Array of result items on current page
     def_delegators :results, :each, :to_ary
 
+    # Returns the array of results from the current page
+    #
+    # @return [Array<Hash>] Array of result items
     def results
       to_hash["results"]
     end
 
+    # Checks if there is a next page available
+    #
+    # @return [Boolean] true if next page exists
     def next_page?
       !page_link("next").nil?
     end
 
+    # Fetches the next page of results
+    #
+    # Results are memoized to avoid refetching the same page multiple times.
+    #
+    # @return [ListResponse, nil] Next page response or nil if no next page
     def next_page
       # This shouldn't be a performance problem, since the cache will generally
       # avoid us making multiple requests for the same page, but we shouldn't
@@ -38,33 +73,40 @@ module ApiAdaptor
       @next_page ||= (@api_client.get_list page_link("next").href if next_page?)
     end
 
+    # Checks if there is a previous page available
+    #
+    # @return [Boolean] true if previous page exists
     def previous_page?
       !page_link("previous").nil?
     end
 
+    # Fetches the previous page of results
+    #
+    # Results are memoized to avoid refetching the same page multiple times.
+    #
+    # @return [ListResponse, nil] Previous page response or nil if no previous page
     def previous_page
       # See the note in `next_page` for why this is memoised
       @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
-    # or #results which only iterate over the current page.
+    # Returns an enumerator that transparently fetches and iterates over all pages
     #
-    # Example:
+    # Pages are fetched on demand as you iterate. If you call a method like #count,
+    # all pages will be fetched immediately. Results are memoized to avoid duplicate requests.
     #
-    #   list_response.with_subsequent_pages.each do |result|
-    #     ...
-    #   end
+    # @return [Enumerator] Enumerator for all results across all pages
     #
-    # or:
+    # @example Iterate over all pages
+    #   response.with_subsequent_pages.each do |item|
+    #     puts item["title"]
+    #   end
     #
-    #   list_response.with_subsequent_pages.count
+    # @example Count all items across all pages
+    #   total_count = response.with_subsequent_pages.count
     #
-    # Pages of results are fetched on demand. When iterating, that means
-    # fetching pages as results from the current page are exhausted. If you
-    # invoke a method such as #count, this method will fetch all pages at that
-    # point. Note that the responses are stored so subsequent pages will not be
-    # loaded multiple times.
+    # @example Convert all pages to array
+    #   all_items = response.with_subsequent_pages.to_a
     def with_subsequent_pages
       Enumerator.new do |yielder|
         each { |i| yielder << i }