halchemy 1.0.2

data/__tests__/make_http_requests/http_response_details.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+When(/^I make a request$/) do
+  @resource = {}
+  ALL_METHODS.each do |method|
+    @resource[method] = @api.follow(@root_resource).to("resource1").public_send(method)
+  end
+end
+
+Then(/^the HTTP request and response details are available to me$/) do
+  ALL_METHODS.each do |method|
+    resource = @resource[method]
+    expect(resource).not_to be_nil
+    request = resource._halchemy.request
+    response = resource._halchemy.response
+    error = resource._halchemy.error
+
+    expect(request).not_to be_nil
+    expect(response).not_to be_nil
+
+    expect(request.method).to eq(method)
+    expect(request.url).to end_with("/path/to/resource1")
+
+    expect(response.status_code).to eq(200)
+    expect(response.reason).to eq("OK")
+
+    expect(error).to be_nil
+  end
+end
+
+When(/^the request I made fails: (.*)$/) do |failure|
+  @api.error_handling.raise_for_network_errors = false
+
+  server = stub_request(:any, %r{\A#{BASE_URL}/path(/.*)?\z})
+  if failure.start_with?("status_code:")
+    server.to_return(status: failure.sub("status_code:", "").to_i, body: { error: "error" }.to_json)
+  else
+    server.to_raise(failure)
+  end
+  @expected_failure = failure
+
+  @resource = {}
+  ALL_METHODS.each do |method|
+    @resource[method] = @api.follow(@root_resource).to("resource1").public_send(method)
+  end
+end
+
+Then(/^I can access the error details$/) do
+  ALL_METHODS.each do |method|
+    response = @resource[method]._halchemy.response
+    error = @resource[method]._halchemy.error
+    expect(error).not_to be_nil
+
+    if @expected_failure.start_with?("status_code:")
+      expect(response.status_code).to eq(@expected_failure.sub("status_code:", "").to_i)
+    else
+      expect(error.message).to be @expected_failure
+    end
+  end
+end

data/__tests__/make_http_requests/optimistic_concurrency.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+Given(/^a modifiable HAL resource$/) do
+  stub_for_hal_resource_scenarios
+  @api = Halchemy::Api.new BASE_URL
+  root_resource = @api.root.get
+  @resource = @api.follow(root_resource).to("resource1").get
+end
+
+When(/^I request a change to the resource$/) do
+  @requests = make_requests(MODIFY_METHODS, @api.follow(@resource).to("self"))
+end
+
+Then(/^the If-Match header uses the resource's Etag header$/) do
+  MODIFY_METHODS.each do |method|
+    expect(@requests[method].headers["If-Match"]).to eq("from header")
+  end
+end
+
+And(/^the response does not have an Etag header$/) do
+  @resource._halchemy&.response&.headers&.delete("Etag")
+end
+
+Then(/^the If-Match header uses the resource's _etag field$/) do
+  MODIFY_METHODS.each do |method|
+    expect(@requests[method].headers["If-Match"]).to eq("from field")
+  end
+end
+
+And(/^the resource does not have an _etag field$/) do
+  @resource.delete("_etag")
+end
+
+Then(/^the request is made without an If-Match header$/) do
+  MODIFY_METHODS.each do |method|
+    expect(@requests[method].headers.keys).not_to include("If-Match")
+  end
+end

data/__tests__/make_http_requests/with_headers.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+When(/^I specify additional headers for a request$/) do
+  requester = @api.follow(@root_resource).to("resource1").with_headers({ "X-CustomHeader" => "custom value" })
+  @requests = make_requests(ALL_METHODS, requester)
+end
+
+Then(/^the request is made with those headers$/) do
+  ALL_METHODS.each do |method|
+    headers = @requests[method].headers
+    expect(headers.keys.map(&:downcase)).to include("x-customheader")
+    expect(headers["X-Customheader"]).to eq("custom value") # this case sensitivity is from WebMock, not halchemy
+  end
+end
+
+Given(/^I have made a request with additional headers$/) do
+  stub_for_hal_resource_scenarios
+  @api = Halchemy::Api.new BASE_URL
+  @root_resource = @api.root.get
+  @api.follow(@root_resource).to("resource1").with_headers({ "X-CustomHeader" => "custom value" }).get
+end
+
+When(/^I make a new request without headers$/) do
+  @requests = make_requests(ALL_METHODS, @api.follow(@root_resource).to("resource1"))
+end
+
+Then(/^the previous request's headers are not included$/) do
+  ALL_METHODS.each do |method|
+    headers = @requests[method].headers
+    expect(headers.keys.map(&:downcase)).not_to include("x-customheader")
+  end
+end

data/__tests__/make_http_requests/with_parameters.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+When(/^I supply (.*)$/) do |parameters|
+  requester = @api.follow(@root_resource).to("resource1").with_parameters(JSON.parse(parameters))
+  @requests = make_requests(ALL_METHODS, requester)
+end
+
+Then(/^the parameters are added to the URL as a RFC 3986 compliant (.*)$/) do |query_string|
+  ALL_METHODS.each do |method|
+    request_path = normalize_path(@requests[method].uri.to_s)
+    correct_query_string = normalize_path("/path?#{query_string}")[5..]
+    expect(request_path).to end_with(correct_query_string)
+  end
+end
+
+Given(/^an endpoint at (.*)$/) do |url|
+  @api = Halchemy::Api.new(BASE_URL)
+  @endpoint = @api.using_endpoint(url)
+end
+
+When(/^I provide (.*)$/) do |parameters|
+  parameters = JSON.parse(parameters)
+  @url = @endpoint.with_parameters(parameters).url
+end
+
+Then(/^the result is a (.*)$/) do |correct_url|
+  expect(@url).to end_with(correct_url)
+end
+
+And(/^I choose a parameters (.*)$/) do |list_style|
+  @api.parameters_list_style = list_style
+end

data/__tests__/make_http_requests/with_templates.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+Given(/^a HAL resource with a link that is an RFC 6570 compliant (.*)$/) do |templated_href|
+  resource1_json = {
+    data: "some resource",
+    _links: {
+      self: { href: "/path/to/resource1" },
+      next: {
+        href: templated_href,
+        templated: true
+      }
+    }
+  }.to_json
+  stub_request(:any, /.*/).to_return(body: resource1_json, status: 200)
+  @api = Halchemy::Api.new BASE_URL
+  # @hal_resource = Halchemy::HalResource.new.merge! JSON.parse(resource1_json)
+  @hal_resource = @api.using_endpoint("/resource1").get
+end
+
+When(/^I follow that link and provide (.*)$/) do |template_values|
+  requester = @api.follow(@hal_resource).to("next").with_template_values(JSON.parse(template_values))
+  @requests = make_requests(ALL_METHODS, requester)
+end
+
+Then(/^the requested URL ends with the (.*)$/) do |correct_path|
+  ALL_METHODS.each do |method|
+    request_path = normalize_path(@requests[method].uri.to_s)
+    correct_path = normalize_path(correct_path)
+    expect(request_path).to eq(correct_path)
+  end
+end
+
+When(/^the (.*) provided are missing one or more values$/) do |template_values|
+  requester = @api.follow(@hal_resource).to("next")
+  requester = requester.with_template_values(JSON.parse(template_values)) unless template_values == "-omit-"
+  @requests = make_requests(ALL_METHODS, requester)
+end
+
+Then(/^the constructed URL ends with the (.*)$/) do |correct_path|
+  ALL_METHODS.each do |method|
+    request_path = normalize_path(@requests[method].uri.to_s)
+    correct_path = normalize_path(correct_path)
+    expect(request_path).to eq(correct_path)
+  end
+end

data/__tests__/use_resources/iterate_collections.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+Given(/^a HAL resource that has a field which is a collection of objects in HAL format$/) do
+  @resource = Halchemy::HalResource.new.merge!(JSON.parse({
+    _items: [
+      {
+        field: "alpha",
+        _links: { self: { href: "/resource/alpha" } }
+      },
+      {
+        field: "beta",
+        _links: { self: { href: "/resource/beta" } }
+      },
+      {
+        field: "delta",
+        _links: { self: { href: "/resource/delta" } }
+      }
+    ],
+    _links: { self: { href: "/resource" } }
+  }.to_json))
+end
+
+When(/^I iterate the items in that field's collection$/) do
+  @iterator = @resource.collection("_items")
+  @all_hal = @resource.collection("_items").reduce(false) do |all_hal, item|
+    all_hal || item.is_a?(Halchemy::HalResource)
+  end
+end
+
+Then(/^each item is a HAL resource$/) do
+  expect(@all_hal).to be true
+end
+
+When(/^I try to iterate as a collection a field in the resource that does not exist$/) do
+  @root_resource.collection("_items").reduce(false) { |all_hal, item| all_hal || item.is_a?(Halchemy::HalResource) }
+rescue KeyError => e
+  @error = e
+end
+
+Then(/^it throws an exception telling me that the field does not exist$/) do
+  expect(@error).to be_a(KeyError)
+  expect(@error.message).to include("does not exist")
+end
+
+Given(/^a HAL resource with a non-collection field$/) do
+  @resource = Halchemy::HalResource.new.merge!(JSON.parse({
+    _id: "3a834-34f9f03-39b843",
+    _links: { self: { href: "/resource" } }
+  }.to_json))
+end
+
+When(/^I try to iterate as a collection a field that is not a collection$/) do
+  @resource.collection("_id").reduce(false) { |all_hal, item| all_hal || item.is_a?(Halchemy::HalResource) }
+rescue TypeError => e
+  @error = e
+end
+
+Then(/^it throws an exception telling me that the field is not a collection$/) do
+  expect(@error).to be_a(TypeError)
+  expect(@error.message).to include("is not a collection")
+end
+
+Given(/^a HAL resource that has a field which is a collection, but not of HAL formatted objects$/) do
+  @resource = Halchemy::HalResource.new.merge!(JSON.parse({
+    _items: [
+      {
+        make: "Ford Mustang"
+      },
+      {
+        make: "Chrysler 300"
+      },
+      {
+        make: "RAM 1500"
+      }
+    ],
+    _links: { self: { href: "/resource" } }
+  }.to_json))
+end
+
+When(/^I try to iterate the items in that field's collection$/) do
+  @resource.collection("_items").reduce(false) { |all_hal, item| all_hal || item.is_a?(Halchemy::HalResource) }
+rescue TypeError => e
+  @error = e
+end
+
+Then(/^it throws an exception telling me collection contains non-HAL formatted objects$/) do
+  expect(@error).to be_a(TypeError)
+  expect(@error.message).to include("non-HAL")
+end

data/bdd

@@ -0,0 +1 @@
+cucumber ../../features/configurable/configure_base_url.feature:24 --publish-quiet

data/lib/halchemy/api.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "cicphash"
+require "httpx"
+require "http_status_codes"
+
+require_relative "requester"
+require_relative "follower"
+require_relative "error_handling"
+require_relative "status_codes"
+require_relative "resource"
+require_relative "http_model"
+require_relative "metadata"
+
+module Halchemy
+  # This is the Halchemy::Api class, that is the main class for interacting with HAL-based APIs
+  class Api
+    attr_accessor :base_url, :headers, :error_handling, :parameters_list_style
+
+    def initialize(base_url = "http://localhost:2112", headers: {})
+      @base_url = base_url
+      configure
+
+      @headers.merge!(headers)
+    end
+
+    def root
+      using_endpoint("/", is_root: true)
+    end
+
+    def using_endpoint(target, is_root: false)
+      if is_root
+        ReadOnlyRequester.new(self, target)
+      else
+        Requester.new(self, target)
+      end
+    end
+
+    # @param [Hash[String, string]] headers
+    def add_headers(headers)
+      @headers.merge!(headers)
+    end
+
+    # @param [Array[String] headers
+    def remove_headers(header_keys)
+      header_keys.map { |key| @headers.delete(key) }
+    end
+
+    def request(method, target, headers = nil, data = nil)
+      url = build_url(target)
+
+      request_headers = headers.nil? ? @headers : @headers.merge(headers)
+      request = HttpModel::Request.new(method, url, data, request_headers)
+
+      http = HTTPX.with(headers: request_headers)
+      result = http.public_send(method, url, body: data)
+
+      raise_for_errors(result)
+      build_resource(request, result)
+    end
+
+    def follow(resource)
+      Follower.new(self, resource)
+    end
+
+    def optimistic_concurrency_header(resource)
+      etag = resource._halchemy.response.headers["Etag"] || resource[@etag_field]
+      etag.nil? ? {} : { "If-Match" => etag }
+    end
+
+    private
+
+    def configure
+      @headers = CICPHash.new.merge!({
+                                       "Authorization" => "Basic cm9vdDpwYXNzd29yZA==",
+                                       "Content-type" => "application/json",
+                                       "Accept" => "application/hal+json, application/json;q=0.9, */*;q=0.8"
+                                     })
+      @error_handling = ErrorHandling.new
+      @parameters_list_style = "repeat_key"
+      @etag_field = "_etag"
+    end
+
+    def build_url(target)
+      return target if target.start_with?("http")
+
+      [@base_url.chomp("/"), target.sub(%r{\A/+}, "")].join("/")
+    end
+
+    def raise_for_errors(result)
+      if @error_handling.raise_for_network_errors && result.error.instance_of?(StandardError)
+        raise HttpError, result.error.message
+      end
+
+      return unless result.respond_to?(:status)
+      return unless settings_include_status_code?(@error_handling.raise_for_status_codes, result.status)
+
+      raise HttpError, "Status code #{result.status} matches \"#{@error_handling.raise_for_status_codes}\""
+    end
+
+    # @param [HttpModel::Request] request
+    # @param [Object] result
+    # @return [Halchemy::Resource | Halchemy::HalResource]
+    def build_resource(request, result)
+      # result.request.url, result.request.headers, result.request.body
+      response = build_response(result)
+      json = parse_body(result)
+
+      resource = if json.nil?
+                   Resource.new
+                 elsif HalResource.hal?(json)
+                   HalResource.new.merge! json
+                 else
+                   Resource.new.merge! json
+                 end
+
+      resource.tap { |r| r._halchemy = Metadata.new(request, response, result.error) }
+    end
+
+    def parse_body(result)
+      body = extract_body(result)
+      return body if body.is_a?(Hash)
+
+      begin
+        json = JSON.parse(body.to_s) unless body.is_a?(Hash) || body.nil?
+      rescue JSON::ParserError
+        json = nil
+      end
+      json
+    end
+
+    def extract_body(result)
+      begin
+        body = result.json if result.respond_to?("json")
+      rescue HTTPX::Error
+        body = result.to_s # Return raw text if it fails
+      end
+      body
+    end
+
+    def build_response(result)
+      status = result.respond_to?(:status) ? result.status : 0
+      reason = status.positive? ? HTTPStatusCodes::MAP[status] : "Did not receive a response from the server"
+      headers = result.headers if result.respond_to?(:headers)
+      body = result.body if result.respond_to?(:body)
+
+      HttpModel::Response.new(status, reason, headers, body)
+    end
+  end
+end

data/lib/halchemy/error_handling.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Halchemy
+  # A container for the settings which govern how errors are handled.
+  class ErrorHandling
+    attr_accessor :raise_for_network_errors, :raise_for_status_codes
+
+    def initialize
+      @raise_for_network_errors = true
+      @raise_for_status_codes = nil
+    end
+  end
+end

data/lib/halchemy/follower.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Halchemy
+  # Provides the way to navigate from a resource by following to a link relation
+  class Follower
+    def initialize(api, resource)
+      @api = api
+      @resource = resource
+    end
+
+    # @param [String] rel
+    def to(rel)
+      unless @resource["_links"].key?(rel)
+        raise KeyError, "#{@resource.class} does not have a link relation named #{rel}"
+      end
+
+      Requester.new(@api, [@resource, rel])
+    end
+  end
+end

data/lib/halchemy/http_model.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Halchemy
+  module HttpModel
+    # frozen_string_literal: true
+
+    # Provides essential details about the request that was made which resulted in the Resource
+    # this is attached to
+    class Request
+      attr_accessor :method, :url, :headers, :body
+
+      def initialize(method, url, headers, body = nil)
+        @method = method
+        @url = url
+        @headers = headers
+        @body = body
+      end
+
+      def to_s
+        "#{@method.to_s.upcase} #{@url}"
+      end
+    end
+
+    # Provides HTTP metadata that came along with the response resulting in the Resource
+    # this is attached to
+    class Response
+      attr_accessor :status_code, :reason, :headers, :body, :error
+
+      def initialize(status_code, reason, headers, body = nil)
+        @status_code = status_code
+        @reason = reason
+        @headers = headers
+        @body = body
+      end
+
+      def to_s
+        "#{@status_code} #{@reason}"
+      end
+    end
+  end
+end

data/lib/halchemy/metadata.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Halchemy
+  # Allows a Resource to act first as a Hash, by keeping all HTTP related info in resource._halchemy
+  class Metadata
+    attr_reader :request, :response, :error
+
+    def initialize(request, response, error)
+      @request = request
+      @response = response
+      @error = error
+    end
+
+    def raise_for_status_codes(settings = ">399")
+      return unless settings_include_status_code?(settings, @response.status_code)
+
+      raise HttpError, "Status code #{@response.status_code} matches \"#{settings}\""
+    end
+  end
+end