heroku-forward 0.1.0

data/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2012 Daniel Doubrovkine, Art.sy Inc.
+
+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,117 @@
+Heroku::Forward [![Build Status](https://travis-ci.org/dblock/heroku-forward.png?branch=master)](https://travis-ci.org/dblock/heroku-forward)
+===============
+
+Beat Heroku's 60 seconds timeout with a forward proxy.
+
+What's this?
+------------
+
+[Heroku](http://www.heroku.com/) will report an application crashing and yield an `R10 Boot Timeout` error when a web process took longer than 60 seconds to bind to its assigned `$PORT`. This error is often caused by a process being unable to reach an external resource, such as a database or because Heroku is pretty slow and you have a lot of gems in your `Gemfile`.
+
+This gem implements a forward proxy using [em-proxy](https://github.com/igrigorik/em-proxy). This proxy is booted almost immediately, binding to the port assigned by Heroku. Heroku now reports the dyno up. The proxy then spawns your application's web server and establishes a connection over a unix domain socket (a file) between the proxy and the application. Once the application is ready, it will be able to serve HTTP requests normally. Until then requests may queue and some may timeout depending on how long it actually takes to start.
+
+Usage
+-----
+
+Add `heroku-forward` and `em-proxy` to your `Gemfile`. Curently requires HEAD of `em-proxy` because of [this pull request](https://github.com/igrigorik/em-proxy/pull/31).
+
+``` ruby
+gem "heroku-forward", :git => "https://github.com/dblock/heroku-forward.git"
+gem "em-proxy", :git => "https://github.com/igrigorik/em-proxy.git"
+```
+
+Create an application rackup file, eg. `my_app.ru` that boots your application. Under Rails, this is the file that calls `run`.
+
+``` ruby
+require ::File.expand_path('../config/environment',  __FILE__)
+run MyApp::Application
+```
+
+Modify your rackup file as follows. Under Rails this file is called `config.ru`.
+
+``` ruby
+require 'rubygems'
+require 'bundler'
+
+$stdout.sync = true
+Bundler.require(:rack)
+
+port = (ARGV.first || ENV['PORT'] || 3000).to_i
+env = ENV['RACK_ENV'] || 'development'
+
+require 'em-proxy'
+require 'logger'
+require 'heroku-forward'
+
+application = File.expand_path('../my_app.ru', __FILE__)
+backend = Heroku::Forward::Backends::Thin.new(application: application, env: env)
+proxy = Heroku::Forward::Proxy::Server.new(backend, { host: '0.0.0.0', port: port })
+proxy.logger = Logger.new(STDOUT)
+proxy.forward!
+```
+
+This sets up a proxy on the port requested by Heroku and runs your application with Thin.
+
+Foreman
+-------
+
+Heroku Cedar expects a `Procfile` that defines your application processes.
+
+```
+web: bundle exec ruby config.ru
+worker: bundle exec rake jobs:work
+```
+
+You can use `foreman` to test the proxy locally with `foreman start web`.
+
+Heroku Log
+----------
+
+Here's the log output from an application that uses this gem. Notice that Heroku reports the state of `web.1` up after just 4 seconds, while the application takes 67 seconds to boot.
+
+```
+2012-12-11T23:33:42+00:00 heroku[web.1]: Starting process with command `bundle exec ruby config.ru`
+2012-12-11T23:33:46+00:00 app[web.1]:  INFO -- : Launching Backend ...
+2012-12-11T23:33:46+00:00 app[web.1]:  INFO -- : Launching Proxy Server at 0.0.0.0:42017 ...
+2012-12-11T23:33:46+00:00 app[web.1]: DEBUG -- : Attempting to connect to /tmp/thin20121211-2-1bfazzx.
+2012-12-11T23:33:46+00:00 app[web.1]:  WARN -- : no connection, 10 retries left.
+2012-12-11T23:33:46+00:00 heroku[web.1]: State changed from starting to up
+2012-12-11T23:34:32+00:00 app[web.1]: >> Thin web server (v1.5.0 codename Knife)
+2012-12-11T23:34:32+00:00 app[web.1]: >> Maximum connections set to 1024
+2012-12-11T23:34:32+00:00 app[web.1]: >> Listening on /tmp/thin20121211-2-1bfazzx, CTRL+C to stop
+2012-12-11T23:34:53+00:00 app[web.1]: DEBUG -- : Attempting to connect to /tmp/thin20121211-2-1bfazzx.
+2012-12-11T23:34:53+00:00 app[web.1]: DEBUG -- : Proxy Server ready at 0.0.0.0:42017 (67s).
+```
+
+Proxy Forwarding Options
+------------------------
+
+`Heroku::Forward::Proxy::Server.forward!` accepts the following options:
+
+* `delay`: number of seconds to sleep before launching the proxy, eg. `proxy.forward!(delay: 15)`. This prevents queuing of requests or reporting invalid `up` status to Heroku. It's recommended to set this value to as close as possible to the boot time of your application and less than the Heroku's 60s boot limit.
+
+Fail-Safe
+---------
+
+If you're worried about this implementation, consider building a fail-safe. Modify your `config.ru` to run without a proxy if `DISABLE_FORWARD_PROXY` is set as demonstrated in [this gist](https://gist.github.com/4263488). Add `DISABLE_FORWARD_PROXY` via `heroku config:add DISABLE_FORWARD_PROXY=1`.
+
+Reading Materials
+-----------------
+
+* [Heroku R10 Boot Timeout](https://devcenter.heroku.com/articles/error-codes#r10-boot-timeout)
+* [Beating Heroku's 60s Boot Times with the Cedar Stack and a Reverse Proxy](http://noverloop.be/beating-herokus-60s-boot-times-with-the-cedar-stack-and-a-reverse-proxy/) by Nicolas Overloop
+* [Fighting the Unicorns: Becoming a Thin Wizard on Heroku](http://jgwmaxwell.com/fighting-the-unicorns-becoming-a-thin-wizard-on-heroku/) by JGW Maxwell
+* [eventmachine](https://github.com/eventmachine/eventmachine)
+* [em-proxy](https://github.com/igrigorik/em-proxy)
+
+Contributing
+------------
+
+Fork the project. Make your feature addition or bug fix with tests. Send a pull request. Bonus points for topic branches.
+
+Copyright and License
+---------------------
+
+MIT License, see [LICENSE](http://github.com/dblock/heroku-forward/raw/master/LICENSE.md) for details.
+
+(c) 2012 [Daniel Doubrovkine](http://github.com/dblock), [Art.sy](http://artsy.github.com)

data/lib/heroku-forward.rb

@@ -0,0 +1,10 @@
+require 'i18n'
+require 'tempfile'
+require 'em-proxy'
+require 'posix/spawn'
+
+I18n.load_path << File.join(File.dirname(__FILE__), "heroku", "forward", "config", "locales", "en.yml")
+
+require 'heroku/forward'
+
+

data/lib/heroku/forward.rb

@@ -0,0 +1,4 @@
+require 'heroku/forward/version'
+require 'heroku/forward/errors'
+require 'heroku/forward/backends'
+require 'heroku/forward/proxy'

data/lib/heroku/forward/backends.rb

@@ -0,0 +1 @@
+require 'heroku/forward/backends/thin'

data/lib/heroku/forward/backends/thin.rb

@@ -0,0 +1,56 @@
+module Heroku
+  module Forward
+    module Backends
+      class Thin
+        include POSIX::Spawn
+
+        attr_accessor :application
+        attr_accessor :socket
+        attr_accessor :environment
+        attr_accessor :pid
+
+        # options:
+        #  application: passed with -R, eg. app.ru
+        #  socket: passed with --socket, eg. /tmp/thin.sock
+        #  env: passed with -e, defaults to 'development'
+        def initialize(options = {})
+          @application = options[:application]
+          @socket = options[:socket] || new_socket
+          @env = options[:env] || :development
+        end
+
+        def spawn!
+          return false if spawned?
+          check!
+          @pid = spawn("thin start -R #{@application} --socket #{@socket} -e #{@env}")
+          @spawned = true
+        end
+
+        def terminate!
+          return false unless spawned?
+          Process.kill 'QUIT', @pid
+          @spawned = false
+          true
+        end
+
+        def spawned?
+          !! @spawned
+        end
+
+        private
+
+          def new_socket
+            Tempfile.open 'thin' do |file|
+              return file.path
+            end
+          end
+
+          def check!
+            raise Heroku::Forward::Errors::MissingBackendOptionError.new('application') unless @application && @application.length > 0
+            raise Heroku::Forward::Errors::MissingBackendApplicationError.new(@application) unless File.exists?(@application)
+          end
+
+      end
+    end
+  end
+end

data/lib/heroku/forward/config/locales/en.yml

@@ -0,0 +1,17 @@
+en:
+  heroku:
+    forward:
+      errors:
+        messages:
+          missing_backend_option:
+            message: "Missing backend option: %{name}."
+            summary: "A required option was not provided to the back-end."
+            resolution: "Review the documentation for the back-end that you're trying to proxy to."
+          missing_backend_application:
+            message: "Missing backend application in '%{path}'."
+            summary: "The file supplied to the back-end in the 'application' option is invalid."
+            resolution: "This is typically a file called 'myapp.ru', for Rails applications it will contain a call to 'MyApp::Application.initialize!'."
+          backend_failed_to_start:
+            message: "The back-end failed to start in a timely fashion."
+            summary: "The proxy started, but failed to connect to the back-end after retrying multiple times."
+            resolution: "Check that your application can start without the proxy and serve HTTP requests."

data/lib/heroku/forward/errors.rb

@@ -0,0 +1,4 @@
+require 'heroku/forward/errors/heroku_forward_error'
+require 'heroku/forward/errors/missing_backend_option_error'
+require 'heroku/forward/errors/missing_backend_application_error'
+require 'heroku/forward/errors/backend_failed_to_start_error'

data/lib/heroku/forward/errors/backend_failed_to_start_error.rb

@@ -0,0 +1,11 @@
+module Heroku
+  module Forward
+    module Errors
+      class BackendFailedToStartError < HerokuForwardError
+        def initialize
+          super(compose_message("backend_failed_to_start"))
+        end
+      end
+    end
+  end
+end

data/lib/heroku/forward/errors/heroku_forward_error.rb

@@ -0,0 +1,88 @@
+# encoding: utf-8
+module Heroku #:nodoc:
+  module Forward
+    module Errors #:nodoc:
+
+      # Default parent error for all custom errors. This handles the base
+      # key for the translations and provides the convenience method for
+      # translating the messages.
+      #
+      # Generously borrowed from Mongoid[https://github.com/mongoid/mongoid/blob/master/lib/mongoid/errors/mongoid_error.rb].
+      class HerokuForwardError < StandardError
+
+        # Problem occurred.
+        attr_reader :problem
+
+        # Summary of the problem.
+        attr_reader :summary
+
+        # Suggested problem resolution.
+        attr_reader :resolution
+
+        # Compose the message.
+        # === Parameters
+        # [key] Lookup key in the translation table.
+        # [attributes] The objects to pass to create the message.
+        def compose_message(key, attributes = {})
+          @problem = create_problem(key, attributes)
+          @summary = create_summary(key, attributes)
+          @resolution = create_resolution(key, attributes)
+
+          "\nProblem:\n  #{@problem}"+
+          "\nSummary:\n  #{@summary}"+
+          "\nResolution:\n  #{@resolution}"
+        end
+
+        private
+
+          BASE_KEY = "heroku.forward.errors.messages" #:nodoc:
+
+          # Given the key of the specific error and the options hash, translate the
+          # message.
+          #
+          # === Parameters
+          # [key] The key of the error in the locales.
+          # [options] The objects to pass to create the message.
+          #
+          # Returns a localized error message string.
+          def translate(key, options)
+            ::I18n.translate("#{BASE_KEY}.#{key}", { :locale => :en }.merge(options)).strip
+          end
+
+          # Create the problem.
+          #
+          # === Parameters
+          # [key] The error key.
+          # [attributes] The attributes to interpolate.
+          #
+          # Returns the problem.
+          def create_problem(key, attributes)
+            translate("#{key}.message", attributes)
+          end
+
+          # Create the summary.
+          #
+          # === Parameters
+          # [key] The error key.
+          # [attributes] The attributes to interpolate.
+          #
+          # Returns the summary.
+          def create_summary(key, attributes)
+            translate("#{key}.summary", attributes)
+          end
+
+          # Create the resolution.
+          #
+          # === Parameters
+          # [key] The error key.
+          # [attributes] The attributes to interpolate.
+          #
+          # Returns the resolution.
+          def create_resolution(key, attributes)
+            translate("#{key}.resolution", attributes)
+          end
+
+      end
+    end
+  end
+end

data/lib/heroku/forward/errors/missing_backend_application_error.rb

@@ -0,0 +1,13 @@
+module Heroku
+  module Forward
+    module Errors
+      class MissingBackendApplicationError < HerokuForwardError
+        def initialize(path)
+          super(compose_message("missing_backend_application", {
+            :path => path
+          }))
+        end
+      end
+    end
+  end
+end

data/lib/heroku/forward/errors/missing_backend_option_error.rb

@@ -0,0 +1,13 @@
+module Heroku
+  module Forward
+    module Errors
+      class MissingBackendOptionError < HerokuForwardError
+        def initialize(name)
+          super(compose_message("missing_backend_option", {
+            :name => name
+          }))
+        end
+      end
+    end
+  end
+end

data/lib/heroku/forward/proxy.rb

@@ -0,0 +1 @@
+require 'heroku/forward/proxy/server'

data/lib/heroku/forward/proxy/server.rb

@@ -0,0 +1,96 @@
+module Heroku
+  module Forward
+    module Proxy
+
+      class Server
+        attr_reader :host, :port, :backend, :retries, :start
+        attr_accessor :logger
+
+        def initialize(backend, options = {})
+          @host = options[:host] || '0.0.0.0'
+          @port = options[:port] || 3000
+          @retries = options[:retries] || 10
+          @backend = backend
+        end
+
+        def on_connect(&callback)
+          if block_given?
+            @on_connect = callback
+          elsif @on_connect
+            @on_connect.call
+          end
+        end
+
+        def forward!(options = {})
+
+          @start = Time.now
+
+          logger.info "Launching Backend ..." if logger
+
+          backend.spawn!
+
+          if options[:delay] && (delay = options[:delay].to_i) > 0
+            logger.info "Waiting #{delay}s to Launch Proxy Server ..." if logger
+            sleep delay
+          end
+
+          logger.info "Launching Proxy Server at #{host}:#{port} ..." if logger
+
+          s = self
+          ::Proxy.start({ :host => host, :port => port, :debug => false }) do |conn|
+            if @start
+              EM.next_tick do
+                s.send(:connect, conn)
+              end
+            else
+              s.send(:connect, conn)
+            end
+
+            conn.on_connect do
+              s.on_connect
+            end
+
+            conn.on_data do |data|
+              data
+            end
+
+            conn.on_response do |backend, resp|
+              resp
+            end
+
+            conn.on_finish do
+            end
+          end
+
+        end
+
+        def stop!
+          logger.info "Terminating Proxy Server" if logger
+          EventMachine.stop
+          logger.info "Terminating Web Server" if logger
+          backend.terminate!
+        end
+
+        private
+
+          def connect(conn)
+            begin
+              if start
+                logger.debug "Attempting to connect to #{backend.socket}." if logger
+              end
+              conn.server backend, :socket => backend.socket
+              if @start
+                logger.debug "Proxy Server ready at #{host}:#{port} (#{(Time.now - start).to_i}s)." if logger
+                @start = nil
+              end
+            rescue RuntimeError => e
+              raise BackendFailedToStartError.new if @retries <= 0
+              logger.warn "#{e.message}, #{retries} #{retries == 1 ? 'retry' : 'retries'} left." if logger
+              @retries -= 1
+            end
+          end
+
+      end
+    end
+  end
+end

data/lib/heroku/forward/version.rb

@@ -0,0 +1,5 @@
+module Heroku
+  module Forward
+    VERSION = '0.1.0'
+  end
+end

metadata

@@ -0,0 +1,209 @@
+--- !ruby/object:Gem::Specification
+name: heroku-forward
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Daniel Doubrovkine
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-12-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: em-proxy
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.1.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.1.8
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: posix-spawn
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: thin
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: em-http-request
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: 
+email: dblock@dblock.org
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.md
+- README.md
+files:
+- lib/heroku-forward.rb
+- lib/heroku/forward.rb
+- lib/heroku/forward/backends.rb
+- lib/heroku/forward/backends/thin.rb
+- lib/heroku/forward/config/locales/en.yml
+- lib/heroku/forward/errors.rb
+- lib/heroku/forward/errors/backend_failed_to_start_error.rb
+- lib/heroku/forward/errors/heroku_forward_error.rb
+- lib/heroku/forward/errors/missing_backend_application_error.rb
+- lib/heroku/forward/errors/missing_backend_option_error.rb
+- lib/heroku/forward/proxy.rb
+- lib/heroku/forward/proxy/server.rb
+- lib/heroku/forward/version.rb
+- LICENSE.md
+- README.md
+homepage: http://github.com/dblock/heroku-forward
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 394519437
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Beat Heroku's 60s boot timeout with a forward proxy.
+test_files: []