octarine 0.0.1

data/README.rdoc

@@ -0,0 +1,44 @@
+= Octarine
+
+Octarine is a Sinatra-like DSL for writing a HTTP routing proxy, i.e. a service
+that accepts incoming requests, re-issues them to the appropriate endpoint, and
+relays the output. It also includes support for modifying the output, or
+transforming one external request in to multiple internal requests.
+
+== Installation
+
+gem install octarine
+
+== Usage
+
+  class Router
+    include Octarine::App
+    
+    get "/gp*rest" do |request|
+      request.to("globalpersonals.co.uk", request.path.lchomp("/gp"))
+    end
+  end
+
+== Licence
+
+(The MIT License)
+
+Copyright (c) 2011 Global Personals, Ltd.
+
+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/lib/octarine.rb

@@ -0,0 +1,2 @@
+libs = %W{app endpoint path request response}.map(&"../octarine/".method(:+))
+libs.map {|lib| File.expand_path(lib, __FILE__)}.each(&method(:require))

data/lib/octarine/app.rb

@@ -0,0 +1,112 @@
+require "forwardable"
+require "http_router"
+require_relative "request"
+require_relative "endpoint"
+
+module Octarine # :nodoc:
+  module App
+    module ClassMethods
+      
+      ##
+      # :method: add
+      # :call-seq: add(path, opts={}) {|request| block }
+      # 
+      # Adds block as a handler for path.
+      
+      ##
+      # :method: get
+      # :call-seq: get(path, opts={}) {|request| block }
+      # 
+      # Adds block as a handler for path when the request method is GET.
+      
+      ##
+      # :method: post
+      # :call-seq: post(path, opts={}) {|request| block }
+      # 
+      # Adds block as a handler for path when the request method is POST.
+      
+      ##
+      # :method: delete
+      # :call-seq: delete(path, opts={}) {|request| block }
+      # 
+      # Adds block as a handler for path when the request method is DELETE.
+      
+      ##
+      # :method: put
+      # :call-seq: put(path, opts={}) {|request| block }
+      # 
+      # Adds block as a handler for path when the request method is PUT.
+      
+      ##
+      # :method: default
+      # :call-seq: default {|request| block }
+      # 
+      # Adds block as a handler for when no path is matched.
+      
+      [:add, :get, :post, :delete, :put, :default].each do |method|
+        define_method(method) do |*args, &block|
+          (@handlers ||= []) << [method, *args, block]
+        end
+      end
+      
+      def add_route(route) # :nodoc:
+        (@handlers ||= []) << [__method__, route, nil]
+      end
+      
+      # :call-seq: request_class(klass)
+      # 
+      # Set the class of the request object handed to the path handler blocks.
+      # Defaults to Octarine::Request.
+      # 
+      def request_class(klass=nil)
+        klass ? @request_class = klass : @request_class || Octarine::Request
+      end
+      
+      # :call-seq: environment -> string
+      # 
+      # Returns the current enviroment. Defaults to "development".
+      # 
+      def environment
+        ENV["RACK_ENV"] || "development"
+      end
+      
+      def new(*args) # :nodoc:
+        instance = super
+        instance.router = HttpRouter.new
+        @handlers.each do |method, *args|
+          block = args.pop
+          instance.router.send(method, *args) do |env|
+            instance.instance_exec(request_class.new(env), &block)
+          end
+        end
+        instance
+      end
+    end
+    
+    attr_accessor :router # :nodoc:
+    
+    ##
+    # :method: call
+    # :call-seq: app.call(env) -> array
+    # 
+    # Rack-compatible #call method.
+    
+    extend Forwardable
+    def_delegators :router, :url, :call
+    
+    def self.included(includer) # :nodoc:
+      includer.extend(ClassMethods)
+    end
+    
+    # :call-seq: app.endpoint(string) -> endpoint
+    # app.endpoint(client) -> endpoint
+    # 
+    # Create an Octarine::Endpoint with either a string of the host:port or
+    # a client instance API compatible with Octarine::SimpleHTTP.
+    # 
+    def endpoint(host_or_client)
+      Octarine::Endpoint.new(host_or_client)
+    end
+    
+  end
+end

data/lib/octarine/endpoint.rb

