rom-http 0.7.0 → 0.9.0

data/lib/rom/http/dataset.rb

@@ -1,114 +1,199 @@
-require 'uri'
-require 'dry-configurable'
-require 'dry/core/deprecations'
-require 'rom/initializer'
-require 'rom/http/dataset/class_interface'
+# frozen_string_literal: true
+
+require "uri"
+
+require "dry/configurable"
+require "dry/core/deprecations"
+
+require "rom/support/memoizable"
+require "rom/constants"
+require "rom/initializer"
+require "rom/http/types"
+require "rom/http/transformer"
 
 module ROM
   module HTTP
     # HTTP Dataset
     #
-    # Represents a specific HTTP collection resource
+    # Represents a specific HTTP collection resource. This class can be
+    # subclassed in a specialized HTTP adapter to provide its own
+    # response/request handlers or any other configuration that should
+    # differ from the defaults.
     #
     # @api public
     class Dataset
-      PATH_SEPARATOR = '/'.freeze
-
-      extend ::ROM::Initializer
-      extend ::Dry::Configurable
-      extend ::ROM::HTTP::Dataset::ClassInterface
-      include ::Enumerable
-      include ::Dry::Equalizer(:config, :options)
-
-      setting :default_request_handler
-      setting :default_response_handler
-      setting :param_encoder, ->(params) { URI.encode_www_form(params) }
-
-      param :config
-
-      option :request_method, type: Types::Symbol, default: proc { :get }, reader: true
-      option :base_path, type: Types::String, default: proc { name }
-      option :path, type: Types::String, default: proc { '' }, reader: false
-      option :params, type: Types::Hash, default: proc { {} }, reader: true
-      option :headers, type: Types::Hash, default: proc { {} }
-
-      # Return the gateway's URI
-      #
-      # @return [String]
-      #
-      # @raise [Error] if the configuration does not contain a URI
+      PATH_SEPARATOR = "/"
+
+      extend Dry::Configurable
+      extend ROM::Initializer
+
+      include ROM::Memoizable
+      include Enumerable
+      include Dry::Equalizer(:options)
+
+      # @!method self.default_request_handler
+      #   Return configured default request handler
+      #
+      #   @example
+      #     class MyDataset < ROM::HTTP::Dataset
+      #       configure do |config|
+      #         config.default_request_handler = MyRequestHandler
+      #       end
+      #     end
+      #
+      #     MyDataset.default_request_handler # MyRequestHandler
+      #     MyDataset.new(uri: "http://localhost").request_handler # MyRequestHandler
+      setting :default_request_handler, reader: true
+
+      # @!method self.default_response_handler
+      #   Return configured default response handler
+      #
+      #   @example
+      #     class MyDataset < ROM::HTTP::Dataset
+      #       configure do |config|
+      #         config.default_response_handler = MyResponseHandler
+      #       end
+      #     end
+      #
+      #     MyDataset.default_response_handler # MyResponseHandler
+      #     MyDataset.new(uri: "http://localhost").response_handler # MyResponseHandler
+      setting :default_response_handler, reader: true
+
+      # @!method self.query_param_encoder
+      #   Return configured query param encoder
+      #
+      #   @example
+      #     class MyDataset < ROM::HTTP::Dataset
+      #       configure do |config|
+      #         config.query_param_encoder = MyParamEncoder
+      #       end
+      #     end
+      #
+      #     MyDataset.query_param_encoder # MyParamEncoder
+      #     MyDataset.new(uri: "http://localhost").query_param_encoder # MyParamEncoder
+      setting :query_param_encoder, default: URI.method(:encode_www_form), reader: true
+
+      # @!attribute [r] request_handler
+      #   @return [Object]
+      #   @api public
+      option :request_handler, default: proc { self.class.default_request_handler }
+
+      # @!attribute [r] response_handler
+      #   @return [Object]
+      #   @api public
+      option :response_handler, default: proc { self.class.default_response_handler }
+
+      # @!attribute [r] request_method
+      #   @return [Symbol]
+      #   @api public
+      option :request_method, type: Types::Symbol, default: proc { :get }
+
+      # @!attribute [r] base_path
+      #   @return [String]
+      #   @api public
+      option :base_path, type: Types::Path, default: proc { EMPTY_STRING }
+
+      # @!attribute [r] path
+      #   @return [String]
+      #   @api public
+      option :path, type: Types::Path, default: proc { EMPTY_STRING }
+
+      # @!attribute [r] query_params
+      #   @return [Hash]
+      #   @api public
+      option :query_params, type: Types::Hash, default: proc { EMPTY_HASH }
+
+      # @!attribute [r] body_params
+      #   @return [Hash]
+      #   @api public
+      option :body_params, type: Types::Hash, default: proc { EMPTY_HASH }
+
+      # @!attribute [r] headers
+      #   @return [Hash]
+      #   @api public
+      option :headers, type: Types::Hash, default: proc { EMPTY_HASH }
+
+      # @!attribute [r] headers
+      #   @return [Hash]
+      #   @api public
+      option :query_param_encoder, default: proc { self.class.query_param_encoder }
+
+      # @!attribute [r] uri
+      #   @return [String]
+      #   @api public
+      option :uri, type: Types::String
+
+      # Return the dataset's URI
+      #
+      # @return [URI::HTTP]
       #
       # @api public
       def uri
