modware 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 89d92353fe1c300cb4eab370fa9838b6d104e8a6
+  data.tar.gz: 5d0f202e063fd925a3d57a663e7bcc54548f707b
+SHA512:
+  metadata.gz: 24ac95fc4d539362292a322a92f9d7111671d7fd76fcc312f4b9494b27e26c1d113d110286eeb1c8899d835b02cafa61ca189c20ff2069d4b4d2a34aaae1fbd9
+  data.tar.gz: ca9b22dc6012180c1a109ae2713855d5866bc1969ba75b41a4141074b96ac6668f722084bf7d2d36595662668779b282481ccfe88b4d5621f99c418a1fc1fd18

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.travis.yml

@@ -0,0 +1,7 @@
+sudo: false
+rvm:
+  - 2.1.5
+script: bundle exec rake spec_with_coveralls
+notifications:
+  recipients:
+    - ronen@barzel.org

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in modware.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 ronen barzel
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,106 @@
+[![Gem Version](https://badge.fury.io/rb/modware.svg)](http://badge.fury.io/rb/modware)
+[![Build Status](https://secure.travis-ci.org/ronen/modware.svg)](http://travis-ci.org/ronen/modware)
+[![Coverage Status](https://img.shields.io/coveralls/ronen/modware.svg)](https://coveralls.io/r/ronen/modware)
+
+# Modware
+
+Modware is a library for using middleware (pipeline) patterns in Ruby projects.  It features a simple interface and supports "callback" style semantics in the middleware stack, including `before`, `after`, and `around` methods.
+
+
+## Installation
+
+As usual:
+
+```ruby
+gem 'modware'                   # in a Gemfile
+spec.add_dependency 'modware'   # in a .gemspec
+```
+
+## Usage
+
+### Creating a stack
+
+Create a stack using:
+
+```ruby
+stack = Modware::Stack.new(env: klass)
+```
+
+where `klass` is a Class for the environment instance that will be passed to the layers of the stack.  As a shorthand for the common case, you can simply pass an array of keys, e.g.
+
+```ruby
+stack = Modware::Stack.new(env: [:name, :options, :results])
+```
+
+and Modware will define a class that accepts those keys as keyword arguments, and has accessor methods for each (see 
+[`KeyStruct`](https://rubygems.org/gems/key_struct)).
+
+
+### Defining middleware
+
+Middleware is defined as a module that defines one or more middleware methods:
+
+```ruby
+module MyMiddleware
+
+  # define any of these as needed...
+
+  def before(env)
+    # code to be called before the base implementation
+  end
+
+  def after(env)
+    # code to be called after the base implementation
+  end
+
+  def around(env)
+    # setup/wrapper code
+    yield env # continues execution down the stack
+    # cleanup code
+  end
+
+  def implement(env)
+    # completely replaces the base implementation or any earlier middleware's implement()
+  end
+end
+```
+
+The module may use instance variables and define other methods as needed (e.g. to abide by [Metz' rule #2](http://robots.thoughtbot.com/sandi-metz-rules-for-developers)).
+
+To add the middleware to a stack:
+
+```ruby
+stack.add(MyMiddleware)
+```
+
+Middleware is always added to the end of the stack.
+
+### Executing a stack
+
+To execute a stack do:
+
+```ruby
+stack.start(*args) { |env|
+  # base implementation 
+}
+```
+
+The execution sequence of the stack is as follows:
+
+1. Create environment instance `env = env_klass.new(*args)`
+2. Call each middleware `before(env)` method, in the order they were added
+3. Call each middleware `around(env)` method, in the order they were added.  This bottoms out with the last `implement(env)` method to be added, if any, otherwise the base implementation
+4. Call each middleware `after(env)` method, in the order they were added
+5. Return `env`
+
+### Helpers
+
+* `Modware.is_middleware?(mod)` returns truthy if `mod`'s instance methods include any of the middleware methods `:before`, `:after`, `:around`, or `:implement`
+
+## See also
+
+The [middleware](https://rubygems.org/gems/middleware) gem works well, following a [rack](http://rack.github.io/)-like execution model.
+
+## Contributing
+
+Contributions welcome -- feel free to open issues or submit pull requests.  Thanks!

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.rspec_opts = '-Ispec'
+end
+
+require 'coveralls/rake/task'
+Coveralls::RakeTask.new
+task :spec_with_coveralls => [:spec, 'coveralls:push']

data/lib/modware.rb

@@ -0,0 +1,9 @@
+require "modware/errors"
+require "modware/stack"
+require "modware/version"
+
+module Modware
+  def self.is_middleware?(mod)
+    (mod.instance_methods & [:before, :around, :after, :implement]).any?
+  end
+end

data/lib/modware/errors.rb

@@ -0,0 +1,4 @@
+module Modware
+  class StackError < Exception
+  end
+end

data/lib/modware/stack.rb

@@ -0,0 +1,80 @@
+require 'its-it'
+require 'key_struct'
+
+module Modware
+  class Stack
+    def initialize(env:)
+      @env_klass = case env
+                   when Class then env
+                   else KeyStruct[*env]
+                   end
+      @middlewares = []
+    end
+
+    def add(mod)
+      middleware = Middleware.new(self, mod)
+      @middlewares.last._next = middleware if @middlewares.any?
+      @middlewares << middleware
+    end
+
+    def start(*args, &implementation)
+      env = @env_klass.new(*args)
+      @base_implementation = implementation
+      execute_stack(env)
+      env
+    end
+
+    private
+
+    def execute_stack(env)
+      return call_implementation(env) unless @middlewares.any?
+
+      @middlewares.each do |middleware|
+        middleware.before env if middleware.respond_to? :before
+      end
+
+      @middlewares.first._call(env)
+
+      @middlewares.each do |middleware|
+        middleware.after env if middleware.respond_to? :after
+      end
+    end
+
+    def call_implementation(env)
+      if middleware = @middlewares.select(&it.respond_to?(:implement)).last
+        middleware.implement(env)
+      elsif @base_implementation
+        @base_implementation.call env
+      else
+        raise StackError, "No base implementation nor middleware implementation in stack"
+      end
+    end
+
+    class Middleware
+      attr_accessor :_next
+
+      def initialize(stack, mod)
+        @stack = stack
+        singleton_class.send :include, mod
+      end
+
+      def _call(env)
+        if respond_to? :around
+          around(env) { |env|
+            _continue env
+          }
+        else
+          _continue env
+        end
+      end
+
+      def _continue(env)
+        if self._next
+          self._next._call(env)
+        else
+          @stack.send :call_implementation, env
+        end
+      end
+    end
+  end
+end

data/lib/modware/version.rb

@@ -0,0 +1,3 @@
+module Modware
+  VERSION = "0.1.0"
+end

data/modware.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'modware/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "modware"
+  spec.version       = Modware::VERSION
+  spec.authors       = ["ronen barzel"]
+  spec.email         = ["ronen@barzel.org"]
+  spec.summary       = %q{A middleware library, featuring a simple interface and "callback" style semantics in the middleware stack}
+  spec.homepage      = "https://github.com/ronen/modware"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.1.0"
+  spec.add_dependency "key_struct", "~> 0.4"
+  spec.add_dependency "its-it"
+
+  spec.add_development_dependency 'coveralls'
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rspec-given"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "simplecov-gem-profile"
+end

data/spec/env_spec.rb

@@ -0,0 +1,24 @@
+require 'spec_helper'
+
+describe "Env" do
+
+  When(:env) { Modware::Stack.new(env: klass).start(args) {} }
+
+  context "if env: klass is a Class" do
+
+    Given(:klass) { String }
+    Given(:args) { "EnvArgs" }
+
+    Then { expect(env).to eq klass.new(args) }
+
+  end
+
+  context "if env: klass is an array of keys" do
+
+    Given(:klass) { [:a, :b, :c] }
+    Given(:args) { {a: 1, b: 2, c: 3} }
+
+    Then { expect(env.to_hash).to eq args }
+  end
+
+end

data/spec/execution_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+
+describe "Execution" do
+
+  Given(:stack) { Modware::Stack.new(env: [:result]) }
+
+  context "when start with no implementation" do
+
+    When(:env) { stack.start result: [] }
+
+    Then { expect(env).to have_failed(Modware::StackError, /implementation/) }
+  end
+
+  context "when start with base implementation" do
+
+    When(:env) { stack.start result: [] { |env| env.result << :base } }
+
+    Then { expect(env.result).to eq [:base] }
+
+    context "if add middleware1" do
+
+      Given { stack.add Factory.middleware(1, around: nil) }
+
+      Then { expect(env.result).to eq [:before1, :implement1, :after1 ] }
+
+      context "if add middleware2" do
+
+        Given { stack.add Factory.middleware(2, implement: nil) }
+
+        Then { expect(env.result).to eq [:before1, :before2, :around_pre2, :implement1, :around_post2, :after1, :after2 ] }
+      end
+    end
+
+  end
+
+end

data/spec/helper_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+describe "Helper" do
+
+  let(:none) { { before: nil, after:nil, around: nil, implement: nil } }
+
+  context "Modware.is_middleware?" do
+    [:before, :after, :around, :implement].each do |method|
+      it "returns truthy for a module with #{method.inspect} method" do
+        expect(Modware.is_middleware? Factory.middleware(none.merge(method => true))).to be_truthy
+      end
+    end
+
+    it "returns falsey for other modules" do
+      expect(Modware.is_middleware? Factory.middleware(none.merge(other: true))).to be_falsey
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+require 'simplecov'
+require 'simplecov-gem-profile'
+SimpleCov.start "gem"
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'rspec'
+require 'rspec/given'
+require 'modware'
+
+Dir[File.dirname(__FILE__) + "/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  config.warnings = true
+end

data/spec/support/factory.rb

@@ -0,0 +1,40 @@
+module Factory
+  def self.middleware(n=nil, before: true, after: true, around: true, implement: true, other: nil)
+
+    methods = []
+
+    methods << (before && <<-END)
+      def before(env)
+        env.result << :"before#{n}"
+      end
+    END
+
+    methods << (after && <<-END)
+      def after(env)
+        env.result << :"after#{n}"
+      end
+    END
+
+    methods << (around && <<-END)
+      def around(env)
+        env.result << :"around_pre#{n}"
+        yield env
+        env.result << :"around_post#{n}"
+      end
+    END
+
+    methods << (implement && <<-END)
+      def implement(env)
+        env.result << :"implement#{n}"
+      end
+    END
+
+    methods << (other && <<-END)
+      def other(env)
+        env.result << :"other#{n}"
+      end
+    END
+
+    Module.new.tap(&it.module_eval(methods.compact.join))
+  end
+end

metadata

@@ -0,0 +1,192 @@
+--- !ruby/object:Gem::Specification
+name: modware
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ronen barzel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: key_struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: its-it
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-given
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov-gem-profile
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- ronen@barzel.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/modware.rb
+- lib/modware/errors.rb
+- lib/modware/stack.rb
+- lib/modware/version.rb
+- modware.gemspec
+- spec/env_spec.rb
+- spec/execution_spec.rb
+- spec/helper_spec.rb
+- spec/spec_helper.rb
+- spec/support/factory.rb
+homepage: https://github.com/ronen/modware
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A middleware library, featuring a simple interface and "callback" style semantics
+  in the middleware stack
+test_files:
+- spec/env_spec.rb
+- spec/execution_spec.rb
+- spec/helper_spec.rb
+- spec/spec_helper.rb
+- spec/support/factory.rb