@@ -0,0 +1,125 @@
+require "forwardable"
+require_relative "simple_http"
+require_relative "response"
+
+module Octarine # :nodoc:
+  
+  # Octarine::Endpoint is a wrapper round a http client that presents a DSL for
+  # generating paths and making requests.
+  # 
+  # Examples:
+  # 
+  #   # GET users/123/messages/567
+  #   endpoint.users(123).messages[567]
+  # 
+  #   # GET 123/details/address
+  #   endpoint.(123).details["address"]
+  # 
+  #   # POST users/123/messages
+  #   endpoint.users(123).post("messages", body)
+  # 
+  class Endpoint
+    attr_accessor :path
+    protected :path, :path=
+    attr_reader :client
+    private :client
+    
+    extend Forwardable
+    def_delegators :@client, :host, :port
+    
+    # :call-seq: Endpoint.new(host) -> endpoint
+    # Endpoint.new(client) -> endpoint
+    # 
+    # Create a new Endpoint instance, either with a string of host:port, or a
+    # http client instance API compatible with Octarine::SimpleHTTP
+    # 
+    def initialize(host_or_client)
+      if host_or_client.respond_to?(:get)
+        @client = host_or_client
+      else
+        @client = Octarine::SimpleHTTP.new(host_or_client)
+      end
+      @path = ""
+    end
+    
+    # :call-seq: endpoint.call(obj) -> new_endpoint
+    # endpoint.(obj) -> new_endpoint
+    # 
+    # Returns a new endpoint with the string respresentation of obj added to the
+    # path. E.g. `endpoint.(123)` will return an endpoint with `/123` appended
+    # to the path.
+    # 
+    def call(id)
+      method_missing(id)
+    end
+    
+    # :call-seq: endpoint.method_missing(name, id) -> new_endpoint
+    # endpoint.method_missing(name) -> new_endpoint
+    # endpoint.anything(id) -> new_endpoint
+    # endpoint.anything -> new_endpoint
+    # 
+    # Implements the path generation DSL.
+    #   endpoint.foo(1).bar   #=> new endpoint with path set to /foo/1/bar
+    # 
+    def method_missing(name, *args)
+      super unless args.length <= 1 && !block_given?
+      copy = dup
+      copy.path = join(copy.path, name.to_s, *args)
+      copy
+    end
+    
+    # :call-seq: endpoint.head(id, headers={}) -> response
+    # 
+    # Make a HEAD request to endpoint's path plus `/id`.
+    # 
+    def head(id, headers={})
+      response = client.head(join(path, id.to_s), headers)
+      Octarine::Response.new(response.body, response.headers, response.status)
+    end
+    
+    # :call-seq: endpoint.head(id, headers={}) -> response
+    # endpoint[id] -> response
+    # 
+    # Make a GET request to endpoint's path plus `/id`.
+    # 
+    def get(id, headers={})
+      response = client.get(join(path, id.to_s), headers)
+      Octarine::Response.new(response.body, response.headers, response.status)
+    end
+    alias [] get
+    
+    # :call-seq: endpoint.head(id, body=nil, headers={}) -> response
+    # 
+    # Make a POST request to endpoint's path plus `/id`.
+    # 
+    def post(id, body=nil, headers={})
+      response = client.post(join(path, id.to_s), body, headers)
+      Octarine::Response.new(response.body, response.headers, response.status)
+    end
+    
+    # :call-seq: endpoint.head(id, body=nil, headers={}) -> response
+    # 
+    # Make a PUT request to endpoint's path plus `/id`.
+    # 
+    def put(id, body=nil, headers={})
+      response = client.put(join(path, id.to_s), body, headers)
+      Octarine::Response.new(response.body, response.headers, response.status)
+    end
+    
+    # :call-seq: endpoint.head(id, headers={}) -> response
+    # 
+    # Make a DELETE request to endpoint's path plus `/id`.
+    # 
+    def delete(id, headers={})
+      response = client.delete(join(path, id.to_s), headers)
+      Octarine::Response.new(response.body, response.headers, response.status)
+    end
+    
+    private
+    
+    def join(*paths)
+      paths.map {|path| path.gsub(%r{(^/|/$)}, "")}.join("/")
+    end
+    
+  end
+end

data/lib/octarine/path.rb

