web_pipe 0.8.0 → 0.9.0

data/docs/introduction.md

@@ -0,0 +1,73 @@
+# Introduction
+
+`web_pipe` is a rack application builder.
+
+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_pipe` applications are built as a [pipe of
+operations](/docs/design_model.md) on an [immutable
+struct](/docs/connection_struct.md). The struct is automatically created
+with data from an HTTP request, and it contains methods to
+incrementally add data to generate an HTTP response. The pipe can
+be [halted](/docs/connection_struct/halting_the_pipe.md) at any moment,
+taking away from all operations downstream any chance to modify the
+response.
+
+`web_pipe` has a modular design, with only the minimal functionalities needed
+to build a web application enabled by default. However, it ships with several
+[extensions](/docs/extensions.md) to make your life easier.
+
+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`.
+
+```ruby
+require 'web_pipe'
+
+WebPipe.load_extensions(:params)
+
+class HelloApp
+  include WebPipe
+  
+  AUTHORIZED_USERS = %w[Alice Joe]
+  
+  plug :html
+  plug :authorize
+  plug :greet
+  
+  private
+  
+  def html(conn)
+    conn.add_response_header('Content-Type', 'text/html')
+  end
+  
+  def authorize(conn)
+    user = conn.params['user']
+    if AUTHORIZED_USERS.include?(user)
+      conn.add(:user, user)
+    else
+      conn.
+        set_status(401).
+        set_response_body('<h1>Not authorized</h1>').
+        halt
+    end
+  end
+  
+  def greet(conn)
+    conn.set_response_body("<h1>Hello #{conn.fetch(:user)}</h1>")
+  end
+end
+
+run HelloApp.new
+``

data/docs/plugging_operations/composing_operations.md

@@ -0,0 +1,36 @@
+# Composing operations
+
+As we already have said, operations are functions taking a connection struct
+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.
+
+```ruby
+class HtmlApp
+  include WebPipe
+  
+  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
+  
+  plug :html, HtmlApp.new
+  # plug ...
+end
+```

data/docs/plugging_operations/injecting_operations.md

@@ -0,0 +1,32 @@
+# Injecting operations
+
+Operations can be injected at the moment an application is initialized,
+which 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.
+
+This 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
+`'Hello from injection'`:
+
+```ruby
+# config.ru
+require 'web_pipe'
+
+class MyApp
+  include WebPipe
+  
+  plug(:hello) do |conn|
+    conn.set_response_body('Hello from definition')
+  end
+end
+
+injection = lambda do |conn|
+  conn.set_response_body('Hello from injection')
+end
+
+run MyApp.new(plugs: { hello: injection })
+```

data/docs/plugging_operations/resolving_operations.md

@@ -0,0 +1,71 @@
+# Resolving operations
+
+There are several ways you can specify how an operation is resolved.
+
+## Instance method
+
+Operations can be plugged as methods (both public and private) in the
+application class:
+
+```ruby
+class MyApp
+  include WebPipe
+  
+  plug :html
+  
+  private
+  
+  def html(conn)
+    conn.add_response_header('Content-Type' => 'text/html')
+  end
+end
+```
+
+## `#call`
+
+Operations can be plugged inline as anything responding to `#call`, like a
+`Proc` or a `lambda`:
+
+```ruby
+class MyApp
+  include WebPipe
+  
+  plug :html, ->(conn) { conn.add_response_header('Content-Type' => 'text/html') }
+end
+```
+
+## Block
+
+In the same way that `#call`, operations can also be plugged inline as blocks:
+
+```ruby
+class MyApp
+  include WebPipe
+  
+  plug :html do |conn|
+    conn.add_response_header('Content-Type' => 'text/html')
+  end
+end
+```
+
+## Container
+
+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:
+
+```ruby
+MyContainer = Hash[
+  'plugs.html' => lambda do |conn|
+    conn.add_response_header('Content-Type' => 'text/html')
+   end
+]
+
+class MyApp
+  include WebPipe.(container: MyContainer)
+  
+  plug :html, 'plugs.html'
+end
+```

data/docs/plugging_operations.md

