web_pipe 0.13.0 → 0.16.0

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'web_pipe/types'
+require 'web_pipe/conn'
+require 'hanami/view'
+
+# :nodoc:
+module WebPipe
+  # 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
+
+    # Default request's view context
+    DEFAULT_VIEW_CONTEXT = ->(_conn) { Types::EMPTY_HASH }
+
+    # Sets string output of a view as response body.
+    #
+    # If the view is not a {Hanami::View} instance, it is resolved from
+    # the configured container.
+    #
+    # `kwargs` is used as the input for the view (the arguments that
+    # {Hanami::View#call} receives). If they doesn't contain an explicit
+    # `context:` key, it can be added through the injection of the
+    # result of a lambda present in context's `:view_context`.(see
+    # {Hanami::View::Context#with}).
+    #
+    # @param view_spec [Hanami::View, Any]
+    # @param kwargs [Hash] Arguments to pass along to `Hanami::View#call`
+    #
+    # @return WebPipe::Conn
+    def view(view_spec, **kwargs)
+      view_instance = view_instance(view_spec)
+      view_input = view_input(kwargs, view_instance)
+
+      set_response_body(
+        view_instance.call(
+          **view_input
+        ).to_str
+      )
+    end
+
+    private
+
+    def view_instance(view_spec)
+      return view_spec if view_spec.is_a?(Hanami::View)
+
+      fetch_config(:container)[view_spec]
+    end
+
+    def view_input(kwargs, view_instance)
+      return kwargs if kwargs.key?(:context)
+
+      context = view_instance
+                .config
+                .default_context
+                .with(
+                  **fetch_config(
+                    VIEW_CONTEXT_KEY, DEFAULT_VIEW_CONTEXT
+                  ).call(self)
+                )
+      kwargs.merge(context: context)
+    end
+  end
+
+  Conn.include(DryView)
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# :nodoc:
+module WebPipe
+  # See the docs for the extension linked from the README.
+  module NotFound
+    # @api private
+    RESPONSE_BODY_STEP_CONFIG_KEY = :not_found_body_step
+
+    # Generates the not-found response
+    #
+    # @return [WebPipe::Conn::Halted]
+    # @see NotFound
+    def not_found
+      set_status(404)
+        .then do |conn|
+          response_body_step = conn.fetch_config(RESPONSE_BODY_STEP_CONFIG_KEY,
+                                                 ->(c) { c.set_response_body('Not found') })
+
+          response_body_step.call(conn)
+        end.halt
+    end
+
+    Conn.include(NotFound)
+  end
+end

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,130 +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 `dry-view`, which integrates
-  # itself easily with Rails. Furthermore, we have a tailored `dry_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://dry-rb.org/gems/dry-view/
-  # @see https://github.com/dry-rb/dry-view/tree/master/examples/rails
-  # @see https://waiting-for-dev.github.io/web_pipe/docs/extensions/dry_view.html
-  # @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.
     #