web_pipe 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d89f930070f399bae4f6949b4f62b61d2fcb6f8716e9527baa350cf673daa4a6
-  data.tar.gz: a7942d96afa3110e68dd55591a56b780d39a61c6e5b22cff5087a628b5997a6e
+  metadata.gz: 2f0e9b6d0efd9e7280bd1628237d3219f1307a28d63ec0d8f0e63366ce93e166
+  data.tar.gz: 407269e3f023e97a84855fe315ca3558ccf49a2b0cb78674336274fb1ae2c800
 SHA512:
-  metadata.gz: 9a5b905649927d6bbba53540583f9429ef862aa0ee764087f037f3b490e32c87d3d24cbd30980267d7a7bd89735d23c9a3965c21938fa50d326f7a794eab6c6b
-  data.tar.gz: 19c1b7ec4247cfe48cde66b0c74eee6978f905759f943b77d0b93d315e2cc603759a4ae5afc7282945255093d4fd746e4101e62834067b10853aaa9f69e3d254
+  metadata.gz: a2bf1652e9c88e4dcd708b95fc573d1daffeea2f3d56fd908598eb447c1819912c2ac53a35eecf0a5315d4e1195b9c412c34e5a58fb70cf3c5cfa36da602aa45
+  data.tar.gz: 386e1da635847bc21ab2eee5203babda8020fb89f8a11be51e2718bf844e34405ccdb60f4e537d3d3e7afb3d62264f32add6be94711420f490e2f02c3420c9be

data/CHANGELOG.md

