stub_requests 0.1.0

data/lib/stub_requests/service_registry.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "concurrent/map"
+
+#
+# Abstraction over WebMock to reduce duplication
+#
+# @author Mikael Henriksson <mikael@zoolutions.se>
+# @since 0.1.0
+#
+module StubRequests
+  #
+  # Class ServiceRegistry provides registration of services
+  #
+  class ServiceRegistry
+    include Singleton
+    include Enumerable
+
+    #
+    # @!attribute [rw] services
+    #   @return [Concurrent::Map<Symbol, Service>] a map with services
+    attr_reader :services
+
+    def initialize
+      @services = Concurrent::Map.new
+    end
+
+    #
+    # Resets the map with registered services
+    #
+    #
+    # @api private
+    def reset
+      services.clear
+    end
+
+    #
+    # Required by Enumerable
+    #
+    #
+    # @return [Concurrent::Map<Symbol, Service>] an map with services
+    #
+    # @yield used by Enumerable
+    #
+    def each(&block)
+      services.each(&block)
+    end
+
+    #
+    # Registers a service in the registry
+    #
+    #
+    # @param [Symbol] service_id a symbolic id of the service
+    # @param [String] service_uri a string with a base_uri to the service
+    #
+    # @return [Service] the service that was just registered
+    #
+    def register_service(service_id, service_uri)
+      if (service = get_service(service_id))
+        StubRequests.logger.warn("Service already registered #{service}")
+        raise ServiceHaveEndpoints, service if service.endpoints?
+      end
+      services[service_id] = Service.new(service_id, service_uri)
+    end
+
+    #
+    # Removes a service from the registry
+    #
+    #
+    # @param [Symbol] service_id the service_id to remove
+    #
+    # @raise [ServiceNotFound] when the service was not removed
+    #
+    def remove_service(service_id)
+      services.delete(service_id) || raise(ServiceNotFound, service_id)
+    end
+
+    #
+    # Fetches a service from the registry
+    #
+    #
+    # @param [Symbol] service_id id of the service to remove
+    #
+    # @return [Service] the found service
+    #
+    def get_service(service_id)
+      services[service_id]
+    end
+
+    #
+    # Fetches a service from the registry or raises {ServiceNotFound}
+    #
+    #
+    # @param [Symbol] service_id the id of a service
+    #
+    # @raise [ServiceNotFound] when an endpoint couldn't be found
+    #
+    # @return [Endpoint]
+    #
+    def get_service!(service_id)
+      get_service(service_id) || raise(ServiceNotFound, service_id)
+    end
+  end
+end

data/lib/stub_requests/stub_requests.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+#
+# Abstraction over WebMock to reduce duplication
+#
+# @author Mikael Henriksson <mikael@zoolutions.se>
+# @since 0.1.0
+#
+module StubRequests
+  #
+  # Error is a base class for all gem errors
+  #
+  class Error < StandardError; end
+
+  #
+  # ServiceHaveEndpoints is raised to prevent overwriting a registered service's endpoints
+  #
+  class ServiceHaveEndpoints < StandardError
+    def initialize(service)
+      super("Service with id #{service.id} have already been registered. #{service}")
+    end
+  end
+
+  #
+  # InvalidType is raised when an argument is invalid
+  #
+  class InvalidType < Error
+    def initialize(actual:, expected:)
+      super("Expected `#{actual}` to be any of [#{expected}]")
+    end
+  end
+
+  #
+  # EndpointNotFound is raised when an endpoint cannot be found
+  #
+  class EndpointNotFound < Error; end
+
+  #
+  # ServiceNotFound is raised when a service cannot be found
+  #
+  class ServiceNotFound < Error
+    def initialize(service_id)
+      super("Couldn't find a service with id=:#{service_id}")
+    end
+  end
+
+  #
+  # UriSegmentMismatch is raised when a segment cannot be replaced
+  #
+  class UriSegmentMismatch < Error; end
+
+  #
+  # InvalidUri is raised when a URI is invalid
+  #
+  class InvalidUri < Error
+    def initialize(uri)
+      super("'#{uri}' is not a valid URI.")
+    end
+  end
+
+  # extends "self"
+  # @!parse extend self
+  extend self
+
+  # includes "UriFor" and extends "UriFor"
+  # using the API.included callback
+  # @!parse include UriFor
+  # @!parse extend UriFor
+
+  # includes "API" and extends "API"
+  # using the API.included callback
+  # @!parse include API
+  # @!parse extend API
+  include API
+
+  #
+  # @!attribute [rw] logger
+  #   @return [Logger] the logger to use in the gem
+  attr_accessor :logger
+
+  #
+  # The current version of the gem
+  #
+  #
+  # @return [String] version string, `"1.0.0"`
+  #
+  def version
+    VERSION
+  end
+end

