pinglish 0.0.0

data/.gitignore

@@ -0,0 +1,2 @@
+/*.gem
+/.bundle

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/Gemfile.lock

@@ -0,0 +1,18 @@
+PATH
+  remote: .
+  specs:
+    pinglish (0.0.0)
+      rack
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    minitest (4.5.0)
+    rack (1.5.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  minitest (~> 4.5)
+  pinglish!

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 John Barnette, Will Farrington, and contributors.
+
+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,124 @@
+# Pinglish
+
+A simple Rack middleware for checking application health. Pinglish
+exposes a `/_ping` resource via HTTP `GET`, returning JSON that
+conforms to the spec below.
+
+## The Spec
+
+0. The application __must__ respond to `GET /_ping` as an HTTP request.
+
+0. The request handler __should__ check the health of all services the
+  application depends on, answering questions like, "Can I query
+  agains my MySQL database," "Can I create/read keys in Reds," or "How
+  many docs are in my ElasticSearch index?"
+
+0. The response __must__ return within 29 seconds. This is one second
+   less than the default timeout for many monitoring services.
+
+0. The response __must__ return an `HTTP 200 OK` status code if all
+   health checks pass.
+
+0. The response __must__ return an `HTTP 503 SERVICE UNAVAILABLE`
+   status code if any health checks fail.
+
+0. The response __must__ return an `HTTP 418 I'M A TEAPOT` status code
+   if the request asks for any content-type but `application/json`.
+
+0. The response __must__ be of Content-Type `application/json;
+   charset=UTF-8`.
+
+0. The response __must__ be valid JSON no matter what, even if JSON
+   serialization or other fundamental code fails.
+
+0. The response __must__ contain a `"status"` key set either to `"ok"`
+   or `"fail"`.
+
+0. The response __must__ contain a `"now"` key set to the current
+   server's time in seconds since epoch as a string.
+
+0. If the `"status"` key is set to `"fail"`, the response __may__
+   contain a `"failures"` key set to an Array of string names
+   representing failed checks.
+
+0. If the `"status"` key is set to `"fail"`, the response __may__
+   contain a `"timeouts"` key set to an Array of string names
+   representing checks that exceeded an implementation-specific
+   individual timeout.
+
+0. The response body __may__ contain any other top-level keys to
+   supply additional data about services the application consumes, but
+   all values must be strings, arrays of strings, or hashes where both
+   keys and values are strings.
+
+### An Example Response
+
+```javascript
+{
+
+  // These two keys will always exist.
+
+  "now": "1359055102",
+  "status": "fail",
+
+  // This key may only exist when a named check has failed.
+
+  "failures": ["db"],
+
+  // This key may only exist when a named check exceeds its timeout.
+
+  "timeouts": ["really-long-check"],
+
+  // Keys like this may exist to provide extra information about
+  // healthy services, like the number of objects in an S3 bucket.
+
+  "s3": "127"
+}
+```
+
+## The Middleware
+
+FIX: exegesis
+
+```ruby
+require "pinglish"
+
+use Pinglish do |ping|
+
+  # A single unnamed check is the simplest possible way to use
+  # Pinglish, and you'll probably never want combine it with other
+  # named checks. An unnamed check contributes to overall success or
+  # failure, but never adds additional data to the response.
+
+  ping.check do
+    App.healthy?
+  end
+
+  # A named check like this can provide useful summary information
+  # when it succeeds. In this case, a top-level "db" key will appear
+  # in the response containing the number of items in the database. If
+  # a check returns nil, no key will be added to the response.
+
+  ping.check :db do
+    App.db.items.size
+  end
+
+  # By default, checks time out after one second. You can override
+  # this with the :timeout option, but be aware that no combination of
+  # checks is ever allowed to exceed the overall 29 second limit.
+
+  ping.check :long, :timeout => 5 do
+    App.dawdle
+  end
+
+  # Signal check failure by raising an exception.
+
+  ping.check :fails do
+    false or raise "Everything's ruined."
+  end
+end
+```
+
+## Contributing
+
+FIX

data/lib/pinglish.rb

@@ -0,0 +1,161 @@
+require "json"
+require "timeout"
+
+# This Rack middleware provides a "/_ping" endpoint for configurable
+# system health checks. It's intended to be consumed by machines.
+
+class Pinglish
+
+  # The HTTP headers sent for every response.
+
+  HEADERS = {
+    "Content-Type" => "application/json; charset=UTF-8"
+  }
+
+  # The maximum amount of time for all checks. 29 seconds, to come in
+  # just under the 30 second limit of many monitoring services.
+
+  MAX_TOTAL_TIME = 29
+
+  # This triple is returned if the request media type isn't
+  # "application/json".
+
+  TEAPOT = [418, HEADERS, ['{"teapot":"true"}']]
+
+  # Represents a check, which is a behavior block with a name and
+  # timeout in seconds.
+
+  class Check
+    attr_reader :name
+    attr_reader :timeout
+
+    def initialize(name, options = nil, &block)
+      @name    = name
+      @timeout = options && options[:timeout] || 1
+      @block   = block
+    end
+
+    # Call this check's behavior, returning the result of the block.
+
+    def call(*args, &block)
+      @block.call *args, &block
+    end
+  end
+
+  # Raised when a check exceeds its timeout.
+
+  class TooLong < RuntimeError; end
+
+  # Create a new instance of the middleware wrapping `app`, with an
+  # optional `path` (the default is `"/_ping"`) and behavior `block`.
+
+  def initialize(app, path = nil, &block)
+    @app    = app
+    @checks = {}
+    @path   = path || "/_ping"
+
+    yield self if block_given?
+  end
+
+  # Exercise the middleware, immediately delegating to the wrapped app
+  # unless the request path matches `path`.
+
+  def call(env)
+    request = Rack::Request.new env
+
+    return @app.call env unless request.path == @path
+    return TEAPOT unless request.media_type == "application/json"
+
+    timeout MAX_TOTAL_TIME do
+      results = {}
+
+      @checks.values.each do |check|
+        begin
+          timeout check.timeout do
+            results[check.name] = check.call
+          end
+        rescue StandardError => e
+          results[check.name] = e
+        end
+      end
+
+      failed      = results.values.any? { |v| failure? v }
+      http_status = failed ? 503 : 200
+      text_status = failed ? "fail" : "ok"
+
+      data = {
+        :now    => Time.now.to_i.to_s,
+        :status => text_status
+      }
+
+      results.each do |name, value|
+
+        # The unnnamed/default check doesn't contribute data.
+        next if name.nil?
+
+        if failure? value
+
+          # If a check fails its name is added to a `failures` array.
+          # If the check failed because it timed out, its name is
+          # added to a `timeouts` array instead.
+
+          key = timeout?(value) ? :timeouts : :failures
+          (data[key] ||= []) << name
+
+        elsif value
+
+          # If the check passed and returned a value, the stringified
+          # version of the value is returned under the `name` key.
+
+          data[name] = value.to_s
+        end
+      end
+
+      [http_status, HEADERS, [JSON.generate(data)]]
+    end
+
+  rescue Exception => ex
+
+    p :fuck => ex
+    # Something catastrophic happened. We can't even run the checks
+    # and render a JSON response. Fall back on a pre-rendered string
+    # and interpolate the current epoch time.
+
+    now = Time.now.to_i.to_s
+    [500, HEADERS, ['{"status":"fail","now":"' + now + '"}']]
+  end
+
+  # Add a new check with optional `name`. A `:timeout` option can be
+  # specified in seconds for checks that might take longer than the
+  # one second default. A previously added check with the same name
+  # will be replaced.
+
+  def check(name = nil, options = nil, &block)
+    @checks[name] = Check.new(name, options, &block)
+  end
+
+  # Does `value` represent a check failure? This default
+  # implementation returns `true` for any value that is an Exception.
+  # Subclasses can override this method for different behavior.
+
+  def failure?(value)
+    value.is_a? Exception
+  end
+
+  # Raise Pinglish::TooLong after `seconds` has elapsed. This default
+  # implementation uses Ruby's built-in Timeout class. Subclasses can
+  # override this method for different behavior, but any new
+  # implementation must raise Pinglish::TooLong when the timeout is
+  # exceeded or override `timeout?` appropriately.
+
+  def timeout(seconds, &block)
+    Timeout.timeout seconds, Pinglish::TooLong, &block
+  end
+
+  # Does `value` represent a check timeout? Returns `true` for any
+  # value that is an instance of Pinglish::TooLong.
+
+  def timeout?(value)
+    value.is_a? Pinglish::TooLong
+  end
+end

data/pinglish.gemspec

@@ -0,0 +1,18 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |gem|
+  gem.name          = "pinglish"
+  gem.version       = "0.0.0"
+  gem.authors       = ["John Barnette", "Will Farrington"]
+  gem.email         = ["jbarnette@github.com", "wfarr@github.com"]
+  gem.description   = "A simple Rack middleware for checking app health."
+  gem.summary       = "/_ping your way to freedom."
+  gem.homepage      = "https://github.com/jbarnette/pinglish"
+
+  gem.files         = `git ls-files`.split $/
+  gem.test_files    = gem.files.grep /^test/
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency "rack"
+  gem.add_development_dependency "minitest", "~> 4.5"
+end

data/script/bootstrap

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Make sure local development dependencies are satisfied.
+
+set -e
+
+cd $(dirname "$0")/..
+rm -rf .bundle/config
+
+bundle install --path .bundle --binstubs .bundle/binstubs --quiet

data/script/release

@@ -0,0 +1,38 @@
+#!/bin/sh
+# Tag and push a release.
+
+set -e
+
+# Make sure we're in the project root.
+
+cd $(dirname "$0")/..
+
+# Build a new gem archive.
+
+rm -rf pinglish-*.gem
+gem build -q pinglish.gemspec
+
+# Make sure we're on the master branch.
+
+(git branch | grep -q '* master') || {
+  echo "Only release from the master branch."
+  exit 1
+}
+
+# Figure out what version we're releasing.
+
+tag=v`ls pinglish-*.gem | sed 's/^pinglish-\(.*\)\.gem$/\1/'`
+
+# Make sure we haven't released this version before.
+
+git fetch -t origin
+
+(git tag -l | grep -q "$tag") && {
+  echo "Whoops, there's already a '${tag}' tag."
+  exit 1
+}
+
+# Tag it and bag it.
+
+gem push pinglish-*.gem && git tag "$tag" &&
+  git push origin master && git push origin "$tag"

data/script/tests

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Run the tests.
+
+set -e
+
+cd $(dirname "$0")/..
+
+script/bootstrap && ruby -I lib -rubygems \
+  -e 'require "bundler/setup"; Dir["test/**/*_test.rb"].each { |f| load f }' "$@"

data/test/pinglish_test.rb

@@ -0,0 +1,7 @@
+require "minitest/autorun"
+
+class PinglishTest < MiniTest::Unit::TestCase
+  def test_sanity
+    assert true
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: pinglish
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+  prerelease: 
+platform: ruby
+authors:
+- John Barnette
+- Will Farrington
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4.5'
+description: A simple Rack middleware for checking app health.
+email:
+- jbarnette@github.com
+- wfarr@github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- lib/pinglish.rb
+- pinglish.gemspec
+- script/bootstrap
+- script/release
+- script/tests
+- test/pinglish_test.rb
+homepage: https://github.com/jbarnette/pinglish
+licenses: []
+post_install_message: 
+rdoc_options: []
+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.23
+signing_key: 
+specification_version: 3
+summary: /_ping your way to freedom.
+test_files:
+- test/pinglish_test.rb