@@ -0,0 +1,21 @@
+# Plugging operations
+
+You can plug operations to 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](/docs/plugging_operations/injecting_operations.md) on
+initialization).
+
+```ruby
+class MyApp
+  include WebPipe
+  
+  plug :dummy_operation, ->(conn) { conn }
+end
+```
+
+Remember, an operation is just a function (in ruby, anything responding to
+`#call`) that takes a struct with connection information and returns another
+instance of it. First operation in the stack receives a struct which has been
+automatically created with the request data. From then on, any operation can
+add to it response data.

data/docs/plugs/config.md

@@ -0,0 +1,18 @@
+# Config
+
+`Config` plug helps in the addition of configuration settings (`#config` hash
+attribute) to an instance of `WebPipe::Conn`.
+
+```ruby
+require 'web_pipe'
+require 'web_pipe/plugs/config'
+
+class MyApp
+  include WebPipe
+  
+  plug :config, WebPipe::Plugs::Config.(
+    key1: :value1,
+    key2: :value2
+  )
+end
+```

data/docs/plugs/content_type.md

@@ -0,0 +1,16 @@
+# ContentType
+
+`ContentType` plug is just a helper to set `Content-Type` response header.
+
+Example:
+
+```ruby
+require 'web_pipe'
+require 'web_pipe/plugs/content_type'
+
+class MyApp
+  include WebPipe
+  
+  plug :html, WebPipe::Plugs::ContentType.('text/html')
+end
+```

data/docs/plugs.md

@@ -0,0 +1,13 @@
+# Plugs
+
+Some group of operations can be generalized as following 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.
+
+Being just functions, we take as convention that plugs respond to `#call` in
+order to create an operation.
+
+This library ships with some useful plugs.

data/docs/recipes/dry_rb_integration.md

