web_pipe 0.1.0

data/lib/web_pipe/conn_support/builder.rb

@@ -0,0 +1,36 @@
+require 'rack'
+require 'web_pipe/conn'
+require 'web_pipe/conn_support/headers'
+
+module WebPipe
+  module ConnSupport
+    # Helper module to build a {Conn} from a rack's env.
+    #
+    # It always return a {Conn::Clean} subclass.
+    #
+    # @private
+    module Builder
+      # @param env [Types::Env] Rack's env
+      #
+      # @return [Conn::Clean]
+      def self.call(env)
+        rr = ::Rack::Request.new(env)
+        Conn::Clean.new(
+          request: rr,
+          env: env,
+
+          scheme: rr.scheme.to_sym,
+          request_method: rr.request_method.downcase.to_sym,
+          host: rr.host,
+          ip: rr.ip,
+          port: rr.port,
+          script_name: rr.script_name,
+          path_info: rr.path_info,
+          query_string: rr.query_string,
+          request_body: rr.body,
+          request_headers: Headers.extract(env)
+        )
+      end
+    end
+  end
+end

data/lib/web_pipe/conn_support/errors.rb

@@ -0,0 +1,16 @@
+module WebPipe
+  module ConnSupport
+    # Error raised when trying to fetch an entry in {Conn}'s bag for
+    # an unknown key.
+    class KeyNotFoundInBagError < KeyError
+      # @param key [Any] Key not found in the bag
+      def initialize(key)
+        super(
+          <<~eos
+            Bag does not contain a key with name +key+.
+          eos
+        )
+      end
+    end
+  end
+end

data/lib/web_pipe/conn_support/headers.rb

@@ -0,0 +1,97 @@
+module WebPipe
+  module ConnSupport
+    # Helpers to work with headers and its rack's env representation.
+    #
+    # @private
+    module Headers
+      # Headers which come as plain CGI-like variables (without the `HTTP_`
+      # prefixed) from the rack server.
+      HEADERS_AS_CGI = %w[CONTENT_TYPE CONTENT_LENGTH].freeze
+
+      # Extracts headers from rack's env.
+      #
+      # Headers are all those pairs which key begins with `HTTP_` plus
+      # those detailed in {HEADERS_AS_CGI}.
+      # 
+      # @param env [Types::Env[]]
+      #
+      # @return [Types::Headers[]]
+      #
+      # @see HEADERS_AS_CGI
+      # @see .normalize_key
+      def self.extract(env)
+        Hash[
+          env.
+            select { |k, _v| k.start_with?('HTTP_') }.
+            map { |k, v| pair(k[5 .. -1], v) }.
+            concat(
+              env.
+                select { |k, _v| HEADERS_AS_CGI.include?(k) }.
+                map { |k, v| pair(k, v) }
+            )
+        ]
+      end
+
+      # Adds key/value pair to given headers.
+      #
+      # Key is normalized.
+      #
+      # @param headers [Type::Headers[]]
+      # @param key [String]
+      # @param value [String]
+      #
+      # @return [Type::Headers[]]
+      #
+      # @see .normalize_key
+      def self.add(headers, key, value)
+        Hash[
+          headers.to_a.push(pair(key, value))
+        ]
+      end
+
+      # Deletes pair with given key form headers.
+      #
+      # Accepts a non normalized key.
+      #
+      # @param headers [Type::Headers[]]
+      # @param key [String]
+      #
+      # @return [Type::Headers[]]
+      #
+      # @see .normalize_key
+      def self.delete(headers, key)
+        headers.reject { |k, _v| normalize_key(key) == k }
+      end
+
+      # Creates a pair with normalized key and raw value.
+      #
+      # @param key [String]
+      # @param key [String]
+      #
+      # @return [Array<String>]
+      #
+      # @see .normalize_key
+      def self.pair(key, value)
+        [normalize_key(key), value]
+      end
+
+      # Normalizes a header key to convention.
+      #
+      # As per RFC2616, headers names are case insensitive. This
+      # function normalizes them to PascalCase acting on dashes ('-').
+      #
+      # When a rack server maps headers to CGI-like variables, both
+      # dashes and underscores (`_`) are treated as dashes. This
+      # function substitutes all '-' to '_'.
+      #
+      # @param key [String]
+      #
+      # @return [String]
+      #
+      # @see https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2
+      def self.normalize_key(key)
+        key.downcase.gsub('_', '-').split('-').map(&:capitalize).join('-')
+      end
+    end
+  end
+end

data/lib/web_pipe/conn_support/types.rb

