web_pipe 0.8.0 → 0.9.0

data/docs/connection_struct.md

@@ -0,0 +1,77 @@
+# Connection struct
+
+First operation you plug in a `web_pipe` application receives an instance of
+`WebPipe::Conn` which has been automatically created.
+
+This is just a struct data type which contains all the information from current
+web request. In this regard, you can think of it as a structured rack's env
+hash.
+
+Request related attributes of this struct are:
+
+- `#scheme`: `:http` or `:https`.
+- `#request_method`: `:get`, `:post`...
+- `#host`: e.g. `'www.example.org'`.
+- `#ip`:  e.g. `'192.168.1.1'`.
+- `#port`: e.g. `80` or `443`.
+- `#script_name`: e.g. `'index.rb'`.
+- `#path_info`: e.g. `'/foor/bar'`.
+- `#query_string`: e.g. `'foo=bar&bar=foo'`
+- `#request_body`: e.g. `'{ id: 1 }'`
+- `#request_headers`: e.g. `{ 'Accept-Charset' => 'utf8' }`
+- `#env`: Rack's env hash.
+- `#request`: Rack::Request instance.
+
+Your operations must return another (or same) instance of the struct, which
+will be consumed by next operation downstream. The struct contains methods to
+add response data to it:
+
+- `#set_status(code)`: makes it accessible in `#status` attribute.
+- `#set_response_body(body)`: makes it accessible in `#response_body`
+  attribute.
+- `#set_response_headers(headers)`: makes them accessible in
+  `#response_headers` attribute. Besides, there are also
+  `#add_response_header(key, value)` and `#delete_response_header(key)`
+  methods.
+
+Response in last struct returned in the pipe will be what is sent to client.
+
+Every attribute and method is [fully
+documented](https://www.rubydoc.info/github/waiting-for-dev/web_pipe/master/WebPipe/Conn)
+in code documentation.
+
+Here we have a contrived web application which just returns as response body
+the request body it has received:
+
+```ruby
+# config.ru
+require 'web_pipe'
+
+class DummyApp
+  include WebPipe
+  
+  plug :build_response
+  
+  private
+  
+  def build_response(conn)
+    conn.
+      set_status(200).
+      add_response_header('Content-Type', 'text/html').
+      set_response_body(
+        "<p>#{conn.request_body}</p>"
+      )
+  end
+end
+
+run DummyApp.new
+```
+
+As you can see, default available features are the very minimal to read from a
+request and to write a response. However, you can pick from several
+(extensions)[/docs/extensions.md] which will make your life much easier.
+
+Immutability is a core design principle in `web_pipe`. All methods in
+`WebPipe::Conn` which are used to add data to it (both in core behaviour and
+extensions) return a fresh new instance. It also makes possible chaining
+methods in a very readable way.

data/docs/design_model.md

@@ -0,0 +1,44 @@
+# Design model
+
+If you are familiar with rack you know that it models a two-way pipe. In it,
+each middleware has the ability to:
+
+- During the outbound trip modifying the request as it heads to the actual
+  application.
+
+- During the return trip modifying the response as it gets back from the
+  application.
+
+```
+
+  --------------------->  request ----------------------->
+
+  Middleware 1          Middleware 2          Application
+
+  <--------------------- response <-----------------------
+
+
+```
+
+`web_pipe` follows a simpler but equally powerful model: a one-way pipe which
+is abstracted on top of rack. A struct that contains data from a web request is
+piped trough a stack of operations (functions). Each operation takes as
+argument an instance of the struct and returns also an instance of it.
+Response data can be added to the struct at any moment in the pipe.
+
+```
+
+  Operation 1          Operation 2          Operation 3
+
+  --------------------- request/response ---------------->
+
+```
+
+Additionally, any operation in the stack can halt the propagation of the pipe,
+leaving downstream operations unexecuted. In this way, final response is the
+one contained in the struct at the moment the pipe was halted, or last one if
+the pipe wasn't halted.
+
+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.

data/docs/dsl_free_usage.md

@@ -0,0 +1,26 @@
+# DSL free usage
+
+DSL's (like the one in `web_pipe` with methods like `plug` or
+`use`) provide developers with a user friendly and ergonomic way to
+use a library. However, they usually come at expenses of increasing complexity
+in internal code (which sooner than later translates into some kind of issue).
+
+`web_pipe` has tried to do an extra effort to minimize these problems. For this
+reason, DSL in this library is just a layer on top of an independent core
+functionality.
+
+To use `web_pipe` without its DSL layer, you just need to initialize a
+`WebPipe::App` instance with an array of all the operations that otherwise
+you'd `plug`. That instance will be a rack application ready to be used.
+
+```ruby
+# config.ru
+require 'web_pipe/app'
+
+op_1 = ->(conn) { conn.set_status(200) }
+op_2 = ->(conn) { conn.set_response_body('Hello, World!') }
+
+app = WebPipe::App.new([op_1, op_2])
+
+run app
+```

