web_pipe 0.13.0 → 0.16.0

data/lib/web_pipe/pipe.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require 'web_pipe/conn_support/composition'
+require 'web_pipe/app'
+require 'web_pipe/plug'
+require 'web_pipe/rack_support/middleware_specification'
+require 'web_pipe/rack_support/app_with_middlewares'
+require 'web_pipe/types'
+
+module WebPipe
+  # Composable rack application builder.
+  #
+  # An instance of this class helps build rack applications that can compose.
+  # Besides the DSL, which only adds a convenience layer, this is the higher
+  # abstraction on the library.
+  #
+  # Applications are built by plugging functions that take and return a
+  # {WebPipe::Conn} instance. That's an immutable struct that contains all the
+  # request information alongside methods to build the response. See {#plug} for
+  # details.
+  #
+  # Middlewares can also be added to the resulting application thanks to {#use}.
+  #
+  # Be aware that instances of this class are immutable, so methods return new
+  # objects every time.
+  #
+  # The instance itself is the final rack application.
+  #
+  # @example
+  # # config.ru
+  # require 'web_pipe/pipe'
+  #
+  # app = WebPipe::Pipe.new
+  #                    .use(:runtime, Rack::Runtime)
+  #                    .plug(:content_type) do |conn|
+  #                      conn.add_response_header('Content-Type', 'text/plain')
+  #                    end
+  #                    .plug(:render) do |conn|
+  #                      conn.set_response_body('Hello, World!')
+  #                    end
+  #
+  # run app
+  class Pipe
+    # Container that resolves nothing
+    EMPTY_CONTAINER = {}.freeze
+
+    # @!attribute [r] container
+    #   Container from where resolve operations. See {#plug}.
+    attr_reader :container
+
+    # @!attribute [r] context
+    #   Object from where resolve operations. See {#plug}.
+    attr_reader :context
+
+    # @api private
+    EMPTY_PLUGS = [].freeze
+
+    # @api private
+    EMPTY_MIDDLEWARE_SPECIFICATIONS = [].freeze
+
+    # @api private
+    Container = Types.Interface(:[])
+
+    # @api private
+    attr_reader :plugs
+
+    # @api private
+    attr_reader :middleware_specifications
+
+    # @param container [#to_h] Container from where resolve plug's operations
+    # (see {#plug}).
+    # @param context [Any] Object from where resolve plug's operations (see
+    # {#plug})
+    def initialize(
+      container: EMPTY_CONTAINER,
+      context: nil,
+      plugs: EMPTY_PLUGS,
+      middleware_specifications: EMPTY_MIDDLEWARE_SPECIFICATIONS
+    )
+      @plugs = plugs
+      @middleware_specifications = middleware_specifications
+      @container = Container[container]
+      @context = context
+    end
+
+    # Names and adds a plug operation to the application.
+    #
+    # The operation can be provided in several ways:
+    #
+    # - Through the `spec` parameter as:
+    #   - Anything responding to `#call` (like a {Proc}).
+    #   - As a string or symbol key for something registered in {#container}.
+    #   - Anything responding to `#to_proc` (like another {WebPipe::Pipe}
+    #   instance or an instance of a class including {WebPipe}).
+    #   - As `nil` (default), meaning that the operation is a method in
+    #   {#context} matching the `name` parameter.
+    # - Through a block, if the `spec` parameter is `nil`.
+    #
+    # @param name [Symbol]
+    # @param spec [#call, #to_proc, String, Symbol, nil]
+    # @yieldparam [WebPipe::Conn]
+    #
+    # @return [WebPipe::Pipe] A fresh new instance with the added plug.
+    def plug(name, spec = nil, &block_spec)
+      with(
+        plugs: [
+          *plugs,
+          Plug.new(name: name, spec: spec || block_spec)
+        ]
+      )
+    end
+
+    # Names and adds a rack middleware to the final application.
+    #
+    # The middleware can be given in three forms:
+    #
+    # - As one or two arguments, the first one being a
+    # rack middleware class, and optionally a second one with its initialization
+    # options.
+    # - As something responding to `#to_middlewares` with an array of
+    # {WebPipe::RackSupport::Middleware} (like another {WebPipe::Pipe} instance
+    # or a class including {WebPipe}), case in which all middlewares are used.
+    #
+    # @overload use(name, middleware_class)
+    #   @param name [Symbol]
+    #   @param middleware_class [Class]
+    # @overload use(name, middleware_class, middleware_options)
+    #   @param name [Symbol]
+    #   @param middleware_class [Class]
+    #   @param middleware_options [Any]
+    # @overload use(name, to_middlewares)
+    #   @param name [Symbol]
+    #   @param middleware_class [#to_middlewares]
+    #
+    # @return [WebPipe::Pipe] A fresh new instance with the added middleware.
+    def use(name, *spec)
+      with(
+        middleware_specifications: [
+          *middleware_specifications,
+          RackSupport::MiddlewareSpecification.new(name: name, spec: spec)
+        ]
+      )
+    end
+
+    # Shortcut for {#plug} and {#use} a pipe at once.
+    #
+    # @param name [#to_sym]
+    # @param spec [#to_proc#to_middlewares]
+    def compose(name, spec)
+      use(name, spec)
+        .plug(name, spec)
+    end
+
+    # Operations {#plug}ged to the app, mapped by their names.
+    #
+    # @return [Hash{Symbol => Proc}]
+    def operations
+      @operations ||= Hash[
+        plugs.map { |plug| [plug.name, plug.call(container, context)] }
+      ]
+    end
+
+    # Middlewares {#use}d in the app, mapped by their names.
+    #
+    # Returns them wrapped within {WebPipe::RackSupport::Middleware} instances,
+    # from where you can access their classes and options.
+    #
+    # @return [Hash{Symbol=>Array<WebPipe::RackSupport::Middleware>}]
+    def middlewares
+      @middlewares ||= Hash[
+        middleware_specifications.map { |mw_spec| [mw_spec.name, mw_spec.call] }
+      ]
+    end
+
+    # @api private
+    def to_proc
+      ConnSupport::Composition
+        .new(operations.values)
+        .method(:call)
+    end
+
+    # @api private
+    def to_middlewares
+      middlewares.values.flatten
+    end
+
+    # @api private
+    def inject(plugs: {}, middleware_specifications: {})
+      res_mw_specs = RackSupport::MiddlewareSpecification.inject(
+        self.middleware_specifications, middleware_specifications
+      )
+      res_plugs = Plug.inject(
+        self.plugs, plugs
+      )
+      with(
+        plugs: res_plugs,
+        middleware_specifications: res_mw_specs
+      )
+    end
+
+    # @api private
+    def call(env)
+      rack_app.call(env)
+    end
+
+    private
+
+    def app
+      App.new(operations.values).freeze
+    end
+
+    def rack_app
+      RackSupport::AppWithMiddlewares.new(
+        to_middlewares,
+        app
+      ).freeze
+    end
+
+    def with(plugs: nil, middleware_specifications: nil)
+      self.class.new(
+        container: container,
+        context: context,
+        middleware_specifications: middleware_specifications ||
+                                     self.middleware_specifications,
+        plugs: plugs || self.plugs
+      )
+    end
+  end
+end

