web_pipe 0.13.0 → 0.16.0

data/docs/using_rack_middlewares/injecting_middlewares.md

@@ -1,19 +1,19 @@
 # Injecting middlewares
 
-Middlewares can be injected at the moment an application is initialized,
+You can inject middlewares at the moment an application is initialized,
 allowing you to override what you have defined in the DSL.
 
-For that purpose, you have to use `middlewares:` keyword argument. It must be a
+For that purpose, you have to use the `middlewares:` keyword argument. It must be a
 hash where middlewares are matched by the name you gave them in its definition.
 
-A middleware must be specified as an `Array`. First item must be a rack
-middleware class. The rest of arguments (if any) should be any option it may
+A middleware must be specified as an `Array`. The first item must be a rack
+middleware class. The rest of the arguments (if any) should be any options it may
 need.
 
-This is mainly useful for testing purposes, where you can switch a heavy
+That is mainly useful for testing purposes, where you can switch a heavy
 middleware and use a mocked one instead.
 
-In the following example, rack session mechanism is being mocked:
+In the following example, we mock the rack session mechanism:
 
 ```ruby
 # config.ru

data/docs/using_rack_middlewares/inspecting_middlewares.md

@@ -0,0 +1,35 @@
+# Inspecting middlewares
+
+Once a `WebPipe` class is initialized, all its middlewares get resolved. You
+can access them through the `#middlewares` method.
+
+Each middleware is represented by a
+`WebPipe::RackSupport::MiddlewareSpecification` instance, which contains two
+accessors: `middleware` returns the middleware class. In contrast, `options`
+returns an array with the arguments provided to the middleware on
+initialization.
+
+Keep in mind that every middleware is resolved as an array. That is because it
+can be composed by a chain of middlewares built through
+[composition](composing_middlewares.md).
+
+
+```ruby
+require 'web_pipe'
+require 'rack/session'
+
+class MyApp
+  include WebPipe
+  
+  use :session, Rack::Session::Cookie, key: 'my_app.session', secret: 'long'
+
+  plug(:hello) do |conn|
+    conn.set_response_body('Hello world!')
+  end
+end
+
+app = MyApp.new
+session_middleware = app.middlewares[:session][0]
+session_middleware.middleware # => Rack::Session::Cookie
+session_middleware.options # => [{ key: 'my_app.session', secret: 'long' }]
+```

data/docs/using_rack_middlewares.md

@@ -1,16 +1,16 @@
 # Using rack middlewares
 
 A one-way pipe like the one `web_pipe` implements can deal with any required
-feature in a web application. However, usually it is convenient to be able to
-use some well-known rack middleware so you don't have to reinvent the wheel.
-Even if you can add them at the router layer, `web_pipe` allows you to
-encapsulate them in your application definition.
+feature in a web application. However, usually, it is convenient to use some
+well-known rack middleware, so you don't have to reinvent the wheel.  Even if
+you can add them to the router layer, `web_pipe` allows you to encapsulate them
+in your application definition.
 