data/lib/stub_requests/uri/builder.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+#
+# Abstraction over WebMock to reduce duplication
+#
+# @author Mikael Henriksson <mikael@zoolutions.se>
+# @since 0.1.0
+#
+module StubRequests
+  #
+  # Builds a URI from a #host, #template and #replacements
+  #
+  module URI
+    #
+    # Builder constructs and validates URIs
+    #
+    # :reek:TooManyInstanceVariables { max_instance_variables: 6 }
+    class Builder
+      #
+      # @return [Regexp] A pattern for matching url segment keys
+      URL_SEGMENT_REGEX = /(:\w+)/.freeze
+
+      #
+      # Convenience method to avoid .new.build
+      #
+      #
+      # @raise [UriSegmentMismatch] when there are unused URI segments
+      # @raise [UriSegmentMismatch] when the template have unplaced URI segments
+      #
+      # @param [String] host the URI used to reach the service
+      # @param [String] template the endpoint template
+      # @param [Hash<Symbol>] replacements a list of uri_replacement keys
+      #
+      # @return [String] a validated URI string
+      #
+      def self.build(host, template, replacements = {})
+        new(host, template, replacements).build
+      end
+
+      #
+      # @!attribute [r] uri
+      #   @return [String] the request host {Service#service_uri}
+      attr_reader :host
+      #
+      # @!attribute [r] template
+      #   @return [String] a string template for the endpoint
+      attr_reader :template
+      #
+      # @!attribute [r] path
+      #   @return [String] a valid URI path
+      attr_reader :path
+      #
+      # @!attribute [r] replacements
+      #   @return [Hash<Symbol] a hash with keys matching the {#template}
+      attr_reader :replacements
+      #
+      # @!attribute [r] unused
+      #   @return [Array<String>] a list with unused {#replacements}
+      attr_reader :unused
+      #
+      # @!attribute [r] unreplaced
+      #   @return [Array<String>] a list of uri_segments that should have been replaced
+      attr_reader :unreplaced
+
+      #
+      # Initializes a new Builder
+      #
+      #
+      # @param [String] host the URI used to reach the service
+      # @param [String] template the endpoint template
+      # @param [Hash<Symbol>] replacements a list of uri_replacement keys
+      #
+      def initialize(host, template, replacements = {})
+        @host         = +host
+        @template     = +template
+        @path         = +@template.dup
+        @replacements = replacements
+      end
+
+      #
+      # Builds a URI string
+      #
+      #
+      # @raise [UriSegmentMismatch] when there are unused URI segments
+      # @raise [UriSegmentMismatch] when the template have unplaced URI segments
+      #
+      # @return [String] a validated URI string
+      #
+      def build
+        build_uri
+        run_validations
+
+        uri
+      end
+
+      private
+
+      def build_uri
+        replace_segments
+        parse_unreplaced_segments
+      end
+
+      def uri
+        @uri ||= [host, path].join("/")
+      end
+
+      def run_validations
+        validate_replacements_used
+        validate_segments_replaced
+        validate_uri
+      end
+
+      #
+      # Replaces the URI segments with the arguments in replacements
+      #
+      #
+      # @return [Array] an list with unused replacements
+      #
+      def replace_segments
+        @unused = replacements.map do |key, value|
+          uri_segment = ":#{key}"
+          if path.include?(uri_segment)
+            path.gsub!(uri_segment.to_s, value.to_s)
+            next
+          else
+            uri_segment
+          end
+        end.compact
+      end
+
+      #
+      # Validates that all replacements have been used
+      #
+      #
+      # @raise [UriSegmentMismatch] when there are unused replacements
+      #
+      # @return [void]
+      #
+      def validate_replacements_used
+        return if replacents_used?
+
+        raise UriSegmentMismatch,
+              "The URI segment(s) [#{unused.join(',')}] are missing in template (#{path})"
+      end
+
+      #
+      # Checks that no replacements are left
+      #
+      #
+      # @return [true,false]
+      #
+      def replacents_used?
+        unused.none?
+      end
+
+      #
+      # Validates that all URI segments have been replaced in {#path}
+      #
+      #
+      # @raise [UriSegmentMismatch] when the path have unplaced URI segments
+      #
+      # @return [void]
+      #
+      def validate_segments_replaced
+        return if segments_replaced?
+
+        raise UriSegmentMismatch,
+              "The URI segment(s) [#{unreplaced.join(',')}]" \
+              " were not replaced in template (#{path})." \
+              " Given replacements=[#{segment_keys.join(',')}]"
+      end
+
+      def segment_keys
+        @segment_keys ||= replacements.keys.map { |segment_key| ":#{segment_key}" }
+      end
+
+      #
+      # Checks that all URI segments were replaced
+      #
+      #
+      # @return [true,false]
+      #
+      def segments_replaced?
+        unreplaced.none?
+      end
+
+      #
+      # Parses out all unused URI segments
+      #
+      #
+      # @return [Array<String>] a list of not replaced uri_segments
+      #
+      def parse_unreplaced_segments
+        @unreplaced = URL_SEGMENT_REGEX.match(path).to_a.uniq
+      end
+
+      #
+      # Validates {#uri} is valid
+      #
+      #
+      # @return [true, false]
+      #
+      def validate_uri
+        StubRequests::URI::Validator.valid?(uri)
+      rescue InvalidUri
+        StubRequests.logger.warn("URI (#{uri}) is not valid.")
+        false
+      end
+
+      #
+      # Raise exception when {#validate_uri} is false
+      #
+      # @see #validate_uri
+      #
+      # @raise [InvalidUri] when #{uri} is invalid
+      #
+      # @return [void]
+      #
+      # :nocov:
+      # :nodoc:
+      def validate_uri!
+        raise InvalidUri, uri unless validate_uri
+      end
+    end
+  end
+end