@@ -4,6 +4,70 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/) 
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [0.3.0] - 2019-07-12
+### Added
+- **BREAKING**: When plugging with `plug:`, the operation is no longer specified through `with:`. Now it is just the second positional argument ([9](https://github.com/waiting-for-dev/web_pipe/pull/9)):
+
+```ruby
+plug :from_container, 'container'
+plug :inline, ->(conn) { conn.set_response_body('Hello world') }
+```
+- It is possible to plug a block ([9](https://github.com/waiting-for-dev/web_pipe/pull/9)):
+```ruby
+  plug(:content_type) { |conn| conn.add_response_header('Content-Type', 'text/html') }
+```
+
+- WebPipe plug's can be composed. A WebPipe proc representation is the composition of all its operations, which is an operation itself ([9](https://github.com/waiting-for-dev/web_pipe/pull/9)):
+
+```ruby
+class HtmlApp
+  include WebPipe
+
+  plug :content_type
+  plug :default_status
+
+  private
+
+  def content_type(conn)
+    conn.add_response_header('Content-Type', 'text/html')
+  end
+
+  def default_status(conn)
+    conn.set_status(404)
+  end
+end
+
+class App
+  include WebPipe
+
+  plug :html, &HtmlApp.new
+  plug :body
+
+  private
+
+  def body(conn)
+     conn.set_response_body('Hello, world!')
+  end
+end
+```
+
+- WebPipe's middlewares can be composed into another WebPipe class, also through `:use`:
+
+```ruby
+class HtmlApp
+  include WebPipe
+
+  use Rack::Session::Cookie, key: 'key', secret: 'top_secret'
+  use Rack::MethodOverride
+end
+
+class App
+  include WebPipe
+
+  use HtmlApp
+end
+```
+
 ## [0.2.0] - 2019-07-05
 ### Added
 - dry-view integration ([#1](https://github.com/waiting-for-dev/web_pipe/pull/1), [#3](https://github.com/waiting-for-dev/web_pipe/pull/3), [#4](https://github.com/waiting-for-dev/web_pipe/pull/4), [#5](https://github.com/waiting-for-dev/web_pipe/pull/5) and  [#6](https://github.com/waiting-for-dev/web_pipe/pull/6))
@@ -15,4 +79,4 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [0.1.0] - 2019-05-07
 ### Added
-- Initial release.
+- Initial release.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    web_pipe (0.1.0)
+    web_pipe (0.2.0)
       dry-initializer (~> 3.0)
       dry-monads (~> 1.2)
       dry-struct (~> 1.0)

data/README.md

@@ -180,20 +180,52 @@ class App
 
 #### Proc (or anything responding to `#call`)
 
-Operations can also be defined inline, through the `with:` keyword, as
-anything that responds to `#call`, like a `Proc`:
+Operations can also be defined inline as anything that responds to
+`#call`, like a `Proc`, or also like a block:
 
 ```ruby
 class App
   include WebPipe
 
-  plug :hello, with: ->(conn) { conn }
+  plug :hello, ->(conn) { conn }
+  plug(:hello2) { |conn| conn }
+end
+```
+
+The representation of a `WebPipe` as a Proc is itself an operation
+accepting a `Conn` and returning a `Conn`: the composition of all its
+plugs. Therefore, it can be plugged to any other `WebPipe`:
+
+```ruby
+class HtmlApp
+  include WebPipe
+
+  plug :html
+
+  private
+
+  def html(conn)
+    conn.add_response_header('Content-Type', 'text/html')
+  end
+end
+
+class App
+  include WebPipe
+
+  plug :html, &HtmlApp.new
+  plug :body
+
+  private
+
+  def body(conn)
+     conn.set_response_body('Hello, world!')
+  end
 end
 ```
 
 #### Container
 
-When `with:` is a `String` or a `Symbol`, it can be used as the key to
+When a `String` or a `Symbol` is given, it can be used as the key to
 resolve an operation from a container. A container is just anything
 responding to `#[]`.
 
@@ -207,7 +239,7 @@ class App
 
   include WebPipe.(container: Container)
 
-  plug :hello, with: 'plugs.hello'
+  plug :hello, 'plugs.hello'
 end
 ```
 
@@ -220,7 +252,7 @@ overriding those configured through `plug`:
 class App
   include WebPipe
 
-  plug :hello, with: ->(conn) { conn.set_response_body('Hello') }
+  plug :hello, ->(conn) { conn.set_response_body('Hello') }
 end
 
 run App.new(
@@ -243,7 +275,20 @@ class App
   use Middleware1
   use Middleware2, option_1: value_1
 
-  plug :hello, with: ->(conn) { conn }
+  plug :hello, ->(conn) { conn }
+end
+```
+
+It is also possible to compose all the middlewares from another pipe
+class. Extending from previous example:
+
+```ruby
+class App2
+  include WebPipe
+
+  use App # it will also use Middleware1 and Middleware2
+
+  plug :hello, ->(conn) { conn }
 end
 ```
 

data/lib/web_pipe/app.rb

@@ -1,11 +1,8 @@
 require 'dry/initializer'
-require 'dry/monads/result'
 require 'web_pipe/types'
 require 'web_pipe/conn'
 require 'web_pipe/conn_support/builder'
-require 'dry/monads/result/extensions/either'
-
-Dry::Monads::Result.load_extensions(:either)
+require 'web_pipe/conn_support/composition'
 
 module WebPipe
   # Rack application built around applying a pipe of {Operation} to
@@ -26,41 +23,24 @@ module WebPipe
   # whenever the stack is emptied or a {Conn::Dirty} is
   # returned in any of the steps.
   class App
-    # Type for an operation.
-    #
-    # It should be anything callable expecting a {Conn} and
-    # returning a {Conn}.
-    Operation = Types.Interface(:call)
-
     # Type for a rack environment.
     RackEnv = Types::Strict::Hash
 
-    # Error raised when an {Operation} returns something that is not a
-    # {Conn}.
-    class InvalidOperationResult < RuntimeError
-      # @param returned [Any] What was returned from the {Operation}
-      def initialize(returned)
-        super(
-          <<~eos
-            An operation returned +#{returned.inspect}+. To be valid,
-            an operation must return whether a
-            WebPipe::Conn::Clean or a WebPipe::Conn::Dirty.
-          eos
-        )
-      end
-    end
-
     include Dry::Monads::Result::Mixin
 
     include Dry::Initializer.define -> do
       # @!attribute [r] operations
       #   @return [Array<Operation[]>]
-      param :operations, type: Types.Array(Operation)
+      param :operations, type: Types.Array(
+              ConnSupport::Composition::Operation
+            )
     end
 
     # @param env [Hash] Rack env
     #
     # @return env [Array] Rack response
+    # @raise ConnSupport::Composition::InvalidOperationResult when an
+    # operation does not return a {Conn}
     def call(env)
       extract_rack_response(
         apply_operations(
@@ -74,33 +54,15 @@ module WebPipe
     private
 
     def conn_from_env(env)
-      Success(
-        ConnSupport::Builder.(env)
-      )
+      ConnSupport::Builder.(env)
     end
 
     def apply_operations(conn)
-      operations.reduce(conn) do |new_conn, operation|
-        new_conn.bind { |c| apply_operation(c, operation) }
-      end
-    end
-
-    def apply_operation(conn, operation)
-      result = operation.(conn)
-      case result
-      when Conn::Clean
-        Success(result)
-      when Conn::Dirty
-        Failure(result)
-      else
-        raise InvalidOperationResult.new(result)
-      end
+      ConnSupport::Composition.new(operations).call(conn)
     end
 
     def extract_rack_response(conn)
-      extract_proc = :rack_response.to_proc
-
-      conn.either(extract_proc, extract_proc)
+      conn.rack_response
     end
   end
 end

data/lib/web_pipe/conn_support/composition.rb

@@ -0,0 +1,89 @@
+require 'dry/initializer'
+require 'dry/monads/result'
+require 'web_pipe/types'
+require 'web_pipe/conn'
+require 'dry/monads/result/extensions/either'
+
+Dry::Monads::Result.load_extensions(:either)
+
+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::Clean} or a {Conn::Dirty}. On execution time,
+    # the composition is stopped whenever the stack is emptied or a
+    # {Conn::Dirty} is returned in any of the steps.
+    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}.
+      class InvalidOperationResult < RuntimeError
+        # @param returned [Any] What was returned from the {Operation}
+        def initialize(returned)
+          super(
+            <<~eos
+            An operation returned +#{returned.inspect}+. To be valid,
+            an operation must return whether a
+            WebPipe::Conn::Clean or a WebPipe::Conn::Dirty.
+          eos
+          )
+        end
+      end
+
+      include Dry::Monads::Result::Mixin
+
+      include Dry::Initializer.define -> do
+        # @!attribute [r] operations
+        #   @return [Array<Operation[]>]
+        param :operations, type: Types.Array(Operation)
+      end
+
+      # @param conn [Conn]
+      # @return [Conn]
+      # @raise InvalidOperationResult when an operation does not
+      # return a {Conn}
+      def call(conn)
+        extract_result(
+          apply_operations(
+            conn
+          )
+        )
+      end
+
+      private
+
+      def apply_operations(conn)
+        operations.reduce(Success(conn)) do |new_conn, operation|
+          new_conn.bind { |c| apply_operation(c, operation) }
+        end
+      end
+
+      def apply_operation(conn, operation)
+        result = operation.(conn)
+        case result
+        when Conn::Clean
+          Success(result)
+        when Conn::Dirty
+          Failure(result)
+        else
+          raise InvalidOperationResult.new(result)
+        end
+      end
+
+      def extract_result(result)
+        extract_proc = :itself.to_proc
+
+        result.either(extract_proc, extract_proc)
+      end
+    end
+  end
+end

data/lib/web_pipe/dsl/class_context.rb

@@ -51,8 +51,8 @@ module WebPipe
       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)
+            define_method(method) do |*args, &block|
+              dsl_context.method(method).(*args, &block)
             end
           end
         end

data/lib/web_pipe/dsl/dsl_context.rb

@@ -2,6 +2,7 @@ require 'dry/initializer'
 require 'web_pipe/types'
 require 'web_pipe/plug'
 require 'web_pipe/rack/middleware'
+require 'web_pipe/rack/middleware_specification'
 
 module WebPipe
   module DSL
@@ -21,32 +22,42 @@ module WebPipe
 
       include Dry::Initializer.define -> do
         param :middlewares,
-              type: Types.Array(Rack::Middleware::Instance)
+              type: Types.Array(Rack::Middleware)
 
         param :plugs,
               type: Types.Array(Plug::Instance)
       end
 
-      # Creates and add a rack middleware to the stack.
+      # Creates and add rack middlewares to the stack.
       #
-      # @param middleware
-      # [WebPipe::Rack::Middleware::MiddlewareClass[]] Rack middleware
-      # @param middleware [WebPipe::Rack::Options[]] Options to
-      # initialize
+      # The spec can be given in two forms:
+      #
+      # - As one or two arguments, first one being a
+      # {::Rack::Middleware} class and second one optionally its
+      # initialization options.
+      # - As a {WebPipe} class, in which case all its rack middlewares
+      # will be added to the stack in order.
+      #
+      # @param spec [Rack::MiddlewareSpecification::Spec[]]
       #
       # @return [Array<Rack::Middleware>]
-      def use(middleware, *options)
-        middlewares << Rack::Middleware.new(middleware, options)
+      def use(*spec)
+        middlewares.push(*Rack::MiddlewareSpecification.call(spec))
       end
 
       # Creates and adds a plug to the stack.
       #
+      # The spec can be given as a {Plug::Spec} or as a block, which
+      # is captured into a {Proc} (one of the options for a
+      # {Plug::Spec}.
+      #
       # @param name [Plug::Name[]]
-      # @param with [Plug::Spec[]]
+      # @param spec [Plug::Spec[]]
+      # @param block_spec [Proc]
       #
       # @return [Array<Plug>]
-      def plug(name, with: nil)
-        plugs << Plug.new(name, with)
+      def plug(name, spec = nil, &block_spec)
+        plugs << Plug.new(name, spec || block_spec)
       end
     end
   end

data/lib/web_pipe/dsl/instance_methods.rb

@@ -4,6 +4,7 @@ require 'web_pipe/conn'
 require 'web_pipe/app'
 require 'web_pipe/plug'
 require 'web_pipe/rack/app_with_middlewares'
+require 'web_pipe/conn_support/composition'
 
 module WebPipe
   module DSL
@@ -35,14 +36,17 @@ module WebPipe
               type: Injections
       end
 
-      # @return [Rack::AppWithMiddlewares]
+      # @return [Rack::AppWithMiddlewares[]]
       attr_reader :rack_app
 
+      # @return [ConnSupport::Composition::Operation[]]
+      attr_reader :operations
+
       def initialize(*args)
         super
         middlewares = self.class.middlewares
         container = self.class.container
-        operations = Plug.inject_and_resolve(self.class.plugs, injections, container, self)
+        @operations = Plug.inject_and_resolve(self.class.plugs, injections, container, self)
         app = App.new(operations)
         @rack_app = Rack::AppWithMiddlewares.new(middlewares, app)
       end
@@ -55,6 +59,44 @@ module WebPipe
       def call(env)
         rack_app.call(env)
       end
+
+      # Proc for the composition of all operations.
+      #
+      # This can be used to plug a {WebPipe} itself as an operation.
+      #
+      # @example
+      #   class HtmlApp
+      #     include WebPipe
+      #
+      #     plug :html
+      #
+      #     private
+      #
+      #     def html(conn)
+      #       conn.add_response_header('Content-Type', 'text/html')
+      #     end
+      #   end
+      #
+      #   class App
+      #     include WebPipe
+      #
+      #     plug :html, &HtmlApp.new
+      #     plug :body
+      #
+      #     private
+      #
+      #     def body(conn)
+      #        conn.set_response_body('Hello, world!')
+      #     end
+      #   end
+      #
+      # @see ConnSupport::Composition
+      def to_proc
+        ConnSupport::Composition.
+          new(operations).
+          method(:call).
+          to_proc
+      end
     end
   end
 end

data/lib/web_pipe/extensions/dry_view/dry_view.rb

@@ -38,7 +38,7 @@ module WebPipe
   #
   #     Container = { 'views.say_hello' => SayHelloView.new }.freeze
   #
-  #     plug :container, with: WebPipe::Plugs::Container[Container]
+  #     plug :container, WebPipe::Plugs::Container[Container]
   #     plug :render
   #
   #     def render(conn)

data/lib/web_pipe/extensions/dry_view/plugs/view_context.rb

@@ -17,7 +17,7 @@ module WebPipe
     #
     #     ViewContext = (conn) -> { { current_path: conn.full_path } }
     #
-    #     plug :view_context, with: WebPipe::Plugs::ViewContext[ViewContext]
+    #     plug :view_context, WebPipe::Plugs::ViewContext[ViewContext]
     #     plug :render
     #
     #     def render

data/lib/web_pipe/plug.rb

@@ -1,6 +1,6 @@
 require 'dry/initializer'
 require 'web_pipe/types'
-require 'web_pipe/app'
+require 'web_pipe/conn_support/composition'
 
 module WebPipe
   # A plug is a specification to resolve a callable object.
@@ -25,8 +25,8 @@ module WebPipe
         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."
+            callable, an instance method when no operation is given,
+            or something callable registered in the container."
           eos
         )
       end
@@ -35,9 +35,13 @@ module WebPipe
     # 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 the spec to resolve and
+    # {ConnSupport::Composition::Operation} on a {Conn} used by
+    # {Plug}.
+    Spec = ConnSupport::Composition::Operation |
+           Types.Constant(nil) |
+           Types::Strict::String |
+           Types::Strict::Symbol
 
     # Type for an instance of self.
     Instance = Types.Instance(self)
@@ -68,7 +72,7 @@ module WebPipe
     # @param container [Types::Container[]]
     # @param object [Object]
     #
-    # @return [Operation[]]
+    # @return [ConnSupport::Composition::Operation[]]
     # @raise [InvalidPlugError] When nothing callable is resolved.
     def call(container, pipe)
       if spec.respond_to?(:call)
@@ -89,7 +93,7 @@ module WebPipe
     # @container container [Types::Container[]]
     # @object [Object]
     #
-    # @return [Array<Operation[]>]
+    # @return [Array<ConnSupport::Composition::Operation[]>]
     def self.inject_and_resolve(plugs, injections, container, object)
       plugs.map do |plug|
         if injections.has_key?(plug.name)

data/lib/web_pipe/plugs/container.rb

@@ -13,7 +13,7 @@ module WebPipe
     #
     #     Cont = { name: SomeDependency.new }.freeze
     #
-    #     plug :container, with: WebPipe::Plugs::Container[Cont]
+    #     plug :container, WebPipe::Plugs::Container[Cont]
     #     plug :resolve
     #
     #     private

data/lib/web_pipe/plugs/content_type.rb

@@ -10,7 +10,7 @@ module WebPipe
     #   class App
     #     include WebPipe
     #
-    #     plug :html, with: WebPipe::Plugs::ContentType['text/html']
+    #     plug :html, WebPipe::Plugs::ContentType['text/html']
     #   end
     module ContentType
       # Content-Type header

data/lib/web_pipe/rack/app_with_middlewares.rb

@@ -24,7 +24,7 @@ module WebPipe
 
       include Dry::Initializer.define -> do
         param :rack_middlewares,
-              type: Types.Array(Middleware::Instance)
+              type: Types.Array(Middleware)
 
         param :app, type: App
       end
@@ -51,7 +51,7 @@ module WebPipe
       def build_rack_app(rack_middlewares, app)
         ::Rack::Builder.new.tap do |b|
           rack_middlewares.each do |middleware|
-            b.use(middleware.middleware, *middleware.middleware_options)
+            b.use(middleware.middleware, *middleware.options)
           end
           b.run(app)
         end

data/lib/web_pipe/rack/middleware.rb

@@ -1,14 +1,14 @@
 require 'dry/initializer'
 require 'web_pipe/types'
+require 'dry/struct'
 
 module WebPipe
   module Rack
     # Simple data structure to represent a rack middleware class with
     # its initialization options.
-    class Middleware
-      # Type for an instance of self.
-      Instance = Types.Instance(self)
-
+    #
+    # @api private
+    class Middleware < Dry::Struct
       # Type for a rack middleware class.
       MiddlewareClass = Types.Instance(Class)
 
@@ -17,17 +17,11 @@ module WebPipe
 
       # @!attribute [r] middleware
       #   @return [MiddlewareClass[]] Rack middleware
+      attribute :middleware, MiddlewareClass
 
       # @!attribute [r] options
-      # @return [Options[]]
-      # Options to initialize the rack middleware
-
-
-      include Dry::Initializer.define -> do
-        param :middleware, type: MiddlewareClass
-
-        param :middleware_options, type: Options
-      end
+      # @return [Options[]] Options to initialize the rack middleware
+      attribute :options, Options
     end
   end
 end

data/lib/web_pipe/rack/middleware_specification.rb

@@ -0,0 +1,33 @@
+require 'web_pipe/rack/middleware'
+require 'web_pipe/types'
+
+module WebPipe
+  module Rack
+    # 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 a class including
+    # {WebPipe}. This specifies all {Rack::Middlewares} configured
+    # for that {WebPipe}.
+    #
+    # @api private
+    module MiddlewareSpecification
+      # Resolves {Rack::Middlewares} from given specification.
+      #
+      # @param spec [Array]
+      # @return [Array<Rack::Middleware>]
+      def self.call(spec)
+        klass = spec[0]
+        options = spec[1..-1] || Types::EMPTY_ARRAY
+        if klass.included_modules.include?(WebPipe)
+          klass.middlewares
+        elsif klass.is_a?(Class)
+          [Middleware.new(middleware: klass, options: options)]
+        end
+      end
+    end
+  end
+end

data/lib/web_pipe/version.rb

@@ -1,3 +1,3 @@
 module WebPipe
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: web_pipe
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Marc Busqué
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-05 00:00:00.000000000 Z
+date: 2019-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -221,6 +221,7 @@ files:
 - lib/web_pipe/app.rb
 - lib/web_pipe/conn.rb
 - lib/web_pipe/conn_support/builder.rb
+- lib/web_pipe/conn_support/composition.rb
 - lib/web_pipe/conn_support/errors.rb
 - lib/web_pipe/conn_support/headers.rb
 - lib/web_pipe/conn_support/types.rb
@@ -236,6 +237,7 @@ files:
 - lib/web_pipe/plugs/content_type.rb
 - lib/web_pipe/rack/app_with_middlewares.rb
 - lib/web_pipe/rack/middleware.rb
+- lib/web_pipe/rack/middleware_specification.rb
 - lib/web_pipe/types.rb
 - lib/web_pipe/version.rb
 - web_pipe.gemspec