web_pipe 0.1.0

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/dry/monads/result/extensions/either.rb

@@ -0,0 +1,42 @@
+require "dry/core/extensions"
+
+module Dry
+  module Monads
+    # This is currently a PR in dry-monads:
+    #
+    # https://github.com/dry-rb/dry-monads/pull/84
+    class Result
+      extend Dry::Core::Extensions
+
+      register_extension(:either) do
+        class Success
+          # Returns result of applying first function to the internal value.
+          #
+          # @example
+          #   Dry::Monads.Success(1).either(-> x { x + 1 }, -> x { x + 2 }) # => 2
+          #
+          # @param f [#call] Function to apply
+          # @param g [#call] Ignored
+          # @return [Any] Return value of `f`
+          def either(f, _g)
+            f.(success)
+          end
+        end
+
+        class Failure
+          # Returns result of applying second function to the internal value.
+          #
+          # @example
+          #   Dry::Monads.Failure(1).either(-> x { x + 1 }, -> x { x + 2 }) # => 3
+          #
+          # @param f [#call] Ignored
+          # @param g [#call] Function to call
+          # @return [Any] Return value of `g`
+          def either(_f, g)
+            g.(failure)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/web_pipe.rb

@@ -0,0 +1,16 @@
+require 'web_pipe/dsl/builder'
+
+# See [the
+# README](https://github.com/waiting-for-dev/web_pipe/blob/master/README.md)
+# for a general overview of this library.
+module WebPipe
+  # Including just delegates to an instance of `Builder`, so
+  # `Builder#included` is finally called.
+  def self.included(klass)
+    klass.include(call())
+  end
+
+  def self.call(*args)
+    DSL::Builder.new(*args)
+  end
+end

data/lib/web_pipe/app.rb

@@ -0,0 +1,106 @@
+require 'dry/initializer'
+require 'dry/monads/result'
+require 'web_pipe/types'
+require 'web_pipe/conn'
+require 'web_pipe/conn_support/builder'
+require 'dry/monads/result/extensions/either'
+
+Dry::Monads::Result.load_extensions(:either)
+
+module WebPipe
+  # Rack application built around applying a pipe of {Operation} to
+  # a {Conn}.
+  #
+  # A rack application is something callable accepting rack's `env`
+  # as argument and returning a rack response. So, the workflow
+  # followed to build it is:
+  #
+  # - Take rack's `env` and create a {Conn} from here.
+  # - Starting from it, apply the pipe of operations (anything
+  # callable accepting a {Conn} and returning a {Conn}).
+  # - Convert last {Conn} back to a rack response and
+  # return it.
+  #
+  # {Conn} can itself be of two different types (subclasses of it}:
+  # {Conn::Clean} and {Conn::Dirty}. The pipe is stopped
+  # whenever the stack is emptied or a {Conn::Dirty} is
+  # returned in any of the steps.
+  class App
+    # Type for an operation.
+    #
+    # It should be anything callable expecting a {Conn} and
+    # returning a {Conn}.
+    Operation = Types.Contract(:call)
+
+    # Type for a rack environment.
+    RackEnv = Types::Strict::Hash
+
+    # Error raised when an {Operation} returns something that is not a
+    # {Conn}.
+    class InvalidOperationResult < RuntimeError
+      # @param returned [Any] What was returned from the {Operation}
+      def initialize(returned)
+        super(
+          <<~eos
+            An operation returned +#{returned.inspect}+. To be valid,
+            an operation must return whether a
+            WebPipe::Conn::Clean or a WebPipe::Conn::Dirty.
+          eos
+        )
+      end
+    end
+
+    include Dry::Monads::Result::Mixin
+
+    include Dry::Initializer.define -> do
+      # @!attribute [r] operations
+      #   @return [Array<Operation[]>]
+      param :operations, type: Types.Array(Operation)
+    end
+
+    # @param env [Hash] Rack env
+    #
+    # @return env [Array] Rack response
+    def call(env)
+      extract_rack_response(
+        apply_operations(
+          conn_from_env(
+            RackEnv[env]
+          )
+        )
+      )
+    end
+
+    private
+
+    def conn_from_env(env)
+      Success(
+        ConnSupport::Builder.(env)
+      )
+    end
+
+    def apply_operations(conn)
+      operations.reduce(conn) do |new_conn, operation|
+        new_conn.bind { |c| apply_operation(c, operation) }
+      end
+    end
+
+    def apply_operation(conn, operation)
+      result = operation.(conn)
+      case result
+      when Conn::Clean
+        Success(result)
+      when Conn::Dirty
+        Failure(result)
+      else
+        raise InvalidOperationResult.new(result)
+      end
+    end
+
+    def extract_rack_response(conn)
+      extract_proc = :rack_response.to_proc
+
+      conn.either(extract_proc, extract_proc)
+    end
+  end
+end

data/lib/web_pipe/conn.rb