data/docs/extensions/container.md

@@ -0,0 +1,41 @@
+# Container
+
+`:container` is a very simple extension which allows you to configure a
+dependency injection container to be accessible from a `WebPipe::Conn`
+instance.
+
+The container to use must be configured under `:configuration` key. It will be
+accessible through the `#container` method.
+
+You may be thinking why you should worry about configuring a container for a
+connection instance when you already have access to the container configured
+for an application (from where you can resolve plugged operations). The idea
+here is decoupling operations from application DSL. If at anytime in the future
+you decide to get rid off the DSL, the process will be straightforward if
+operations are using the container configured in a connection instance.
+
+```ruby
+require 'web_pipe'
+require 'web_pipe/plugs/config'
+require 'my_container'
+
+WebPipe.load_extensions(:container)
+
+class MyApp
+  include WebPipe.(container: MyContainer)
+  
+  plug :config, WebPipe::Plugs::Config.(
+    container: MyContainer
+  )
+  plug :this, :this # Resolved thanks to the container in `include`
+  plug :that
+  
+  private
+  
+  def that(conn)
+    conn.set_response_body(
+      conn.container['do'].() # Resolved thanks to the container in `:config`
+    )
+  end
+end
+```

data/docs/extensions/cookies.md

@@ -0,0 +1,47 @@
+# Cookies
+
+Extension helping to deal with request and response cookies.
+
+Remember, cookies are just the value of `Set-Cookie` header.
+
+This extension adds following methods:
+
+- `#request_cookies`: Returns request cookies
+
+- `#set_cookie(key, value)` or `#set_cookie(key, value, options)`: Instructs
+  browser to add a new cookie with given key and value.
+  
+  Some options can be given as keyword arguments (see [MDN reference on
+  cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) for an
+  explanation):
+
+  - `domain:` must be a string.
+  - `path:` must be a string.
+  - `max_age:` must be an integer with the number of seconds.
+  - `expires:` must be a `Time`.
+  - `secure:` must be `true` or `false`.
+  - `http_only:` must be `true` or `false`.
+  - `same_site:` must be one of the symbols `:none`, `:lax` or `:strict`.
+
+- `#delete_cookie(key)` or `#delete_cookie(key, options)`: Instructs browser to
+  delete a previously sent cookie. Deleting a cookie just means setting again
+  the same key with an expiration time in the past.
+  
+  It accepts `domain:` and `path:` options (see above for a description of
+  them).
+
+Example:
+  
+```ruby
+require 'web_pipe'
+
+WebPipe.load_extensions(:cookies)
+
+class MyApp
+  include WebPipe
+  
+  plug(:set_cookie) do |conn|
+    conn.set_cookie('foo', 'bar', secure: true, http_only: true)
+  end
+end
+```

data/docs/extensions/dry_schema.md