-        uri = config.fetch(:uri) { fail Error, '+uri+ configuration missing' }
-        uri = URI(join_path(uri, path))
-        if request_method == :get && params.any?
-          uri.query = self.class.config.param_encoder.call(params)
+        uri = URI(join_path(super, path))
+
+        if query_params.any?
+          uri.query = query_param_encoder.call(query_params)
         end
 
         uri
       end
 
-      # Return request headers
+      # Return true if request method is set to :get
       #
-      # Merges default headers from the Gateway configuration and the
-      # current Dataset
+      # @return [Boolean]
       #
-      # @example
-      #   config = { Accepts: 'application/json' }
-      #   users  = Dataset.new(config, headers: { 'Cache-Control': 'no-cache' }
-      #   users.headers
-      #   # => {:Accepts => "application/json", :'Cache-Control' => 'no-cache'}
+      # @api public
+      def get?
+        request_method.equal?(:get)
+      end
+
+      # Return true if request method is set to :post
       #
-      # @return [Hash]
+      # @return [Boolean]
       #
       # @api public
-      def headers
-        config.fetch(:headers, {}).merge(options.fetch(:headers, {}))
+      def post?
+        request_method.equal?(:post)
       end
 
-      # Return the dataset name
+      # Return true if request method is set to :put
       #
-      # @return [String]
+      # @return [Boolean]
       #
       # @api public
-      def name
-        config[:name].to_s
+      def put?
+        request_method.equal?(:put)
       end
 
-      # Return the base path
-      #
-      # @example
-      #   Dataset.new(config, base_path: '/users').base_path
-      #   # => 'users'
+      # Return true if request method is set to :delete
       #
-      # @return [String] the dataset path, without a leading slash
+      # @return [Boolean]
       #
       # @api public
-      def base_path
-        strip_path(super)
+      def delete?
+        request_method.equal?(:delete)
       end
 
       # Return the dataset path
       #
       # @example
-      #   Dataset.new(config, path: '/users').path
+      #   Dataset.new(path: '/users').path
       #   # => 'users'
       #
       # @return [String] the dataset path, without a leading slash
       #
       # @api public
       def path
-        join_path(base_path, strip_path(options[:path].to_s))
+        join_path(base_path, super)
       end
 
       # Return the dataset path
       #
       # @example
-      #   Dataset.new(config, path: '/users').path
+      #   Dataset.new(path: '/users').path
       #   # => '/users'
       #
-      # @return [string] the dataset path, with leading slash
+      # @return [String] the dataset path, with leading slash
       #
       # @api public
       def absolute_path
@@ -123,7 +208,7 @@ module ROM
       #   To non-destructively add a new header, use `#add_header`
       #
       # @example
-      #   users = Dataset.new(config, headers: { Accept: 'application/json' })
+      #   users = Dataset.new(headers: { Accept: 'application/json' })
       #   users.with_headers(:'X-Api-Key' => '1234').headers
       #   # => { :'X-Api-Key' => '1234' }
       #
@@ -131,7 +216,7 @@ module ROM
       #
       # @api public
       def with_headers(headers)
-        __new__(config, options.merge(headers: headers))
+        with_options(headers: headers)
       end
 
       # Return a new dataset with additional header
@@ -140,7 +225,7 @@ module ROM
       # @param value  [String] the header value
       #
       # @example
-      #   users = Dataset.new(config, headers: { Accept: 'application/json' })
+      #   users = Dataset.new(headers: { Accept: 'application/json' })
       #   users.add_header(:'X-Api-Key', '1234').headers
       #   # => { :Accept => 'application/json', :'X-Api-Key' => '1234' }
       #
@@ -159,7 +244,7 @@ module ROM
       #
       # @api public
       def with_options(opts)
-        __new__(config, options.merge(opts))
+        __new__(**options.merge(opts))
       end
 
       # Return a new dataset with a different base path
@@ -204,7 +289,7 @@ module ROM
       #
       # @api public
       def append_path(append_path)
-        with_options(path: join_path(path, append_path))
+        with_path(join_path(options[:path], append_path))
       end
 
       # Return a new dataset with a different request method
