web_pipe 0.15.1 → 0.16.0

data/lib/web_pipe/extensions/not_found/not_found.rb

@@ -1,46 +1,8 @@
 # frozen_string_literal: true
 
-#:nodoc:
+# :nodoc:
 module WebPipe
-  # Generates a not-found response
-  #
-  # This extension helps to build a not-found response in a single method
-  # invocation. The {#not_found} method will:
-  #
-  # - Set 404 as response status.
-  # - Set 'Not found' as the response body, or instead run a step configured in
-  # a `:not_found_body_step` config key.
-  # - Halt the connection struct.
-  #
-  # @example
-  #   require 'web_pipe'
-  #   require 'web_pipe/plugs/config'
-  #
-  #   WebPipe.load_extensions(:params, :not_found)
-  #
-  #   class ShowItem
-  #     include 'web_pipe'
-  #
-  #     plug :config, WebPipe::Plugs::Config.(
-  #       not_found_body_step: ->(conn) { conn.set_response_body('Nothing') }
-  #     )
-  #
-  #     plug :fetch_item do |conn|
-  #       conn.add(:item, Item[params['id']])
-  #     end
-  #
-  #     plug :check_item do |conn|
-  #       if conn.fetch(:item)
-  #         conn
-  #       else
-  #         conn.not_found
-  #       end
-  #     end
-  #
-  #     plug :render do |conn|
-  #       conn.set_response_body(conn.fetch(:item).name)
-  #     end
-  #   end
+  # See the docs for the extension linked from the README.
   module NotFound
     # @api private
     RESPONSE_BODY_STEP_CONFIG_KEY = :not_found_body_step

data/lib/web_pipe/extensions/params/params.rb

@@ -3,70 +3,9 @@
 require 'web_pipe/types'
 require 'web_pipe/extensions/params/params/transf'
 
-#:nodoc:
+# :nodoc:
 module WebPipe
-  # Adds a {Conn#params} method which can perform any number of
-  # transformations to the request parameters.
-  #
-  # When no transformations are given, {#params} just returns request
-  # parameters (both GET and POST) as a hash:
-  #
-  # @example
-  #   # http://www.example.com?foo=bar
-  #   conn.params #=> { 'foo' => 'bar' }
-  #
-  # Further processing can be specified thanks to `dry-transformer` gem (you
-  # need to add it yourself to the Gemfile). All hash transformations
-  # in `dry-transformer` are available:
-  #
-  # @example
-  #   # http://www.example.com?foo=bar
-  #   conn.params([:deep_symbolize_keys]) #=> { foo: 'bar' }
-  #
-  # Extra needed arguments can be provided as an array:
-  #
-  # @example
-  #   # http://www.example.com?foo=bar&zoo=zoo
-  #   conn.params([:deep_symbolize_keys, [:reject_keys, [:zoo]]) #=> { foo: 'bar' }
-  #
-  # Instead of injecting transformations at the moment `#params` is
-  # called, you can configure them to be automatically used.
-  #
-  # @example
-  #   # http://www.example.com?foo=bar
-  #   conn.
-  #     add_config(:param_transformations, [:deep_symbolize_keys]).
-  #     params #=> { foo: 'bar' }
-  #
-  # You can register your own transformation functions:
-  #
-  # @example
-  #   # http://www.example.com?foo=bar
-  #   fake = ->(_params) { { fake: :params } }
-  #   WebPipe::Params::Transf.register(:fake, fake)
-  #   conn.params([:fake]) #=> { fake: :params }
-  #
-  # Your own transformation functions can depend on the {Conn}
-  # instance at the moment of execution. For that, just place it as the
-  # last argument of the function and it will be curried automatically:
-  #
-  # @example
-  #   # http://www.example.com?foo=bar
-  #   add_name = ->(params, conn) { params.merge(name: conn.fetch(:name)) }
-  #   WebPipe::Params::Transf.register(:add_name, add_name)
-  #   conn.
-  #     add(:name, 'Joe').
-  #     params([:deep_symbolize_keys, :add_name]) #=> { foo: 'bar', name: 'Joe' }
-  #
-  # Inline transformations can also be provided:
-  #
-  # @example
-  #   # http://www.example.com?foo=bar
-  #   fake = ->(_params) { { fake: :params } }
-  #   conn.
-  #     params(fake) #=> { fake: :params }
-  #
-  # @see https://github.com/dry-rb/dry-transformer
+  # See the docs for the extension linked from the README.
   module Params
     # Key where configured transformations are set
     PARAM_TRANSFORMATION_KEY = :param_transformations

data/lib/web_pipe/extensions/rails/rails.rb