@@ -0,0 +1,50 @@
+require 'dry/types'
+require 'rack/request'
+require 'web_pipe/types'
+
+module WebPipe
+  module ConnSupport
+    # Types used for {Conn} struct.
+    #
+    # Implementation self-describes them, but you can look at {Conn}
+    # attributes for documentation.
+    module Types
+      include Dry.Types()
+
+      Env = Strict::Hash
+      Request = Instance(::Rack::Request)
+
+      Scheme = Strict::Symbol.enum(:http, :https)
+      Method = Strict::Symbol.enum(
+        :get, :head, :post, :put, :delete, :connect, :options, :trace, :patch
+      )
+      Host = Strict::String
+      Ip = Strict::String.optional
+      Port = Strict::Integer
+      ScriptName = Strict::String
+      PathInfo = Strict::String
+      QueryString = Strict::String
+      RequestBody = WebPipe::Types.Contract(:gets, :each, :read, :rewind)
+
+      BaseUrl = Strict::String
+      Path = Strict::String
+      FullPath = Strict::String
+      Url = Strict::String
+      Params = Strict::Hash
+
+      Status = Strict::Integer.
+                 default(200).
+                 constrained(gteq: 100, lteq: 599)
+      ResponseBody = WebPipe::Types.Contract(:each).
+                       default([''].freeze)
+
+      Headers = Strict::Hash.
+                  map(Strict::String, Strict::String).
+                  default({}.freeze)
+
+      Bag = Strict::Hash.
+              map(Strict::Symbol, Strict::Any).
+              default({}.freeze)
+    end
+  end
+end

data/lib/web_pipe/dsl/builder.rb

@@ -0,0 +1,38 @@
+require 'dry/initializer'
+require 'web_pipe/dsl/class_context'
+require 'web_pipe/dsl/instance_methods'
+
+module WebPipe
+  module DSL
+    # When an instance of it is included in a module, the module
+    # extends a {ClassContext} instance and includes
+    # {InstanceMethods}.
+    #
+    # @private
+    class Builder < Module
+      # Container with nothing registered.
+      EMPTY_CONTAINER = {}.freeze
+      
+      # @!attribute [r] container
+      # @return [Types::Container[]]
+
+
+      include Dry::Initializer.define -> do
+        option :container, type: Types::Container, default: proc { EMPTY_CONTAINER }
+      end
+
+      # @return [ClassContext]
+      attr_reader :class_context
+
+      def initialize(*args)
+        super
+        @class_context = ClassContext.new(container: container)
+      end
+      
+      def included(klass)
+        klass.extend(class_context)
+        klass.include(InstanceMethods)
+      end
+    end
+  end
+end

data/lib/web_pipe/dsl/class_context.rb

@@ -0,0 +1,62 @@
+require 'dry-initializer'
+require 'web_pipe/types'
+require 'web_pipe/dsl/dsl_context'
+
+module WebPipe
+  module DSL
+    # Defines the DSL and keeps the state for the pipe.
+    #
+    # This is good to be an instance because it keeps the
+    # configuration (state) for the pipe class: the container
+    # configured on initialization and both rack middlewares and plugs
+    # added through the DSL {DSLContext}.
+    #
+    # As the pipe is extended with an instance of this class, methods
+    # that are meant to be class methods in the pipe are defined as
+    # singleton methods of the instance.
+    #
+    # @private
+    class ClassContext < Module
+      # Methods to be imported from the {DSLContext}.
+      DSL_METHODS = %i[middlewares use plugs plug].freeze
+
+      # @!attribute [r] container
+      # @return [Types::Container[]]
+
+
+      include Dry::Initializer.define -> do
+        option :container, type: Types::Container
+      end
+
+      # @return [DSLContext]
+      attr_reader :dsl_context
+
+      def initialize(*args)
+        super
+        @dsl_context = DSLContext.new([], [])
+        define_container
+        define_dsl
+      end
+      
+      private
+
+      def define_container
+        module_exec(container) do |container|
+          define_method(:container) do
+            container
+          end
+        end
+      end
+
+      def define_dsl
+        DSL_METHODS.each do |method|
+          module_exec(dsl_context) do |dsl_context|
+            define_method(method) do |*args|
+              dsl_context.method(method).(*args)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/web_pipe/dsl/dsl_context.rb

@@ -0,0 +1,53 @@
+require 'dry/initializer'
+require 'web_pipe/types'
+require 'web_pipe/plug'
+require 'web_pipe/rack/middleware'
+
+module WebPipe
+  module DSL
+    # Defines the DSL for the pipe class and keeps it state.
+    #
+    # This allows adding rack middlewares and plugs at the class
+    # definition level.
+    #
+    # @private
+    class DSLContext
+      # @!attribute middlewares
+      # @return [Array<Rack::Middleware>]
+
+      # @!attribute plugs
+      # @return [Array<Plug>]
+
+
+      include Dry::Initializer.define -> do
+        param :middlewares,
+              type: Types.Array(Rack::Middleware::Instance)
+
+        param :plugs,
+              type: Types.Array(Plug::Instance)
+      end
+
+      # Creates and add a rack middleware to the stack.
+      #
+      # @param middleware
+      # [WebPipe::Rack::Middleware::MiddlewareClass[]] Rack middleware
+      # @param middleware [WebPipe::Rack::Options[]] Options to
+      # initialize
+      #
+      # @return [Array<Rack::Middleware>]
+      def use(middleware, *options)
+        middlewares << Rack::Middleware.new(middleware, options)
+      end
+
+      # Creates and adds a plug to the stack.
+      #
+      # @param name [Plug::Name[]]
+      # @param with [Plug::Spec[]]
+      #
+      # @return [Array<Plug>]
+      def plug(name, with: nil)
+        plugs << Plug.new(name, with)
+      end
+    end
+  end
+end