@@ -221,39 +306,70 @@ module ROM
         with_options(request_method: request_method)
       end
 
-      # Return a new dataset with replaced request parameters
+      # Return a new dataset with replaced request query parameters
       #
-      # @param [Hash] params the new request parameters
+      # @param [Hash] query_params the new request query parameters
       #
       # @example
-      #   users = Dataset.new(config, params: { uid: 33 })
-      #   users.with_params(login: 'jdoe').params
+      #   users = Dataset.new(query_params: { uid: 33 })
+      #   users.with_query_params(login: 'jdoe').query_params
       #   # => { :login => 'jdoe' }
       #
       # @return [Dataset]
       #
       # @api public
-      def with_params(params)
-        with_options(params: params)
+      def with_query_params(query_params)
+        with_options(query_params: query_params)
       end
 
-      # Return a new dataset with merged request parameters
+      # Return a new dataset with merged request query parameters
       #
-      # @param [Hash] params the new request parameters to add
+      # @param [Hash] query_params the new request query parameters to add
       #
       # @example
-      #   users = Dataset.new(config, params: { uid: 33 })
-      #   users.add_params(login: 'jdoe').params
+      #   users = Dataset.new(query_params: { uid: 33 })
+      #   users.add_query_params(login: 'jdoe').query_params
       #   # => { uid: 33, :login => 'jdoe' }
       #
       # @return [Dataset]
       #
       # @api public
-      def add_params(new_params)
-        # TODO: Should we merge arrays?
-        with_options(
-          params: ::ROM::HTTP::Transformer[:deep_merge][params, new_params]
-        )
+      def add_query_params(new_query_params)
+        with_options(query_params: ::ROM::HTTP::Transformer[:deep_merge][query_params,
+                                                                         new_query_params])
+      end
+
+      # Return a new dataset with replaced request body parameters
+      #
+      # @param [Hash] body_params the new request body parameters
+      #
+      # @example
+      #   users = Dataset.new(body_params: { uid: 33 })
+      #   users.with_body_params(login: 'jdoe').body_params
+      #   # => { :login => 'jdoe' }
+      #
+      # @return [Dataset]
+      #
+      # @api public
+      def with_body_params(body_params)
+        with_options(body_params: body_params)
+      end
+
+      # Return a new dataset with merged request body parameters
+      #
+      # @param [Hash] body_params the new request body parameters to add
+      #
+      # @example
+      #   users = Dataset.new(body_params: { uid: 33 })
+      #   users.add_body_params(login: 'jdoe').body_params
+      #   # => { uid: 33, :login => 'jdoe' }
+      #
+      # @return [Dataset]
+      #
+      # @api public
+      def add_body_params(new_body_params)
+        with_options(body_params: ::ROM::HTTP::Transformer[:deep_merge][body_params,
+                                                                        new_body_params])
       end
 
       # Iterate over each response value
@@ -266,34 +382,35 @@ module ROM
       # @api public
       def each(&block)
         return to_enum unless block_given?
+
         response.each(&block)
       end
 
       # Perform an insert over HTTP Post
       #
-      # @params [Hash] params The request parameters to send
+      # @param [Hash] attributes the attributes to insert
       #
       # @return [Array<Hash>]
       #
       # @api public
-      def insert(params)
+      def insert(attributes)
         with_options(
           request_method: :post,
-          params: params
+          body_params: attributes
         ).response
       end
 
       # Perform an update over HTTP Put
       #
-      # @params [Hash] params The request parameters to send
+      # @param [Hash] attributes the attributes to update
       #
       # @return [Array<Hash>]
       #
       # @api public
-      def update(params)
+      def update(attributes)
         with_options(
           request_method: :put,
-          params: params
+          body_params: attributes
         ).response
       end
 
@@ -304,9 +421,7 @@ module ROM
       #
       # @api public
       def delete
-        with_options(
-          request_method: :delete
-        ).response
+        with_options(request_method: :delete).response
       end
 
       # Execute the current dataset
@@ -318,37 +433,19 @@ module ROM
         response_handler.call(request_handler.call(self), self)
       end
 
-      private
-
-      def response_handler
-        response_handler = config.fetch(
-          :response_handler,
-          self.class.config.default_response_handler
-        )
-        fail Error, '+default_response_handler+ configuration missing' if response_handler.nil?
-        response_handler
-      end
+      memoize :uri, :absolute_path
 
-      def request_handler
-        request_handler = config.fetch(
-          :request_handler,
-          self.class.config.default_request_handler
-        )
-        fail Error, '+default_response_handler+ configuration missing' if request_handler.nil?
-        request_handler
-      end
+      private
 
