hookout 0.1.1

data/README.rdoc

@@ -0,0 +1,98 @@
+= Hookout - Reverse HTTP Webhooks
+Developing webhook based applications from behind a firewall or NAT provides many challenges. The
+biggest is allowing external applications to see your hook. Hookout allows you to use a 
+ReverseHTTP (http://www.reversehttp.net) server to expose your application to the outside world, without needing
+to configure any complicated firewall holes.
+
+== Getting Started
+=== Installing
+Hookout can be installed via RubyGems with:
+  gem sources -a http://gems.github.com
+  gem install paulj-hookout
+
+It can also be installed manually with:
+  git clone git://github.com/paulj/hookout.git
+  cd hookout
+  rake build install
+
+=== Running an application via the hookout helper
+Hookout provides a Rack (http://rack.rubyforge.org) adapter, allowing any standard Rack application to
+be made available. It also bundles a script called hookout that will start up an instance of Thin using
+ReverseHTTP as a backend. This section will cover running a simple Sinatra application with the hookout helper.
+
+Firstly, say we have a simple Sinatra application (called simple-app.rb):
+  require 'rubygems'
+  require 'sinatra'
+  
+  get '/' do
+    "Hello World"
+  end
+
+To run with the hookout adapter, you'll need a simple rackup configuration file. Create a config.ru such as:
+  require 'simple-app'
+  
+  set :run, false
+
+  run Sinatra::Application
+
+From the command line, you can now start this application with a command line such as:
+  hookout -a http://www.reversehttp.net/reversehttp -n simple-ruby-app -R config.ru start
+Thin should boot, and provide output such as:
+  >> Thin web server (v1.0.0 codename That's What She Said)
+  >> Maximum connections set to 1024
+  >> Listening on simple-ruby-app via http://www.reversehttp.net/reversehttp, CTRL+C to stop
+  Bound to location http://simple-ruby-app.www.reversehttp.net/
+
+You can now visit http://simple-ruby-app.www.reversehttp.net to see you application.
+
+=== Configuring Sinatra to use Hookout as the default server
+To make a Sintatra application run Hookout instead of thin, a simple script such as the following can be used:
+  require 'rubygems'
+  require 'sinatra'
+  require 'hookout'
+  
+  set :server, 'hookout'
+  set :host, 'http://www.reversehttp.net/reversehttp'
+  set :port, 'standalone-ruby-app'
+
+  get '/' do
+    "Hello World"
+  end
+
+This instructs Sinatra to start Hookout as the Rack adapter; and informs hookout that it should use
+the public http://www.reversehttp.net server; and informs hookout that it should request the
+"standalone-ruby-app" space on that server for this application. (Note: To prevent problems, it is HIGHLY
+recommended to change this to something more unique before trying this!).
+
+You can now run the application with:
+  ruby test-app.rb
+
+You should see it startup with something like:
+  == Sinatra/0.9.2 has taken the stage on test-ruby-app for development with backup from Hookout
+  Location changed to http://standalone-ruby-app.www.reversehttp.net/
+
+You can now visit http://standalone-ruby-app.www.reversehttp.net, and see you own Sinatra app serving pages!
+
+== Software License
+  Copyright (c) 2008, 2009 Paul Jones <paulj@lshift.net>
+  Copyright (c) 2008, 2009 LShift Ltd. <query@lshift.net>
+
+  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/Rakefile

@@ -0,0 +1,70 @@
+require 'rake'
+require 'spec/rake/spectask'
+require 'rake/clean'
+require 'rake/rdoctask'
+require 'rubygems/specification'
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new('spec') do |t|
+	t.spec_opts  = ["-cfs"]
+	t.spec_files = FileList['spec/**/*_spec.rb']
+	t.libs = ['lib']
+end
+
+desc "Print specdocs"
+Spec::Rake::SpecTask.new(:doc) do |t|
+	t.spec_opts = ["--format", "specdoc", "--dry-run"]
+	t.spec_files = FileList['spec/*_spec.rb']
+end
+
+desc "Generate RCov code coverage report"
+Spec::Rake::SpecTask.new('rcov') do |t|
+	t.spec_files = FileList['spec/*_spec.rb']
+	t.rcov = true
+	t.rcov_opts = ['--exclude', 'examples']
+end
+
+def gemspec
+  @gemspec ||= begin
+    file = File.expand_path('../hookout.gemspec', __FILE__)
+    eval(File.read(file), binding, file)
+  end
+end
+
+begin
+  require 'rake/gempackagetask'
+rescue LoadError
+  task(:gem) { $stderr.puts '`gem install rake` to package gems' }
+else
+  Rake::GemPackageTask.new(gemspec) do |pkg|
+    pkg.gem_spec = gemspec
+  end
+  task :gem => :gemspec
+end
+
+desc "install the gem locally"
+task :install => :package do
+  sh %{gem install pkg/#{gemspec.name}-#{gemspec.version}}
+end
+
+desc "validate the gemspec"
+task :gemspec do
+  gemspec.validate
+end
+
+task :package => :gemspec
+
+
+Rake::RDocTask.new do |t|
+	t.rdoc_dir = 'rdoc'
+	t.title    = "Hookout"
+	t.options << '--line-numbers' << '--inline-source' << '-A cattr_accessor=object'
+	t.options << '--charset' << 'utf-8'
+	t.rdoc_files.include('README.rdoc')
+	t.rdoc_files.include('lib/hookout/*.rb')
+end
+
+CLEAN.include [ 'build/*', '**/*.o', '**/*.so', '**/*.a', 'lib/*-*', '**/*.log', 'pkg', 'lib/*.bundle', '*.gem', '.config' ]
+
+task :test => [ :spec ]
+task :default => :spec

data/VERSION.yml

@@ -0,0 +1,5 @@
+--- 
+:patch: 0
+:major: 0
+:minor: 1
+

data/bin/hookout

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# Hookout command line interface script.
+# Run <tt>hookout -h</tt> to get more usage.
+require 'rubygems'
+require File.dirname(__FILE__) + '/../lib/hookout'
+
+Hookout::Runner.new(ARGV).run!

data/lib/hookout.rb

@@ -0,0 +1,7 @@
+$:.unshift File.expand_path(File.dirname(__FILE__))
+
+require 'hookout/reversehttp_connector'
+require 'hookout/rack_adapter'
+require 'hookout/runner'
+require 'hookout/thin_backend'
+require 'rack/handler/hookout'

data/lib/hookout/rack_adapter.rb

@@ -0,0 +1,25 @@
+require 'thin'
+
+module Hookout
+  class RackAdapter
+    def initialize(app)
+      @app = app
+    end
+    
+    def handle_request(request)
+      thin_request = Thin::Request.new
+      thin_request.parse request.body
+
+      status,headers,body = @app.call(thin_request.env)
+
+      thin_response = Thin::Response.new
+      thin_response.status = status
+      thin_response.headers = headers
+      thin_response.body = body
+
+      thin_response.each do |chunk|
+        request.write(chunk)
+      end
+    end
+  end
+end

data/lib/hookout/reversehttp_connector.rb

@@ -0,0 +1,228 @@
+require 'net/http'
+require 'cgi'
+
+module Hookout
+  class ReverseHttpConnector
+    DEFAULT_SERVER = 'http://localhost:8000/reversehttp'
+    DEFAULT_LABEL = 'ruby'
+    
+    attr_accessor :failure_delay, :lease_seconds, :report_poll_exceptions, :location_change_callback
+  
+    def initialize(label, server_address, handler)
+      @label = label
+      @server_address = server_address
+      @handler = handler
+    
+      @next_req = nil
+      @location = nil
+      @failure_delay = 2
+      @token = '-'
+      @lease_seconds = 30
+      @report_poll_exceptions = false
+      @location_change_callback = nil
+      @closed = false
+      @requestor = Hookout::Utils.new
+    end
+  
+    def start
+      until @closed
+        begin
+          (request, client) = next_request()
+          unless request.nil?
+            @handler.handle_request(request)
+            request.close
+          end
+        rescue
+          puts $!
+          puts $@
+        end
+      end
+    end
+    
+    def stop
+      @closed = true
+      @requestor.abort
+    end
+  
+    def next_request
+      until @closed
+        declare_mode = (@next_req == nil)
+        begin
+          response = nil
+          if declare_mode
+            response = @requestor.post_form @server_address, {:name => @label, :token => @token}
+          else
+            response = @requestor.get @next_req
+          end
+          
+          return nil if response.nil?
+      
+          @failure_delay = 2
+          if declare_mode
+            link_headers = parse_link_headers(response)
+            
+            @next_req = link_headers['first']
+            location_text = link_headers['related']
+            if location_text
+              @location = location_text
+              on_location_changed()
+            end
+          elsif response['Requesting-Client']
+            client_addr = response['Requesting-Client'].split(":")
+            this_req = @next_req
+            @next_req = parse_link_headers(response)['next']
+            return [ReverseHttpRequest.new(this_req, @server_address, response.body), client_addr]
+          end
+        rescue
+          if @report_poll_exceptions
+            report_poll_exception
+          end
+          sleep(@failure_delay)  unless @closed
+          
+          if @failure_delay < 30
+            @failure_delay = @failure_delay * 2
+          end
+        end
+      end
+    end
+  
+    private
+      def urlencode(hash)
+        hash.each { |k, v| "#{CGI.escape(k)}=#{CGI.escape(v)}" }.join("&")
+      end
+    
+      def parse_link_headers(resp)
+        result = {}
+        resp['Link'].split(", ").each do |link_header|
+          url, rel = nil, nil
+        
+          link_header.split(";").each do |piece|
+            piece = piece.strip
+          
+            if piece[0..0] == '<':
+              url = piece[1..-2]
+            elsif piece[0..4].downcase == 'rel="':
+              rel = piece[5..-2]
+            end
+          end
+
+          if url and rel
+            result[rel] = url
+          end
+        end
+      
+        result
+      end
+      
+      def handle_error(request, client_address)
+        if not request.closed:
+          begin
+              request.write("HTTP/1.0 500 Internal Server Error\r\n\r\n")
+              request.close()
+          rescue
+          end
+        end
+      end
+
+      def report_poll_exception
+        puts $!
+        puts $@
+      end
+
+      def on_location_changed
+        if @location_change_callback
+          @location_change_callback.call(@location)
+        end
+      end
+  end
+
+  class ReverseHttpRequest
+    attr_reader :body, :server_address
+  
+    def initialize(reply_url, server_address, body)
+      @reply_url = reply_url
+      @server_address = server_address
+      @body = body
+      @response_buffer = StringIO.new
+      @closed = false
+    end
+
+    def makefile(mode, bufsize)
+      if mode[0] == 'r':
+        StringIO.new(@body)
+      elsif mode[0] == 'w':
+        self
+      end
+    end
+
+    def write(x)
+      @response_buffer.write(x)
+    end
+
+    def flush
+    end
+  
+    def close
+      if not @closed
+        @response_buffer.flush
+        resp_body = @response_buffer.string
+
+        Hookout::Utils.post_data @reply_url, resp_body
+        @closed = true
+      end
+    end
+  end
+  
+  class Utils
+    def initialize
+      @current_http = nil
+      @current_thread = nil
+    end
+    
+    def get(url)
+      parts = URI.parse(url)
+      req = Net::HTTP::Get.new(parts.path)
+      execute_request(parts, req)
+    end
+
+    def post_form(url, params)
+      parts = URI.parse(url)
+      req = Net::HTTP::Post.new(parts.path)
+      req.set_form_data(params)
+      execute_request(parts, req)
+    end
+    
+    def abort
+      @current_http.finish if @current_http
+      @current_thread.raise ConnectorAbortException.new if @current_thread
+    end
+    
+    def execute_request(parts, req)
+      begin
+        Net::HTTP.start(parts.host, parts.port) {|http|
+          @current_http = http
+          @current_thread = Thread.current
+          http.request(req)
+        }
+      rescue ConnectorAbortException
+        return nil
+      ensure
+        @current_http = nil
+        @current_thread = nil
+      end
+    end
+    
+    def self.post_data(url, data)
+      parts = URI.parse(url)
+      req = Net::HTTP::Post.new(parts.path)
+      req.body = data
+      req.content_type = 'message/http'
+      Net::HTTP.start(parts.host, parts.port) {|http|
+        http.request(req)
+      }
+    end
+    
+    class ConnectorAbortException < Exception
+    end
+  end
+end

data/lib/hookout/runner.rb

@@ -0,0 +1,92 @@
+require 'optparse'
+require 'yaml'
+
+module Hookout  
+  # Hookout overrides of the Hookout runner
+  class Runner < Thin::Runner
+    def parser
+      # Load in Hookup specific defaults
+      # Default options values
+      @options[:address] = ReverseHttpConnector::DEFAULT_SERVER
+      @options[:label] = ReverseHttpConnector::DEFAULT_LABEL
+      @options[:log] = 'log/hookout.log'
+      @options[:pid] = 'tmp/pids/hookout.pid'
+      @options[:backend] =Hookout::ThinBackend.name
+      
+      # NOTE: If you add an option here make sure the key in the +options+ hash is the
+      # same as the name of the command line option.
+      # +option+ keys are used to build the command line to launch other processes,
+      # see <tt>lib/thin/command.rb</tt>.
+      @parser ||= OptionParser.new do |opts|
+        opts.banner = "Usage: hookout [options] #{self.class.commands.join('|')}"
+
+        opts.separator ""
+        opts.separator "Server options:"
+
+        opts.on("-a", "--address SERVER", "use SERVER for Reverse HTTP bindings " +
+                                        "(default: #{@options[:address]})")             { |host| @options[:address] = host }
+        opts.on("-n", "--label LABEL", "use LABEL (default: #{@options[:label]})")      { |label| @options[:label] = label }
+        opts.on("-A", "--adapter NAME", "Rack adapter to use (default: autodetect)",
+                                        "(#{Rack::ADAPTERS.map{|(a,b)|a}.join(', ')})") { |name| @options[:adapter] = name }
+        opts.on("-R", "--rackup FILE", "Load a Rack config file instead of " +
+                                       "Rack adapter")                                  { |file| @options[:rackup] = file }
+        opts.on("-c", "--chdir DIR", "Change to dir before starting")                   { |dir| @options[:chdir] = File.expand_path(dir) }
+        opts.on(      "--stats PATH", "Mount the Stats adapter under PATH")             { |path| @options[:stats] = path }
+        
+        opts.separator ""
+        opts.separator "Adapter options:"
+        opts.on("-e", "--environment ENV", "Framework environment " +                       
+                                           "(default: #{@options[:environment]})")      { |env| @options[:environment] = env }
+        opts.on(      "--prefix PATH", "Mount the app under PATH (start with /)")       { |path| @options[:prefix] = path }
+        
+        unless Thin.win? # Daemonizing not supported on Windows
+          opts.separator ""
+          opts.separator "Daemon options:"
+                                                                                      
+          opts.on("-d", "--daemonize", "Run daemonized in the background")              { @options[:daemonize] = true }
+          opts.on("-l", "--log FILE", "File to redirect output " +                      
+                                      "(default: #{@options[:log]})")                   { |file| @options[:log] = file }
+          opts.on("-P", "--pid FILE", "File to store PID " +                            
+                                      "(default: #{@options[:pid]})")                   { |file| @options[:pid] = file }
+          opts.on("-u", "--user NAME", "User to run daemon as (use with -g)")           { |user| @options[:user] = user }
+          opts.on("-g", "--group NAME", "Group to run daemon as (use with -u)")         { |group| @options[:group] = group }
+                                                                                      
+          opts.separator ""
+          opts.separator "Cluster options:"                                             
+                                                                                      
+          opts.on("-s", "--servers NUM", "Number of servers to start")                  { |num| @options[:servers] = num.to_i }
+          opts.on("-o", "--only NUM", "Send command to only one server of the cluster") { |only| @options[:only] = only }
+          opts.on("-C", "--config FILE", "Load options from config file")               { |file| @options[:config] = file }
+          opts.on(      "--all [DIR]", "Send command to each config files in DIR")      { |dir| @options[:all] = dir } if Thin.linux?
+        end
+        
+        opts.separator ""
+        opts.separator "Tuning options:"
+        
+        opts.on("-b", "--backend CLASS", "Backend to use (ignored)")                    { |name|  }
+        opts.on("-p", "--port PORT",     "Port to use (ignored)")                       { |name|  }
+        opts.on("-t", "--timeout SEC", "Request or command timeout in sec " +            
+                                       "(default: #{@options[:timeout]})")              { |sec| @options[:timeout] = sec.to_i }
+        opts.on("-f", "--force", "Force the execution of the command")                  { @options[:force] = true }
+        opts.on(      "--max-conns NUM", "Maximum number of connections " +
+                                         "(default: #{@options[:max_conns]})",
+                                         "Might require sudo to set higher then 1024")  { |num| @options[:max_conns] = num.to_i } unless Thin.win?
+        opts.on(      "--max-persistent-conns NUM",
+                                       "Maximum number of persistent connections",
+                                       "(default: #{@options[:max_persistent_conns]})") { |num| @options[:max_persistent_conns] = num.to_i }
+        opts.on(      "--threaded", "Call the Rack application in threads " +
+                                    "[experimental]")                                   { @options[:threaded] = true }
+        opts.on(      "--no-epoll", "Disable the use of epoll")                         { @options[:no_epoll] = true } if Thin.linux?
+        
+        opts.separator ""
+        opts.separator "Common options:"
+
+        opts.on_tail("-r", "--require FILE", "require the library")                     { |file| @options[:require] << file }
+        opts.on_tail("-D", "--debug", "Set debbuging on")                               { @options[:debug] = true }
+        opts.on_tail("-V", "--trace", "Set tracing on (log raw request/response)")      { @options[:trace] = true }
+        opts.on_tail("-h", "--help", "Show this message")                               { puts opts; exit }
+        opts.on_tail('-v', '--version', "Show version")                                 { puts Thin::SERVER; exit }
+      end
+    end
+  end
+end

data/lib/hookout/thin_backend.rb

@@ -0,0 +1,68 @@
+module Hookout
+  # Backend allowing Thin to act as a Reverse HTTP server
+  class ThinBackend < Thin::Backends::Base
+    # Address and port on which the server is listening for connections.
+    attr_accessor :server_address, :label
+    
+    def initialize(server, label, options)
+      @server_address = options[:address]
+      @label = options[:label]
+      
+      super()
+    end
+    
+    # Connect the server
+    def connect
+      @connector = ReverseHttpConnector.new(@label, @server_address, self)
+      @connector.report_poll_exceptions = true
+      @connector.location_change_callback = lambda { |l| puts "Bound to location #{l}" }
+      
+      EventMachine.defer do
+        @connector.start
+      end
+    end
+    
+    # Stops the server
+    def disconnect
+      @connector.stop
+    end
+          
+    def to_s
+      "#{@label} via #{@server_address}"
+    end
+    
+    def handle_request(request)
+      connection = ThinConnection.new(request.to_s)
+      connection.rhttp_req = request
+      connection.backend = self
+      initialize_connection(connection)
+      
+      connection.receive_data(request.body)
+    end
+  end
+  
+  class ThinConnection < Thin::Connection
+    attr_accessor :rhttp_req
+    attr_accessor :backend
+    
+    def persistent?
+      false
+    end
+    
+    def comm_inactivity_timeout=(timeout)
+      # Ignore
+    end
+    
+    def send_data(data)
+      @rhttp_req.write(data)
+    end
+    
+    def close_connection_after_writing
+      begin
+        @rhttp_req.close
+      ensure
+        @backend.connection_finished(self)
+      end
+    end
+  end
+end

data/lib/rack/handler/hookout.rb

@@ -0,0 +1,32 @@
+module Rack
+  module Handler
+    # Rack Handler stricly to be able to use Hookout through the rackup command.
+    # To do so, simply require 'hookout' in your Rack config file and run like this
+    #
+    #   rackup --server hookout
+    #
+    class Hookout
+      def self.run(app, options={})
+        # Determine our host
+        host = options[:Host] || 'http://localhost:8000/reversehttp'
+        host = 'http://localhost:8000/reversehttp' if host[0..3].downcase != 'http'
+        
+        # Determine our label
+        label = options[:Port] || 'ruby'
+        label = 'ruby' if label.to_i != 0
+        
+        server = ::Hookout::ReverseHttpConnector.new(
+          label, 
+          host,
+          ::Hookout::RackAdapter.new(app))
+        server.report_poll_exceptions = options[:report_poll_exceptions] || true  # false
+        server.location_change_callback = lambda {|l| puts "Location changed to #{l}"} # if options[:log_location_change]
+          
+        yield server if block_given?
+        server.start
+      end
+    end
+    
+    register 'hookout', 'Rack::Handler::Hookout'
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification 
+name: hookout
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 1
+  version: 0.1.1
+platform: ruby
+authors: 
+- Paul Jones
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-10 00:00:00 +01:00
+default_executable: hookout
+dependencies: []
+
+description: Hookout allows you to expose your web hook applications to the web via Reverse HTTP.
+email: pauljones23@gmail.com
+executables: 
+- hookout
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- bin/hookout
+- lib/hookout/rack_adapter.rb
+- lib/hookout/reversehttp_connector.rb
+- lib/hookout/runner.rb
+- lib/hookout/thin_backend.rb
+- lib/hookout.rb
+- lib/rack/handler/hookout.rb
+- Rakefile
+- README.rdoc
+- VERSION.yml
+has_rdoc: true
+homepage: http://github.com/paulj/hookout/
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 2
+summary: Hookout Reverse HTTP Connector
+test_files: []
+