web_pipe 0.13.0 → 0.16.0

data/docs/extensions/{dry_view.md → hanami_view.md}

@@ -1,21 +1,23 @@
-# Dry View
+# Hanami View
 
-This extensions integrates with
-[dry-view](https://dry-rb.org/gems/dry-view/) rendering system to
-set a dry-view output as response body.
+This extension currently works with `hanami-view` v2.0.0.alpha2, which is not
+still released but available on the gem repository.
+
+This extension integrates with [hanami-view](https://github.com/hanami/view)
+rendering system to set a hanami-view output as the response body.
 
 `WebPipe::Conn#view` method is at the core of this extension. In its basic
-behaviour, you provide to it a view instance you want to render and any
+behavior, you provide to it a view instance you want to render and any
 exposures or options it may need:
 
 ```ruby
 require 'web_pipe'
-require 'dry/view'
+require 'hanami/view'
 require 'my_context'
 
-WebPipe.load_extensions(:dry_view)
+WebPipe.load_extensions(:hanami_view)
 
-class SayHelloView < Dry::View
+class SayHelloView < Hanami::View
   config.paths = [File.join(__dir__, '..', 'templates')]
   config.template = 'say_hello'
   config.default_context = MyContext
@@ -35,17 +37,16 @@ class MyApp
   end
 end
 ```
-
-However, you can resolve a view from a container if you also use (`:container`
-extension)[container.md]:
+However, you can resolve a view from a container if you also use the
+(`:container` extension)[container.md]:
 
 ```ruby
-require 'dry_view'
+require 'hanami_view'
 require 'my_container'
 require 'web_pipe'
 require 'web_pipe/plugs/config'
 
-WebPipe.load_extensions(:dry_view, :container)
+WebPipe.load_extensions(:hanami_view, :container)
 
 class MyApp
  include WebPipe
@@ -61,20 +62,17 @@ class MyApp
 end
 ```
 
-As in a standard call to `Dry::View#call`, you can override the context
-(`Dry::View::Context`) to use through `context:` option. However, it is still
-possible to leverage configured default context while being able to inject
-request specific data to it.
+As in a standard call to `Hanami::View#call`, you can override the context
+(`Hanami::View::Context`) to use through the `context:` option. However, it is still possible to leverage the configured default context while injecting specific data to it.
 
-For that to work, you have to specify required dependencies (in this case,
-request specific data) to your dry-view's context. A very convenient way to do
-that is with [`dry-auto_inject`](https://dry-rb.org/gems/dry-auto_inject):
+To work, you have to specify required dependencies (in this case,
+request specific data) to your hanami-view's context. A very convenient way to do that is with [`dry-auto_inject`](https://dry-rb.org/gems/dry-auto_inject):
 
 ```ruby
-require 'dry/view/context'
+require 'hanami/view/context'
 require 'my_import'
 
-class MyContext < Dry::View::Context
+class MyContext < Hanami::View::Context
  include MyImport::Import[:current_path]
  
  # Without `dry-auto_inject` you have to manually specify dependencies and

data/docs/extensions/not_found.md

@@ -0,0 +1,40 @@
+# Not found
+
+This extension helps to build a not-found response in a single method
+invocation. The `WebPipe::Conn#not_found` method will:
+
+- Set 404 as response status.
+- Set 'Not found' as the response body, or instead run a step configured in
+`:not_found_body_step` config key.
+- Halt the connection struct.
+
+```ruby
+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
+```

data/docs/extensions/params.md

@@ -1,10 +1,11 @@
 # Params
 
 This extension adds a `WebPipe::Conn#params` method which returns
-request parameters as a Hash where any number of transformations
-can be configured.
+request parameters as a Hash. Then, any number of transformations on it can be
+configured.
 
-When no transformations are configured, `#params` just returns GET and POST parameters as a hash:
+When no transformations are configured, `#params` returns GET and POST
+parameters as a hash:
 
 ```ruby
 # http://www.example.com?foo=bar
@@ -102,7 +103,8 @@ plug(:this) do |conn|
 end
 # ...
 ```
-Finally, you can override configured transformations injecting another set at the moment of calling `#params`:
+Finally, you can override the configured transformations injecting another set
+at the moment of calling `#params`:
 
 ```ruby
 # ...

data/docs/extensions/rails.md

@@ -1,8 +1,8 @@
 # Rails
 
-The first two things to keep in mind in order to integrate with Rails is
+The first two things to keep in mind to integrate with Rails are
 that `WebPipe` instances are Rack applications and that rails router can
-perfectly [dispatch to a rack application](https://guides.rubyonrails.org/routing.html#routing-to-rack-applications). For example:
+perfectly [dispatch to a rack application](https://guides.rubyonrails.org/routing.html#routing-to-rack-applications).
 
 ```ruby
 # config/routes.rb
@@ -22,31 +22,29 @@ class MyRoute
 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 `#set_response_body`.
+To do something like the previous example, you don't need to enable this
+extension. Notice that rails dispatched the request to our `WebPipe` rack
+application, which was then responsible for generating the response. In this
+case, it used a simple call to `#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
+integration. Of course, 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`](https://dry-rb.org/gems/dry-view/), which
-[integrates](https://github.com/dry-rb/dry-view/tree/master/examples/rails)
-itself easily with Rails. Furthermore, we have a tailored `dry_view`
-[extension](https://waiting-for-dev.github.io/web_pipe/docs/extensions/dry_view.html).
+option that will play especially well here is
+[`hanami-view`](https://github.com/hanami/view). Furthermore, we have a
+tailored `hanami_view`
+[extension](https://waiting-for-dev.github.io/web_pipe/docs/extensions/hanami_view.html).
 
-You need to use `:rails` extension if:
+You need to use the `: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 `action_view` as a 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:
+Rails' responsibilities for controlling the request/response cycle are coupled
+to the rendering process. 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` to define some behavior for the view layer:
 
 - Which layout is applied to the template.
 - Which helpers will become available to the templates.
@@ -56,11 +54,11 @@ 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](https://api.rubyonrails.org/v6.0.1/classes/ActionController/Renderer.html)
-as you'd do in a typical rails controller. Remember that you can provide
-template instance variables through the keyword `:assigns`.
+The main method that this extension adds to `WebPipe::Conn` is `#render`, which
+delegates to the [Rails implementation]
+(https://api.rubyonrails.org/v6.0.1/classes/ActionController/Renderer.html) 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
@@ -93,10 +91,10 @@ 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 })`.
+automatic template lookup. We did that way so that we don't have to create an
+`ArticlesController`, but it's up to you. In the case of having an
+`ArticlesController`, we could do `conn.render(:index, assigns: { articles:
+Article.all })`.
 
 Besides, this extension provides with two other methods:
 
@@ -105,12 +103,7 @@ Besides, this extension provides with two other methods:
 - `helpers` returns the associated [controller
   helpers](https://api.rubyonrails.org/classes/ActionController/Helpers.html).
 
-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`](https://guides.rubyonrails.org/autoloading_and_reloading_constants.html#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
-
+We have placed `WebPipe` applications within `app/controllers/` directory in
+all the examples. However, remember you can put them wherever you like as long
+as you respect rails
+[`autoload_paths`](https://guides.rubyonrails.org/autoloading_and_reloading_constants.html#autoload-paths).

data/docs/extensions/redirect.md

@@ -1,14 +1,15 @@
 # Redirect
 
-This extension helps with creating a redirect response.
+This extension helps create a redirect response.
 
 Redirect responses consist of two pieces:
 
-- `Location` response header with the URL to which browsers should redirect.
+- The `Location` response header with the URL to which browsers should
+  redirect.
 - A 3xx status code.
 
-A `#redirect(location, code)` method is added to `WebPipe::Conn` which takes
-care of both steps. `code` argument is optional, defaulting to `302`.
+A `#redirect(location, code)` method is added to `WebPipe::Conn`, which takes
+care of both steps. The `code` argument is optional, defaulting to `302`.
 
 ```ruby
 require 'web_pipe'

data/docs/extensions/router_params.md

@@ -1,12 +1,12 @@
 # Router params
 
-This extension can be used in order to merge placeholder parameters
+This extension can be used to merge placeholder parameters
 that usually routers support (like `get /users/:id`) to the parameters hash
-added through [`:params` extension](params.md) (which is
-automatically loaded).
+added through the [`:params` extension](params.md) (which is
+automatically loaded if using `:router_params`).
 
-What this extension does is adding a transformation function to the registry
-with name `:router_params`. Internally, it merges what is present in rack env's
+This extension adds a transformation function named `:router_params`to the
+registry. Internally, it merges what is present in rack env's
 `router.params` key.
 
 It automatically integrates with

data/docs/extensions/session.md

@@ -1,11 +1,11 @@
 # Session
 
-Wrapper around `Rack::Session` middleware to help working with
-sessions in your plugged operations.
+Wrapper around `Rack::Session` middleware to help work with sessions in your
+plugged operations.
 
-It depends on `Rack::Session` middleware, which is shipped by rack.
+It depends on the `Rack::Session` middleware, which is shipped by rack.
 
-It adds following methods to `WebPipe::Conn`:
+It adds the following methods to `WebPipe::Conn`:
 
 - `#fetch_session(key)`, `#fetch_session(key, default)` or
   `#fetch_session(key) { default }`. Returns what is stored under

data/docs/extensions/url.md

@@ -1,11 +1,11 @@
 # URL
 
-`:url` extension just adds a few methods which cook raw request information
-about the URL into something more digestible.
+The `:url` extension adds a few methods that process the raw URL information
+into something more digestable.
 
 Specifically, it adds:
 
-- `#base_url`: Which is schema + host + port (unless it is the default for the scheme). I.e. `'https://example.org'` or `'http://example.org:8000'`.
-- `#path`: Which is script name (if any) + path information. I.e. `'index.rb/users/1'` or `'users/1'`.
-- `#full_path`: Which is path + query string (if any). I.e. `'users/1?view=table'`.
-- `#url`: Which is base url + full path. I.e. `'http://example.org:8000/users/1?view=table'`.
+- `#base_url`: That's schema + host + port (unless it is the default for the scheme). E.g. `'https://example.org'` or `'http://example.org:8000'`.
+- `#path`: That's script name (if any) + path information. E.g. `'index.rb/users/1'` or `'users/1'`.
+- `#full_path`: That's path + query string (if any). E.g. `'users/1?view=table'`.
+- `#url`: That's base url + full path. E.g. `'http://example.org:8000/users/1?view=table'`.

data/docs/extensions.md

@@ -1,12 +1,11 @@
 # Extensions
 
-`WebPipe::Conn` features are by default raw: the very minimal you
-need to be able to build a web application. However, there are
-several extensions to progressively add just the ingredients you
-want to use.
+`WebPipe::Conn` features are bare-bones by default: the very minimal you need
+to be able to build a web application. However, there are several extensions to
+add just the ingredients you want to use progressively.
 
-In order to load the extensions, you have to call
-`#load_extensions` method in `WebPipe`:
+To load the extensions, you have to call `#load_extensions` method in
+`WebPipe`:
 
 ```ruby
 WebPipe.load_extensions(:params, :cookies)

data/docs/introduction.md

@@ -6,10 +6,10 @@ It means that with it and a rack router (like
 [`hanami-router`](https://github.com/hanami/router),
 [`http_router`](https://github.com/joshbuddy/http_router) or plain
 [rack](https://github.com/rack/rack) routing methods you can build a complete
-web application.  However, the idea behind `web_pipe` is being a decoupled
-component within a web framework.  For this reason, it plays extremely well
-with [dry-rb](https://dry-rb.org/) ecosystem. If it helps, you can think of it
-as a decoupled web controller (as the C in MVC).
+web application.  However, the idea behind `web_pipe` is for it to be a
+decoupled component within a web framework.  For this reason, it plays
+extremely well with [dry-rb](https://dry-rb.org/) ecosystem. If it helps, you
+can think of it as a decoupled web controller (as the C in MVC).
 
 `web_pipe` applications are built as a [pipe of
 operations](design_model.md) on an [immutable
@@ -28,9 +28,9 @@ Following there is a simple example. It is a web application that will check
 the value of a `user` parameter. When it is `Alice` or `Joe`, it will kindly
 say hello. Otherwise, it will unauthorize:
 
-> In order to try this example you can paste it to a file with name `config.ru`
-and launch the rack command `rackup` within the same directory. The application
-will be available in `http://localhost:9292`.
+> To try this example, you can paste it to a file with the name `config.ru` and
+launch the rack command `rackup` within the same directory. The application
+will be available at `http://localhost:9292`.
 
 ```ruby
 require 'web_pipe'

data/docs/plugging_operations/composing_operations.md

@@ -5,9 +5,9 @@ and returning a connection struct. As a result, a composition of operations is
 an operation in itself (as it also takes a connection struct and returns a
 connection struct).
 
-This can be leveraged to plug a whole `web_pipe` application as an operation
-to another application. Doing so, you are plugging an operation which is the
-composition of all operations for given application.
+We can leverage that to plug a whole `web_pipe` application as an operation to
+another application. By doing so, you are plugging an operation which is the
+composition of all operations for a given application.
 
 ```ruby
 class HtmlApp

data/docs/plugging_operations/injecting_operations.md

@@ -1,12 +1,12 @@
 # Injecting operations
 
-Operations can be injected at the moment an application is initialized,
-which allows you to override what the definition declares.
+You can inject operations at the moment an application is initialized. It
+allows you to override what the definition declares.
 
 To this effect, you must use `plugs:` keyword argument. It must be a hash where
-operations are matched by the name you gave them in its definition.
+the operations are matched by the name you gave them in its definition.
 
-This is mainly useful for testing purposes, where you can switch a heavy
+That is mainly useful for testing purposes, where you can switch a heavy
 operation and use another lighter one.
 
 In the following example, the response body of the application will be

data/docs/plugging_operations/inspecting_operations.md

@@ -0,0 +1,24 @@
+# Inspecting operations
+
+Once a `WebPipe` class is initialized, all its operations get resolved. It
+happens because they are whether [resolved](resolving_operations.md) or
+[injected](injecting_operations.md). The final result can be accessed through
+the `#operations` method:
+
+```ruby
+require 'web_pipe'
+require 'web_pipe/conn_support/builder'
+
+class MyApp
+  include WebPipe
+
+  plug(:hello) do |conn|
+    conn.set_response_body('Hello world!')
+  end
+end
+
+app = MyApp.new
+conn = WebPipe::ConnSupport::Builder.call(Rack::MockRequest.env_for)
+new_conn = app.operations[:hello].call(con)
+conn.response_body #=> ['Hello world!']
+```

data/docs/plugging_operations/resolving_operations.md

@@ -1,6 +1,6 @@
 # Resolving operations
 
-There are several ways you can specify how an operation is resolved.
+There are several ways you can specify how to resolve an operation.
 
 ## Instance method
 
@@ -53,8 +53,8 @@ end
 Operations can be resolved from a dependency injection container.
 
 A container is anything that responds to `#[]` (accepting `Symbol` or `String`
-as argument) in order to resolve a dependency. It can be configured at the
-moment `WebPipe` module is included:
+as argument) to resolve a dependency. It can be configured at the
+moment you include the `WebPipe` module:
 
 ```ruby
 MyContainer = Hash[

data/docs/plugging_operations.md

@@ -1,10 +1,10 @@
 # Plugging operations
 
-You can plug operations to your application with the DSL method `plug`. The
+You can plug operations into your application with the DSL method `plug`. The
 first argument it always takes is a symbol with the name you want
 to give to the operation (which is needed to allow
-[injection](plugging_operations/injecting_operations.md) on
-initialization).
+[injection](plugging_operations/injecting_operations.md) at
+initialization time).
 
 ```ruby
 class MyApp

data/docs/plugs/config.md

@@ -1,6 +1,6 @@
 # Config
 
-`Config` plug helps in the addition of configuration settings (`#config` hash
+The `Config` plug helps in adding configuration settings (`#config` hash
 attribute) to an instance of `WebPipe::Conn`.
 
 ```ruby

data/docs/plugs/content_type.md

@@ -1,6 +1,7 @@
 # ContentType
 
-`ContentType` plug is just a helper to set `Content-Type` response header.
+The `ContentType` plug is just a helper to set the `Content-Type` response
+header.
 
 Example:
 

data/docs/plugs.md

@@ -1,13 +1,12 @@
 # Plugs
 
-Some group of operations can be generalized as following same pattern. For
+Some groups of operations can be generalized as following the same pattern. For
 example, an operation setting `Content-Type` header to `text/html` is very
-similar to another one setting same header to `application/json`. We name plugs
-to this level of abstraction on top of operations: plugs are operation
-builders. In other words, they are higher order functions which return
-functions.
+similar to setting the same header to `application/json`. We name plugs to this
+level of abstraction on top of operations: plugs are operation builders. In
+other words, they are higher-order functions that return functions.
 
-Being just functions, we take as convention that plugs respond to `#call` in
-order to create an operation.
+Being just functions, we take as a convention that plugs respond to `#call` to
+create an operation.
 
 This library ships with some useful plugs.

data/docs/recipes/hanami_2_and_dry_rb_integration.md

@@ -0,0 +1,12 @@
+# Hanami 2 and dry-rb integration
+
+`web_pipe` has been designed to integrate smoothly with
+the [hanami](https://hanamirb.org/) & [dry-rb](https://dry-rb.org/) ecosystems. It shares the same design
+principles, and it ships with some extensions that even make this
+integration painless (like [`:dry-schema`](../extensions/dry_schema.md)
+extension or [`:hanami_view`](../extensions/hanami_view.md)).
+
+If you want to use `web_pipe` within a hanami 2 application, you can take
+inspiration from this sample todo app:
+
+https://github.com/waiting-for-dev/hanami_2_web_pipe_todo_app

data/docs/recipes/hanami_router_integration.md

@@ -22,4 +22,6 @@ end
 run router
 ```
 
-In order to perform [string matching with variables](https://github.com/hanami/router#string-matching-with-variables) you just need to load [`:router_params` extension](../extensions/router_params.md).
+To perform [string matching with
+variables](https://github.com/hanami/router#string-matching-with-variables) you
+just need to load [`:router_params` extension](../extensions/router_params.md).

data/docs/recipes/using_all_restful_methods.md

@@ -1,6 +1,6 @@
 # Using all RESTful methods
 
-As you probably know, a lot of browsers don't support some RESTful
+As you probably know, most browsers don't support some RESTful
 methods like `PATCH` or `PUT`. [Rack's `MethodOverride`
 middleware](https://github.com/rack/rack/blob/master/lib/rack/method_override.rb)
 provides a workaround for this limitation, allowing to override
@@ -9,12 +9,13 @@ request method in rack's env if a magical `_method` parameter or
 
 You have to be aware that if you use this middleware within a
 `web_pipe` application (through [`use` DSL
-method](../using_rack_middlewares.md)) it will have no effect.
-When your `web_pipe` application takes control of the request it
-has already gone through the router, which is the one who should
+method](../using_rack_middlewares.md)), it will have no effect.
+When your `web_pipe` application takes control of the request, it
+has already gone through the router, which is the one that should
 read the request method set by rack.
 
-The solution for this is very simple. Just use `MethodOverride` middleware before your router does its work. For example, in `config.ru`:
+The solution for this is straightforward. Just use `MethodOverride` middleware
+before your router does its work. For example, in `config.ru`:
 
 ```ruby
 # config.ru

data/docs/testing.md

@@ -0,0 +1,64 @@
+# Testing
+
+## Testing the rack application
+
+A `WebPipe` instance is a just a rack application, so you can test it as such:
+
+```ruby
+require 'web_pipe'
+require 'rack/mock'
+require 'rspec'
+
+class MyApp
+  include WebPipe
+
+  plug :response
+
+  private
+
+  def response(conn)
+    conn
+      .set_response_body('Hello!')
+      .set_status(200)
+  end
+end
+
+RSpec.describe MyApp do
+  it 'responds with 200 status code' do
+    env = Rack::MockRequest.env_for
+
+    status, _headers, _body = described_class.new.call(env)
+
+    expect(status).to be(200)
+  end
+end
+```
+
+## Testing individual operations
+
+Each operation in a pipe is an isolated function that takes a connection struct
+as argument. You can leverage [the inspection of
+operations](docs/plugging_operations/inspecting_operations.md) to unit test them.
+
+There's also a `WebPipe::TestSupport` module that you can include to get a
+helper method `#build_conn` to easily create a connection struct.
+
+```ruby
+RSpec.describe MyApp do
+  include WebPipe::TestSupport
+
+  describe '#response' do
+    it 'responds with 200 status code' do
+      conn = build_conn
+      operation = described_class.new.operations[:response]
+
+      new_conn = operation.call(conn)
+
+      expect(new_conn.status).to be(200)
+    end
+  end
+end
+```
+
+Check the API documentation for the options you can provide to
+[`#build_conn`](https://www.rubydoc.info/github/waiting-for-dev/web_pipe/master/WebPipe/TestSupport#build_conn).

data/docs/using_rack_middlewares/composing_middlewares.md

@@ -3,9 +3,8 @@
 In a similar way that you compose plugged operations, you can also compose rack
 middlewares from another application.
 
-For that, you just need to `use` another application. When you do so, all the
-middlewares for that application will be added to the stack in the same order
-they had there.
+For that, you just need to `use` another application. All the middlewares for
+that application will be added to the stack in the same order.
 
 ```ruby
 class HtmlApp