halchemy 1.0.2

data/lib/halchemy/requester.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "uri_template"
+
+LIST_STYLE_HANDLERS = {
+  "repeat_key" => ->(key, array) { array.map { |item| [key, URI.encode_www_form_component(item.to_s)] } },
+  "bracket" => ->(key, array) { array.map { |item| ["#{key}[]", URI.encode_www_form_component(item.to_s)] } },
+  "index" => lambda { |key, array|
+    array.each_with_index.map do |item, index|
+      ["#{key}[#{index}]", URI.encode_www_form_component(item.to_s)]
+    end
+  },
+  "comma" => ->(key, array) { [[key, array.map { |item| URI.encode_www_form_component(item.to_s) }.join(",")]] },
+  "pipe" => ->(key, array) { [[key, array.map { |item| URI.encode_www_form_component(item.to_s) }.join("|")]] }
+}.freeze
+
+module Halchemy
+  # The results of a Follower#to is a Requester.  In the case of a GET for the root resource, the Requester is Read Only
+  # Otherwise it is a full Requester.  Both requester types share much in common.  This is defined in BaseRequester
+  class BaseRequester
+    # @param [Halchemy::Api] api
+    # @param [String | Tuple[HalResource, String]] target
+    # @return [void]
+    def initialize(api, target)
+      @api = api
+      @_data = nil
+      @_headers = CICPHash.new
+      @_template_values = {}
+      @_parameters = {}
+
+      process_target(target)
+    end
+
+    def url
+      rtn = @_url
+
+      if @_is_templated
+        tpl = URITemplate.new(rtn)
+        rtn = tpl.expand(@_template_values)
+      end
+
+      rtn = add_parameters_to_url rtn unless @_parameters.empty?
+      rtn
+    end
+
+    # @param [Hash] headers
+    def with_headers(headers)
+      @_headers.merge! headers
+      self
+    end
+
+    # @param [Hash] values
+    def with_template_values(values)
+      @_template_values.merge! values
+      self
+    end
+
+    # @param [Hash] parameters
+    def with_parameters(parameters)
+      @_parameters.merge! parameters
+      self
+    end
+
+    def request(method)
+      data = @_data.is_a?(Hash) ? @_data.to_json : @_data
+      @api.request(method, url, @_headers, data)
+    end
+
+    private
+
+    # @param [String | Tuple[HalResource, String]] target
+    # @return [void]
+    def process_target(target)
+      if target.is_a?(String)
+        @_url = target
+      else
+        resource, rel = target
+        @_url = resource["_links"][rel]["href"]
+        @_is_templated = resource["_links"][rel].fetch("templated", false)
+        @resource = resource
+      end
+    end
+
+    # Handle list-style parameters based on the list style configuration
+    def handle_list(key, array)
+      handler = LIST_STYLE_HANDLERS[@api.parameters_list_style]
+      raise ArgumentError, "Unsupported parameters list style: #{@api.parameters_list_style}" unless handler
+
+      handler.call(key, array)
+    end
+
+    # Recursively flatten parameters into a list of key-value pairs
+    def flatten_parameters(prefix, parameters)
+      flattened = []
+
+      parameters.each do |key, value|
+        full_key = prefix.nil? || prefix.empty? ? key.to_s : "#{prefix}.#{key}"
+
+        case value
+        when nil
+          flattened << [full_key, nil]
+        when Array
+          flattened.concat(handle_list(full_key, value))
+        when Hash
+          flattened.concat(flatten_parameters(full_key, value))
+        when TrueClass, FalseClass
+          flattened << [full_key, value.to_s]
+        else
+          flattened << [full_key, URI.encode_www_form_component(value.to_s)]
+        end
+      end
+
+      flattened
+    end
+
+    # Add the flattened parameters to the URL as a query string
+    def add_parameters_to_url(url)
+      query_params = flatten_parameters(nil, @_parameters)
+      query_string = query_params.map { |key, value| value.nil? ? key : "#{key}=#{value}" }.join("&")
+
+      if url.include?("?")
+        "#{url}&#{query_string}"
+      else
+        "#{url}?#{query_string}"
+      end
+    end
+  end
+
+  # The result of GET on the root URL is a ReadOnlyRequester, i.e. only
+  # GET, HEAD, and OPTIONS are permitted
+  class ReadOnlyRequester < BaseRequester
+    def get
+      request :get
+    end
+
+    def head
+      request :head
+    end
+
+    def options
+      request :options
+    end
+  end
+
+  # This provides a full-suite of HTTP methods, with handling of payload conversion and
+  # optimistic concurrency.
+  class Requester < ReadOnlyRequester
+    def post(data = nil, content_type = nil)
+      prepare_payload(content_type, data)
+      request :post
+    end
+
+    def put(data = nil, content_type = nil)
+      prepare_payload(content_type, data)
+      prepare_modify_header
+      request :put
+    end
+
+    def patch(data = nil, content_type = nil)
+      prepare_payload(content_type, data)
+      prepare_modify_header
+      request :patch
+    end
+
+    def delete
+      prepare_modify_header
+      request :delete
+    end
+
+    private
+
+    def prepare_payload(content_type, data)
+      @_data = data
+      @_headers["Content-Type"] = content_type unless content_type.nil?
+    end
+
+    def prepare_modify_header
+      @_headers.merge!(@api.optimistic_concurrency_header(@resource)) if @resource.is_a?(HalResource)
+    end
+  end
+end

