web_pipe 0.15.1 → 0.16.0

data/lib/web_pipe/plug.rb

@@ -5,118 +5,73 @@ 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 [Hash<Name[], ConnSupport::Composition::Operation[]>]
-    def self.inject_and_resolve(plugs, injections, container, object)
-      Hash[
-        plugs.map do |plug|
-          inject_and_resolve_plug(plug, injections, container, object)
-        end
-      ]
+    def self.inject(plugs, injections)
+      plugs.map do |plug|
+        inject_plug(plug, injections)
+      end
     end
 
-    def self.inject_and_resolve_plug(plug, injections, container, object)
+    def self.inject_plug(plug, injections)
       name = plug.name
-      [
-        name,
-        if injections.key?(name)
-          plug.with(injections[name])
-        else
-          plug
-        end.call(container, object)
-      ]
+      if injections.key?(name)
+        plug.with(injections[name])
+      else
+        plug
+      end
     end
-    private_class_method :inject_and_resolve_plug
   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,83 +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 [Hash<Name[], Array<RackSupport::Middleware>]
-      def self.inject_and_resolve(middleware_specifications, injections)
-        Hash[
-          middleware_specifications.map do |middleware_spec|
-            inject_and_resolve_middleware(middleware_spec, injections)
-          end
-        ]
+      def self.inject(middleware_specifications, injections)
+        middleware_specifications.map do |middleware_spec|
+          inject_middleware(middleware_spec, injections)
+        end
       end
 
-      def self.inject_and_resolve_middleware(middleware_spec, injections)
+      def self.inject_middleware(middleware_spec, injections)
         name = middleware_spec.name
-        [
-          name,
-          if injections.key?(name)
-            middleware_spec.with(injections[name])
-          else
-            middleware_spec
-          end.call
-        ]
+        if injections.key?(name)
+          middleware_spec.with(injections[name])
+        else
+          middleware_spec
+        end
       end
-      private_class_method :inject_and_resolve_middleware
 
-      # 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.values
-        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/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.15.1'
+  VERSION = '0.16.0'
 end

data/lib/web_pipe.rb

@@ -1,23 +1,83 @@
 # frozen_string_literal: true
 
+require 'dry/core/extensions'
 require 'web_pipe/dsl/builder'
 
-# See [the
-# README](https://github.com/waiting-for-dev/web_pipe/blob/master/README.md)
-# for a general overview of this library.
+# Entry-point for the DSL layer.
+#
+# Including this module into your class adds to it a DSL layer which makes it
+# convenient to interact with an instance of {WebPipe::Pipe} transparently. It
+# means that the DSL is actually an optional layer, and you can achieve
+# everything by using {WebPipe::Pipe} instances.
+#
+# Your class gets access to {WebPipe::DSL::ClassContext::DSL_METHODS} at the
+# class level, while {WebPipe::DSL::InstanceContext::PIPE_METHODS} are available
+# for every instance of it. Both groups of methods are delegating to
+# {WebPipe::Pipe}, so you can look there for documentation.
+#
+# @example
+#   class HelloWorld
+#     include WebPipe
+#
+#     use :runtime, Rack::Runtime
+#
+#     plug :content_type do |conn|
+#       conn.add_response_header('Content-Type', 'plain/text')
+#     end
+#
+#     plug :render do |conn|
+#       conn.set_response_body('Hello, World!')
+#     end
+#   end
+#
+# The instance of your class is itself the final rack application. When you
+# initialize it, you have the chance to inject different plugs or middlewares
+# from those defined at the class level.
+#
+# @example
+#   HelloWorld.new(
+#     middlewares: {
+#       runtime: [Class.new do
+#         def initialize(app)
+#           @app = app
+#         end
+#
+#         def call(env)
+#           status, headers, body = @app.call(env)
+#           [status, headers.merge('Injected' => '1'), body]
+#         end
+#       end]
+#     },
+#     plugs: {
+#       render: ->(conn) { conn.set_response_body('Injected!') }
+#     }
+#   )
 module WebPipe
   extend Dry::Core::Extensions
 