-      def __new__(*args, &block)
-        self.class.new(*args, &block)
+      # @api private
+      def __new__(*args, **kwargs, &block)
+        self.class.new(*args, **kwargs, &block)
       end
 
+      # @api private
       def join_path(*paths)
         paths.reject(&:empty?).join(PATH_SEPARATOR)
       end
-
-      def strip_path(path)
-        path.sub(%r{\A/}, '')
-      end
     end
   end
 end

data/lib/rom/http/error.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ROM
   module HTTP
     Error = Class.new(StandardError)

data/lib/rom/http/gateway.rb

@@ -1,5 +1,10 @@
-require 'concurrent'
-require 'rom/http/dataset'
+# frozen_string_literal: true
+
+require "concurrent"
+
+require "rom/http/dataset"
+require "rom/http/handlers"
+require "rom/http/mapper_compiler"
 
 module ROM
   module HTTP
@@ -19,7 +24,6 @@ module ROM
       adapter :http
 
       attr_reader :datasets, :config
-      private :datasets, :config
 
       # HTTP gateway interface
       #
@@ -54,8 +58,7 @@ module ROM
       #
       # @api public
       def dataset(name)
-        dataset_klass = namespace.const_defined?(:Dataset) ? namespace.const_get(:Dataset) : Dataset
-        datasets[name] = dataset_klass.new(config.merge(name: name))
+        datasets[name] = dataset_class.new(**dataset_options(name))
       end
 
       # Check if dataset exists
@@ -69,8 +72,46 @@ module ROM
 
       private
 
+      # Return Dataset class
+      #
+      # @return [Class]
+      #
+      # @api private
+      def dataset_class
+        namespace.const_defined?(:Dataset) ? namespace.const_get(:Dataset) : Dataset
+      end
+
+      # Return Dataset options
+      #
+      # @return [Class]
+      #
+      # @api private
+      def dataset_options(name)
+        config.merge(uri: uri, base_path: name, **default_handlers)
+      end
+
+      # Return default handlers registered in Handlers registry
+      #
+      # @return [Hash]
+      #
+      # @api private
+      def default_handlers
+        if handlers_key = config[:handlers]
+          Handlers[handlers_key]
+            .map { |key, value| [:"#{key}_handler", value] }.to_h
+        else
+          EMPTY_HASH
+        end
+      end
+
+      # @api private
+      def uri
+        config.fetch(:uri) { raise Error, "+uri+ configuration missing" }
+      end
+
+      # @api private
       def namespace
-        self.class.to_s[/(.*)(?=::)/].split('::').inject(::Object) do |constant, const_name|
+        self.class.to_s[/(.*)(?=::)/].split("::").inject(::Object) do |constant, const_name|
           constant.const_get(const_name)
         end
       end

data/lib/rom/http/handlers/json.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "uri"
+require "net/http"
+require "json"
+
+require "rom/support/inflector"
+
+module ROM
+  module HTTP
+    # Default request/response handlers
+    #
+    # @api public
+    class Handlers
+      # Default handler for JSON requests
+      #
+      # @api public
+      class JSONRequest
+        # Handle JSON request for the provided dataset
+        #
+        # @param [Dataset] dataset
+        #
+        # @return [Array<Hash>]
+        #
+        # @api public
+        def self.call(dataset)
+          uri = dataset.uri
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true if uri.scheme.eql?("https")
+
+          request_class = Net::HTTP.const_get(ROM::Inflector.classify(dataset.request_method))
+
+          request = request_class.new(uri.request_uri)
+
+          dataset.headers.each_with_object(request) do |(header, value), request|
+            request[header.to_s] = value
+          end
+
+          request.body = JSON.dump(dataset.body_params) if dataset.body_params.any?
+
+          http.request(request)
+        end
+      end
+
+      # Default handler for JSON responses
+      #
+      # @api public
+      class JSONResponse
+        # Handle JSON responses
+        #
+        # @param [Net::HTTP::Response] response
+        # @param [Dataset] dataset
+        #
+        # @return [Array<Hash>]
+        #
+        # @api public
+        def self.call(response, _dataset)
+          Array([JSON.parse(response.body)]).flatten(1)
+        end
+      end
+    end
+  end
+end

data/lib/rom/http/handlers.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rom/http/handlers/json"
+
+module ROM
+  module HTTP
+    # Request/response handler registry
+    #
+    # @api public
+    class Handlers
+      extend Dry::Container::Mixin
+
+      register(:json, request: JSONRequest, response: JSONResponse)
+    end
+  end
+end

data/lib/rom/http/mapper_compiler.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rom/mapper_compiler"
+
+module ROM
+  module HTTP
+    class MapperCompiler < ROM::MapperCompiler
+      mapper_options(reject_keys: true)
+    end
+  end
+end