data/lib/halchemy/resource.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Halchemy
+  # The Resource class extends a Hash to include a metadata object containing details
+  # about the HTTP request and response.  This lets the metadata stay "out of the way" allowing
+  # the client code to use the result of a request directly as a resource without losing access
+  # to the request details, response details, and any error details.
+  class Resource < Hash
+    attr_accessor :_halchemy
+
+    def to_s
+      if !keys.empty?
+        to_json
+      else
+        _halchemy&.response&.body.to_s
+      end
+    end
+  end
+
+  # The HalResource, like Resource, is also a Hash that adds functionality to work with the
+  # link relations in a HAL Resource.
+  class HalResource < Resource
+    # @param [Hash] hash
+    # @return [boolean]
+    def self.hal?(hash)
+      return false unless hash.is_a?(Hash)
+
+      links = hash["_links"]
+      embedded = hash["_embedded"]
+
+      return false unless links.is_a?(Hash)
+      return false unless links["self"].is_a?(Hash)
+      return false unless links["self"]["href"].is_a?(String)
+      return false if embedded && !embedded.is_a?(Hash)
+
+      true
+    end
+
+    def rel?(rel_name)
+      self["_links"].key?(rel_name)
+    end
+
+    def links
+      self["_links"].keys ||= []
+    end
+
+    def raise_for_syntax_error(field)
+      unless keys.include?(field)
+        raise KeyError, "Field '#{field}' does not exist, so cannot be iterated as a collection"
+      end
+      raise TypeError, "Field '#{field}' is not a collection" unless self[field].is_a?(Array)
+    end
+
+    def collection(field)
+      raise_for_syntax_error(field)
+
+      Enumerator.new do |y|
+        self[field].each do |item|
+          unless Halchemy::HalResource.hal?(item)
+            raise TypeError, "The '#{field}' collection contains non-HAL formatted objects"
+          end
+
+          y.yield Halchemy::HalResource.new.merge!(item)
+        end
+      end
+    end
+  end
+end

data/lib/halchemy/status_codes.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+private
+
+PATTERNS = [
+  [/^(\d+)-(\d+)$/, ->(m) { { type: :range, start: m[1].to_i, end: m[2].to_i } }],
+  [/^>=(\d+)$/, ->(m) { { type: :gte, value: m[1].to_i } }],
+  [/^<=(\d+)$/, ->(m) { { type: :lte, value: m[1].to_i } }],
+  [/^>(\d+)$/, ->(m) { { type: :gt, value: m[1].to_i } }],
+  [/^<(\d+)$/, ->(m) { { type: :lt, value: m[1].to_i } }],
+  [/^(\d+)$/, ->(m) { { type: :eq, value: m[1].to_i } }]
+].freeze
+
+MATCHERS = {
+  range: ->(condition, status_code) { (condition[:start]..condition[:end]).include?(status_code) },
+  gt: ->(condition, status_code) { status_code > condition[:value] },
+  lt: ->(condition, status_code) { status_code < condition[:value] },
+  gte: ->(condition, status_code) { status_code >= condition[:value] },
+  lte: ->(condition, status_code) { status_code <= condition[:value] },
+  eq: ->(condition, status_code) { status_code == condition[:value] }
+}.freeze
+
+def settings_include_status_code?(settings, status_code)
+  return false if settings.nil? || settings.strip.empty?
+
+  parse_status_code_settings(settings).any? do |condition|
+    match_condition?(condition, status_code)
+  end
+end
+
+# @return [Array[String]]
+# @param [String] settings
+def parse_status_code_settings(settings)
+  settings.split(/,|\s+/).each_with_object([]) do |part, conditions|
+    part.strip!
+    conditions << parse_condition(part)
+  end.compact
+end
+
+# Parses an individual condition string into a hash.
+# @param [String] part The individual condition string.
+# @return [Hash, nil] The parsed condition hash or nil for blank parts.
+def parse_condition(part)
+  return nil if part.match?(/^\s*$/)
+
+  PATTERNS.each do |pattern, handler|
+    if (match = part.match(pattern))
+      return handler.call(match)
+    end
+  end
+
+  raise SyntaxError, "Invalid status code settings string: '#{part}'"
+end
+
+# @param [Array[Hash]] condition
+# @param [Integer] status_code
+# @return [bool]
+def match_condition?(condition, status_code)
+  MATCHERS.fetch(condition[:type], ->(_, _) { false }).call(condition, status_code)
+end