@@ -0,0 +1,51 @@
+# Dry Schema
+
+Extension providing integration for a common
+[`dry-schema`](https://dry-rb.org/gems/dry-schema/) workflow to validate
+parameters.
+
+A plug `WebPipe::Plugs::SanitizeParams` is added so that you can use it in your
+pipe of operations. It takes as arguments a `dry-schema` schema and a handler.
+On success, it makes output available at `WebPipe::Conn#sanitized_params`. On
+error, it calls given handler with the connection struct and validation result.
+
+This extension automatically loads [`:params` extension](/docs/extensions/params.md),
+as it takes `WebPipe::Conn#params` as input for the validation schema.
+
+Instead of providing an error handler as the second argument for the plug, you
+can configure it under `:param_sanitization_handler` key. In this way, it can
+be reused through composition by others applications.
+
+```ruby
+require 'db'
+require 'dry/schema'
+require 'web_pipe'
+require 'web_pipe/plugs/config'
+
+WebPipe.load_extensions(:dry_schema)
+
+class MyApp
+  include WebPipe
+  
+  Schema = Dry::Schema.Params do
+    required(:name).filled(:string)
+  end
+  
+  plug :config, WebPipe::Plugs::Config.(
+    param_sanitization_handler: lambda do |conn, result|
+      conn.
+        set_status(500).
+        set_response_body('Error with request parameters').
+        halt
+    end
+  )
+  
+  plug :sanitize_params, WebPipe::Plugs::SanitizeParams.(
+    Schema
+  )
+  
+  plug(:this) do |conn|
+    DB.persist(:entity, conn.sanitized_params)
+  end
+end
+```

data/docs/extensions/dry_view.md

@@ -0,0 +1,113 @@
+# Dry 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.
+
+`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
+exposures or options it may need:
+
+```ruby
+require 'web_pipe'
+require 'dry/view'
+require 'my_context'
+
+WebPipe.load_extensions(:dry_view)
+
+class SayHelloView < Dry::View
+  config.paths = [File.join(__dir__, '..', 'templates')]
+  config.template = 'say_hello'
+  config.default_context = MyContext
+
+  expose :name
+end
+    
+class MyApp
+  include WebPipe
+
+  plug :render
+  
+  private
+  
+  def render(conn)
+    conn.view(SayHelloView.new, name: 'Joe')
+  end
+end
+```
+
+However, you can resolve a view from a container if you also use (`:container`
+extension)[/docs/extensions/container.md]:
+
+```ruby
+require 'dry_view'
+require 'my_container'
+require 'web_pipe'
+require 'web_pipe/plugs/config'
+
+WebPipe.load_extensions(:dry_view, :container)
+
+class MyApp
+ include WebPipe
+
+ plug :config, WebPipe::Plugs::Config.(
+   container: MyContainer
+ )
+ plug :render
+
+ def render(conn)
+   conn.view('views.say_hello', name: 'Joe')
+ end
+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.
+
+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):
+
+```ruby
+require 'dry/view/context'
+require 'my_import'
+
+class MyContext < Dry::View::Context
+ include MyImport::Import[:current_path]
+ 
+ # Without `dry-auto_inject` you have to manually specify dependencies and
+ # override the initializer:
+ #
+ # attr_reader :current_path
+ # 
+ # def initialize(current_path:, **options)
+ #   @current_path = current_path
+ #   super
+ # end
+end
+```
+
+Then, you have to configure a `:view_context` setting, which must be a lambda
+accepting a `WebPipe::Conn` instance and returning a hash matching required
+dependencies:
+
+```ruby
+require 'web_pipe'
+require 'web_pipe/plugs/config'
+
+WebPipe.load_extensions(:url)
+
+class MyApp
+  include WebPipe
+  
+  plug :config, WebPipe::Plugs::Config.(
+    view_context: ->(conn) { { current_path: conn.full_path} }
+  )
+  plug(:render) do |conn|
+    conn.view(SayHelloView.new, name: 'Joe')
+    # `:current_path` will be provided to the context
+  end
+end
+```