@@ -0,0 +1,93 @@
+require "forwardable"
+
+module Octarine # :nodoc:
+  
+  # Octarine::Path represents the path and query string portion of a url.
+  # 
+  # You are unlikely to need to create a Path instance yourself, insted you
+  # will usually obtain one from Request#path.
+  # 
+  # If you set a handler like so:
+  #   get "/users/:user_id/messages/:message_id" {|request| ... }
+  # and a request is made like:
+  #   GET /users/1234/messages/4567?history=true
+  # then `request.path` will behave as below:
+  #   path.user_id        #=> "1234"
+  #   path[:user_id]      #=> "1234"
+  #   path.message_id     #=> "5678"
+  #   path[:message_id]   #=> "5678"
+  #   path["history"]     #=> "true"
+  #   path.to_s           #=> "/users/1234/messages/4567?history=true"
+  #   path.path           #=> "/users/1234/messages/4567"
+  #   path.query_string   #=> "history=true"
+  #   path.to_hash        #=> {:user_id=>"1234", :message_id=>"5678", "history"=>"true"}
+  #   path.query          #=> {"history"=>"true"}
+  # 
+  # The following methods are available and behave as if the path was a hash:
+  # assoc, [], each_key, each_pair, each_value, empty?, fetch, has_key?,
+  # has_value?, key, key?, keys, merge, rassoc, to_a, to_hash, value?, values,
+  # values_at and all Enumerable methods
+  # 
+  # The following methods are available and behave as if path was a string:
+  # +, =~, bytesize, gsub, length, size, sub, to_str, to_s
+  # 
+  class Path
+    # String of the path, without the query string.
+    attr_reader :path
+    # String of the query string.
+    attr_reader :query_string
+    # Hash of the query string.
+    attr_reader :query
+    
+    extend Forwardable
+    def_delegators :@params, :assoc, :[], :each_key, :each_pair,
+      :each_value, :empty?, :fetch, :has_key?, :has_value?, :key, :key?, :keys,
+      :merge, :rassoc, :to_a, :value?, :values, :values_at,
+      *Enumerable.public_instance_methods
+    def_delegator :@params, :dup, :to_hash
+    def_delegators :@full_path, :+, :=~, :bytesize, :gsub, :length, :size, :sub,
+      :to_str, :to_s
+    
+    # :call-seq: Path.new(string, path_params, query_string) -> path
+    # 
+    # Create a new Path instance from the a string or the path, the path
+    # parameters as a hash, and a string of the query string.
+    # 
+    def initialize(path, params, query_string)
+      @path = path
+      params.each do |key, value|
+        self.class.class_eval do
+          define_method(key) {@params[key]}
+        end
+      end
+      @query_string = query_string
+      @query = parse_query(@query_string)
+      @full_path = @path.dup
+      @full_path << "?#{@query_string}" if @query_string && !@query_string.empty?
+      @params = params.merge(@query)
+    end
+    
+    # :call-seq: path.lchomp(separator=$/) -> string
+    # 
+    # Like String#chomp, but removes seperator from the left of the path.
+    # 
+    def lchomp(separator=$/)
+      string = to_s
+      string.start_with?(separator) ? string[separator.length..-1] : string
+    end
+    
+    private
+    
+    def parse_query(string)
+      string.split("&").each_with_object({}) do |key_value, out|
+        key, value = key_value.split("=")
+        key, value = url_decode(key), url_decode(value)
+        out[key] = out.key?(key) ? [*out[key]].push(value) : value
+      end
+    end
+    
+    def url_decode(str)
+      str.tr("+", " ").gsub(/(%[0-9a-f]{2})+/i) {|m| [m.delete("%")].pack("H*")}
+    end
+  end
+end

data/lib/octarine/request.rb

