truss-router 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: acb68fcca495a20529240f4dbc8879756ef8984d
-  data.tar.gz: d66814d6ee823e2d89064d97f55643d93a8c64e1
+  metadata.gz: 9b56c1774dc9e3e09defdd552298a3a10bfc61bd
+  data.tar.gz: 76018cd3ef0a703260177cc158ca4223f91bcbd1
 SHA512:
-  metadata.gz: 15dffabd400cd9d351261d4612caca972bb553ce40b657780347984e3a74943ad6770ba7935b83b19a5978f54ceef039a3d555124a04ffe4a38835989aefe125
-  data.tar.gz: 8ca1c257d8cea17dc77ca830066c43cb7624e19e1f611611c1a479efee03cdd341cdab98a75987a90d595be88908050d08b78c68251775eb77fe14e64ee6501c
+  metadata.gz: d3c1fc3a28002932edb13878189dca29d9b7a3cc60d76d2907263238f6d39edb6ff20b46395a00f151f98f1c5a7f7e38ddad91f1f4428e27767156b1afd21066
+  data.tar.gz: f02753a22f37ea3837d34c819dcae69964a53c8e2aabca5cac9bfe1069f3983e2e8b0497d1d33852246ce61b6f32b816a7eb91486d720bb8774ce1016f214b39

data/README.md