data/lib/stub_requests/uri/scheme.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+#
+# Abstraction over WebMock to reduce duplication
+#
+# @author Mikael Henriksson <mikael@zoolutions.se>
+# @since 0.1.0
+#
+module StubRequests
+  #
+  # Provides convenience methods for URI
+  #
+  module URI
+    #
+    # Module Scheme handles validation of {URI} schemes
+    #
+    module Scheme
+      #
+      # @return [Array<String>] a list of valid HTTP schemes
+      SCHEMES = %w[http https].freeze
+
+      #
+      # Checks if the scheme is valid
+      #
+      # @param [String] scheme a string with the URI scheme to check
+      #
+      # @return [true,false]
+      #
+      def self.valid?(scheme)
+        SCHEMES.include?(scheme.to_s)
+      end
+    end
+  end
+end

data/lib/stub_requests/uri/suffix.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+#
+# Abstraction over WebMock to reduce duplication
+#
+# @author Mikael Henriksson <mikael@zoolutions.se>
+# @since 0.1.0
+#
+module StubRequests
+  module URI
+    #
+    # Module Suffix deals with validating {URI} suffix
+    #
+    module Suffix
+      #
+      # @return [RegExp] a pattern used for matching HTTP(S) ports
+      PORT_REGEX = %r{:(\d+)/}.freeze
+
+      #
+      # Checks if the host has a valid suffix
+      #
+      # @param [String] host a string to check
+      #
+      # @return [true,false]
+      #
+      def self.valid?(host)
+        PublicSuffix.valid?(host, default_rule: nil)
+      end
+    end
+  end
+end

data/lib/stub_requests/uri/validator.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+#
+# Abstraction over WebMock to reduce duplication
+#
+# @author Mikael Henriksson <mikael@zoolutions.se>
+# @since 0.1.0
+#
+module StubRequests
+  #
+  # Provides convenience methods for URI
+  #
+  module URI
+    #
+    # Validator provides functionality for validating a {::URI}
+    #
+    class Validator
+      #
+      # Validates a URI
+      #
+      # @param [String] uri a full uri with path
+      #
+      # @return [true, false]
+      #
+      def self.valid?(uri)
+        new(uri).valid?
+      end
+
+      #
+      # @!attribute [r] uri
+      #   @return [String] a complete URI
+      attr_reader :uri
+      #
+      # @!attribute [r] host
+      #   @return [String] the URI host
+      attr_reader :host
+      #
+      # @!attribute [r] scheme
+      #   @return [String] the URI scheme
+      attr_reader :scheme
+
+      #
+      # Initialize a new instance of {Validator}
+      #
+      # @raise [InvalidUri] when URI can't be parsed
+      #
+      # @param [String] uri the full URI
+      #
+      #
+      def initialize(uri)
+        @uri    = ::URI.parse(uri)
+        @host   = @uri.host
+        @scheme = @uri.scheme
+      rescue ::URI::InvalidURIError
+        raise InvalidUri, uri
+      end
+
+      #
+      # Checks if a URI is valid
+      #
+      #
+      # @return [true,false] <description>
+      #
+      def valid?
+        URI::Scheme.valid?(scheme) && URI::Suffix.valid?(host)
+      end
+    end
+  end
+end