data/lib/web_pipe/plug.rb

@@ -5,106 +5,72 @@ require 'web_pipe/types'
 require 'web_pipe/conn_support/composition'
 
 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`.
-  #
   # @api private
   class Plug < Dry::Struct
-    # Error raised when no operation can be resolved from a {Spec}.
+    # Raised when the specification for an operation is invalid.
     class InvalidPlugError < ArgumentError
-      # @param name [Any] Name for the plug that can't be resolved
       def initialize(name)
         super(
           <<~MSG
-            Plug with name +#{name}+ is invalid. It must be something
-            callable, an instance method when no operation is given,
-            or something callable registered in the container."
+            Plug with name +#{name}+ can't be resolved. You must provide
+            something responding to `#call` or `#to_proc`, or a key for
+            something registered in the container obeying those exact
+            constraints. If nothing is given, it's expected to be a method
+            defined in the context object.
           MSG
         )
       end
     end
-
-    # Type for the name of a plug.
     Name = Types::Strict::Symbol.constructor(&:to_sym)
 
-    # Type for the spec to resolve and
-    # {ConnSupport::Composition::Operation} on a {Conn} used by
-    # {Plug}.
-    Spec = ConnSupport::Composition::Operation |
+    Spec = Types.Interface(:call) |
+           Types.Interface(:to_proc) |
            Types.Constant(nil) |
            Types::Strict::String |
            Types::Strict::Symbol
 
-    # Type for an instance of self.
-    Instance = Types.Instance(self)
-
-    # Schema expected to inject plugs.
-    #
-    # @see #inject_and_resolve
     Injections = Types::Strict::Hash.map(
-      Plug::Name, Plug::Spec
+      Name, Spec
     ).default(Types::EMPTY_HASH)
 