data/lib/halchemy/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Halchemy
+  VERSION = "1.0.2"
+end

data/lib/halchemy.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "halchemy/version"
+require_relative "halchemy/api"
+
+module Halchemy
+  class HttpError < StandardError; end
+end

data/sig/__tests__/base_url.rbs

@@ -0,0 +1 @@
+BASE_URL: String

data/sig/__tests__/halchemy.rbs

@@ -0,0 +1,4 @@
+module Halchemy
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/sig/__tests__/headers.rbs

@@ -0,0 +1 @@
+HEADERS: hash[String, String]

data/sig/__tests__/remove_headers.rbs

@@ -0,0 +1 @@
+REMOVE_HEADERS: array[String]

data/sig/halchemy/api.rbs

@@ -0,0 +1,54 @@
+module Halchemy
+  class Api
+    @error_handling: ErrorHandling
+
+    @etag_field: String
+    @parameters_list_style: String
+
+    def self.build_response: -> HttpModel::Response
+
+    attr_accessor base_url: String
+    attr_accessor error_handling: ErrorHandling
+    attr_accessor headers: hash[String, String]
+
+    attr_accessor parameters_list_style: String
+
+    def add_headers: -> void
+
+    def follow: -> Follower
+
+    def optimistic_concurrency_header: -> Hash[String, String]
+
+    def remove_headers: -> void
+
+    def request: -> (Resource | HalResource)
+
+    def root: -> BaseRequester
+
+    def using_endpoint: -> BaseRequester
+
+    private
+
+    def self.build_resource: -> (Resource | HalResource)
+
+    def build_resource: -> (Resource | HalResource)
+
+    def build_response: -> HttpModel::Response
+
+    def build_url: -> String
+
+    def configure: -> void
+
+    def do_settings_include_status_code: -> bool
+
+    def extract_body: -> (String | Hash[String, Object] | nil)
+
+    def match_condition?: -> bool
+
+    def parse_body: -> (Hash[String, Object] | nil)
+
+    def parse_status_code_setting: -> Array[String]
+
+    def raise_for_errors: -> void
+  end
+end

data/sig/halchemy/base_requester.rbs

@@ -0,0 +1,35 @@
+module Halchemy
+  class BaseRequester
+    @_data: Object | nil
+    @_headers: CICPHash
+    @_is_templated: bool
+    @_parameters: Hash[String, Object]
+    @_template_values: Hash[String, Object]
+    @_url: String
+    @api: Api
+    @resource: Resource | HalResource
+
+    def initialize: -> void
+
+    def request: -> (Resource | HalResource)
+
+    def url: -> String
+
+    def with_headers: -> (BaseRequester | ReadOnlyRequester | Requester)
+
+    def with_parameters: -> (BaseRequester | ReadOnlyRequester | Requester)
+
+    def with_template_values: -> (BaseRequester | ReadOnlyRequester | Requester)
+
+    private
+
+    def add_parameters_to_url: -> String
+
+    def flatten_parameters: -> Array[String]
+
+    def handle_list: -> Array[Object]
+
+    def process_target: -> void
+
+  end
+end

data/sig/halchemy/error_handling.rbs

@@ -0,0 +1,6 @@
+module Halchemy
+  class ErrorHandling
+    attr_accessor raise_for_network_errors: bool
+    attr_accessor raise_for_status_codes: String | nil
+  end
+end

data/sig/halchemy/follower.rbs

@@ -0,0 +1,9 @@
+module Halchemy
+  class Follower
+    @api: Api
+
+    @resource: Resource
+
+    def to: -> Requester
+  end
+end

data/sig/halchemy/hal_resource.rbs

@@ -0,0 +1,13 @@
+module Halchemy
+  class HalResource
+    def self.hal?: -> bool
+
+    def collection: -> Enumerator[HalResource]
+
+    def links: -> Array[String]
+
+    def raise_for_syntax_error: -> void
+
+    def rel?: -> bool
+  end
+end

data/sig/halchemy/http_model/request.rbs

@@ -0,0 +1,14 @@
+module Halchemy
+  module HttpModel
+    class Request
+      @headers: CICPHash
+      @method: String
+      @url: String
+
+      attr_accessor body: Object | nil
+      attr_accessor headers: CICPHash
+      attr_accessor method: Symbol
+      attr_accessor url: String
+    end
+  end
+end

