clutterbuck-router 0.0.1

data/README.md

@@ -0,0 +1,103 @@
+This is a fairly minimal, unobtrusive request routing library, part of the
+Clutterbuck Web Application Construction Kit.
+
+
+# Installation
+
+It's a gem:
+
+    gem install clutterbuck-router
+
+There's also the wonders of [the Gemfile](http://bundler.io):
+
+    gem 'clutterbuck-router'
+
+If you're the sturdy type that likes to run from git:
+
+    rake install
+
+Or, if you've eschewed the convenience of Rubygems entirely, then you
+presumably know what to do already.
+
+
+# Usage
+
+Load the code:
+
+    require 'clutterbuck-router'
+
+Then include {Clutterbuck::Router} in any class you wish to be a Rack
+application using the Clutterbuck router:
+
+    class ExampleApp
+      include Clutterbuck::Router
+    end
+
+Now, you define the routes you wish the application to respond to:
+
+    class ExampleApp
+      include Clutterbuck::Router
+
+      get '/' do
+        [200, [["Content-Type", "text/plain"]], ["Ohai!"]]
+      end
+
+      post %r{^/mail/([^/]+)$} do |path_opt|
+        [200, [["Content-Type", "text/plain"]],
+         ["You posted #{env['rack.input'].read} to #{path_opt}"]
+        ]
+      end
+    end
+
+The above example pretty much demonstrates all the features that
+{Clutterbuck::Router} provides.  You define routes by means of methods named
+after the HTTP verb to respond to, and the path is either a string or a
+regex.  If you specify a string, then the path provided must match *exactly*
+the request path.  If you specify a regex, then the first route which
+matches the request path and method gets run, with any captured
+subexpressions (ie "the bits in the parentheses") get passed as arguments to
+the block.
+
+The `env` method returns the request's Rack environment; apart from that,
+you're on your own as far as interacting with Rack itself -- you have to
+parse out the query params and request body, and return your own response
+array in the Rack-compatible format.  If that all sounds like too much work,
+you might want to look at `clutterbuck-request` and/or
+`clutterbuck-response` to get syntactic sugar to help with those parts of
+your app.
+
+Once your app is crafted to your liking, you can put it into a `config.ru`:
+
+    require 'example_app'
+
+    use ExampleApp
+
+Fire that up via `rackup`, and you're off and running.
+
+
+# Contributing
+
+Bug reports should be sent to the [Github issue
+tracker](https://github.com/mpalmer/clutterbuck-router/issues), or
+[e-mailed](mailto:theshed+clutterbuck@hezmatt.org).  Patches can be sent as a
+Github pull request, or [e-mailed](mailto:theshed+clutterbuck@hezmatt.org).
+
+
+# Licence
+
+Unless otherwise stated, everything in this repo is covered by the following
+copyright notice:
+
+    Copyright (C) 2015  Matt Palmer <matt@hezmatt.org>
+
+    This program is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License version 3, as
+    published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/clutterbuck-router.gemspec

@@ -0,0 +1,33 @@
+require 'git-version-bump' rescue nil
+
+Gem::Specification.new do |s|
+	s.name = "clutterbuck-router"
+
+	s.version = GVB.version rescue "0.0.0.1.NOGVB"
+	s.date    = GVB.date    rescue Time.now.strftime("%Y-%m-%d")
+
+	s.platform = Gem::Platform::RUBY
+
+	s.summary  = "Rack-based minimal request router"
+
+	s.authors  = ["Matt Palmer"]
+	s.email    = ["theshed+clutterbuck@hezmatt.org"]
+	s.homepage = "http://theshed.hezmatt.org/clutterbuck"
+
+	s.files = `git ls-files -z`.split("\0").reject { |f| f =~ /^(G|spec|Rakefile)/ }
+
+	s.required_ruby_version = ">= 1.9.3"
+
+	s.add_runtime_dependency "rack", "~> 1.5"
+
+	s.add_development_dependency 'bundler'
+	s.add_development_dependency 'github-release'
+	s.add_development_dependency 'guard-spork'
+	s.add_development_dependency 'guard-rspec'
+	s.add_development_dependency 'rake', '~> 10.4', '>= 10.4.2'
+	# Needed for guard
+	s.add_development_dependency 'rb-inotify', '~> 0.9'
+	s.add_development_dependency 'redcarpet'
+	s.add_development_dependency 'rspec'
+	s.add_development_dependency 'yard'
+end

data/config.ru

@@ -0,0 +1,4 @@
+require 'pp'
+
+run proc { |env| pp env }
+

data/lib/clutterbuck-router.rb

@@ -0,0 +1 @@
+require 'clutterbuck/router'

data/lib/clutterbuck/router.rb

@@ -0,0 +1,269 @@
+require 'clutterbuck/router/route'
+
+#:nodoc:
+module Clutterbuck; end
+
+# A minimal router for Rack-compatible web applications.
+#
+# Does request routing, and *only* request routing.  You specify
+# routes as strings (exact match) or regexes, and then when the
+# app gets a request, the appropriate route gets executed.
+#
+module Clutterbuck::Router
+	#:nodoc:
+	# Signals that the router got a 404.  Should never escape the app call.
+	#
+	class NotFoundError < StandardError; end
+
+	#:nodoc:
+	# Signals that the router got a 405.  Should never escape the app call.
+	#
+	class MethodNotAllowedError < StandardError; end
+
+	# All of the methods to define the app's routing behaviour are defined
+	# on the class, because that's where the config lives.  Instances of the
+	# app class are created to handle requests.
+	#
+	module ClassMethods
+		# Process a request from the app.
+		#
+		def call(env)
+			self.new(env).call
+		end
+
+		# @!macro handler_args
+		#   See {.add_handler} for all the gory details.
+		#
+		#   @param path [String, Regexp]
+		#
+		#   @param block [Proc]
+		#
+		#   @return void
+		#
+
+		# Define a handler for `GET <path>` and `HEAD <path>` requests.
+		#
+		# @macro handler_args
+		#
+		def get(path, &block)
+			add_handler('GET', path, &block)
+			add_handler('HEAD', path, &block)
+		end
+
+		# Define a handler for `PUT <path>` requests.
+		#
+		# @macro handler_args
+		#
+		def put(path, &block)
+			add_handler('PUT', path, &block)
+		end
+
+		# Define a handler for `POST <path>` requests.
+		#
+		# @macro handler_args
+		#
+		def post(path, &block)
+			add_handler('POST', path, &block)
+		end
+
+		# Define a handler for `DELETE <path>` requests.
+		#
+		# @macro handler_args
+		#
+		def delete(path, &block)
+			add_handler('DELETE', path, &block)
+		end
+
+		# Define a handler for `PATCH <path>` requests.
+		#
+		# @macro handler_args
+		#
+		def patch(path, &block)
+			add_handler('PATCH', path, &block)
+		end
+
+		# Define a handler for an arbitrary HTTP method and path.
+		#
+		# If more than one handler for a given `verb` and `path` match a URL,
+		# then the first handler defined will be called.
+		#
+		# If no handler matches given `path`, then `404 Not Found` will be
+		# returned.  If a handler exists for `path`, but does not support the
+		# method of the request, then `405 Method Not Allowed` will be
+		# returned to the client.
+		#
+		# The return value of the `block` can be one of a number of different
+		# things.  If you set the `Content-Type` response header (by calling
+		# `set_header 'Content-Type', <something>`), then no special
+		# processing is done and your content is sent to the client
+		# more-or-less as-is, with only `Content-Length` calculation and
+		# wrapping your returned object in an array (if it doesn't already
+		# respond to `#each`, as required by Rack).  This allows your API to
+		# return anything at all if it feels like it.
+		#
+		# However, by far the most common response will be a JSON document.
+		# If you don't set a `Content-Type` header in your handler, then we
+		# try quite hard to turn what you return from your handler into either
+		# JSON (if possible), or `text/plain`.
+		#
+		# For starters, if what you send back responds to `#each`, then we
+		# assume that you know what you're doing and will be sending back
+		# strings that will come together to be valid JSON.  We'll set
+		# `Content-Type` and `Link` headers to match with the handler's
+		# schema, and that is that.
+		#
+		# If what you send back doesn't respond to `#each`, then we try to
+		# determine if its valid JSON by parsing it as JSON (if it's a string)
+		# or trying to call `#to_json` on it.  If either of those work, then
+		# `Content-Type` and `Link` are set to match the schema for your
+		# handler, and all is well.  Otherwise, we're kinda out of options and
+		# we'll send back the content as `text/plain` and hope the client
+		# knows what to do with it.
+		#
+		# @param verb [String] the **case sensitive** HTTP method which you
+		#   wish this handler to respond for.  If you're using the
+		#   `get`/`post/`put`/etc wrappers for `add_handler`, this argument is
+		#   taken care of for you.  It's only if you want to define your own
+		#   custom HTTP verbs that you'd ever need to worry about this
+		#   argument.
+		#
+		# @param path [String, Regexp] defines the path which is to be handled
+		#   by this handler.  The path is defined relative to the root of the
+		#   application; that is, there may be path components in the request
+		#   URI which won't be matched against, because they're handled by the
+		#   webserver or Rack itself (if the app is routed to via a `map`
+		#   block, for example).
+		#
+		#   If `path` is a string, the matching logic is very simple: if the
+		#   path of the request matches exactly with `path`, then we run this
+		#   handler.  If not, we skip it.
+		#
+		#   If `path` is a regex, things are ever so slightly more
+		#   complicated.  In that instance, we'll run the handler if the given
+		#   regex matches the path of the request.  In addition, any capturing
+		#   subexpressions (aka "the bits in parentheses") in the regular
+		#   expression will be passed as arguments to the handler block.
+		#
+		#   In almost all cases, you'll want to anchor your regular
+		#   expressions (surround them in `^` and `$`); while it's very
+		#   unlikely that you'll want to handle a URL with `/foo` anywhere in
+		#   the path, we don't want to *forbid* you from doing so, so there's
+		#   no automatic anchoring of regexes.
+		#
+		# @param block [Proc] the code to execute when this handler is
+		#   invoked.  An arbitrary number of arguments may be passed to this
+		#   block, if `path` is a regex which contains capturing
+		#   subexpressions (that is, parts of the regular expression
+		#   surrounded by unescaped parentheses).  This is useful to capture
+		#   portions of the URL, such as resource IDs, and feed them into your
+		#   handler as arguments.
+		#
+		# @raise [ArgumentError] if you don't pass in a block, or you pass an
+		#   invalid type for `path`.
+		#
+		def add_handler(verb, path, &block)
+			unless block_given?
+				raise ArgumentError,
+				      "Must pass a block"
+			end
+
+			@routes ||= []
+			@routes << Route.new(verb, path, method_for(verb, path, block))
+		end
+
+		# :nodoc:
+		# Grovel through the list of routes, looking for a match.
+		#
+		# @raise [Clutterbuck::Router::NotFoundError] if no route matched the
+		#   given path.
+		#
+		# @raise [Clutterbuck::Router::MethodNotAllowedError] if a route matched
+		#   the given path, but it didn't have the right verb.
+		#
+		def find_route(verb, path)
+			if @routes.nil?
+				raise Clutterbuck::Router::NotFoundError,
+				      path
+			end
+
+			candidates = @routes.select { |r| r.handles?(path) }
+
+			if candidates.empty?
+				raise Clutterbuck::Router::NotFoundError,
+				      path
+			end
+
+			candidates = candidates.select { |r| r.verb == verb }
+
+			if candidates.empty?
+				raise Clutterbuck::Router::MethodNotAllowedError,
+				      "#{verb} not permitted on #{path}"
+			end
+
+			candidates.first
+		end
+
+		private
+
+		# Get an unbound instance method for the given verb/path/block.
+		#
+		# @param verb [String]
+		#
+		# @param path [String, Regexp]
+		#
+		# @param block [Proc]
+		#
+		# @return [UnboundMethod]
+		#
+		def method_for(verb, path, block)
+			name = "#{verb} #{path}".to_sym
+			define_method(name, &block)
+			instance_method(name).tap do |m|
+				remove_method name
+			end
+		end
+	end
+
+	#:nodoc:
+	# Add in the class-level methods to the app.
+	#
+	def self.included(mod)
+		mod.extend(ClassMethods)
+	end
+
+	# Create a new instance of the app.
+	#
+	# @param env [Hash] The Rack environment for this request.
+	#
+	def initialize(env)
+		@env = env
+	end
+
+	# Handle the request.
+	#
+	# Find the route, run it, and return the result.
+	#
+	def call
+		path = env["PATH_INFO"].empty? ? "/" : env["PATH_INFO"]
+
+		begin
+			route = self.class.find_route(env["REQUEST_METHOD"], path)
+		rescue Clutterbuck::Router::NotFoundError
+			return [404, [["Content-Type", "text/plain"]], ["Not found"]]
+		rescue Clutterbuck::Router::MethodNotAllowedError => ex
+			return [405, [["Content-Type", "text/plain"]], [ex]]
+		end
+
+		route.run(self, path).tap do |response|
+			if env["REQUEST_METHOD"] == "HEAD"
+				response[2] = []
+			end
+		end
+	end
+
+	protected
+	# Return the Rack environment for this request.
+	def env
+		@env
+	end
+end

data/lib/clutterbuck/router/route.rb

@@ -0,0 +1,59 @@
+#:nodoc:
+module Clutterbuck; end
+#:nodoc:
+module Clutterbuck::Router; end
+
+# A route within the application.
+#
+# Not something you should ever have to deal with yourself directly, it's
+# part of the internal plumbing of {Clutterbuck::Router}.
+#
+class Clutterbuck::Router::Route
+	attr_accessor :verb, :path_match
+
+	# @param verb [String]
+	#
+	# @param path_match [String, Regexp]
+	#
+	# @param method [UnboundMethod] is a method to call on an instance of the
+	#   app class this route is defined on, which will do whatever is needed
+	#   to handle the route.  Because you can't just create an
+	#   `UnboundMethod` out of thin air, the `UnboundMethod` needs to be
+	#   created in the class, and then passed into here.  Ugly.
+	#
+	def initialize(verb, path_match, method)
+		unless path_match.is_a?(String) or path_match.is_a?(Regexp)
+			raise ArgumentError,
+			      "path must be either a string or a regexp"
+		end
+
+		@verb, @path_match, @method = verb, path_match, method
+	end
+
+	# Can this route handle a request for the specified path?
+	#
+	# @param path [String]
+	#
+	# @return Boolean
+	#
+	def handles?(path)
+		!!case @path_match
+		when String
+			@path_match == path
+		when Regexp
+			@path_match =~ path
+		end
+	end
+
+	# Execute the handler for the route
+	#
+	# Run the method
+	def run(obj, path)
+		args = case @path_match
+			when String then []
+			when Regexp then @path_match.match(path)[1..-1]
+		end
+
+		@method.bind(obj).call(*args)
+	end
+end