data/docs/extensions/flash.md

@@ -0,0 +1,41 @@
+# Flash
+
+This extension provides with typical flash messages functionality. Messages for
+users are stored in session in order to be consumed by another request after a
+redirect.
+
+This extension depends on
+[`Rack::Flash`](https://rubygems.org/gems/rack-flash3) (gem name is
+`rack-flash3`) and `Rack::Session` (shipped with rack) middlewares.
+
+`WebPipe::Conn#flash` contains the flash bag. In order to add a message to it,
+you can use `#add_flash(key, value)` method.
+
+There is also an `#add_flash_now(key, value)` method, which is used to add a
+message to the bag with the intention for it to be consumed in the current
+request. Be aware that it is in fact a coupling with the view layer.
+Something that has to be consumed in the current request should be just data
+given to the view layer, but it helps when it can treat both scenarios as flash
+messages.
+
+```ruby
+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') }
+  
+  # Usually you will end up making `conn.flash` available to your view
+  # system:
+  #
+  # <div class="notice"><%= flash[:notice] %></div>
+ end
+```

data/docs/extensions/params.md

@@ -0,0 +1,117 @@
+# Params
+
+This extension adds a `WebPipe::Conn#params` method which returns
+request parameters as a Hash where any number of transformations
+can be configured.
+
+When no transformations are configured, `#params` just returns GET and POST parameters as a hash:
+
+```ruby
+# http://www.example.com?foo=bar
+conn.params # => { 'foo' => 'bar' }
+```
+
+You can configure a stack of transformations to be applied to the
+parameter hash. For that, we lean on [`transproc`
+gem](https://github.com/solnic/transproc) (you have to add it yourself to your
+Gemfile). All hash transformations in `transproc` are available by default.
+
+Transformations must be configured under `:param_transformations`
+key:
+
+```ruby
+require 'web_pipe'
+require 'web_pipe/plugs/config'
+
+WebPipe.load_extensions(:params)
+
+class MyApp
+  incude WebPipe
+  
+  plug :config, WebPipe::Plugs::Config.(
+    param_transformations: [:deep_symbolize_keys]
+  )
+
+  plug(:this) do |conn|
+    # http://www.example.com?foo=bar
+    conn.params => # => { foo: 'bar' }
+    # ...
+  end
+end
+```
+
+Extra needed arguments can be provided as an array:
+
+```ruby
+# ...
+plug :config, WebPipe::Plugs::Config.(
+  param_transformations: [
+    :deep_symbolize_keys, [:reject_keys, [:zoo]]
+  ]
+)
+
+plug(:this) do |conn|
+  # http://www.example.com?foo=bar&zoo=zoo
+  conn.params => # => { foo: 'bar' }
+  # ...
+end
+# ...
+```
+
+Custom transformations can be registered in `WebPipe::Params::Transf` `transproc` register:
+
+```ruby
+fake = ->(_params) { { fake: :params } }
+WebPipe::Params::Transf.register(:fake, fake)
+
+# ...
+plug :config, WebPipe::Plugs::Config.(
+  param_transformations: [:fake]
+)
+
+plug(:this) do |conn|
+  # http://www.example.com?foo=bar
+  conn.params => # => { fake: :params }
+  # ...
+end
+# ...
+```
+
+Your own transformation functions can depend on the `WebPipe::Conn`
+instance at the moment of calling `#params`. Those functions must accept
+the connection struct as its last argument:
+
+```ruby
+add_name = ->(params, conn) { params.merge(name: conn.fetch(:name)) }
+WebPipe::Params::Transf.register(:add_name, add_name)
+
+# ...
+plug :config, WebPipe::Plugs::Config.(
+  param_transformations: [:deep_symbolize_keys, :add_name]
+)
+
+plug(:add_name) do |conn|
+  conn.add(:name, 'Alice')
+end
+
+plug(:this) do |conn|
+  # http://www.example.com?foo=bar
+  conn.params => # => { foo: :bar, name: 'Alice' }
+  # ...
+end
+# ...
+```
+Finally, you can override configured transformations injecting another set at the moment of calling `#params`:
+
+```ruby
+# ...
+plug :config, WebPipe::Plugs::Config.(
+  param_transformations: [:deep_symbolize_keys]
+)
+
+plug(:this) do |conn|
+  # http://www.example.com?foo=bar&zoo=zoo
+  conn.params([:reject_keys, ['zoo']]) => # => { 'foo' => 'zoo' }
+  # ...
+end
+# ...

data/docs/extensions/redirect.md

@@ -0,0 +1,25 @@
+# Redirect
+
+This extension helps with creating a redirect response.
+
+Redirect responses consist of two pieces:
+
+- `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`.
+
+```ruby
+require 'web_pipe'
+
+WebPipe.load_extensions(:redirect)
+
+class MyApp
+  include WebPipe
+
+  plug(:redirect) do |conn|
+    conn.redirect('/')
+  end
+end
+```

data/docs/extensions/router_params.md

@@ -0,0 +1,40 @@
+# Router params
+
+This extension can be used in order to merge placeholder parameters
+that usually routers support (like `get /users/:id`) to the parameters hash
+added through [`:params` extension](/docs/extensions/params.md) (which is
+automatically loaded).
+
+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
+`router.params` key.
+
+It automatically integrates with
+[`hanami-router`](https://github.com/hanami/router).
+
+Don't forget that you have to add yourself the `:router_params`
+transformation to the stack.
+
+```ruby
+require 'web_pipe'
+require 'web_pipe/plugs/config'
+
+WebPipe.load_extensions(:router_params)
+
+class MyApp
+  include WebPipe
+
+  plug :config, WebPipe::Plugs::Config.(
+    param_transformations: [:router_params, :deep_symbolize_keys]
+  )
+  plug :this
+
+  private
+
+  def this(conn)
+    # http://example.com/users/1/edit
+    conn.params # => { id: 1 }
+    # ...
+  end
+end
+```

data/docs/extensions/session.md

@@ -0,0 +1,39 @@
+# Session
+
+Wrapper around `Rack::Session` middleware to help working with
+sessions in your plugged operations.
+
+It depends on `Rack::Session` middleware, which is shipped by rack.
+
+It adds following methods to `WebPipe::Conn`:
+
+- `#fetch_session(key)`, `#fetch_session(key, default)` or
+  `#fetch_session(key) { default }`. Returns what is stored under
+  given session key. A default value can be given as a second
+  argument or a block.
+- `#add_session(key, value)`. Adds given key/value pair to the
+  session.
+- `#delete_session(key)`. Deletes given key from the session.
+- `#clear_session`. Deletes everything from the session.
+
+```ruby
+require 'web_pipe'
+require 'rack/session'
+
+WebPipe.load_extensions(:session)
+
+class MyApp
+  include WebPipe
+  
+  use Rack::Session::Cookie, secret: 'top_secret'
+  
+  plug(:add_to_session) do |conn|
+    conn.add_session('foo', 'bar')
+  end
+  plug(:fetch_from_session) do |conn|
+    conn.add(
+      :foo, conn.fetch_session('foo')
+    )
+  end
+end
+```

data/docs/extensions/url.md

@@ -0,0 +1,11 @@
+# URL
+
+`:url` extension just adds a few methods which cook raw request information
+about the URL into something more digestible.
+
+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'`.

data/docs/extensions.md

@@ -0,0 +1,13 @@
+# 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.
+
+In order to load the extensions, you have to call
+`#load_extensions` method in `WebPipe`:
+
+```ruby
+WebPipe.load_extensions(:params, :cookies)
+```