@@ -0,0 +1,89 @@
+require_relative "response"
+require_relative "endpoint"
+
+module Octarine # :nodoc:
+  class Request
+    # The Rack enviroment hash
+    attr_reader :env
+    # The request method, e.g. "GET", "POST"
+    attr_reader :method
+    # The host name the request was made to
+    attr_reader :host
+    # The port the request was made to
+    attr_reader :port
+    # An Octarine::Path representing the path request was made to
+    attr_reader :path
+    # The request POST/PUT body
+    attr_reader :input
+    
+    # :call-seq: Request.new(env) -> request
+    # 
+    # Create a Request instance with a Rack enviroment hash.
+    # 
+    def initialize(env)
+      @env = env
+      env.delete("router")
+      path_params = env.delete("router.params")
+      @method = env["REQUEST_METHOD"]
+      @host = env["SERVER_NAME"]
+      @port = env["SERVER_PORT"]
+      @path = Path.new(env["SCRIPT_NAME"] || env["PATH_INFO"], path_params,
+        env["QUERY_STRING"])
+      @input = env["rack.input"]
+    end
+    
+    # :call-seq: request[header_name] -> header_value
+    # 
+    # Retrieve headers.
+    #   request["Content-Length"]   #=> "123"
+    #   request["Content-Type"]     #=> "application/json"
+    # 
+    def [](key)
+      upper_key = key.to_s.tr("a-z-", "A-Z_")
+      unless upper_key == "CONTENT_LENGTH" || upper_key == "CONTENT_TYPE"
+        upper_key[0,0] = "HTTP_"
+      end
+      @env[key]
+    end
+    
+    # :call-seq: request.to(endpoint) -> response
+    # request.to(endpoint, path) -> response
+    # request.to(endpoint, path, input) -> response
+    # 
+    # Re-issue request to new host/path.
+    # 
+    def to(endpoint=Octarine::Endpoint.new(host), to_path=path, to_input=input)
+      res = if %W{POST PUT}.include?(method)
+        header = {"content-type" => "application/json"}
+        endpoint.send(method.downcase, to_path, to_input, header)
+      else
+        endpoint.send(method.downcase, to_path)
+      end
+      headers = res.headers
+      headers.delete("transfer-encoding")
+      headers.delete("content-length")
+      Octarine::Response.new(res.body, headers, res.status)
+    end
+    
+    # :call-seq: request.redirect(path) -> response
+    # 
+    # Issue redirect to path.
+    # 
+    def redirect(path)
+      
+    end
+    
+    def to_s # :nodoc:
+      header = Hash[@env.select do |k,v|
+        k =~ /^HTTP_[^(VERSION)]/ || %W{CONTENT_LENGTH CONTENT_TYPE}.include?(k)
+      end.map do |key, value|
+        [key.sub(/HTTP_/, "").split(/_/).map(&:capitalize).join("-"), value]
+      end]
+      version = " " + @env["HTTP_VERSION"] if @env.key?("HTTP_VERSION")
+      "#{method} #{path}#{version}\r\n" << header.map do |key, value|
+        "#{key}: #{value}"
+      end.join("\r\n") << "\r\n\r\n"
+    end
+    
+  end
+end

data/lib/octarine/response.rb

@@ -0,0 +1,109 @@
+require "forwardable"
+
+module Octarine # :nodoc:
+  class Response
+    attr_accessor :body, :status, :header
+    alias headers header
+    alias headers= header=
+    
+    extend Forwardable
+    def_delegators :to_ary, :first, :last
+    
+    # :call-seq: Response.new(body) -> response
+    # Response.new(body, header) -> response
+    # Response.new(body, header, status) -> response
+    # 
+    # Create a new Response instance.
+    # 
+    def initialize(body=[], header={}, status=200)
+      status, header = header, status if header.respond_to?(:to_i)
+      @body = body
+      @header = header
+      @status = status.to_i
+      header["content-type"] ||= "text/html" unless [204, 304].include?(@status)
+    end
+    
+    # :call-seq: response.update {|body| block } -> response
+    # response.update(path) {|value| block } -> response
+    # 
+    # Called without an argument, the block will be supplied the response body,
+    # and the response body will be set to the result of the block. The response
+    # itself is returned.
+    # 
+    # When called with an argument the body should be a hash, the body will be
+    # traversed accoring to the path supplied, the value of the body will be
+    # yielded to the block, and then replaced with the result of the block.
+    # Example:
+    #   response.body
+    #   #=> {"data" => [{"user" => "1234", "message" => "..."}]}
+    #   
+    #   response.update("data.user") {|id| User.find(id).to_hash}
+    #   
+    #   response.body
+    #   #=> {"data" => [{"user" => {"id" => "1234", ...}, "message" => "..."}]}
+    # 
+    def update(path=nil, &block)
+      @body = if body.respond_to?(:to_ary) && path.nil?
+        block.call(body)
+      else
+        apply(body, path, &block)
+      end
+      self
+    end
+    
+    # :call-seq: response[key] -> value
+    # 
+    # Get a header.
+    # 
+    def [](key)
+      (key.is_a?(Numeric) ? to_ary : header)[key]
+    end
+    
+    # :call-seq: response[key] = value -> value
+    # 
+    # Set a header.
+    # 
+    def []=(key, value)
+      return header[key] = value unless key.is_a?(Numeric)
+      case key
+      when 0
+        @status = value
+      when 1
+        @header = value
+      when 2
+        @body = value
+      else
+        raise ArgumentError("Unexpected key #{key}")
+      end
+    end
+    
+    # :call-seq: response.to_ary -> array
+    # response.to_a -> array
+    # 
+    # Convert to a Rack response array of [status, headers, body]
+    # 
+    def to_ary
+      [status, header, body.respond_to?(:each) ? body : [body].compact]
+    end
+    alias to_a to_ary
+    
+    private
+    
+    def apply(object, path=nil, &block)
+      if object.respond_to?(:to_ary)
+        return object.to_ary.map {|obj| apply(obj, path, &block)}
+      end
+      
+      key, rest = path.split(".", 2) if path
+      if rest
+        object[key] = apply(object[key], rest, &block)
+      elsif key
+        object[key] = block.call(object[key])
+      else
+        return block.call(object)
+      end
+      object
+    end
+    
+  end
+end