@@ -0,0 +1,397 @@
+require 'dry/struct'
+require 'web_pipe/conn_support/types'
+require 'web_pipe/conn_support/errors'
+require 'web_pipe/conn_support/headers'
+
+module WebPipe
+  # Struct and methods about web request and response data.
+  #
+  # It is meant to contain all the data coming from a web request
+  # along with all the data needed to build a web response. It can
+  # be built with {ConnSupport::Builder}.
+  #
+  # Besides data fetching methods and {#rack_response}, any other
+  # method returns a fresh new instance of it, so it is thought to
+  # be used in an immutable way and to allow chaining of method
+  # calls.
+  #
+  # There are two subclasses (two types) for this:
+  # {Conn::Clean} and {Conn::Dirty}. {ConnSupport::Builder} constructs
+  # a {Conn::Clean} struct, while {#taint} copies the data to a
+  # {Conn::Dirty} instance. The intention of this is to halt
+  # operations on the web request/response cycle one a {Conn::Dirty}
+  # instance is detected.
+  #
+  # @example
+  #   WebPipe::Conn::Builder.call(env).
+  #     set_status(404).
+  #     add_response_header('Content-Type', 'text/plain').
+  #     set_response_body('Not found').
+  #     taint
+  class Conn < Dry::Struct
+    include ConnSupport::Types
+
+    # @!attribute [r] env
+    #
+    # Rack env hash.
+    #
+    # @return [Env[]]
+    #
+    # @see https://www.rubydoc.info/github/rack/rack/file/SPEC
+    attribute :env, Env
+
+    # @!attribute [r] request
+    #
+    # Rack request.
+    #
+    # @return [Request[]]
+    #
+    # @see https://www.rubydoc.info/github/rack/rack/Rack/Request
+    attribute :request, Request
+
+    # @!attribute [r] scheme
+    #
+    # Scheme of the request.
+    #
+    # @return [Scheme[]]
+    #
+    # @example
+    #   :http
+    attribute :scheme, Scheme
+
+    # @!attribute [r] request_method
+    #
+    # Method of the request.
+    #
+    # It is not called `:method` in order not to collide with
+    # {Object#method}.
+    #
+    # @return [Method[]]
+    #
+    # @example
+    #   :get
+    attribute :request_method, Method
+
+    # @!attribute [r] host
+    #
+    # Host being requested.
+    #
+    # @return [Host[]]
+    #
+    # @example
+    #   'www.example.org'
+    attribute :host, Host
+
+    # @!attribute [r] ip
+    #
+    # IP being requested.
+    #
+    # @return [IP[]]
+    #
+    # @example
+    #   '192.168.1.1'
+    attribute :ip, Ip
+
+    # @!attribute [r] port
+    #
+    # Port in which the request is made.
+    #
+    # @return [Port[]]
+    #
+    # @example
+    #   443
+    attribute :port, Port
+
+    # @!attribute [r] script_name
+    #
+    # Script name in the URL, or the empty string if none.
+    #
+    # @return [ScriptName[]]
+    #
+    # @example
+    #   'index.rb'
+    attribute :script_name, ScriptName
+
+    # @!attribute [r] path_info
+    #
+    # Besides {#script_name}, the remainder path of the URL or the
+    # empty string if none. It is, at least, `/` when `#script_name`
+    # is empty.
+    #
+    # This doesn't include the {#query_string}.
+    #
+    # @return [PathInfo[]]
+    #
+    # @example
+    #   '/foo/bar'.
+    attribute :path_info, PathInfo
+
+    # @!attribute [r] query_string
+    #
+    # Query String of the URL (everything after `?` , or the empty
+    # string if none).
+    #
+    # @return [QueryString[]]
+    #
+    # @example
+    #   'foo=bar&bar=foo'
+    attribute :query_string, QueryString
+
+    # @!attribute [r] request_body
+    #
+    # Body sent by the request.
+    #
+    # @return [RequestBody[]]
+    #
+    # @example
+    #   '{ resource: "foo" }'
+    attribute :request_body, RequestBody
+
+    # @!attribute [r] request_headers
+    #
+    # Hash of request headers.
+    #
+    # As per RFC2616, headers names are case insensitive. Here, they
+    # are normalized to PascalCase acting on dashes ('-').
+    #
+    # Notice that when a rack server maps headers to CGI-like
+    # variables, both dashes and underscores (`_`) are treated as
+    # dashes. Here, they always remain as dashes.
+    #
+    # @return [Headers[]]
+    #
+    # @see https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2
+    #
+    # @example
+    #   { 'Accept-Charset' => 'utf8' }
+    attribute :request_headers, Headers
+
+    # @!attribute [r] status
+    #
+    # Status sent by the response.
+    #
+    # @return [Status[]]
+    #
+    # @example
+    #   200
+    attribute :status, Status
+
+    # @!attribute [r] response_body
+    #
+    # @return [ResponseBody[]] Body sent by the response.
+    #
+    # @example
+    #    ['<html></html>']
+    attribute :response_body, ResponseBody
+
+    # @!attribute [r] response_headers
+    #
+    # Response headers.
+    #
+    # @see #request_headers for normalization details
+    #
+    # @return [Headers[]]
+    #
+    # @example
+    #
+    #   { 'Content-Type' => 'text/html' }
+    attribute :response_headers, Headers
+
+    # @!attribute [r] bag
+    #
+    # Hash where anything can be stored. Keys
+    # must be symbols.
+    #
+    # This can be used to store anything that is needed to be
+    # consumed downstream in a pipe of operations action on and
+    # returning {Conn}.
+    #
+    # @return [Bag[]]
+    attribute :bag, Bag
+
+    # Base part of the URL.
+    #
+    # This is {#scheme} and {#host}, adding {#port} unless it is the
+    # default one for the scheme.
+    #
+    # @return [BaseUrl]
+    #
+    # @example
+    #   'https://example.org'
+    #   'http://example.org:8000'
+    def base_url
+      request.base_url
+    end
+
+    # URL path.
+    #
+    # This is {#script_name} and {#path_info}.
+    #
+    # @return [Path]
+    #
+    # @example
+    #   'index.rb/users'
+    def path
+      request.path
+    end
+
+    # URL full path.
+    #
+    # This is {#path} with {#query_string} if present.
+    #
+    # @return [FullPath]
+    #
+    # @example
+    #   '/users?id=1'
+    def full_path
+      request.fullpath
+    end
+
+    # Request URL.
+    #
+    # This is the same as {#base_url} plus {#full_path}.
+    #
+    # @return [Url]
+    #
+    # @example
+    #   'http://www.example.org:8000/users?id=1'
+    def url
+      request.url
+    end
+
+    # GET and POST params merged in a hash.
+    #
+    # @return [Params]
+    #
+    # @example
+    #   { 'id' => 1, 'name' => 'Joe' }
+    def params
+      request.params
+    end
+
+    # Sets response status code.
+    #
+    # @param code [StatusCode]
+    #
+    # @return {Conn}
+    def set_status(code)
+      new(
+        status: code
+      )
+    end
+
+    # Sets response body.
+    #
+    # As per rack specification, the response body must respond to
+    # `#each`. Here, when given `content` responds to `:each` it is
+    # set as it is as the new response body. Otherwise, what is set
+    # is a one item array of it.
+    #
+    # @param content [#each, String]
+    #
+    # @return {Conn}
+    #
+    # @see https://www.rubydoc.info/github/rack/rack/master/file/SPEC#label-The+Body
+    def set_response_body(content)
+      new(
+        response_body: content.respond_to?(:each) ? content : [content]
+      )
+    end
+
+    # Adds given pair to response headers.
+    #
+    # `key` is normalized.
+    #
+    # @param key [String]
+    # @param value [String]
+    #
+    # @return {Conn}
+    #
+    # @see ConnSupport::Headers.normalize_key
+    def add_response_header(key, value)
+      new(
+        response_headers: ConnSupport::Headers.add(
+          response_headers, key, value
+        )
+      )
+    end
+
+    # Deletes pair with given key from response headers.
+    #
+    # It accepts a non normalized key.
+    #
+    # @param key [String]
+    #
+    # @return {Conn}
+    #
+    # @see ConnSupport::Headers.normalize_key
+    def delete_response_header(key)
+      new(
+        response_headers: ConnSupport::Headers.delete(
+          response_headers, key
+        )
+      )
+    end
+
+    # Reads an item from {#bag}.
+    #
+    # @param key [Symbol]
+    #
+    # @return [Object]
+    #
+    # @raise ConnSupport::KeyNotFoundInBagError when key is not
+    # registered in the bag.
+    def fetch(key)
+      bag.fetch(key) { raise ConnSupport::KeyNotFoundInBagError.new(key) }
+    end
+
+    # Writes an item to the {#bag}.
+    #
+    # If it already exists, it is overwritten.
+    #
+    # @param key [Symbol]
+    # @param value [Object]
+    #
+    # @return [Conn]
+    def put(key, value)
+      new(
+        bag: bag.merge(key => value)
+      )
+    end
+
+    # Builds response in the way rack expects.
+    #
+    # It is useful to finish a rack application built with a
+    # {Conn}. After every desired operation has been done,
+    # this method has to be called before giving control back to
+    # rack.
+    #
+    # @return
+    #   [Array<StatusCode, Headers, ResponseBody>]
+    #
+    # @private
+    def rack_response
+      [
+        status,
+        response_headers,
+        response_body
+      ]
+    end
+
+    # Copies all the data to a {Dirty} instance and
+    # returns it.
+    #
+    # @return [Dirty]
+    def taint
+      Dirty.new(attributes)
+    end
+
+    # Type of {Conn} representing an ongoing request/response
+    # cycle.
+    class Clean < Conn; end
+
+    # Type of {Conn} representing a halted request/response
+    # cycle.
+    class Dirty < Conn; end
+  end
+end