web_pipe 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09151400e351c909383b2cc9308910d209c6207fc978a55c59eb02997d29b3c7'
-  data.tar.gz: c2fff9105cc8cecc5aad8e2a7232f1a902bb3ec5d30e3a6b4e130db6128ba57b
+  metadata.gz: fc647eb09c8b7eb1d3bcfb910cc55e840285c6b1ab9bd9c69ea9b630f7a116fd
+  data.tar.gz: 6b667b8e71f1fac8d7c46a8160cbff273c70042bf1cc9b06da60c82a83fea5b2
 SHA512:
-  metadata.gz: da96a1e7cdd4278db92e14692248046dbcbeb04c1592ae01dd326b3958f42873f0564080ba70379690ec390bf37160885bbe20e591b6281b97617bac0cc402e5
-  data.tar.gz: e429d891a90cd7c90d9ccf11baca675c508906891c07f833a937c90d3ba751a7f85d73b03823be037e80a77cc20ba729c75115e61f6891829774614813045804
+  metadata.gz: f52d9d4c5b381d13de8f27ae03e8fc8bfb2cfe7e020d507f934341c9823f7c2cb2d94ebddc500d9337a59c2437c8ae3899e1b7ef942ed5e1cfc073591f8ac56f
+  data.tar.gz: 0be15319332d738f2b8ff07d7cb9d73583d00bf907e8787a2b8ab0fadc88d235f441b08e546bf162a6fb6fca8953ab68c34077cf300c0d6c1bb26aa37fe8f964

