web_pipe 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 617c24131c1091c3ec7fb214f8f90af0f6fd199d2684ee8b71e08ac373f9795a
+  data.tar.gz: 68a73cfff54e49580ea8426265579ece63e3abbe78dd93b84862cee86017ba19
+SHA512:
+  metadata.gz: aee8034e0eff973a91df4bed368f459cd841a3ea7de448b584bfef7f7d995f519ea3201bfd3f16290fb6692bf5fe8ab9bfe5d37d443eeb75581127adc3de3cee
+  data.tar.gz: 452773b224c0affce8aeed40251f25835cfea045208d4ba92aeb076d2a3b888df6171cfb7d5323c8d16b5ab8eb830d649d8add14fc17b1c24339957266d7de65

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,10 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.4
+  - 2.5
+  - 2.6
+before_install:
+  - gem update --system --no-doc
+script:
+  - bundle exec rspec

data/.yardopts

@@ -0,0 +1,8 @@
+--title 'web_pipe'
+--embed-mixins
+--output doc
+--readme README.md
+--files CHANGELOG.md
+--markup markdown
+--markup-provider=redcarpet
+lib/**/*.rb

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Change Log
+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.0.1] - 2019-05-07
+### Added
+- Initial release.

data/Gemfile

@@ -0,0 +1,6 @@
+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/Gemfile.lock

@@ -0,0 +1,91 @@
+PATH
+  remote: .
+  specs:
+    web_pipe (0.1.0)
+      dry-initializer (~> 3.0)
+      dry-monads (~> 1.2)
+      dry-struct (~> 1.0)
+      dry-types (~> 1.0)
+      rack (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    byebug (11.0.0)
+    coderay (1.1.2)
+    concurrent-ruby (1.1.5)
+    diff-lcs (1.3)
+    dry-configurable (0.8.2)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 0.4, >= 0.4.7)
+    dry-container (0.7.0)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 0.1, >= 0.1.3)
+    dry-core (0.4.7)
+      concurrent-ruby (~> 1.0)
+    dry-equalizer (0.2.2)
+    dry-inflector (0.1.2)
+    dry-initializer (3.0.1)
+    dry-logic (1.0.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 0.2)
+      dry-equalizer (~> 0.2)
+    dry-monads (1.2.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 0.4, >= 0.4.4)
+      dry-equalizer
+    dry-struct (1.0.0)
+      dry-core (~> 0.4, >= 0.4.3)
+      dry-equalizer (~> 0.2)
+      dry-types (~> 1.0)
+      ice_nine (~> 0.11)
+    dry-types (1.0.0)
+      concurrent-ruby (~> 1.0)
+      dry-container (~> 0.3)
+      dry-core (~> 0.4, >= 0.4.4)
+      dry-equalizer (~> 0.2, >= 0.2.2)
+      dry-inflector (~> 0.1, >= 0.1.2)
+      dry-logic (~> 1.0)
+    ice_nine (0.11.2)
+    method_source (0.9.2)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    pry-byebug (3.7.0)
+      byebug (~> 11.0)
+      pry (~> 0.10)
+    rack (2.0.6)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rake (10.5.0)
+    redcarpet (3.4.0)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    yard (0.9.19)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.17)
+  pry-byebug
+  rack-test (~> 1.1)
+  rake (~> 10.0)
+  redcarpet (~> 3.4)
+  rspec (~> 3.0)
+  web_pipe!
+  yard (~> 0.9)
+
+BUNDLED WITH
+   1.17.2

data/README.md

@@ -0,0 +1,279 @@
+[![Gem Version](https://badge.fury.io/rb/web_pipe.svg)](https://badge.fury.io/rb/web_pipe)
+[![Build Status](https://travis-ci.com/waiting-for-dev/web_pipe.svg?branch=master)](https://travis-ci.com/waiting-for-dev/web_pipe)
+
+# 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
+```
+
+```ruby
+# config.ru
+require "web_pipe"
+
+UsersRepo = {
+  1 => { name: 'Alice', admin: true },
+  2 => { name: 'Joe', admin: false }
+}
+
+class GreetingAdminApp
+  include WebPipe
+
+  plug :set_content_type
+  plug :fetch_user
+  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.
+        put(:user, user)
+    else
+      conn.
+        set_status(404).
+        set_response_body('<h1>Not foud</h1>').
+        taint
+    end
+  end
+
+  def authorize(conn)
+    if conn.fetch(:user)[:admin]
+      conn
+    else
+      conn.
+        set_status(401).
+        set_response_body('<h1>Unauthorized</h1>').
+        taint
+    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::Clean` subclass instance. When one of your operations
+calls `#taint` on it, a `WebPipe::Conn::Dirty` is returned and the pipe
+is halted. This one or the 'clean' 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
+`#put(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, through the `with:` keyword, as
+anything that responds to `#call`, like a `Proc`:
+
+```ruby
+class App
+  include WebPipe
+
+  plug :hello, with: ->(conn) { conn }
+end
+```
+
+#### Container
+
+When `with:` is a `String` or a `Symbol`, 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, with: 'plugs.hello'
+end
+```
+
+### Operations injection
+
+Operations can be injected when the application is initialized,
+overriding those configured through `plug`:
+
+```ruby
+class App
+  include WebPipe
+
+  plug :hello, with: ->(conn) { conn.set_response_body('Hello') }
+end
+
+run App.new(
+  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 Middleware1
+  use Middleware2, option_1: value_1
+
+  plug :hello, with: ->(conn) { conn }
+end
+```
+
+### 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])
+```
+
+## Current status
+
+`web_pipe` is in active development. The very basic features to build
+a rack application are all available. However, very necessary
+conveniences to build a production application, for example a session
+mechanism, are still missing.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/waiting-for-dev/web_pipe.
+
+## Release Policy
+
+`web_pipe` follows the principles of [semantic versioning](http://semver.org/).

data/Rakefile

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

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+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.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "pry"
+Pry.start