data/sig/halchemy/http_model/response.rbs

@@ -0,0 +1,15 @@
+module Halchemy
+  module HttpModel
+    class Response
+      @headers: CICPHash
+      @reason: String
+      @status_code: int
+
+      attr_accessor body: Object | nil
+      attr_accessor error: Object | nil
+      attr_accessor headers: CICPHash
+      attr_accessor reason: String
+      attr_accessor status_code: Integer
+    end
+  end
+end

data/sig/halchemy/metadata.rbs

@@ -0,0 +1,9 @@
+module Halchemy
+  class Metadata
+    attr_reader error: Object
+    attr_reader request: HttpModel::Request
+    attr_reader response: HttpModel::Response
+
+    def raise_for_status_codes: -> void
+  end
+end

data/sig/halchemy/read_only_requester.rbs

@@ -0,0 +1,9 @@
+module Halchemy
+  class ReadOnlyRequester < BaseRequester
+    def get: -> (Resource | HalResource)
+
+    def head: -> (Resource | HalResource)
+
+    def options: -> (Resource | HalResource)
+  end
+end

data/sig/halchemy/requester.rbs

@@ -0,0 +1,18 @@
+module Halchemy
+  class Requester < ReadOnlyRequester
+
+    def delete: -> (Resource | HalResource)
+
+    def patch: -> (Resource | HalResource)
+
+    def post: -> (Resource | HalResource)
+
+    def put: -> (Resource | HalResource)
+
+    private
+
+    def prepare_modify_header: -> void
+
+    def prepare_payload: -> void
+  end
+end

data/sig/halchemy/resource.rbs

@@ -0,0 +1,5 @@
+module Halchemy
+  class Resource
+    attr_accessor _halchemy: Metadata | nil
+  end
+end

data/sig/list_style_handlers.rbs

@@ -0,0 +1 @@
+LIST_STYLE_HANDLERS: Hash[String, Object]

data/sig/matchers.rbs

@@ -0,0 +1 @@
+MATCHERS: Hash[Symbol, Object]

data/sig/patterns.rbs

@@ -0,0 +1 @@
+PATTERNS: Array[Tuple[Regexp, Object]]

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: halchemy
+version: !ruby/object:Gem::Version
+  version: 1.0.2
+platform: ruby
+authors:
+- Michael Ottoson
+bindir: exe
+cert_chain: []
+date: 2025-01-26 00:00:00.000000000 Z
+dependencies: []
+description: Do you have an API that serves data following the HAL specification?  The
+  **halchemy** library makes it easy for your client to make the most of that API.
+email:
+- michael@pointw.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".idea/.gitignore"
+- ".idea/halchemy.iml"
+- ".idea/icon.png"
+- ".idea/inspectionProfiles/Project_Default.xml"
+- ".idea/modules.xml"
+- ".idea/vcs.xml"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- __tests__/common.rb
+- __tests__/configurable/base_url.rb
+- __tests__/configurable/error_handling.rb
+- __tests__/configurable/headers.rb
+- __tests__/make_http_requests/follow_link_relations.rb
+- __tests__/make_http_requests/http_response_details.rb
+- __tests__/make_http_requests/optimistic_concurrency.rb
+- __tests__/make_http_requests/with_headers.rb
+- __tests__/make_http_requests/with_parameters.rb
+- __tests__/make_http_requests/with_templates.rb
+- __tests__/use_resources/iterate_collections.rb
+- bdd
+- lib/halchemy.rb
+- lib/halchemy/api.rb
+- lib/halchemy/error_handling.rb
+- lib/halchemy/follower.rb
+- lib/halchemy/http_model.rb
+- lib/halchemy/metadata.rb
+- lib/halchemy/requester.rb
+- lib/halchemy/resource.rb
+- lib/halchemy/status_codes.rb
+- lib/halchemy/version.rb
+- sig/__tests__/base_url.rbs
+- sig/__tests__/halchemy.rbs
+- sig/__tests__/headers.rbs
+- sig/__tests__/remove_headers.rbs
+- sig/halchemy/api.rbs
+- sig/halchemy/base_requester.rbs
+- sig/halchemy/error_handling.rbs
+- sig/halchemy/follower.rbs
+- sig/halchemy/hal_resource.rbs
+- sig/halchemy/http_model/request.rbs
+- sig/halchemy/http_model/response.rbs
+- sig/halchemy/metadata.rbs
+- sig/halchemy/read_only_requester.rbs
+- sig/halchemy/requester.rbs
+- sig/halchemy/resource.rbs
+- sig/list_style_handlers.rbs
+- sig/matchers.rbs
+- sig/patterns.rbs
+homepage: https://github.com/pointw-dev/halchemy
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/pointw-dev/halchemy
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: HAL for humans
+test_files: []