-In order to add rack middlewares to the stack, you have to use the DSL method
+To add rack middlewares to the stack, you have to use the DSL method
 `use`. The first argument it takes is a `Symbol` with the name you want to
 assign to it (which is needed to allow
 [injection](using_rack_middlewares/injecting_middlewares.md) on
-initialization). Then, it must follow the middleware class and any option it
+initialization). Then, it must follow the middleware class and any options it
 may need:
 
 ```ruby

data/lib/web_pipe/app.rb

@@ -1,54 +1,51 @@
 # frozen_string_literal: true
 
-require 'web_pipe/types'
 require 'web_pipe/conn'
 require 'web_pipe/conn_support/builder'
 require 'web_pipe/conn_support/composition'
 
 module WebPipe
-  # Rack application built around applying a pipe of {Operation} to
-  # a {Conn}.
+  # Rack app built from a chain of functions that take and return a
+  # {WebPipe::Conn}.
   #
-  # A rack application is something callable accepting rack's `env`
-  # as argument and returning a rack response. So, the workflow
-  # followed to build it is:
+  # This is the abstraction encompassing a rack application built only with the
+  # functions on {WebPipe::Conn}. {WebPipe::RackSupport::AppWithMiddlewares}
+  # takes middlewares also into account.
   #
-  # - Take rack's `env` and create a {Conn} from here.
-  # - Starting from it, apply the pipe of operations (anything
-  # callable accepting a {Conn} and returning a {Conn}).
-  # - Convert last {Conn} back to a rack response and
-  # return it.
+  # A rack application is something callable that takes the rack environment as
+  # an argument, and returns a rack response. So, this class needs to:
   #
-  # {Conn} can itself be of two different types (subclasses of it}:
-  # {Conn::Ongoing} and {Conn::Halted}. The pipe is stopped
-  # whenever the stack is emptied or a {Conn::Halted} is
-  # returned in any of the steps.
+  # - Take rack's environment and create a {WebPipe::Conn} struct from there.
+  # - Starting from the initial struct, apply the pipe of functions.
+  # - Convert the last {WebPipe::Conn} back to a rack response.
+  #
+  # {WebPipe::Conn} can itself be of two different types (subclasses of it}:
+  # {Conn::Ongoing} and {Conn::Halted}. The pipe is stopped on two scenarios:
+  #
+  # - The end of the pipe is reached.
+  # - One function returns a {Conn::Halted}.
   class App
-    # Type for a rack environment.
-    RackEnv = Types::Strict::Hash
-
     include Dry::Monads::Result::Mixin
 
     # @!attribute [r] operations
-    #   @return [Array<Operation[]>]
+    #   @return [Array<Proc>]
     attr_reader :operations
 
+    # @param operations [Array<Proc>]
     def initialize(operations)
-      @operations = Types.Array(
-        ConnSupport::Composition::Operation
-      )[operations]
+      @operations = operations
     end
 
-    # @param env [Hash] Rack env
+    # @param env [Hash] Rack environment
     #
     # @return env [Array] Rack response
     # @raise ConnSupport::Composition::InvalidOperationResult when an
-    # operation does not return a {Conn}
+    # operation doesn't return a {WebPipe::Conn}
     def call(env)
       extract_rack_response(
         apply_operations(
           conn_from_env(
-            RackEnv[env]
+            env
           )
         )
       )

data/lib/web_pipe/conn.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'dry/struct'
-require 'web_pipe/types'
 require 'web_pipe/conn_support/types'
 require 'web_pipe/conn_support/errors'
 require 'web_pipe/conn_support/headers'

data/lib/web_pipe/conn_support/builder.rb

@@ -6,15 +6,8 @@ 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::Ongoing} subclass.
-    #
     # @api private
     module Builder
-      # @param env [Types::Env] Rack's env
-      #
-      # @return [Conn::Ongoing]
       # rubocop:disable Metrics/MethodLength
       def self.call(env)
         rr = Rack::Request.new(env)

data/lib/web_pipe/conn_support/composition.rb

@@ -1,31 +1,14 @@
 # frozen_string_literal: true
 
 require 'dry/monads/result'
-require 'web_pipe/types'
 require 'web_pipe/conn'
 
 module WebPipe
   module ConnSupport
-    # Composition of a pipe of {Operation} on a {Conn}.
-    #
-    # It represents the composition of a series of functions which
-    # take a {Conn} as argument and return a {Conn}.
-    #
-    # However, {Conn} can itself be of two different types (subclasses
-    # of it): a {Conn::Ongoing} or a {Conn::Halted}. On execution time,
-    # the composition is stopped whenever the stack is emptied or a
-    # {Conn::Halted} is returned in any of the steps.
+    # @api private
     class Composition
-      # Type for an operation.
-      #
-      # It should be anything callable expecting a {Conn} and
-      # returning a {Conn}.
-      Operation = Types.Interface(:call)
-
-      # Error raised when an {Operation} returns something that is not
-      # a {Conn}.
+      # Raised when operation doesn't return a {WebPipe::Conn}.
       class InvalidOperationResult < RuntimeError
-        # @param returned [Any] What was returned from the {Operation}
         def initialize(returned)
           super(
             <<~MSG
@@ -39,18 +22,12 @@ module WebPipe
 
       include Dry::Monads::Result::Mixin
 
-      # @!attribute [r] operations
-      #   @return [Array<Operation[]>]
       attr_reader :operations
 
       def initialize(operations)
-        @operations = Types.Array(Operation)[operations]
+        @operations = operations
       end
 
-      # @param conn [Conn]
-      # @return [Conn]
-      # @raise InvalidOperationResult when an operation does not
-      # return a {Conn}
       def call(conn)
         extract_result(
           apply_operations(

data/lib/web_pipe/conn_support/errors.rb

@@ -2,7 +2,7 @@
 
 module WebPipe
   module ConnSupport
-    # Error raised when trying to fetch an entry in {Conn#bag} for an
+    # Error raised when trying to fetch an entry in {WebPipe::Conn#bag} for an
     # unknown key.
     class KeyNotFoundInBagError < KeyError
       # @param key [Any] Key not found in the bag
@@ -15,8 +15,8 @@ module WebPipe
       end
     end
 
-    # Error raised when trying to fetch an entry in {Conn#config} for
-    # an unknown key.
+    # Error raised when trying to fetch an entry in {WebPipeConn#config} for an
+    # unknown key.
     class KeyNotFoundInConfigError < KeyError
       # @param key [Any] Key not found in config
       def initialize(key)
@@ -28,8 +28,8 @@ module WebPipe
       end
     end
 
-    # Error raised when trying to use a conn's feature which requires
-    # a rack middleware which is not present
+    # Error raised when trying to use a {WebPipe::Conn} feature which requires a
+    # rack middleware that is not present
     class MissingMiddlewareError < RuntimeError
       # @param feature [String] Name of the feature intended to be used
       # @param middleware [String] Name of the missing middleware

data/lib/web_pipe/conn_support/headers.rb

@@ -2,25 +2,14 @@
 
 module WebPipe
   module ConnSupport
-    # Helpers to work with headers and its rack's env representation.
-    #
     # @api 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
@@ -34,51 +23,20 @@ module WebPipe
         ]
       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 ('-').
       #
@@ -86,18 +44,11 @@ module WebPipe
       # 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
+      # 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
 
-      # Returns a new hash with all keys normalized.
-      #
-      # @see #normalize_key
       def self.normalize(headers)
         headers.transform_keys { |k| normalize_key(k) }
       end

data/lib/web_pipe/conn_support/types.rb

@@ -5,10 +5,10 @@ require 'rack/request'
 
 module WebPipe
   module ConnSupport
-    # Types used for {Conn} struct.
+    # Types used in the {WebPipe::Conn} struct.
     #
-    # Implementation self-describes them, but you can look at {Conn}
-    # attributes for documentation.
+    # The implementation self-describes them, but you can look at the
+    # {WebPipe::Conn} attributes for documentation.
     module Types
       include Dry.Types()
 

data/lib/web_pipe/dsl/builder.rb

@@ -1,36 +1,27 @@
 # frozen_string_literal: true
 
-require 'web_pipe/types'
 require 'web_pipe/dsl/class_context'
-require 'web_pipe/dsl/instance_methods'
+require 'web_pipe/dsl/instance_context'
+require 'web_pipe/pipe'
 
 module WebPipe
   module DSL
-    # When an instance of it is included in a module, the module
-    # extends a {ClassContext} instance and includes
-    # {InstanceMethods}.
-    #
     # @api private
     class Builder < Module
-      # Container with nothing registered.
-      EMPTY_CONTAINER = Types::EMPTY_HASH
+      attr_reader :class_context, :instance_context
 
-      # @!attribute [r] container
-      # @return [Types::Container[]]
-      attr_reader :container
-
-      # @return [ClassContext]
-      attr_reader :class_context
-
-      def initialize(container: EMPTY_CONTAINER)
-        @container = Types::Container[container]
-        @class_context = ClassContext.new(container: container)
+      def initialize(container: Pipe::EMPTY_CONTAINER)
+        @class_context = ClassContext.new
+        @instance_context = InstanceContext.new(
+          class_context: class_context,
+          container: container
+        )
         super()
       end
 
       def included(klass)
         klass.extend(class_context)
-        klass.include(InstanceMethods)
+        klass.include(instance_context)
       end
     end
   end

data/lib/web_pipe/dsl/class_context.rb

@@ -1,57 +1,32 @@
 # frozen_string_literal: true
 
-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.
-    #
     # @api private
     class ClassContext < Module
-      # Methods to be imported from the {DSLContext}.
-      DSL_METHODS = %i[middleware_specifications use plugs plug compose].freeze
+      DSL_METHODS = %i[use plug compose].freeze
 
-      # @!attribute [r] container
-      # @return [Types::Container[]]
-      attr_reader :container
+      attr_reader :ast
 
-      # @return [DSLContext]
-      attr_reader :dsl_context
+      def initialize
+        @ast = []
+        super
+      end
 
-      def initialize(container:)
-        @container = Types::Container[container]
-        @dsl_context = DSLContext.new([], [])
-        define_container
-        define_dsl
-        super()
+      def extended(klass)
+        define_dsl_methods(klass, ast)
       end
 
       private
 
-      def define_container
-        module_exec(container) do |container|
-          define_method(:container) do
-            container
-          end
-        end
-      end
-
-      def define_dsl
+      def define_dsl_methods(klass, ast)
         DSL_METHODS.each do |method|
-          module_exec(dsl_context) do |dsl_context|
-            define_method(method) do |*args, &block|
-              dsl_context.method(method).call(*args, &block)
-            end
+          klass.define_singleton_method(method) do |*args, **kwargs, &block|
+            ast << if block_given?
+                     [method, args, kwargs, block]
+                   else
+                     [method, args, kwargs]
+                   end
           end
         end
       end

data/lib/web_pipe/dsl/instance_context.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'web_pipe/pipe'
+
+module WebPipe
+  module DSL
+    # @api private
+    class InstanceContext < Module
+      PIPE_METHODS = %i[
+        call middlewares operations to_proc to_middlewares
+      ].freeze
+
+      attr_reader :container, :class_context
+
+      def initialize(container:, class_context:)
+        @container = container
+        @class_context = class_context
+        super()
+      end
+
+      def included(klass)
+        define_initialize(klass, class_context.ast, container)
+        define_pipe_methods(klass)
+      end
+
+      private
+
+      # rubocop:disable Metrics/MethodLength
+      def define_initialize(klass, ast, container)
+        klass.define_method(:initialize) do |plugs: {}, middlewares: {}|
+          acc = Pipe.new(container: container, context: self)
+          @pipe = ast.reduce(acc) do |pipe, node|
+            method, args, kwargs, block = node
+            if block
+              pipe.send(method, *args, **kwargs, &block)
+            else
+              pipe.send(method, *args, **kwargs)
+            end
+          end.inject(plugs: plugs, middleware_specifications: middlewares)
+        end
+        # rubocop:enable Metrics/MethodLength
+      end
+
+      def define_pipe_methods(klass)
+        PIPE_METHODS.each do |method|
+          klass.define_method(method) do |*args|
+            @pipe.send(method, *args)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/web_pipe/extensions/container/container.rb

@@ -2,22 +2,9 @@
 
 require 'web_pipe'
 
-#:nodoc:
+# :nodoc:
 module WebPipe
-  # Extension adding a `#container` method which returns {Conn#config}
-  # `:container` key.
-  #
-  # @example
-  #   require 'web_pipe'
-  #
-  #   WebPipe.load_extensions(:container)
-  #
-  #   class App
-  #     include WebPipe
-  #
-  #     plug :container, ->(conn) { conn.add_config(:container, MyContainer) }
-  #     plug :render, ->(conn) { conn.set_response_body(conn.container['view']) }
-  #   end
+  # See the docs for the extension linked from the README.
   module Container
     # Returns {Conn#config} `:container` value
     #