@@ -1,7 +1,16 @@
 [![Build Status](https://travis-ci.org/truss-io/router.png)](https://travis-ci.org/truss-io/router)
-# Truss::Router
+# Truss Router
 
-TODO: Write a gem description
+Truss Router is the first released part of Truss - a new wrapper around Rack to make writing performant Ruby web endpoints easier.
+Truss Router is currently considered alpha software, and as such please don't use in any production environment, but feel free to
+explore and see how it handles for you.
+
+Truss supports the following Ruby platforms in Pure Ruby:
+
+* MRI 1.9.3
+* MRI 2.0.0
+* JRuby 1.7
+* RBX 1.9 mode
 
 ## Installation
 
@@ -19,7 +28,42 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Truss Router admires Journey, although doesn't fancy doing all the hard work that it does. With that in mind, it offers a nice DSL
+and some pleasant features, but doesn't currently support things like namespaces or constraints. To be honest, at this 0.0.2 release
+it doesn't actually support much, but features will come!
+
+So, how do I use it? Basically, just require the gem, and then ```draw``` a map of your routes. Routes are evaluated from top to bottom, so routes at the top of the route block will match and return before routes below them. The route builder takes the following arguments:
+
+1. path, e.g. "/home" (currently only exact matches match, dynamic segments coming soon!)
+2. rack app, e.g. ```->(env){[200, {'Content-Type' => 'text/plain'}, ["Hi, I'm a Rack App"]]}```
+3. an optional hash of options (currently not used!)
+
+```ruby
+require 'truss-router'
+
+Truss::Router.draw do |r|
+    r.get("/", HomeApp)
+    r.post("/login", LoginApp)
+    r.patch("/update", DhhApp)
+    r.delete("/goodbye", RemoveThisApp)
+end
+```
+
+Finally, you can then run the Truss Router as a rack app:
+
+```ruby
+run Truss::Router
+```
+
+## Benchmarks
+
+Truss Router aims to be a highly performant routing solution for your Rack apps, whilst giving you a nicer DSL than some of the
+inbuilt rack types (Cascade/URLMap), and a little bit of Rails Magic, such as param matching and simple binding of different
+request methods to different endpoints on the same path.
+
+Having said that, there isn't much point in having candy if it makes it slow. HTTP Router inspired me to include benchmarks within
+the repo that make it easy to check how performant the solution is. I'll include the current benchmark output in the wiki for each
+supported platform (1.9.3/2.0.0/JRuby1.7/RBX) and update with each release to keep things current.
 
 ## Contributing
 

data/benchmarks/simple_bench.rb

@@ -0,0 +1,74 @@
+require 'benchmark'
+require 'rack'
+require File.expand_path("../../lib/truss-router", __FILE__)
+
+puts "Welcome to Truss Router v#{Truss::Router::VERSION} Benchmark suite. Please wait...\n\n"
+app = ->(env) {
+    [
+        200,
+        {'Content-Type' => 'text/plain'},
+        ["Hello World"]
+    ]
+}
+
+TIMES = 50_000
+REQUEST = Rack::MockRequest.env_for("/", method: "GET")
+
+Truss::Router.draw do |route|
+    route.get("/", app)
+end
+
+puts "Benchmarking in progress with 50k iterations, please wait\n\n"
+
+Benchmark.bm(12) do |x|
+    x.report("Plain app")    { TIMES.times{ app.call(REQUEST) } }
+    x.report("Single route") { TIMES.times { Truss::Router.call(REQUEST) } }
+end
+
+puts "\n\nBenchmarking for 2nd preference route with 50k iterations\n\n"
+
+Truss::Router.reset!
+
+app2 = ->(env) {
+    [
+        200,
+        {'Content-Type' => 'text/plain'},
+        ["Home Page"]
+    ]
+}
+
+Truss::Router.draw do |route|
+    route.get("/", app)
+    route.get("/home", app2)
+end
+
+HOME_REQUEST = Rack::MockRequest.env_for("/home", method: "GET")
+
+Benchmark.bm(12) do |x|
+    x.report("Plain app")    { TIMES.times{ app.call(REQUEST) } }
+    x.report("Single route") { TIMES.times { Truss::Router.call(HOME_REQUEST) } }
+end
+
+
+puts "\n\nBenchmarking 10 route map with 50k iterations, hitting last route\n\n"
+
+Truss::Router.reset!
+
+Truss::Router.draw do |route|
+    route.get("/", app)
+    route.get("/about", app)
+    route.get("/contact", app)
+    route.get("/blog", app)
+    route.get("/structure", app)
+    route.get("/staff", app)
+    route.get("/news", app)
+    route.get("/log-in", app)
+    route.get("/admin", app)
+    route.get("/home", app2)
+end
+
+Benchmark.bm(10) do |x|
+    x.report("Plain app")  { TIMES.times{ app.call(REQUEST) } }
+    x.report("Last route") { TIMES.times { Truss::Router.call(HOME_REQUEST) } }
+end
+

data/lib/truss/router/node.rb

@@ -1,13 +1,35 @@
 module Truss
     module Router
         class Node
-            attr_accessor :request_method, :path, :endpoint
-            def initialize(meth, path, endpoint, opts={})
-                @request_method, @path, @endpoint = meth, path, endpoint
-                @opts = opts
+            attr_accessor :request_method, :path, :endpoint, :matchable_regex, :options
+            def initialize(method, path, endpoint, options={})
+                @request_method, @path, @endpoint = method, path, endpoint
+                @matchable_regex = build_matchable_regex(method, path, options)
+                @options = options
             end
 
-            def matches?
+            def matches? request
+                matchable_regex.match(request.routing_path)
+            end
+
+            def call request
+                endpoint.call(request)
+            end
+
+            private
+            def build_matchable_regex(method, path, options)
+                %r[\A#{method_group(method)}#{path}\Z]
+            end
+
+            def method_group(method)
+                origin = case method
+                when :get
+                    "(GET|HEAD|OPTIONS)"
+                when :options
+                    "OPTIONS"
+                else
+                    "(#{method.to_s.upcase}|OPTIONS)"
+                end
             end
         end
     end

data/lib/truss/router/request.rb

@@ -0,0 +1,9 @@
+module Truss
+    module Router
+        class Request < Rack::Request
+            def routing_path
+                "#{request_method}#{path}"
+            end
+        end
+    end
+end

data/lib/truss/router/routes.rb

@@ -0,0 +1,10 @@
+%w[get post put patch head options delete].each do |type|
+    require "truss/router/routes/#{type}"
+end
+
+module Truss
+    module Router
+        module Routes
+        end
+    end
+end

data/lib/truss/router/routeset.rb

@@ -0,0 +1,33 @@
+module Truss
+    module Router
+        class Routeset
+   
+            attr_accessor :nodes
+            def initialize(nodes=[])
+                @nodes = nodes
+            end
+
+            def add_node(node)
+                @nodes << node
+            end
+
+            def <<(node)
+                @nodes << node
+            end
+
+            def [](node)
+                @nodes[node]
+            end
+
+            def length
+                @nodes.length
+            end
+
+            def find_route request
+                @nodes.detect do |node|
+                    node.matches?(request)
+                end
+            end
+        end
+    end
+end

data/lib/truss/router/version.rb

@@ -1,5 +1,5 @@
 module Truss
   module Router
-    VERSION = "0.0.1"
+    VERSION = "0.0.2"
   end
 end

data/lib/truss/router.rb

@@ -1,7 +1,66 @@
 require "truss/router/version"
+require "truss/router/node"
+require "truss/router/routes"
+require "truss/router/routeset"
+require "truss/router/request"
 
 module Truss
-  module Router
-    # Your code goes here...
-  end
+    module Router
+        extend self
+        def draw(&block)
+            raise ArgumentError unless block_given?
+            block.call(self)
+        end
+
+        def routeset
+            @routeset ||= Truss::Router::Routeset.new
+        end
+
+        def get(path, endpoint, opts={})
+            build_node :Get, path, endpoint, opts
+        end
+
+        def post(path, endpoint, opts={})
+            build_node :Post, path, endpoint, opts
+        end
+
+        def options(path, endpoint, opts={})
+            build_node :Options, path, endpoint, opts
+        end
+
+        def head(path, endpoint, opts={})
+            build_node :Head, path, endpoint, opts
+        end
+
+        def put(path, endpoint, opts={})
+            build_node :Put, path, endpoint, opts
+        end
+
+        def patch(path, endpoint, opts={})
+            build_node :Patch, path, endpoint, opts
+        end
+
+        def delete(path, endpoint, opts={})
+            build_node :Delete, path, endpoint, opts
+        end
+
+        def reset!
+            @routeset = Truss::Router::Routeset.new
+        end
+
+        def call env
+            request = Request.new(env.dup)
+            route = routeset.find_route(request)   
+            if route
+                route.call(request)
+            else
+                [404, {'Content-Type' => 'text/plain'}, ["Not Found"]]
+            end
+        end
+
+        protected
+        def build_node method, path, endpoint, opts
+            routeset << Routes.const_get(method).new(path, endpoint, opts)
+        end
+    end
 end

data/spec/lib/truss/draw_routes_spec.rb

@@ -0,0 +1,55 @@
+require 'truss/router'
+
+describe Truss::Router do
+    let(:app) { ->(env){[200, {'Content-Type' => 'text/plain'}, ["Hello World"]]} }
+    subject { described_class }
+    before(:each) { subject.reset! } 
+    it "requires a block to be passed to #draw" do
+        expect {
+            subject.draw
+        }.to raise_error(ArgumentError)
+    end
+
+    context "drawing routes" do
+        context "triggers the right route builder" do
+            let(:map) { ->(m){ 
+                    m.get("/home", app) 
+                    m.post("/home", app)
+                    m.put("/home", app)
+                    m.patch("/home", app)
+                    m.options("/home", app)
+                    m.head("/home", app)
+                    m.delete("/home", app)
+                }  
+            }
+
+            it { subject.should_receive(:get).with("/home", app);        subject.draw(&map) }
+            it { subject.should_receive(:post).with("/home", app);       subject.draw(&map) }
+            it { subject.should_receive(:put).with("/home", app);        subject.draw(&map) }
+            it { subject.should_receive(:patch).with("/home", app);      subject.draw(&map) }
+            it { subject.should_receive(:head).with("/home", app);       subject.draw(&map) }
+            it { subject.should_receive(:options).with("/home", app);    subject.draw(&map) }
+            it { subject.should_receive(:delete).with("/home", app);     subject.draw(&map) }
+        end
+
+        context "populates the routeset" do
+            let(:map) { ->(m){
+                    m.get("/home", app)
+                    m.post("/home", app)
+                }
+            }
+            before(:each) do
+                subject.draw(&map)
+            end
+            it "should have two route" do
+                subject.routeset.length.should eq(2)
+            end
+            it "should have a Get route as the first member of the routeset" do
+                subject.routeset[0].should be_kind_of(Truss::Router::Routes::Get)
+            end
+            it "should have a Post route as the second member of the routeset" do
+                subject.routeset[1].should be_kind_of(Truss::Router::Routes::Post)
+            end
+        end
+    end
+end

data/spec/lib/truss/request_spec.rb

@@ -0,0 +1,8 @@
+require 'truss/router/request'
+
+describe Truss::Router::Request do
+    let(:env) { Rack::MockRequest.env_for("/home") }
+    subject { described_class.new(env) }
+
+    it { should be_kind_of(Rack::Request) }
+end

data/spec/lib/truss/route_dispatch_spec.rb

@@ -0,0 +1,97 @@
+require 'truss/router'
+
+describe Truss::Router do
+    let(:app) { ->(env){ [200, {'Content-Type' => 'text/plain'}, ["Hello World"]] } }
+    let(:map) { ->(r){ r.get("/home", app) } }
+    let(:env) { Rack::MockRequest.env_for("/home", method: "GET") }
+    subject   { described_class.routeset }
+    context "single route dispatch" do
+        before(:each) do
+            described_class.reset!
+            described_class.draw(&map)
+        end
+
+        it "should interrogate the routeset when called" do
+            subject.should_receive(:find_route).exactly(1).times.with(kind_of(Truss::Router::Request))
+            described_class.call(env)
+        end
+
+        it "should return the first route for a matching path" do
+            subject[0].should_receive(:call).exactly(1).times.with(kind_of(Truss::Router::Request))
+            described_class.call(env)
+        end
+
+        it "should return 404 response for no matching routes" do
+            bad_env = Rack::MockRequest.env_for("/noroute", method: "PATCH")
+            described_class.call(bad_env)[0].should be(404)
+        end
+    end
+
+    context "multiple routes present" do
+        let(:multiple_map) { ->(r){
+                r.get("/", app)
+                r.get("/home", app)
+                r.get("/about", app)
+                r.post("/login", app)
+                r.post("/home", app)
+            }
+        }
+
+        before(:each) do
+            described_class.reset!
+            described_class.draw(&multiple_map)
+        end
+
+        it "should call the second node given a get request for /home" do
+            subject[1].should_receive(:call).exactly(1).times.with(kind_of(Truss::Router::Request))
+            described_class.call(env)
+        end
+
+        it "should call the third node given a get request for /about" do
+            about_env = Rack::MockRequest.env_for("/about", method: "GET")
+            subject[2].should_receive(:call).exactly(1).times.with(kind_of(Truss::Router::Request))
+            described_class.call(about_env)
+        end
+
+        it "should call the fourth node given a post request for /login" do
+            login_env = Rack::MockRequest.env_for("/login", method: "POST")
+            subject[3].should_receive(:call).exactly(1).times.with(kind_of(Truss::Router::Request))
+            described_class.call(login_env)
+        end
+
+        it "should call the fifth node given a post request for /home" do
+            post_home_env = Rack::MockRequest.env_for("/home", method: "POST")
+            subject[4].should_receive(:call).exactly(1).times.with(kind_of(Truss::Router::Request))
+            described_class.call(post_home_env)
+        end
+
+        it "should call the second node given an options request for /home" do
+            options_home_env = Rack::MockRequest.env_for("/home", method: "OPTIONS")
+            subject[1].should_receive(:call).exactly(1).times.with(kind_of(Truss::Router::Request))
+            described_class.call(options_home_env)
+        end
+
+        it "should call the second node given a head request for /home" do
+            head_home_env = Rack::MockRequest.env_for("/home", method: "HEAD")
+            subject[1].should_receive(:call).exactly(1).times.with(kind_of(Truss::Router::Request))
+            described_class.call(head_home_env)
+        end
+
+        it "should call the fourth node given an options request for /login" do
+            options_login_env = Rack::MockRequest.env_for("/login", method: "OPTIONS")
+            subject[3].should_receive(:call).exactly(1).times.with(kind_of(Truss::Router::Request))
+            described_class.call(options_login_env)
+        end
+
+        it "should call the first node given a get request for /" do
+            home_env = Rack::MockRequest.env_for("/", method: "GET")
+            subject[0].should_receive(:call).exactly(1).times.with(kind_of(Truss::Router::Request))
+            described_class.call(home_env)
+        end
+
+        it "should return a 404 response if the route doesn't match" do
+            missing_env = Rack::MockRequest.env_for("/noroutehere", method: "GET")
+            described_class.call(missing_env)[0].should be(404)
+        end
+    end
+end

data/spec/lib/truss/router/node_spec.rb

@@ -1,9 +1,51 @@
 require 'truss/router/node'
 
 describe Truss::Router::Node do
-    subject { Truss::Router::Node.new(:get, "/home", "Class") }
+    let(:app)   { ->(env){ [200, {'Content-Type' => 'text/plain'}, ["Hello World"]] } }
+    subject     { Truss::Router::Node.new(:get, "/home", app) }
     it { should respond_to(:request_method) }
     it { should respond_to(:endpoint) }
     it { should respond_to(:path) }
     it { should respond_to(:matches?) }
+    it { should respond_to(:options) }
+    it { should respond_to(:matchable_regex) }
+    it { should respond_to(:call) }
+
+    describe "routing regexes" do
+        context "for get requests" do
+            subject { Truss::Router::Node.new(:get, "/home", app) }
+            its(:matchable_regex) { should eq(%r[\A(GET|HEAD|OPTIONS)/home\Z]) }
+        end
+
+        context "for post requests" do
+            subject { Truss::Router::Node.new(:post, "/home", app) }
+            its(:matchable_regex) { should eq(%r[\A(POST|OPTIONS)/home\Z]) }
+        end
+
+        context "for put requests" do
+            subject { Truss::Router::Node.new(:put, "/home", app) }
+            its(:matchable_regex) { should eq(%r[\A(PUT|OPTIONS)/home\Z]) }
+        end
+        
+        context "for patch requests" do
+            subject { Truss::Router::Node.new(:patch, "/home", app) }
+            its(:matchable_regex) { should eq(%r[\A(PATCH|OPTIONS)/home\Z]) }
+        end
+        
+        context "for head requests" do
+            subject { Truss::Router::Node.new(:head, "/home", app) }
+            its(:matchable_regex) { should eq(%r[\A(HEAD|OPTIONS)/home\Z]) }
+        end
+        
+        context "for options requests" do
+            subject { Truss::Router::Node.new(:options, "/home", app) }
+            its(:matchable_regex) { should eq(%r[\AOPTIONS/home\Z]) }
+        end
+        
+        context "for delete requests" do
+            subject { Truss::Router::Node.new(:delete, "/home", app) }
+            its(:matchable_regex) { should eq(%r[\A(DELETE|OPTIONS)/home\Z]) }
+        end
+    
+    end
 end

data/spec/lib/truss/router/routes_spec.rb

@@ -0,0 +1,4 @@
+require 'truss/router/routes'
+
+describe Truss::Router::Routes do
+end

data/spec/lib/truss/router/routeset_spec.rb

@@ -0,0 +1,20 @@
+require 'truss/router/routeset'
+require 'truss/router/node'
+
+describe Truss::Router::Routeset do
+    it { should respond_to(:nodes) }
+    it { should respond_to(:add_node) }
+
+    context "adding nodes" do
+        subject     { Truss::Router::Routeset.new }
+        let(:app)   { ->(env){[200, {'Content-Type' => 'text/plain'}, ["Hello World"]]} }
+        let(:node)  { Truss::Router::Node.new(:get, "/home", app, {}) }
+        before(:each) { subject.add_node(node) }
+
+        it  { subject.nodes.length.should eq(1) }
+        it "can contain multiple nodes" do
+            subject.add_node(node)
+            subject.nodes.length.should eq(2)
+        end
+    end
+end

data/spec/lib/truss/router_spec.rb

@@ -0,0 +1,52 @@
+require 'truss/router'
+
+describe Truss::Router do
+    let(:app) { ->(env){[200, {'Content-Type' => 'text/plain'}, ["Hello World"]]} }
+    it { described_class.should respond_to(:draw) }
+    it { should respond_to(:get) }
+    it { should respond_to(:post) }
+    it { should respond_to(:put) }
+    it { should respond_to(:head) }
+    it { should respond_to(:options) }
+    it { should respond_to(:patch) }
+    it { should respond_to(:delete) }
+    it { should respond_to(:reset!) }
+    its(:routeset) { should be_kind_of(Truss::Router::Routeset) }
+
+    it { should respond_to(:call) }
+
+    it "builds a Get route when #get is called" do
+        described_class.should_receive(:build_node).with(:Get, "/home", app, {})
+        described_class.get("/home", app)
+    end
+
+    it "builds a Post route when #post is called" do
+        described_class.should_receive(:build_node).with(:Post, "/home", app, {})
+        described_class.post("/home", app)
+    end
+
+    it "builds a Put route when #put is called" do
+        described_class.should_receive(:build_node).with(:Put, "/home", app, {})
+        described_class.put("/home", app)
+    end
+
+    it "builds a Patch route when #patch is called" do
+        described_class.should_receive(:build_node).with(:Patch, "/home", app, {})
+        described_class.patch("/home", app)
+    end
+
+    it "builds a Head route when #head is called" do
+        described_class.should_receive(:build_node).with(:Head, "/home", app, {})
+        described_class.head("/home", app)
+    end
+
+    it "builds a Options route when #options is called" do
+        described_class.should_receive(:build_node).with(:Options, "/home", app, {})
+        described_class.options("/home", app)
+    end
+
+    it "builds a Delete route when #delete is called" do
+        described_class.should_receive(:build_node).with(:Delete, "/home", app, {})
+        described_class.delete("/home", app)
+    end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: truss-router
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - John Maxwell
@@ -80,9 +80,12 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- benchmarks/simple_bench.rb
 - lib/truss-router.rb
 - lib/truss/router.rb
 - lib/truss/router/node.rb
+- lib/truss/router/request.rb
+- lib/truss/router/routes.rb
 - lib/truss/router/routes/delete.rb
 - lib/truss/router/routes/get.rb
 - lib/truss/router/routes/head.rb
@@ -90,7 +93,11 @@ files:
 - lib/truss/router/routes/patch.rb
 - lib/truss/router/routes/post.rb
 - lib/truss/router/routes/put.rb
+- lib/truss/router/routeset.rb
 - lib/truss/router/version.rb
+- spec/lib/truss/draw_routes_spec.rb
+- spec/lib/truss/request_spec.rb
+- spec/lib/truss/route_dispatch_spec.rb
 - spec/lib/truss/router/node_spec.rb
 - spec/lib/truss/router/routes/delete_spec.rb
 - spec/lib/truss/router/routes/get_spec.rb
@@ -99,6 +106,9 @@ files:
 - spec/lib/truss/router/routes/patch_spec.rb
 - spec/lib/truss/router/routes/post_spec.rb
 - spec/lib/truss/router/routes/put_spec.rb
+- spec/lib/truss/router/routes_spec.rb
+- spec/lib/truss/router/routeset_spec.rb
+- spec/lib/truss/router_spec.rb
 - spec/spec_helper.rb
 - truss-router.gemspec
 homepage: http://truss-io.github.io
@@ -126,6 +136,9 @@ signing_key:
 specification_version: 4
 summary: Truss Router is a modular Rack Router for Truss
 test_files:
+- spec/lib/truss/draw_routes_spec.rb
+- spec/lib/truss/request_spec.rb
+- spec/lib/truss/route_dispatch_spec.rb
 - spec/lib/truss/router/node_spec.rb
 - spec/lib/truss/router/routes/delete_spec.rb
 - spec/lib/truss/router/routes/get_spec.rb
@@ -134,4 +147,7 @@ test_files:
 - spec/lib/truss/router/routes/patch_spec.rb
 - spec/lib/truss/router/routes/post_spec.rb
 - spec/lib/truss/router/routes/put_spec.rb
+- spec/lib/truss/router/routes_spec.rb
+- spec/lib/truss/router/routeset_spec.rb
+- spec/lib/truss/router_spec.rb
 - spec/spec_helper.rb