@@ -2,126 +2,9 @@
 
 require 'web_pipe/conn'
 
-#:nodoc:
+# :nodoc:
 module WebPipe
-  # Integrates with Rails framework.
-  #
-  # The first two things to keep in mind in order to integrate with Rails is
-  # that {WebPipe} instances are Rack applications and that rails router can
-  # perfectly dispatch to a rack application. For example:
-  #
-  # ```ruby
-  # # config/routes.rb
-  # get '/my_route', to: MyRoute.new
-  #
-  # # app/controllers/my_route.rb
-  # class MyRoute
-  #   include WebPipe
-  #
-  #   plug :set_response_body
-  #
-  #   private
-  #
-  #   def set_response_body(conn)
-  #     conn.set_response_body('Hello, World!')
-  #   end
-  # end
-  # ```
-  #
-  # In order to do something like the previous example you don't need to enable
-  # this extension. Notice that rails took care of dispatching the request to
-  # our {WebPipe} rack application, which was then responsible for generating the
-  # response. In this case, it used a simple call to
-  # {WebPipe::Conn#set_response_body}.
-  #
-  # It's quite possible that you don't need more than that in terms of rails
-  # integration. Of course, surely you want something more elaborate to generate
-  # responses. For that, you can use the view or template system you like. One
-  # option that will play specially well here is `hanami-view`. Furthermore, we
-  # have a tailored `hanami_view` extension.
-  #
-  # You need to use `:rails` extension if:
-  #
-  # - You want to use `action_view` as rendering system.
-  # - You want to use rails url helpers from your {WebPipe} application.
-  # - You want to use controller helpers from your {WebPipe} application.
-  #
-  # Rails responsibilities for controlling the request/response cycle and the
-  # rendering process are a little bit tangled. For this reason, even if you
-  # want to use {WebPipe} applications instead of Rails controller actions you
-  # still have to use the typical top `ApplicationController` in order to define
-  # some behaviour for the view layer:
-  #
-  # - Which layout is applied to the template.
-  # - Which helpers will become available to the templates.
-  #
-  # By default, the controller in use is `ActionController::Base`, which means
-  # that no layout is applied and only built-in helpers (for example,
-  # `number_as_currency`) are available. You can change it via the
-  # `:rails_controller` configuration option.
-  #
-  # The main method that this extension adds to {WebPipe::Conn} is `#render`,
-  # which just delegates to the Rails implementation as you'd do in a typical
-  # rails controller. Remember that you can provide template instance variables
-  # through the keyword `:assigns`.
-  #
-  # ```ruby
-  # # config/routes.rb
-  # get '/articles', to: ArticlesIndex.new
-  #
-  # # app/controllers/application_controller.rb
-  # class ApplicationController < ActionController::Base
-  #   # By default uses the layout in `layouts/application`
-  # end
-  #
-  # # app/controllers/articles_index.rb
-  # require 'web_pipe/plugs/config'
-  #
-  #
-  # WebPipe.load_extensions(:rails) # You can put it in an initializer
-  #
-  # class ArticlesIndex
-  #   include WebPipe
-  #
-  #   plug :config, WebPipe::Plugs::Config.(
-  #     rails_controller: ApplicationController
-  #   )
-  #
-  #   def render(conn)
-  #     conn.render(
-  #       template: 'articles/index',
-  #       assigns: { articles: Article.all }
-  #     )
-  #   end
-  # end
-  # ```
-  #
-  # Notice that we used the keyword `template:` instead of taking advantage of
-  # automatic template lookup. We did that way so that we don't have to create
-  # also an `ArticlesController`, but it's up to you. In the case of having an
-  # `ArticlesController` we could just do `conn.render(:index, assigns: {
-  # articles: Article.all })`.
-  #
-  # Besides, this extension provides with two other methods:
-  #
-  # - `url_helpers` returns Rails router url helpers.
-  # - `helpers` returns the associated controller helpers.
-  #
-  # In all the examples we have supposed that we are putting {WebPipe}
-  # applications within `app/controllers/` directory. However, remember you can
-  # put them wherever you like as long as you respect rails `autoload_paths`.
-  #
-  # Here you have a link to a very simple and contrived example of a rails
-  # application integrating `web_pipe`:
-  #
-  # https://github.com/waiting-for-dev/rails-web_pipe
-  #
-  # @see https://guides.rubyonrails.org/routing.html#routing-to-rack-applications
-  # @see https://api.rubyonrails.org/v6.0.1/classes/ActionController/Renderer.html
-  # @see https://api.rubyonrails.org/v6.0.1/classes/ActionController/Renderer.html
-  # @see https://api.rubyonrails.org/v6.0.1/classes/ActionView/Helpers/UrlHelper.html
-  # @see https://api.rubyonrails.org/classes/ActionController/Helpers.html
-  # @see https://guides.rubyonrails.org/autoloading_and_reloading_constants.html#autoload-paths
+  # See the docs for the extension linked from the README.
   module Rails
     def render(*args)
       set_response_body(

data/lib/web_pipe/extensions/redirect/redirect.rb

@@ -2,27 +2,9 @@
 
 require 'web_pipe/types'
 
-#:nodoc:
+# :nodoc:
 module WebPipe
-  # Helper method to create redirect responses.
-  #
-  # This extensions adds a {#redirect} method to {Conn} which helps
-  # setting the `Location` header and the status code needed to
-  # instruct the browser to perform a redirect. By default, `302`
-  # status code is used.
-  #
-  # @example
-  #  require 'web_pipe'
-  #
-  #  WebPipe.load_extensions(:redirect)
-  #
-  #  class MyApp
-  #    include WebPipe
-  #
-  #    plug(:redirect) do |conn|
-  #      conn.redirect('/', 301)
-  #    end
-  #  end
+  # See the docs for the extension linked from the README.
   module Redirect
     # Location header
     LOCATION_HEADER = 'Location'

data/lib/web_pipe/extensions/router_params/router_params.rb

@@ -6,45 +6,7 @@ require 'web_pipe/types'
 WebPipe.load_extensions(:params)
 
 module WebPipe
-  # Adds a transformation to merge router params into {Conn#params}.
-  #
-  # This extension gives an opportunity for rack routers to modify
-  # {Conn#params} hash. This is useful so that they can provide *route
-  # parameters*, which are typically rendered as variables in routes
-  # definitions (e.g.: `/user/:id/edit`).
-  #
-  # It adds a `:router_params` transformation that, when used, will
-  # merged env's `router.params` in {Conn#params} hash. Choosing this
-  # name automatically integrates with `hanami-router`.
-  #
-  # When using this extension, `:params` extension is automatically enabled.
-  #
-  # @example
-  #   require 'web_pipe'
-  #
-  #   WebPipe.load_extensions(:router_params)
-  #
-  #   class MyApp
-  #     include WebPipe
-  #
-  #     plug :config
-  #     plug :get_params
-  #
-  #     private
-  #
-  #     def config(conn)
-  #       conn.add_config(:param_transformation, [:router_params])
-  #     end
-  #
-  #     def get_params(conn)
-  #       # http://example.com/users/1/edit
-  #       conn.params #=> { id: 1 }
-  #       conn
-  #     end
-  #  end
-  #
-  # @see WebPipe::Params
-  # @see https://github.com/hanami/router#string-matching-with-variables
+  # See the docs for the extension linked from the README.
   module RouterParams
     ROUTER_PARAM_KEY = 'router.params'
 

data/lib/web_pipe/extensions/session/session.rb

@@ -4,32 +4,9 @@ require 'web_pipe/conn'
 require 'web_pipe/types'
 require 'rack'
 
-#:nodoc:
+# :nodoc:
 module WebPipe
-  # Wrapper around Rack::Session middlewares.
-  #
-  # This extension provides with helper methods to retrieve rack
-  # session and work with it while still being able to chain {Conn}
-  # method calls.
-  #
-  # It requires one of `Rack::Session` middlewares to be present.
-  #
-  # @example
-  #   require 'web_pipe'
-  #   require 'rack/session'
-  #
-  #   WebPipe.load_extensions(:session)
-  #
-  #   class MyApp
-  #     include WebPipe
-  #
-  #     use Rack::Session::Cookie, secret: 'top_secret'
-  #
-  #     plug :add_session, ->(conn) { conn.add_session('foo', 'bar') }
-  #     plug :fetch_session, ->(conn) { conn.add(:foo, conn.fetch_session('foo')) }
-  #     plug :delete_session, ->(conn) { conn.delete_session('foo') }
-  #     plug :clear_session, ->(conn) { conn.clear_session }
-  #   end
+  # See the docs for the extension linked from the README.
   module Session
     # Type for session keys.
     SESSION_KEY = Types::Strict::String

data/lib/web_pipe/extensions/url/url.rb

@@ -1,11 +1,8 @@
 # frozen_string_literal: true
 
-#:nodoc:
+# :nodoc:
 module WebPipe
-  # Adds helper methods related to the request URL.
-  #
-  # This methods are in fact redundant with the information already
-  # present in {Conn} struct but, of course, they are very useful.
+  # See the docs for the extension linked from the README.
   module Url
     # Base part of the URL.
     #

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