-  # Including just delegates to an instance of `Builder`, so
-  # `Builder#included` is finally called.
+  # Called via {Module#include}, makes available web_pipe's DSL.
+  #
+  # Includes an instance of `Builder`. That means that `Builder#included` is
+  # eventually called.
   def self.included(klass)
     klass.include(call)
   end
 
+  # Chained to {Module#include} to make the DSL available and provide options.
+  #
+  # @param container [#[]] Container from where resolve operations. See
+  # {WebPipe::Plug}.
+  #
+  # @example
+  #   include WebPipe.call(container: Container)
   def self.call(**opts)
     DSL::Builder.new(**opts)
   end
 
+  register_extension :container do
+    require 'web_pipe/extensions/container/container'
+  end
+
   register_extension :cookies do
     require 'web_pipe/extensions/cookies/cookies'
   end
@@ -27,24 +87,16 @@ module WebPipe
     require 'web_pipe/extensions/dry_schema/plugs/sanitize_params'
   end
 
-  register_extension :hanami_view do
-    require 'web_pipe/extensions/hanami_view/hanami_view'
-  end
-
-  register_extension :container do
-    require 'web_pipe/extensions/container/container'
-  end
-
   register_extension :flash do
     require 'web_pipe/extensions/flash/flash'
   end
 
-  register_extension :router_params do
-    require 'web_pipe/extensions/router_params/router_params'
+  register_extension :hanami_view do
+    require 'web_pipe/extensions/hanami_view/hanami_view'
   end
 
-  register_extension :redirect do
-    require 'web_pipe/extensions/redirect/redirect'
+  register_extension :not_found do
+    require 'web_pipe/extensions/not_found/not_found'
   end
 
   register_extension :params do
@@ -55,6 +107,14 @@ module WebPipe
     require 'web_pipe/extensions/rails/rails'
   end
 
+  register_extension :redirect do
+    require 'web_pipe/extensions/redirect/redirect'
+  end
+
+  register_extension :router_params do
+    require 'web_pipe/extensions/router_params/router_params'
+  end
+
   register_extension :session do
     require 'web_pipe/extensions/session/session'
   end
@@ -62,8 +122,4 @@ module WebPipe
   register_extension :url do
     require 'web_pipe/extensions/url/url'
   end
-
-  register_extension :not_found do
-    require 'web_pipe/extensions/not_found/not_found'
-  end
 end

data/web_pipe.gemspec

@@ -12,6 +12,7 @@ Gem::Specification.new do |spec|
 
   spec.summary       = 'Rack application builder through a pipe of operations on an immutable struct.'
   spec.homepage      = 'https://github.com/waiting-for-dev/web_pipe'
+  spec.licenses      = ['MIT']
 
   # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
   # to allow pushing to a single host or delete this section to allow pushing to any host.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: web_pipe
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.16.0
 platform: ruby
 authors:
 - Marc Busqué
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-09-19 00:00:00.000000000 Z
+date: 2021-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-monads
@@ -295,7 +295,7 @@ files:
 - docs/plugs.md
 - docs/plugs/config.md
 - docs/plugs/content_type.md
-- docs/recipes/dry_rb_integration.md
+- docs/recipes/hanami_2_and_dry_rb_integration.md
 - docs/recipes/hanami_router_integration.md
 - docs/recipes/using_all_restful_methods.md
 - docs/testing.md
@@ -313,8 +313,7 @@ files:
 - lib/web_pipe/conn_support/types.rb
 - lib/web_pipe/dsl/builder.rb
 - lib/web_pipe/dsl/class_context.rb
-- lib/web_pipe/dsl/dsl_context.rb
-- lib/web_pipe/dsl/instance_methods.rb
+- lib/web_pipe/dsl/instance_context.rb
 - lib/web_pipe/extensions/container/container.rb
 - lib/web_pipe/extensions/cookies/cookies.rb
 - lib/web_pipe/extensions/dry_schema/dry_schema.rb