-    # @!attribute [r] name
-    #   @return [Name[]]
     attribute :name, Name
 
-    # @!attribute [r] spec
-    #   @return [Spec[]]
     attribute :spec, Spec
 
-    # Creates a new instance with given `spec` but keeping `name`.
-    #
-    # @param new_spec [Spec[]]
-    # @return [self]
     def with(new_spec)
       new(spec: new_spec)
     end
 
-    # Resolves the operation.
-    #
-    # @param container [Types::Container[]]
-    # @param object [Object]
-    #
-    # @return [ConnSupport::Composition::Operation[]]
-    # @raise [InvalidPlugError] When nothing callable is resolved.
-    def call(container, pipe)
-      if spec.respond_to?(:call)
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/AbcSize
+    def call(container, context)
+      if spec.respond_to?(:to_proc) && !spec.is_a?(Symbol)
+        spec.to_proc
+      elsif spec.respond_to?(:call)
         spec
       elsif spec.nil?
-        pipe.method(name)
-      elsif container[spec].respond_to?(:call)
-        container[spec]
+        context.method(name)
+      elsif container[spec]
+        with(container[spec]).call(container, context)
       else
         raise InvalidPlugError, name
       end
     end
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/AbcSize
 
-    # Change `plugs` spec's present in `injections` and resolves.
-    #
-    # @param plugs [Array<Plug>]
-    # @param injections [InstanceMethods::PlugInjections[]]
-    # @container container [Types::Container[]]
-    # @object [Object]
-    #
-    # @return [Array<ConnSupport::Composition::Operation[]>]
-    def self.inject_and_resolve(plugs, injections, container, object)
+    def self.inject(plugs, injections)
       plugs.map do |plug|
-        if injections.key?(plug.name)
-          plug.with(injections[plug.name])
-        else
-          plug
-        end.call(container, object)
+        inject_plug(plug, injections)
+      end
+    end
+
+    def self.inject_plug(plug, injections)
+      name = plug.name
+      if injections.key?(name)
+        plug.with(injections[name])
+      else
+        plug
       end
     end
   end

data/lib/web_pipe/plugs/config.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'web_pipe/types'
-
 module WebPipe
   module Plugs
     # Adds given pairs to {Conn#config}.

data/lib/web_pipe/plugs/content_type.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'web_pipe/types'
-
 module WebPipe
   module Plugs
     # Sets `Content-Type` response header.

data/lib/web_pipe/rack_support/app_with_middlewares.rb

@@ -1,43 +1,20 @@
 # frozen_string_literal: true
 
-require 'web_pipe/types'
 require 'web_pipe/rack_support/middleware'
 require 'rack'
 
 module WebPipe
   module RackSupport
-    # Helper to build and call a rack application with middlewares.
-    #
     # @api private
     class AppWithMiddlewares
-      # Type for a rack application.
-      #
-      # It should be something callable accepting a rack env and
-      # returning a rack response.
-      App = Types.Interface(:call)
-
-      # @!attribute [r] rack_middlewares
-      # @return [Array<RackMiddleware>]
-      attr_reader :rack_middlewares
-
-      # @!attribute [r] app
-      # @return [App[]]
-      attr_reader :app
-
-      # @return [Rack::Builder]
-      attr_reader :builder
+      attr_reader :rack_middlewares, :app, :builder
 
       def initialize(rack_middlewares, app)
-        @rack_middlewares = Types.Array(Middleware)[rack_middlewares]
-        @app = App[app]
+        @rack_middlewares = rack_middlewares
+        @app = app
         @builder = build_rack_app(rack_middlewares, app)
       end
 
-      # Calls rack application.
-      #
-      # @param env [Hash] Rack env
-      #
-      # @return [Array] Rack resonse
       def call(env)
         builder.call(env)
       end

data/lib/web_pipe/rack_support/middleware.rb

@@ -5,10 +5,10 @@ require 'dry/struct'
 
 module WebPipe
   module RackSupport
+    # Wrapper for a rack middleware.
+    #
     # Simple data structure to represent a rack middleware class with
     # its initialization options.
-    #
-    # @api private
     class Middleware < Dry::Struct
       # Type for a rack middleware class.
       MiddlewareClass = Types.Instance(Class)

data/lib/web_pipe/rack_support/middleware_specification.rb

@@ -6,74 +6,45 @@ require 'web_pipe/types'
 
 module WebPipe
   module RackSupport