data/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [0.9.0] - 2019-08-31
+### Added
+- Comprehensive documentation.
+  [[#35]](https://github.com/waiting-for-dev/web_pipe/pull/35)
+
 ## [0.8.0] - 2019-08-30
 ### Added
 - **BREAKING**. Rename `Rack` module to `RackSupport`.

data/Gemfile

@@ -1,6 +1,8 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in web_pipe.gemspec
 gemspec

data/README.md

@@ -3,339 +3,89 @@
 
 # WebPipe
 
-`web_pipe` is a rack application builder through a pipe of operations
-applied to an immutable struct.
-
-You can also think of it as a web controllers builder (the C in `MVC`)
-totally declouped from the web routing (which you can still do with
-something like [`hanami-router`](https://github.com/hanami/router), 
-[`http_router`](https://github.com/joshbuddy/http_router) or plain
-[rack's `map`
-method](https://www.rubydoc.info/github/rack/rack/Rack/Builder#map-instance_method)).
-
-If you are familiar with rack you know that it models a two-way pipe,
-where each middleware in the stack has the chance to modify the
-request before it arrives to the actual application, and the response
-once it comes back from the application:
-
-```
-
-  --------------------->  request ----------------------->
-
-  Middleware 1          Middleware 2          Application
-
-  <--------------------- response <-----------------------
-
-
-```
-
-`web_pipe` follows a simpler but equally powerful model of a one-way
-pipe and abstracts it on top of rack. A struct that contains all the
-data from a web request is piped trough a stack of operations which
-take it as argument and return a new instance of it where response
-data can be added at any step.
-
-```
-
-  Operation 1          Operation 2          Operation 3
-
-  --------------------- request/response ---------------->
-
-```
-
-In addition to that, any operation in the stack has the power to stop
-the propagation of the pipe, leaving any downstream operation
-unexecuted. This is mainly useful to unauthorize a request while being
-sure that nothing else will be done to the response.
-
-As you may know, this is the same model used by Elixir's
-[`plug`](https://hexdocs.pm/plug/readme.html), from which `web_pipe`
-takes inspiration.
-
-This library has been designed to work frictionless along the
-[`dry-rb`]( https://dry-rb.org/) ruby ecosystem and it uses some of
-its libraries internally.
-
-## Usage
-
-This is a sample `config.ru` for a contrived application built with
-`web_pipe`. It simply fetches a user from an `id` request
-parameter. If the user is not found, it returns a not found
-response. If it is found, it will unauthorize when it is a non `admin`
-user or greet it otherwise:
-
-```
-rackup --port 4000
-# http://localhost:4000?id=1 => Hello Alice
-# http://localhost:4000?id=2 => Unauthorized
-# http://localhost:4000?id=3 => Not found
-```
+`web_pipe` is a modular rack application builder through a pipe of
+operations on an immutable struct.
+
+In order to use in conjunction with [dry-rb](https://dry-rb.org/)
+ecosystem, see also
+[`dry-web-web_pipe`](https://github.com/waiting-for-dev/dry-web-web_pipe).
+
+1. [Introduction](/docs/introduction.md)
+1. [Design model](/docs/design_model.md)
+1. [Building a rack application](/docs/building_a_rack_application.md)
+1. [Plugging operations](/docs/plugging_operations.md)
+   1. [Resolving operations](/docs/plugging_operations/resolving_operations.md)
+   1. [Injecting operations](/docs/plugging_operations/injecting_operations.md)
+   1. [Composing operations](/docs/plugging_operations/composing_operations.md)
+1. [Using rack middlewares](/docs/using_rack_middlewares.md)
+   1. [Injecting middlewares](/docs/using_rack_middlewares/injecting_middlewares.md)
+   1. [Composing middlewares](/docs/using_rack_middlewares/composing_middlewares.md)
+1. [Composing applications](/docs/composing_applications.md)
+1. [Connection struct](/docs/connection_struct.md)
+   1. [Sharing data downstream](/docs/connection_struct/sharing_data_downstream.md)
+   1. [Halting the pipe](/docs/connection_struct/halting_the_pipe.md)
+   1. [Configuring the connection struct](/docs/connection_struct/configuring_the_connection_struct.md)
+1. [DSL free usage](/docs/dsl_free_usage.md)
+1. [Plugs](/docs/plugs.md)
+   1. [Config](/docs/plugs/config.md)
+   1. [ContentType](/docs/plugs/content_type.md)
+1. [Extensions](/docs/extensions.md)
+   1. [Container](/docs/extensions/container.md)
+   1. [Cookies](/docs/extensions/cookies.md)
+   1. [Flash](/docs/extensions/flash.md)
+   1. [Dry Schema](/docs/extensions/dry_schema.md)
+   1. [Dry View](/docs/extensions/dry_view.md)
+   1. [Params](/docs/extensions/params.md)
+   1. [Redirect](/docs/extensions/redirect.md)
+   1. [Router params](/docs/extensions/router_params.md)
+   1. [Session](/docs/extensions/session.md)
+   1. [URL](/docs/extensions/url.md)
+1. Recipes
+   1. [dry-rb integration](/docs/recipes/dry_rb_integration.md)
+   1. [hanami-router integration](/docs/recipes/hanami_router_integration.md)
+   1. [Using all RESTful methods](/docs/recipes/using_all_restful_methods.mb)
 
 ```ruby
 # config.ru
-require "web_pipe"
+require 'web_pipe'
 
-UsersRepo = {
-  1 => { name: 'Alice', admin: true },
-  2 => { name: 'Joe', admin: false }
-}
+WebPipe.load_extensions(:params)
 
-class GreetingAdminApp
+class HelloApp
   include WebPipe
-
-  plug :set_content_type
-  plug :fetch_user
+  
+  AUTHORIZED_USERS = %w[Alice Joe]
+  
+  plug :html
   plug :authorize
   plug :greet
-
+  
   private
-
-  def set_content_type(conn)
-    conn.add_response_header(
-      'Content-Type', 'text/html'
-    )
-  end
-
-  def fetch_user(conn)
-    user = UsersRepo[conn.params['id'].to_i]
-    if user
-      conn.
-        add(:user, user)
-    else
-      conn.
-        set_status(404).
-        set_response_body('<h1>Not foud</h1>').
-        halt
-    end
+  
+  def html(conn)
+    conn.add_response_header('Content-Type', 'text/html')
   end
-
+  
   def authorize(conn)
-    if conn.fetch(:user)[:admin]
-      conn
+    user = conn.params['user']
+    if AUTHORIZED_USERS.include?(user)
+      conn.add(:user, user)
     else
       conn.
         set_status(401).
-        set_response_body('<h1>Unauthorized</h1>').
+        set_response_body('<h1>Not authorized</h1>').
         halt
     end
   end
   
   def greet(conn)
-    conn.
-      set_response_body("<h1>Hello #{conn.fetch(:user)[:name]}</h1>")
-  end
-end
-
-run GreetingAdminApp.new
-```
-
-As you see, steps required are:
-
-- Include `WebPipe` in a class.
-- Specify the stack of operations with `plug`.
-- Implement those operations.
-- Initialize the class to obtain resulting rack application.
-
-`WebPipe::Conn` is a struct of request and response date, seasoned
-with methods that act on its data. These methods are designed to
-return a new instance of the struct each time, so they encourage
-immutability and make method chaining possible.
-
-Each operation in the pipe must accept a single argument of a
-`WebPipe::Conn` instance and it must also return an instance of it.
-In fact, what the first operation in the pipe takes is a
-`WebPipe::Conn::Ongoing` subclass instance. When one of your operations
-calls `#halt` on it, a `WebPipe::Conn::Halted` is returned and the pipe
-is halted. This one or the 'ongoing' instance that reaches the end of
-the pipe will be in command of the web response.
-
-Operations have the chance to prepare data to be consumed by
-downstream operations. Data can be added to the struct through
-`#add(key, value)`, while it can be consumed with `#fetch(key)`.
-
-Attributes and methods in `WebPipe::Conn` are [fully
-documented](https://www.rubydoc.info/github/waiting-for-dev/web_pipe/master/WebPipe/Conn).
-
-### Specifying operations
-
-There are several ways you can `plug` operations to the pipe:
-
-#### Instance methods
-
-Operations can be just methods defined in the pipe class. This is what
-you saw in the previous example:
-
-```ruby
-class App
-  include WebPipe
-
-  plug :hello
-
-  private
-
-  def hello(conn)
-    # ...
-  end
-```
-
-#### Proc (or anything responding to `#call`)
-
-Operations can also be defined inline as anything that responds to
-`#call`, like a `Proc`, or also like a block:
-
-```ruby
-class App
-  include WebPipe
-
-  plug :hello, ->(conn) { conn }
-  plug(:hello2) { |conn| conn }
-end
-```
-
-The representation of a `WebPipe` as a Proc is itself an operation
-accepting a `Conn` and returning a `Conn`: the composition of all its
-plugs. Therefore, it can be plugged to any other `WebPipe`:
-
-```ruby
-class HtmlApp
-  include WebPipe
-
-  plug :html
-
-  private
-
-  def html(conn)
-    conn.add_response_header('Content-Type', 'text/html')
+    conn.set_response_body("<h1>Hello #{conn.fetch(:user)}</h1>")
   end
 end
 
-class App
-  include WebPipe
-
-  plug :html, HtmlApp.new
-  plug :body
-
-  private
-
-  def body(conn)
-     conn.set_response_body('Hello, world!')
-  end
-end
-```
-
-#### Container
-
-When a `String` or a `Symbol` is given, it can be used as the key to
-resolve an operation from a container. A container is just anything
-responding to `#[]`.
-
-The container to be used is configured when you include `WebPipe`:
-
-```ruby
-class App
-  Container = Hash[
-    'plugs.hello' => ->(conn) { conn }
-  ]
-
-  include WebPipe.(container: Container)
-
-  plug :hello, 'plugs.hello'
-end
+run HelloApp.new
 ```
 
-### Operations injection
-
-Operations can be injected when the application is initialized,
-overriding those configured through `plug`:
-
-```ruby
-class App
-  include WebPipe
-
-  plug :hello, ->(conn) { conn.set_response_body('Hello') }
-end
-
-run App.new(plugs: {
-    hello: ->(conn) { conn.set_response_body('Injected') }
-  }
-)
-```
-
-In the previous example, resulting response body would be `Injected`.
-
-### Rack middlewares
-
-Rack middlewares can be added to the generated application through
-`use`. They will be executed in declaration order before the pipe of
-plugs:
-
-```ruby
-class App
-  include WebPipe
-
-  use :middleware_1, Middleware1
-  use :middleware_1, Middleware2, option_1: value_1
-
-  plug :hello, ->(conn) { conn }
-end
-```
-
-It is also possible to compose all the middlewares from another pipe
-class. Extending from previous example:
-
-```ruby
-class App2
-  include WebPipe
-
-  use :app, App.new # it will also use Middleware1 and Middleware2
-
-  plug :hello, ->(conn) { conn }
-end
-```
-
-Middlewares can also be injected on initialization:
-
-```ruby
-App.new(middlewares: {
-  middleware_1: [AnotherMiddleware, options]
-})
-```
-
-### Standalone usage
-
-If you prefer, you can use the application builder without the
-DSL. For that, you just have to initialize a `WebPipe::App` with an
-array of all the operations to be performed:
-
-```ruby
-require 'web_pipe/app`
-
-op_1 = ->(conn) { conn.set_status(200) }
-op_2 = ->(conn) { conn.set_response_body('Hello') }
-
-WebPipe::App.new([op_1, op_2])
-```
-
-## Plugs
-
-`web_pipe` ships with a series of common operations you can take
-advantage in order to build your application:
-
-- [content_type](lib/web_pipe/plugs/content_type.rb): Sets
-  `Content-Type` response header.
-
-## Extensions
-
-By default, `web_pipe` behavior is the very minimal you need to build
-a web application. However, you can extend it with the following
-extensions (click on each name for details on the usage):
-
-- [container](lib/web_pipe/plugs/container.rb): Allows
-  configuring a container to resolve dependencies.
-- [dry-view](lib/web_pipe/extensions/dry_view/dry_view.rb):
-  Integration with [`dry-view`](https://dry-rb.org/gems/dry-view/)
-  rendering system.
-
 ## Current status
 
 `web_pipe` is in active development. The very basic features to build
@@ -350,4 +100,4 @@ https://github.com/waiting-for-dev/web_pipe.
 
 ## Release Policy
 
-`web_pipe` follows the principles of [semantic versioning](http://semver.org/).
+`web_pipe` follows the principles of [semantic versioning](http://semver.org/).

data/Rakefile

@@ -1,6 +1,8 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "web_pipe"
+require 'bundler/setup'
+require 'web_pipe'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +11,5 @@ require "web_pipe"
 # require "pry"
 # Pry.start
 
-require "pry"
+require 'pry'
 Pry.start

data/docs/_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-slate

data/docs/building_a_rack_application.md

@@ -0,0 +1,25 @@
+# Building a rack application
+
+In order to build a rack application with `web_pipe` you have to include
+`WebPipe` module in a class:
+
+```ruby
+require 'web_pipe'
+
+class MyApp
+  include WebPipe
+
+  # ...
+end
+```
+
+Then, you can plug the operations and add the rack middlewares you need.
+
+The instance of that class will be the rack application:
+
+```ruby
+# config.ru
+require 'my_app'
+
+run MyApp.new
+```

data/docs/composing_applications.md

@@ -0,0 +1,43 @@
+# Composing applications
+
+Previously, we have seen how to [compose plugged
+operations](/docs/plugging_operations/composing_operations.md) and how to [compose
+rack middlewares](/docs/using_rack_middlewares/composing_middlewares.md). The logical
+next step is thinking about composing `web_pipe` applications, which is exactly
+the same as composing both operations and middlewares at the same time.
+
+The DSL method `compose` does exactly that:
+
+```ruby
+class HtmlApp
+  include WebPipe
+  
+  use :session, Rack::Session::Cookie, key: 'my_app.session', secret: 'long'
+  use :csrf, Rack::Csrf, raise: true
+  
+  plug :content_type
+  plug :default_status
+  
+  private
+  
+  def content_type(conn)
+    conn.add_response_header('Content-Type' => 'text/html')
+  end
+  
+  def default_status(conn)
+    conn.set_status(404)
+  end
+end
+
+class MyApp
+  include WebPipe
+  
+  compose :web, HtmlApp.new
+  # It does exactly the same than:
+  # use :web, HtmlApp.new
+  # plug :web, HtmlApp.new
+  
+  # use ...
+  # plug ...
+end
+```

data/docs/connection_struct/configuring_the_connection_struct.md

@@ -0,0 +1,25 @@
+# Configuring the connection struct
+
+[Extensions](/docs/extensions.md) add extra behaviour to the connection struct.
+Sometimes they need some user provided value to work properly or they may allow
+some tweak depending on user needs.
+
+For this reason, you can add configuration data to a `WebPipe::Conn` instance
+so that extensions can fetch it. This shared place where extensions look for
+what they need is `#config` attribute, which is very similar to `#bag` except
+for its more private intention.
+
+In order to interact with `#config`, you can use the method `#add_config(key,
+value)` or [`Config` plug](/docs/plugs/config.md).
+
+```ruby
+class MyApp
+  include WebPipe
+  
+  plug(:config) do |conn|
+    conn.add_config(
+      foo: :bar
+    )
+  end
+end
+```

data/docs/connection_struct/halting_the_pipe.md

@@ -0,0 +1,71 @@
+# Halting the pipe
+
+Each operation in a pipe takes a single `WebPipe::Conn` instance as argument
+and returns another (or same) instance of it. In this way, a series of
+operations on the connection struct is propagated until final response is sent
+to the client.
+
+More often than not, you may need to conditionally stop the propagation of a
+pipe at a given operation. A lot of times the requirement to do something like
+that will be authorization policies. For example, you could fetch the user
+requesting a resource. In the case she was granted to perform required action
+you would go on.  However, if she wasn't you would like to halt the connection
+and respond with a 4xx http status code.
+
+In order to stop the pipe, you simply have to call `#halt` on the connection
+struct.
+
+At implementation level, we must admit that we've not been 100% accurate until
+now. We said that the first operation in the pipe recerived a `WebPipe::Conn`
+instance. That's true. However, it is more precise saying that it gets a
+`WebPipe::Conn::Ongoing` instance (`WebPipe::Conn::Ongoing` being a subclass of
+`WebPipe::Conn`).
+
+As long as an operation responds with a `WebPipe::Conn::Ongoing`
+instance, the propagation will go on. However, when an operation
+returns a `WebPipe::Conn::Halted` instance (another subclass of
+`WebPipe::Conn`) then any operation downstream will be ignored.
+Calling `#halt` simply copies all attributes to a `WebPipe::Conn::Halted`
+instance and returns it.
+
+This made-up example checks if the user in the request has an admin role. If
+she has, it returns solicited resource. Otherwise she is unauthorized and never
+gets the resource.
+
+```ruby
+WebPipe.load_extensions(:params)
+
+class ShowTaskApp
+  include WebPipe
+  
+  plug :fetch_user
+  plug :authorize
+  plug :render_task
+  
+  private
+  
+  def fetch_user(conn)
+    conn.add(
+      :user, UserRepo.find(conn.params[:user_id])
+    )
+  end
+  
+  def authorize(conn)
+    if conn.fetch(:user).admin?
+      conn
+    else
+      conn.
+        set_status(401).
+        halt
+    end
+  end
+  
+  def render_task(conn)
+    conn.set_response_body(
+      TaskRepo.find(conn.params[:id]).to_json
+    )
+  end
+end
+
+run ShowTaskApp.new
+```

data/docs/connection_struct/sharing_data_downstream.md

@@ -0,0 +1,46 @@
+# Sharing data downstream
+
+Usually you'll find the need to prepare some data in one operation with the
+intention for it to be consumed by another downstream operation. The connection
+struct has a `#bag` attribute which is useful for this purpose.
+
+`WebPipe::Conn#bag` is a `Hash` with `Symbol` keys where values can
+be anything you need to share. To help with the process we have following methods:
+
+- `#add(key, value)`: Assigns a value to a key.
+- `#fetch(key)`, `#fetch(key, default)`: Retrieves value associated
+  to given key. If it is not found, `default` is returned when
+  provided.
+
+This is a simple example of a web application which reads a `name`
+parameter and normalizes it before using in the response body.
+
+```ruby
+# config.ru
+require 'web_pipe'
+
+WebPipe.load_extensions(:params)
+
+class NormalizeNameApp
+  include WebPipe
+  
+  plug :normalize_name
+  plug :respond
+  
+  private
+  
+  def normalize_name(conn)
+    conn.add(
+      :name, conn.params[:name].downcase.capitalize
+    )
+  end
+  
+  def respond(conn)
+    conn.set_response_body(
+      conn.fetch(:name)
+    )
+  end
+end
+
+run NormalizeNameApp.new
+```