@@ -329,6 +328,7 @@ files:
 - lib/web_pipe/extensions/router_params/router_params.rb
 - lib/web_pipe/extensions/session/session.rb
 - lib/web_pipe/extensions/url/url.rb
+- lib/web_pipe/pipe.rb
 - lib/web_pipe/plug.rb
 - lib/web_pipe/plugs.rb
 - lib/web_pipe/plugs/config.rb
@@ -341,7 +341,8 @@ files:
 - lib/web_pipe/version.rb
 - web_pipe.gemspec
 homepage: https://github.com/waiting-for-dev/web_pipe
-licenses: []
+licenses:
+- MIT
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/waiting-for-dev/web_pipe

data/docs/recipes/dry_rb_integration.md

@@ -1,17 +0,0 @@
-# dry-rb integration
-
-`web_pipe` has been designed to integrate smoothly with
-[dry-rb](https://dry-rb.org/) ecosystem. It shares same design
-principles and it ships with some extensions which even make this
-integration tighter (like [`:dry-schema`](../extensions/dry_schema.md)
-extension).
-
-If you want to use `web_pipe` with the rest of dry-rb libraries,
-your best bet is to use
-[`dry-web-web_pipe`](https://github.com/waiting-for-dev/dry-web-web_pipe)
-skeleton generator. It is a fork of
-[`dry-web-roda`](https://github.com/dry-rb/dry-web-roda) with
-`roda` dependency switched to a combination of `web_pipe` and
-[`hanami-router`](https://github.com/hanami/router).
-
-Look at `dry-web-web_pipe` README for more details.

data/lib/web_pipe/dsl/dsl_context.rb

@@ -1,85 +0,0 @@
-# frozen_string_literal: true
-
-require 'web_pipe'
-require 'web_pipe/types'
-require 'web_pipe/plug'
-require 'web_pipe/rack_support/middleware_specification'
-
-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.
-    #
-    # @api private
-    class DSLContext
-      # @!attribute middleware_specifications
-      # @return [Array<RackSupport::MiddlewareSpecifications>]
-      attr_reader :middleware_specifications
-
-      # @!attribute plugs
-      # @return [Array<Plug>]
-      attr_reader :plugs
-
-      def initialize(middleware_specifications, plugs)
-        @middleware_specifications = Types.Array(
-          RackSupport::MiddlewareSpecification
-        )[middleware_specifications]
-        @plugs = Types.Array(Plug::Instance)[plugs]
-      end
-
-      # Creates and add rack middleware specifications to the stack.
-      #
-      # 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 instance, in which case all its rack
-      # middlewares will be considered.
-      #
-      # @param name [RackSupport::MiddlewareSpecification::Name[]]
-      # @param spec [RackSupport::MiddlewareSpecification::Spec[]]
-      #
-      # @return [Array<RackSupport::Middleware>]
-      def use(name, *spec)
-        middleware_specifications << RackSupport::MiddlewareSpecification.new(name: name, spec: spec)
-      end
-
-      # Creates and adds a plug to the stack.
-      #
-      # The spec can be given as a {Plug::Spec}, as a block (which
-      # is captured into a {Proc}, one of the options for a
-      # {Plug::Spec} or as a {WebPipe} (in which case all its plugs
-      # will be composed).
-      #
-      # @param name [Plug::Name[]]
-      # @param spec [Plug::Spec[], WebPipe]
-      # @param block_spec [Proc]
-      #
-      # @return [Array<Plug>]
-      def plug(name, spec = nil, &block_spec)
-        plug_spec = if spec.is_a?(WebPipe)
-                      spec.to_proc
-                    elsif spec
-                      spec
-                    else
-                      block_spec
-                    end
-
-        plugs << Plug.new(name: name, spec: plug_spec)
-      end
-
-      # Adds middlewares and plugs from a WebPipe to respective
-      # stacks.
-      #
-      # @param name [Plug::Name[], Middleware::Name[]]
-      # @param spec [WebPipe]
-      def compose(name, spec)
-        use(name, spec)
-        plug(name, spec)
-      end
-    end
-  end
-end