data/lib/web_pipe/extensions/cookies/cookies.rb

@@ -1,40 +1,11 @@
 # frozen_string_literal: true
 
 require 'web_pipe'
-require 'web_pipe/types'
 require 'rack/utils'
 
-#:nodoc:
+# :nodoc:
 module WebPipe
-  # Extension to help dealing with request and response cookies.
-  #
-  # This extension helps with the addition of the `Set-Cookie` header
-  # to the response, which is the way the server has to instruct the
-  # browser to keep a cookie. A cookie can be added with the
-  # {#set_cookie} method, while it can be marked for deletion with
-  # {#delete_cookie}. Remember that marking a cookie for deletion just
-  # means adding the same cookie name with an expiration time in the
-  # past.
-  #
-  # Besides, it also adds a {#request_cookies} method to get the
-  # cookies in the request.
-  #
-  # @example
-  #  require 'web_pipe'
-  #
-  #  WebPipe.load_extensions(:cookies)
-  #
-  #  class SetCookie
-  #    include WebPipe
-  #
-  #    plug :set_cookie, ->(conn) { conn.set_cookie('foo', 'bar', path: '/') }
-  #  end
-  #
-  #  class DeleteCookie
-  #    include WebPipe
-  #
-  #    plug :delete_cookie, ->(conn) { conn.delete_cookie('foo', path: '/') }
-  #  end
+  # See the docs for the extension linked from the README.
   module Cookies
     # Valid options for {#set_cookie}.
     SET_COOKIE_OPTIONS = Types::Strict::Hash.schema(