data/lib/stub_requests/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+#
+# Abstraction over WebMock to reduce duplication
+#
+# @author Mikael Henriksson <mikael@zoolutions.se>
+# @since 0.1.0
+#
+module StubRequests
+  #
+  # @return [String] a version string
+  VERSION = "0.1.0"
+end

data/lib/stub_requests/webmock_builder.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+#
+# Abstraction over WebMock to reduce duplication
+#
+# @author Mikael Henriksson <mikael@zoolutions.se>
+# @since 0.1.0
+#
+module StubRequests
+  #
+  # Module API abstraction to reduce the amount of WebMock.stub_request
+  #
+  # @note This module can either be used by its class methods
+  #   or included in say RSpec
+  #
+  class WebMockBuilder
+    include HashUtil
+
+    #
+    # Builds and registers a WebMock::RequestStub
+    #
+    #
+    # @param [Symbol] verb a HTTP verb/method
+    # @param [String] uri a URI to call
+    # @param [Hash<Symbol>] options request/response options for Webmock::RequestStub
+    #
+    # @yield a callback to eventually yield to the caller
+    #
+    # @return [WebMock::RequestStub] the registered stub
+    #
+    def self.build(verb, uri, options = {}, &callback)
+      new(verb, uri, options, &callback).build
+    end
+
+    #
+    # @!attribute [r] request_stub
+    #   @return [WebMock::RequestStub] a stubbed webmock request
+    attr_reader :request_stub
+    #
+    # @!attribute [r] options
+    #   @return [Hash<Symbol>] options for the stub_request
+    attr_reader :options
+    #
+    # @!attribute [r] callback
+    #   @return [Block] call back when given a block
+    attr_reader :callback
+
+    #
+    # Initializes a new instance of
+    #
+    #
+    # @param [Symbol] verb a HTTP verb/method
+    # @param [String] uri a URI to call
+    # @param [Hash<Symbol>] options request/response options for Webmock::RequestStub
+    #
+    # @yield a block to eventually yield to the caller
+    #
+    def initialize(verb, uri, options = {}, &callback)
+      @request_stub = WebMock::RequestStub.new(verb, uri)
+      @options      = options
+      @callback     = callback
+    end
+
+    #
+    # Prepares a WebMock::RequestStub and registers it in WebMock
+    #
+    #
+    # @return [WebMock::RequestStub] the registered stub
+    #
+    def build
+      if callback.present?
+        Docile.dsl_eval(request_stub, &callback)
+      else
+        prepare_mock_request
+      end
+
+      WebMock::StubRegistry.instance.register_request_stub(request_stub)
+    end
+
+    private
+
+    def prepare_mock_request
+      prepare_with
+      prepare_to_return
+      prepare_to_raise
+      request_stub.to_timeout if options[:timeout]
+      request_stub
+    end
+
+    def prepare_with
+      HashUtil.compact(options[:request]) do |request_options|
+        request_stub.with(request_options)
+      end
+    end
+
+    def prepare_to_return
+      HashUtil.compact(options[:response]) do |response_options|
+        request_stub.to_return(response_options)
+      end
+    end
+
+    def prepare_to_raise
+      return unless (error = options[:error])
+
+      request_stub.to_raise(*Array(error))
+    end
+  end
+end

data/lib/stub_requests.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "docile"
+require "webmock"
+require "webmock/api"
+
+require "stub_requests/version"
+
+require "stub_requests/core_ext"
+require "stub_requests/hash_util"
+require "stub_requests/argument_validation"
+require "stub_requests/endpoint"
+require "stub_requests/endpoint_registry"
+require "stub_requests/service"
+require "stub_requests/service_registry"
+require "stub_requests/uri/scheme"
+require "stub_requests/uri/suffix"
+require "stub_requests/uri/validator"
+require "stub_requests/uri/builder"
+require "stub_requests/webmock_builder"
+
+require "stub_requests/api"
+
+require "stub_requests/stub_requests"