@@ -0,0 +1,18 @@
+# dry-rb integration
+
+`web_pipe` has been designed to integrate smoothly with
+[dry-rb](https://dry-rb.org/) ecosystem. It shares same design
+principles and it ships with some extensions which even make this
+integration tighter (like
+[`:dry-view`](/docs/extensions/dry_view.md) or
+[`:dry-schema`](/docs/extensions/dry_schema.md) extensions).
+
+If you want to use `web_pipe` with the rest of dry-rb libraries,
+your best bet is to use
+[`dry-web-web_pipe`](https://github.com/waiting-for-dev/dry-web-web_pipe)
+skeleton generator. It is a fork of
+[`dry-web-roda`](https://github.com/dry-rb/dry-web-roda) with
+`roda` dependency switched to a combination of `web_pipe` and
+[`hanami-router`](https://github.com/hanami/router).
+
+Look at `dry-web-web_pipe` README for more details.

data/docs/recipes/hanami_router_integration.md

@@ -0,0 +1,25 @@
+# hanami-router integration
+
+A `web_pipe` application instance is a rack application.
+Consequently, you can mount it with `hanami-router`'s' `to:`
+option.
+
+```ruby
+# config.ru
+require 'hanami/router'
+require 'web_pipe'
+
+class MyApp
+  include WebPipe
+  
+  plug :this, ->(conn) { conn.set_response_body('This') }
+end
+
+router = Hanami::Router.new do
+  get 'my_app', to: MyApp.new
+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](/docs/extensions/router_params.md).

data/docs/recipes/using_all_restful_methods.md

@@ -0,0 +1,25 @@
+# Using all RESTful methods
+
+As you probably know, a lot of 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
+request method in rack's env if a magical `_method` parameter or
+`HTTP_METHOD_OVERRIDE` request header is found.
+
+You have to be aware that if you use this middleware within a
+`web_pipe` application (through [`use` DSL
+method](docs/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
+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`:
+
+```ruby
+# config.ru
+
+use Rack::MethodOverride
+
+# Load your router and map to web_pipe applications
+```

data/docs/using_rack_middlewares/composing_middlewares.md

@@ -0,0 +1,26 @@
+# Composing middlewares
+
+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.
+
+```ruby
+class HtmlApp
+  include WebPipe
+  
+  use :session, Rack::Session::Cookie, key: 'my_app.session', secret: 'long'
+  use :csrf, Rack::Csrf, raise: true
+end
+
+class MyApp
+  include WebPipe
+  
+  use :html, HtmlApp.new
+  # use ...
+  
+  # plug ...
+end
+```

data/docs/using_rack_middlewares/injecting_middlewares.md

@@ -0,0 +1,47 @@
+# Injecting middlewares
+
+Middlewares can be injected at the moment an application is initialized,
+allowing you to override what you have defined in the DSL.
+
+For that purpose, you have to use `middlewares:` keyword argument. It must be a
+hash where middlewares are matched by the name you gave them in its definition.
+
+A middleware must be specified as an `Array`. First item must be a rack
+middleware class. The rest of arguments (if any) should be any option it may
+need.
+
+This is mainly useful for testing purposes, where you can switch a heavy
+middleware and use a mocked one instead.
+
+In the following example, rack session mechanism is being mocked:
+
+```ruby
+# config.ru
+require 'web_pipe'
+require 'rack/session/cookie'
+
+class MyApp
+  include WebPipe
+  
+  use :session, Rack::Session::Cookie, key: 'my_app.session', secret: 'long'
+  
+  plug(:serialize_session) do |conn|
+    conn.set_response_body(conn.env['rack.session'].inspect)
+  end
+end
+
+class MockedSession
+  attr_reader :app, :key
+  
+  def initialize(app, key)
+    @app = app
+    @key = key
+  end
+  
+  def call(env)
+    env['rack.session'] = "Mocked for '#{key}' key"
+  end
+end
+
+run MyApp.new(middlewares: { session: [MockedSession, 'my_app_mocked'] })
+```

data/docs/using_rack_middlewares.md

@@ -0,0 +1,22 @@
+# Using rack middlewares
+
+A one-way pipe like the one `web_pipe` implements can deal with any required
+feature in a web application. However, usually it is convenient to be able to
+use some well-known rack middleware so you don't have to reinvent the wheel.
+Even if you can add them at the router layer, `web_pipe` allows you to
+encapsulate them in your application definition.
+
+In order to add rack middlewares to the stack, you have to use the DSL method
+`use`. The first argument it takes is a `Symbol` with the name you want to
+assign to it (which is needed to allow
+[injection](/docs/using_rack_middlewares/injecting_middlewares.md) on
+initialization). Then, it must follow the middleware class and any option it
+may need:
+
+```ruby
+class MyApp
+  include WebPipe
+  
+  use :cookies, Rack::Session::Cookie, key: 'my_app.session', secret: 'long'
+end
+```

data/lib/web_pipe/app.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'web_pipe/types'
 require 'web_pipe/conn'
 require 'web_pipe/conn_support/builder'
@@ -55,7 +57,7 @@ module WebPipe
     private
 
     def conn_from_env(env)
-      ConnSupport::Builder.(env)
+      ConnSupport::Builder.call(env)
     end
 
     def apply_operations(conn)
@@ -66,4 +68,4 @@ module WebPipe
       conn.rack_response
     end
   end
-end
+end

data/lib/web_pipe/conn.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'dry/struct'
 require 'web_pipe/types'
 require 'web_pipe/conn_support/types'
@@ -315,7 +317,7 @@ module WebPipe
     def fetch(key, default = Types::Undefined)
       return bag.fetch(key, default) unless default == Types::Undefined
 
-      bag.fetch(key) { raise ConnSupport::KeyNotFoundInBagError.new(key) }
+      bag.fetch(key) { raise ConnSupport::KeyNotFoundInBagError, key }
     end
 
     # Writes an item to the {#bag}.
@@ -343,7 +345,7 @@ module WebPipe
     def fetch_config(key, default = Types::Undefined)
       return config.fetch(key, default) unless default == Types::Undefined
 
-      config.fetch(key) { raise ConnSupport::KeyNotFoundInConfigError.new(key) }
+      config.fetch(key) { raise ConnSupport::KeyNotFoundInConfigError, key }
     end
 
     # Writes an item to {#config}.
@@ -402,4 +404,4 @@ module WebPipe
     # cycle.
     class Halted < Conn; end
   end
-end
+end

data/lib/web_pipe/conn_support/builder.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rack'
 require 'web_pipe/conn'
 require 'web_pipe/conn_support/headers'

data/lib/web_pipe/conn_support/composition.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'dry/monads/result'
 require 'web_pipe/types'
 require 'web_pipe/conn'
@@ -27,10 +29,10 @@ module WebPipe
         def initialize(returned)
           super(
             <<~eos
-            An operation returned +#{returned.inspect}+. To be valid,
-            an operation must return whether a
-            WebPipe::Conn::Ongoing or a WebPipe::Conn::Halted.
-          eos
+              An operation returned +#{returned.inspect}+. To be valid,
+              an operation must return whether a
+              WebPipe::Conn::Ongoing or a WebPipe::Conn::Halted.
+            eos
           )
         end
       end
@@ -66,14 +68,14 @@ module WebPipe
       end
 
       def apply_operation(conn, operation)
-        result = operation.(conn)
+        result = operation.call(conn)
         case result
         when Conn::Ongoing
           Success(result)
         when Conn::Halted
           Failure(result)
         else
-          raise InvalidOperationResult.new(result)
+          raise InvalidOperationResult, result
         end
       end
 
@@ -84,4 +86,4 @@ module WebPipe
       end
     end
   end
-end
+end

data/lib/web_pipe/conn_support/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module WebPipe
   module ConnSupport
     # Error raised when trying to fetch an entry in {Conn#bag} for an
@@ -42,4 +44,4 @@ module WebPipe
       end
     end
   end
-end
+end

data/lib/web_pipe/conn_support/headers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module WebPipe
   module ConnSupport
     # Helpers to work with headers and its rack's env representation.
@@ -12,7 +14,7 @@ module WebPipe
       #
       # Headers are all those pairs which key begins with `HTTP_` plus
       # those detailed in {HEADERS_AS_CGI}.
-      # 
+      #
       # @param env [Types::Env[]]
       #
       # @return [Types::Headers[]]
@@ -21,14 +23,14 @@ module WebPipe
       # @see .normalize_key
       def self.extract(env)
         Hash[
-          env.
-            select { |k, _v| k.start_with?('HTTP_') }.
-            map { |k, v| pair(k[5 .. -1], v) }.
-            concat(
-              env.
-                select { |k, _v| HEADERS_AS_CGI.include?(k) }.
-                map { |k, v| pair(k, v) }
-            )
+          env
+          .select { |k, _v| k.start_with?('HTTP_') }
+          .map { |k, v| pair(k[5..-1], v) }
+          .concat(
+            env
+              .select { |k, _v| HEADERS_AS_CGI.include?(k) }
+              .map { |k, v| pair(k, v) }
+          )
         ]
       end
 
@@ -103,4 +105,4 @@ module WebPipe
       end
     end
   end
-end
+end

data/lib/web_pipe/conn_support/types.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'dry/types'
 require 'rack/request'
 
@@ -25,18 +27,18 @@ module WebPipe
       QueryString = Strict::String
       RequestBody = Interface(:gets, :each, :read, :rewind)
 
-      Status = Strict::Integer.
-                 default(200).
-                 constrained(gteq: 100, lteq: 599)
+      Status = Strict::Integer
+               .default(200)
+               .constrained(gteq: 100, lteq: 599)
       ResponseBody = Interface(:each).default { [''] }
 
-      Headers = Strict::Hash.
-                  map(Strict::String, Strict::String).
-                  default { {} }
+      Headers = Strict::Hash
+                .map(Strict::String, Strict::String)
+                .default { {} }
 
-      Bag = Strict::Hash.
-              map(Strict::Symbol, Strict::Any).
-              default { {} }
+      Bag = Strict::Hash
+            .map(Strict::Symbol, Strict::Any)
+            .default { {} }
     end
   end
 end

data/lib/web_pipe/dsl/builder.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'web_pipe/types'
 require 'web_pipe/dsl/class_context'
 require 'web_pipe/dsl/instance_methods'
@@ -12,7 +14,7 @@ module WebPipe
     class Builder < Module
       # Container with nothing registered.
       EMPTY_CONTAINER = Types::EMPTY_HASH
-      
+
       # @!attribute [r] container
       # @return [Types::Container[]]
       attr_reader :container
@@ -24,11 +26,11 @@ module WebPipe
         @container = Types::Container[container]
         @class_context = ClassContext.new(container: container)
       end
-      
+
       def included(klass)
         klass.extend(class_context)
         klass.include(InstanceMethods)
       end
     end
   end
-end
+end