data/lib/web_pipe/dsl/instance_methods.rb

@@ -0,0 +1,60 @@
+require 'dry/initializer'
+require 'web_pipe/types'
+require 'web_pipe/conn'
+require 'web_pipe/app'
+require 'web_pipe/plug'
+require 'web_pipe/rack/app_with_middlewares'
+
+module WebPipe
+  module DSL
+    # Instance methods for the pipe.
+    #
+    # It is from here that you get the rack application you can route
+    # to. The initialization phase gives you the chance to inject any
+    # of the plugs, while the instance you get has the `#call` method
+    # expected by rack.
+    #
+    # The pipe state can be accessed through the pipe class, which
+    # has been configured through {ClassContext}.
+    #
+    # @private
+    module InstanceMethods
+      # No injections at all.
+      EMPTY_INJECTIONS = {}.freeze
+
+      # Type for how plugs should be injected.
+      Injections = Types::Strict::Hash.map(Plug::Name, Plug::Spec)
+
+      # @!attribute [r] injections [Injections[]]
+      #   Injected plugs that allow overriding what has been configured.
+
+
+      include Dry::Initializer.define -> do
+        param :injections,
+              default: proc { EMPTY_INJECTIONS },
+              type: Injections
+      end
+
+      # @return [Rack::AppWithMiddlewares]
+      attr_reader :rack_app
+
+      def initialize(*args)
+        super
+        middlewares = self.class.middlewares
+        container = self.class.container
+        operations = Plug.inject_and_resolve(self.class.plugs, injections, container, self)
+        app = App.new(operations)
+        @rack_app = Rack::AppWithMiddlewares.new(middlewares, app)
+      end
+      
+      # Expected interface for rack.
+      #
+      # @param env [Hash] Rack env
+      #
+      # @return [Array] Rack response
+      def call(env)
+        rack_app.call(env)
+      end
+    end
+  end
+end

data/lib/web_pipe/plug.rb

@@ -0,0 +1,103 @@
+require 'dry/initializer'
+require 'web_pipe/types'
+require 'web_pipe/app'
+
+module WebPipe
+  # A plug is a specification to resolve a callable object.
+  #
+  # It is initialized with a {Name} and a {Spec} and, on resolution
+  # time, is called with a {Types::Container} and an {Object} to act
+  # in the following fashion:
+  #
+  # - When the spec responds to `#call`, it is returned itself as the
+  # callable object.
+  # - When the spec is `nil`, then a {Proc} wrapping a method with the
+  # plug name in `object` is returned.
+  # - Otherwise, spec is taken as the key to resolve the operation
+  # from the `container`.
+  #
+  # @private
+  class Plug
+    # Error raised when no operation can be resolved from a {Spec}.
+    class InvalidPlugError < ArgumentError
+      # @param name [Any] Name for the plug that can't be resolved
+      def initialize(name)
+        super(
+          <<~eos
+            Plug with name +#{name}+ is invalid. It must be something
+            callable, an instance method when `with:` is not given, or
+            something callable registered in the container."
+          eos
+        )
+      end
+    end
+
+    # Type for the name of a plug.
+    Name = Types::Strict::Symbol.constructor(&:to_sym)
+
+    # Type for the spec to resolve and {App::Operation} on a
+    # {Conn} used by {Plug}.
+    Spec = App::Operation | Types.Constant(nil) | Types::Strict::String | Types::Strict::Symbol
+
+    # Type for an instance of self.
+    Instance = Types.Instance(self)
+
+    # @!attribute [r] name
+    #   @return [Name[]]
+
+    # @!attribute [r] spec
+    #   @return [Spec[]]
+
+
+    include Dry::Initializer.define -> do
+      param :name, Name
+
+      param :spec, Spec
+    end
+
+    # Creates a new instance with given `spec` but keeping `name`.
+    #
+    # @param new_spec [Spec[]]
+    # @return [self]
+    def with(new_spec)
+      self.class.new(name, new_spec)
+    end
+
+    # Resolves the operation.
+    #
+    # @param container [Types::Container[]]
+    # @param object [Object]
+    #
+    # @return [Operation[]]
+    # @raise [InvalidPlugError] When nothing callable is resolved.
+    def call(container, pipe)
+      if spec.respond_to?(:call)
+        spec
+      elsif spec.nil?
+        pipe.method(name)
+      elsif container[spec] && container[spec].respond_to?(:call)
+        container[spec]
+      else
+        raise InvalidPlugError.new(name)
+      end
+    end
+
+    # Change `plugs` spec's present in `injections` and resolves.
+    #
+    # @param plugs [Array<Plug>]
+    # @param injections [InstanceMethods::Injections[]]
+    # @container container [Types::Container[]]
+    # @object [Object]
+    #
+    # @return [Array<Operation[]>]
+    def self.inject_and_resolve(plugs, injections, container, object)
+      plugs.map do |plug|
+        if injections.has_key?(plug.name)
+          plug.with(injections[plug.name])
+        else
+          plug
+        end.(container, object)
+      end
+    end
+  end
+end