data/lib/octarine/simple_http.rb

@@ -0,0 +1,82 @@
+require "net/http"
+
+module Octarine # :nodoc:
+  
+  # SimpleHTTP is a bare-bones implementation of a simple http client, designed
+  # to be easily replaceable with another implementation.
+  # 
+  class SimpleHTTP
+    Response = Struct.new(:status, :headers, :body)
+    
+    # :call-seq: SimpleHTTP.new(url, options={}) -> simple_http
+    # SimpleHTTP.new(options) -> simple_http
+    # 
+    # Create a SimpleHTTP instace with either a url and options or options with
+    # a :url key.
+    # 
+    def initialize(url, options={})
+      unless url.respond_to?(:to_str)
+        options = url
+        url = options[:url]
+      end
+      @host, @port = url.to_s.split(/:/)
+    end
+    
+    # :call-seq: simple_http.head(path, headers={}) -> response
+    # 
+    # Perform a HEAD request, returns a response that responds to #status,
+    # #headers, and #body
+    # 
+    def head(path, headers={})
+      request(Net::HTTP::Head.new(path, headers))
+    end
+    
+    # :call-seq: simple_http.get(path, headers={}) -> response
+    # 
+    # Perform a GET request, returns a response that responds to #status,
+    # #headers, and #body
+    # 
+    def get(path, headers={})
+      request(Net::HTTP::Get.new(path, headers))
+    end
+    
+    # :call-seq: simple_http.post(path, body=nil, headers={}) -> response
+    # 
+    # Perform a POST request, returns a response that responds to #status,
+    # #headers, and #body
+    # 
+    def post(path, body=nil, headers={})
+      req = Net::HTTP::Post.new(path, headers)
+      req.body = body if body
+      request(req)
+    end
+    
+    # :call-seq: simple_http.put(path, body=nil, headers={}) -> response
+    # 
+    # Perform a PUT request, returns a response that responds to #status,
+    # #headers, and #body
+    # 
+    def put(path, body=nil, headers={})
+      req = Net::HTTP::Put.new(path, headers)
+      req.body = body if body
+      request(req)
+    end
+    
+    # :call-seq: simple_http.delete(path, headers={}) -> response
+    # 
+    # Perform a DELETE request, returns a response that responds to #status,
+    # #headers, and #body
+    # 
+    def delete(path, headers={})
+      request(Net::HTTP::Delete.new(path, headers))
+    end
+    
+    private
+    def request(request)
+      response = Net::HTTP.start(@host, @port) {|http| http.request(request)}
+      headers = Hash[response.to_hash.map {|h,k| [h, k.join("\n")]}]
+      Response.new(response.code, headers, response.body)
+    end
+    
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: octarine
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Matthew Sadler
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-11-02 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: http_router
+  requirement: &2153077060 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2153077060
+description: Sinatra-like DSL for writing a HTTP routing proxy.
+email: mat@sourcetagsandcodes.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.rdoc
+files:
+- lib/octarine/app.rb
+- lib/octarine/endpoint.rb
+- lib/octarine/path.rb
+- lib/octarine/request.rb
+- lib/octarine/response.rb
+- lib/octarine/simple_http.rb
+- lib/octarine.rb
+- README.rdoc
+homepage: http://github.com/globaldev/octarine
+licenses: []
+post_install_message: 
+rdoc_options:
+- --main
+- README.rdoc
+- --charset
+- utf-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.7
+signing_key: 
+specification_version: 3
+summary: HTTP routing proxy DSL
+test_files: []