web_pipe 0.15.1 → 0.16.0

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(

data/lib/web_pipe/extensions/dry_schema/dry_schema.rb

@@ -4,63 +4,9 @@ require 'web_pipe'
 
 WebPipe.load_extensions(:params)
 
-#:nodoc:
+# :nodoc:
 module WebPipe
-  # Integration with `dry-schema` validation library.
-  #
-  # This extension provides a simple integration with `dry-schema`
-  # library to streamline param sanitization.
-  #
-  # On its own, the library just provides with a
-  # `Conn#sanitized_params` method, which will return what is set into
-  # config's `:sanitized_params` key.
-  #
-  # This key in config is what will be populated by `SanitizeParams` plug. It
-  # takes as arguments the `dry-schema` schema that will be applied to
-  # `Conn#params` and an error handler taking `Conn` instance and the validation
-  # result:
-  #
-  # @example
-  #  require 'web_pipe'
-  #
-  #  WebPipe.load_extensions(:dry_schema)
-  #
-  #  class App
-  #    include WebPipe
-  #
-  #    Schema = Dry::Schema.Params do
-  #      required(:name).filled(:string)
-  #    end
-  #
-  #    plug :sanitize_params, WebPipe::Plugs::SanitizeParams.(
-  #      Schema,
-  #      ->(conn, result) { ... }
-  #    )
-  #    plug(:do_something_with_params) do |conn|
-  #      DB.persist(:entity, conn.sanitized_params)
-  #    end
-  #  end
-  #
-  # A common workflow is applying the same handler for all param
-  # sanitization across your application. This can be achieved configuring
-  # a `:param_sanitization_handler` in a upstream operation which can
-  # be composed downstream from any number of pipes. `SanitizeParams`
-  # will used configured handler if none is injected as
-  # argument.
-  #
-  # @example
-  #  class App
-  #    plug :sanitization_handler, ->(conn, result) { ... }
-  #  end
-  #
-  #  class Subapp
-  #    Schema = Dry::Schema.Params { ... }
-  #
-  #    plug :app, App.new
-  #    plug :sanitize_params, WebPipe::Plugs::SanitizeParams.call(Schema)
-  #  end
-  #
-  # @see https://dry-rb.org/gems/dry-schema/
+  # See the docs for the extension linked from the README.
   module DrySchema
     SANITIZED_PARAMS_KEY = :sanitized_params
 

data/lib/web_pipe/extensions/flash/flash.rb

@@ -3,39 +3,9 @@
 require 'web_pipe/conn'
 require 'web_pipe/conn_support/errors'
 
-#:nodoc:
+# :nodoc:
 module WebPipe
-  # Provides with a typical flash messages functionality.
-  #
-  # @example
-  #   require 'web_pipe'
-  #   require 'rack/session/cookie'
-  #   require 'rack-flash'
-  #
-  #   WebPipe.load_extensions(:flash)
-  #
-  #   class MyApp
-  #     include WebPipe
-  #
-  #     use :session, Rack::Session::Cookie, secret: 'secret'
-  #     use :flash, Rack::Flash
-  #
-  #     plug :add_to_flash, ->(conn) { conn.add_flash(:notice, 'Hello world') }
-  #     plug :add_to_flash_now, ->(conn) { conn.add_flash_now(:notice_now, 'Hello world now') }
-  #   end
-  #
-  # Usually, you will end up making `conn.flash` available to your view system:
-  #
-  # @example
-  #   <div class="notice"><%= flash[:notice] %></div>
-  #
-  # For this extension to be used, `Rack::Flash` middleware must be
-  # added to the stack (gem name is `rack-flash3`. This middleware in
-  # turns depend on `Rack::Session` middleware.
-  #
-  # This extension is a very simple wrapper around `Rack::Flash` API.
-  #
-  # @see https://github.com/nakajima/rack-flash
+  # See the docs for the extension linked from the README.
   module Flash
     RACK_FLASH_KEY = 'x-rack.flash'
 

data/lib/web_pipe/extensions/hanami_view/hanami_view.rb

@@ -4,100 +4,9 @@ require 'web_pipe/types'
 require 'web_pipe/conn'
 require 'hanami/view'
 
-#:nodoc:
+# :nodoc:
 module WebPipe
-  # Integration with `hanami-view` rendering system.
-  #
-  # This extensions adds a {#view} method to {WebPipe::Conn} which
-  # sets the string output of a `hanami-view` view as response body.
-  #
-  # @example
-  #   WebPipe.load_extensions(:hanami_view)
-  #
-  #   class SayHelloView < Hanami::View
-  #     config.paths = [File.join(__dir__, '..', 'templates')]
-  #     config.template = 'say_hello'
-  #
-  #     expose :name
-  #   end
-  #
-  #   class App
-  #     include WebPipe
-  #
-  #     plug :render
-  #
-  #     def render(conn)
-  #       conn.view(SayHello.new, name: 'Joe')
-  #     end
-  #   end
-  #
-  # If there is a `:container` configured (in {Conn#config}), the view
-  # instance can be resolved from it.
-  #
-  # @example
-  #   WebPipe.load_extensions(:hanami_view, :container)
-  #
-  #   class App
-  #     include WebPipe
-  #
-  #     Container = { 'views.say_hello' => SayHelloView.new }.freeze
-  #
-  #     plug :config_container, ->(conn) { conn.add_config(:container, Container) }
-  #     plug :render
-  #
-  #     def render(conn)
-  #       conn.view('views.say_hello', name: 'Joe')
-  #     end
-  #  end
-  #
-  # Context ({Hanami::View::Context}) for the view can be set explicetly
-  # through the `context:` argument, as in a standard call to
-  # {Hanami::View#call}. However, it is possible to leverage configured
-  # default context while still being able to inject request specific
-  # context. For that to work, `:view_context` should be present in
-  # {WebPipe::Conn#config}. Its value must be a lambda accepting the
-  # {Conn} instance and returning a hash, which will be passed to
-  # {Hanami::View::Context#with} to create the final context at the
-  # moment {#view} is called.
-  #
-  # @example
-  #   class MyContext < Hanami::View::Context
-  #     attr_reader :current_path
-  #
-  #     def initialize(current_path: nil, **options)
-  #       @current_path = current_path
-  #       super
-  #     end
-  #   end
-  #
-  #   class SayHelloView < Hanami::View
-  #     config.paths = [File.join(__dir__, '..', 'templates')]
-  #     config.template = 'say_hello'
-  #     config.default_context = MyContext.new
-  #
-  #     expose :name
-  #   end
-  #
-  #   WebPipe.load_extensions(:url)
-  #
-  #   class App
-  #     include WebPipe
-  #
-  #     plug :config_view_context
-  #     plug :render
-  #
-  #     def config_view_context(conn)
-  #       conn.add_config(:view_context, ->(conn) {  { current_path: conn.full_path } })
-  #     end
-  #
-  #     def render(conn)
-  #       conn.view(SayHelloView.new, name: 'Joe') # `current_path`
-  #       # will be available in the view scope
-  #     end
-  #   end
-  #
-  # @see https://github.com/hanami/view
-  # @see WebPipe::Container
+  # See the docs for the extension linked from the README.
   module DryView
     # Where to find in {#config} request's view context generator.
     VIEW_CONTEXT_KEY = :view_context