-    # Specification on how to resolve {Rack::Middleware}'s.
-    #
-    # Rack middlewares can be specified in two ways:
-    #
-    # - As an array where fist element is a rack middleware class
-    # while the rest of elements are its initialization options.
-    # - A single element array where it is an instance of a class
-    # including {WebPipe}. This specifies all {RackSupport::Middlewares} for
-    # that {WebPipe}.
-    #
     # @api private
     class MiddlewareSpecification < Dry::Struct
-      # Type for the name given to a middleware.
       Name = Types::Strict::Symbol.constructor(&:to_sym)
 
-      # Poor type for the specification to resolve a rack middleware.
       Spec = Types::Strict::Array
 
-      # Schema expected to inject middleware specifications.
-      #
-      # @see #inject_and_resolve
       Injections = Types::Strict::Hash.map(
-        RackSupport::MiddlewareSpecification::Name, RackSupport::MiddlewareSpecification::Spec
+        Name, Spec
       ).default(Types::EMPTY_HASH)
 
-      # @!attribute [r] name
-      #   @return [Name[]]
       attribute :name, Name
 
-      # @!attribute [r] spec
-      #   @return [Spec[]]
       attribute :spec, Spec
 
-      # Change spec's present in `injections` and resolves.
-      #
-      # @param middleware_specifications [Array<MiddlewareSpecification>]
-      # @param injections [Injections[]]
-      #
-      # @return [Array<RackSupport::Middleware>]
-      def self.inject_and_resolve(middleware_specifications, injections)
-        middleware_specifications.map do |spec|
-          if injections.key?(spec.name)
-            spec.with(injections[spec.name])
-          else
-            spec
-          end.call
-        end.flatten
+      def self.inject(middleware_specifications, injections)
+        middleware_specifications.map do |middleware_spec|
+          inject_middleware(middleware_spec, injections)
+        end
+      end
+
+      def self.inject_middleware(middleware_spec, injections)
+        name = middleware_spec.name
+        if injections.key?(name)
+          middleware_spec.with(injections[name])
+        else
+          middleware_spec
+        end
       end
 
-      # Resolves {RackSupport::Middlewares} from given specification.
-      #
-      # @return [Array<RackSupport::Middleware>]
       def call
-        klass = spec[0]
+        klass_or_pipe = spec[0]
         options = spec[1..] || Types::EMPTY_ARRAY
-        case klass
-        when WebPipe
-          klass.middlewares
-        when Class
-          [Middleware.new(middleware: klass, options: options)]
+        if klass_or_pipe.respond_to?(:to_middlewares)
+          klass_or_pipe.to_middlewares
+        elsif klass_or_pipe.is_a?(Class)
+          [Middleware.new(middleware: klass_or_pipe, options: options)]
         end
       end
 
-      # Returns new instance with {#spec} replaced.
-      #
-      # @param new_spec [Spec[]]
-      #
-      # @return [MiddlewareSpecification]
       def with(new_spec)
         new(spec: new_spec)
       end

data/lib/web_pipe/test_support.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'web_pipe/conn_support/builder'
+require 'rack/mock'
+
+module WebPipe
+  # Test helper methods.
+  #
+  # This module is meant to be included in a test file to provide helper
+  # methods.
+  module TestSupport
+    # Builds a {WebPipe::Conn}
+    #
+    # @param uri [String] URI that will be used to populate the request
+    # attributes
+    # @param attributes [Hash<Symbol, Any>] Manually set attributes for the
+    # struct. It overrides what is taken from the `uri` parameter
+    # @param env_opts [Hash] Options to be added to the `env` from which the
+    # connection struct is created. See {Rack::MockRequest.env_for}.
+    # @return [Conn]
+    def build_conn(uri = '', attributes: {}, env_opts: {})
+      env = Rack::MockRequest.env_for(uri, env_opts)
+      ConnSupport::Builder
+        .call(env)
+        .new(attributes)
+    end
+  end
+end

data/lib/web_pipe/types.rb

@@ -4,11 +4,9 @@ require 'dry/types'
 require 'dry/core/constants'
 
 module WebPipe
-  # Namespace for generic library types.
+  # Namespace for generic types.
   module Types
     include Dry.Types()
     include Dry::Core::Constants
-
-    Container = Interface(:[])
   end
 end

data/lib/web_pipe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WebPipe
-  VERSION = '0.13.0'
+  VERSION = '0.16.0'
 end