goodguide-pinglish 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 21349b68ac1102b95ac9e8e37ce9a8199af64d56
+  data.tar.gz: 65b356ff81337fa6e66d58547cec1eb8b1ff3fa5
+SHA512:
+  metadata.gz: c6923231c568bcc36da5dc6569b57d23118fd64e14238a05b365409c2f82b189e3df45d8ba729b810e92f866cef66d59b83600b5e489b05b2afddfdad26cce05
+  data.tar.gz: 88ec461eeac036dcfde251f0b62fae7f3ad6a9cb5c17598528b9e20baae72b5d22743815208df81f323b40e7aab81b82f20b79956916f45be7bdd7143cdb0166

data/.gitignore

@@ -0,0 +1,3 @@
+/*.gem
+/.bundle
+/Gemfile.lock

data/Gemfile

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

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,119 @@
+# 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 Redis," 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__ 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 `"failures"`.
+
+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 `"failures"`, 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 `"failures"`, 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": "failures",
+
+  // 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
+
+```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. Any exception will do.
+  ping.check :fails do
+    raise "Everything's ruined."
+  end
+
+  # Additionally, any check that returns false is counted as a failure.
+  ping.check :false_fails do
+    false
+  end
+end
+```

data/goodguide-pinglish.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |gem|
+  gem.name          = "goodguide-pinglish"
+  gem.version       = "1.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/goodguide/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"
+  gem.add_development_dependency "rack-test", "~> 0.6"
+end

data/lib/pinglish/check.rb

@@ -0,0 +1,21 @@
+class Pinglish
+  class Check
+    attr_reader :group
+    attr_reader :name
+    attr_reader :timeout
+
+    def initialize(name, options = nil, &block)
+      options ||= {}
+      @group    = options[:group]
+      @name     = name
+      @timeout  = 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
+end

data/lib/pinglish.rb

@@ -0,0 +1,146 @@
+require "json"
+require "pinglish/check"
+require "rack/request"
+require "timeout"
+
+# This Rack app provides an 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"
+  }
+
+  # Raised when a check exceeds its timeout.
+  class TooLong < RuntimeError; end
+
+  # Create a new instance of the app, with optional parameter `:max` timeout in seconds (default: `29`); yields itself to an optional block for configuring checks.
+  def initialize(options=nil, &block)
+    options ||= {}
+
+    @checks = {}
+    @max    = options[:max] || 29 # seconds
+
+    yield self if block_given?
+  end
+
+  def call(env)
+    request = Rack::Request.new(env)
+
+    begin
+      timeout @max do
+        results = {}
+
+        selected_checks(request.params).each do |check|
+          begin
+            timeout(check.timeout) do
+              results[check.name] = check.call
+            end
+          rescue => e
+            results[check.name] = e
+          end
+        end
+
+        failed = results.values.any? { |v| failure? v }
+        http_status = failed ? 503 : 200
+        text_status = failed ? "failures" : "ok"
+
+        data = {
+          :now    => Time.now.to_i.to_s,
+          :status => text_status
+        }
+
+        results.each do |name, value|
+          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
+
+            if key == :failures and value.is_a?(Exception)
+              data[name] = {
+                state: :error,
+                exception: value.class.name,
+                message: value.message,
+              }
+            end
+
+          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
+          end
+        end
+
+        [http_status, HEADERS, [JSON.generate(data)]]
+      end
+
+    rescue Exception => 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
+
+      body = <<-EOF.gsub(/^ {6}/, '')
+      {
+        "status": "failures",
+        "now": "#{now}",
+        "error": {
+          "class": "#{ex.class.name}",
+          "message": "#{ex.message.tr('"', '')}"
+        }
+      }
+      EOF
+
+      [500, HEADERS, [body]]
+    end
+  end
+
+  def selected_checks(params)
+    if (selected = params['checks'])
+      selected = selected.split(',').map(&:to_sym)
+      return @checks.values_at(*selected).compact
+    end
+    @checks.values
+  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 = :default, options = nil, &block)
+    @checks[name.to_sym] = Check.new(name, options, &block)
+  end
+
+  # Does `value` represent a check failure? This default
+  # implementation returns `true` for any value that is an Exception or false.
+  # Subclasses can override this method for different behavior.
+
+  def failure?(value)
+    value.is_a?(Exception) || value == false
+  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/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/test

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

data/test/check_test.rb

@@ -0,0 +1,23 @@
+require "helper"
+
+class PinglishCheckTest < MiniTest::Unit::TestCase
+  def test_initialize
+    check = Pinglish::Check.new(:db)
+    assert_equal :db, check.name
+  end
+
+  def test_initialize_default_timeout
+    check = Pinglish::Check.new(:db)
+    assert_equal 1, check.timeout
+  end
+
+  def test_initialize_override_timeout
+    check = Pinglish::Check.new(:db, :timeout => 2)
+    assert_equal 2, check.timeout
+  end
+
+  def test_call
+    check = Pinglish::Check.new(:db) { :result_of_block }
+    assert_equal :result_of_block, check.call
+  end
+end

data/test/helper.rb

@@ -0,0 +1,2 @@
+require "minitest/autorun"
+require "pinglish"

data/test/pinglish_test.rb

@@ -0,0 +1,262 @@
+require "helper"
+require "rack/test"
+
+class PinglishTest < MiniTest::Unit::TestCase
+  FakeApp = lambda { |env| [200, {}, ["fake"]] }
+
+  def build_app(*args, &block)
+    Rack::Builder.new do |builder|
+      builder.map '/_ping' do
+        run Pinglish.new(*args, &block)
+      end
+      builder.run FakeApp
+    end
+  end
+
+  def build_app_that_explodes(*args, &block)
+    Rack::Builder.new do |builder|
+      builder.map '/_ping' do
+        run Pinglish.new(*args, &block)
+      end
+      builder.run lambda { |env| raise "boom" }
+    end
+  end
+
+  def test_with_non_matching_request_path_and_exception
+    app = build_app_that_explodes
+    session = Rack::Test::Session.new(app)
+
+    assert_raises RuntimeError do
+      session.get "/something"
+    end
+  end
+
+  def test_with_defaults
+    app = build_app
+
+    session = Rack::Test::Session.new(app)
+    session.get "/_ping"
+    assert_equal 200, session.last_response.status
+    assert_equal "application/json; charset=UTF-8",
+      session.last_response.content_type
+
+    json = JSON.load(session.last_response.body)
+    assert json.key?("now")
+    assert_equal "ok", json["status"]
+  end
+
+  def test_with_good_check
+    app = build_app do |ping|
+      ping.check(:db) { :up_and_at_em }
+      ping.check(:queue) { :pushin_and_poppin }
+    end
+
+    session = Rack::Test::Session.new(app)
+    session.get "/_ping"
+
+    assert_equal "application/json; charset=UTF-8",
+      session.last_response.content_type
+
+    json = JSON.load(session.last_response.body)
+    assert json.key?("now")
+    assert_equal "ok", json["status"]
+    assert_equal "up_and_at_em", json["db"]
+    assert_equal "pushin_and_poppin", json["queue"]
+  end
+
+  def test_with_unnamed_check
+    app = build_app do |ping|
+      ping.check { :yohoho }
+    end
+
+    session = Rack::Test::Session.new(app)
+    session.get "/_ping"
+
+    assert_equal "application/json; charset=UTF-8",
+      session.last_response.content_type
+
+    json = JSON.load(session.last_response.body)
+    assert json.key?("now")
+    assert_equal "ok", json["status"]
+    assert_equal "yohoho", json["default"]
+  end
+
+  def test_with_unnamed_check_that_raises
+    app = build_app do |ping|
+      ping.check { raise "nooooope" }
+    end
+
+    session = Rack::Test::Session.new(app)
+    session.get "/_ping"
+
+    assert_equal "application/json; charset=UTF-8",
+      session.last_response.content_type
+
+    json = JSON.load(session.last_response.body)
+    assert json.key?("now")
+    assert_equal 'failures', json["status"]
+    assert_equal ['default'], json["failures"]
+    assert_equal({
+      'state' => 'error',
+      'exception' => 'RuntimeError',
+      'message' => 'nooooope'
+    }, json["default"])
+  end
+
+
+  def test_with_check_that_raises
+    app = build_app do |ping|
+      ping.check(:db) { :ok }
+      ping.check(:raise) { raise "nooooope" }
+    end
+
+    session = Rack::Test::Session.new(app)
+    session.get "/_ping"
+
+    assert_equal 503, session.last_response.status
+    assert_equal "application/json; charset=UTF-8",
+      session.last_response.content_type
+
+    json = JSON.load(session.last_response.body)
+    assert json.key?("now")
+    assert_equal "failures", json["status"]
+    assert_equal ['raise'], json["failures"]
+    assert_equal({
+      'state' => 'error',
+      'exception' => 'RuntimeError',
+      'message' => 'nooooope'
+    }, json["raise"])
+  end
+
+  def test_with_check_that_returns_false
+    app = build_app do |ping|
+      ping.check(:db) { :ok }
+      ping.check(:fail) { false }
+    end
+
+    session = Rack::Test::Session.new(app)
+    session.get "/_ping"
+
+    assert_equal 503, session.last_response.status
+    assert_equal "application/json; charset=UTF-8",
+      session.last_response.content_type
+
+    json = JSON.load(session.last_response.body)
+    assert json.key?("now")
+    assert_equal "failures", json["status"]
+    assert_equal ["fail"], json["failures"]
+    assert_equal false, json.key?("fail")
+  end
+
+  def test_with_check_that_times_out
+    app = build_app do |ping|
+      ping.check(:db) { :ok }
+      ping.check(:long, :timeout => 0.001) { sleep 0.003 }
+    end
+
+    session = Rack::Test::Session.new(app)
+    session.get "/_ping"
+
+    assert_equal 503, session.last_response.status
+    assert_equal "application/json; charset=UTF-8",
+      session.last_response.content_type
+
+    json = JSON.load(session.last_response.body)
+    assert json.key?("now")
+    assert_equal "failures", json["status"]
+    assert_equal ["long"], json["timeouts"]
+  end
+
+  def test_with_checks_taking_more_than_max
+    app = build_app(:max => 0.001) do |ping|
+      ping.check(:long) { sleep 0.003 }
+    end
+
+    session = Rack::Test::Session.new(app)
+    session.get "/_ping"
+
+    assert_equal 503, session.last_response.status
+    assert_equal "application/json; charset=UTF-8",
+      session.last_response.content_type
+
+    json = JSON.load(session.last_response.body)
+    assert json.key?("now")
+    assert_equal "failures", json["status"]
+    assert_equal ['long'], json["timeouts"]
+  end
+
+  def test_with_script_name
+    app = build_app
+
+    session = Rack::Test::Session.new(app)
+    session.get "/_ping", {}, "SCRIPT_NAME" => "/myapp"
+    assert_equal 200, session.last_response.status
+    assert_equal "application/json; charset=UTF-8",
+      session.last_response.content_type
+
+    json = JSON.load(session.last_response.body)
+    assert json.key?("now")
+    assert_equal "ok", json["status"]
+  end
+
+  def test_with_selective_checks
+    app = build_app do |ping|
+      ping.check(:db) { :ok }
+      ping.check(:foo) { :bar }
+      ping.check(:long, :timeout => 0.001) { sleep 0.003 }
+    end
+
+    session = Rack::Test::Session.new(app)
+    session.get "/_ping?checks=db,foo"
+
+    assert_equal 200, session.last_response.status
+    assert_equal "application/json; charset=UTF-8",
+      session.last_response.content_type
+
+    json = JSON.load(session.last_response.body)
+    assert json.key?("now")
+    assert_equal "ok", json["status"]
+    assert_equal false, json.key?("timeouts")
+    assert_equal false, json.key?("failures")
+    assert_equal 'ok', json['db']
+    assert_equal 'bar', json['foo']
+  end
+
+  def test_check_without_name
+    pinglish = Pinglish.new(FakeApp)
+    check = pinglish.check { :ok }
+    assert_instance_of Pinglish::Check, check
+  end
+
+  def test_check_with_name
+    pinglish = Pinglish.new(FakeApp)
+    check = pinglish.check(:db) { :ok }
+    assert_instance_of Pinglish::Check, check
+    assert_equal :db, check.name
+  end
+
+  def test_failure_boolean
+    pinglish = Pinglish.new(FakeApp)
+
+    assert pinglish.failure?(Exception.new)
+    assert pinglish.failure?(false)
+
+    refute pinglish.failure?(true)
+    refute pinglish.failure?(:ok)
+  end
+
+  def test_timeout
+    pinglish = Pinglish.new(FakeApp)
+
+    assert_raises Pinglish::TooLong do
+      pinglish.timeout(0.001) { sleep 0.003 }
+    end
+  end
+
+  def test_timeout_boolean
+    pinglish = Pinglish.new(FakeApp)
+
+    assert pinglish.timeout?(Pinglish::TooLong.new)
+    refute pinglish.timeout?(Exception.new)
+  end
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: goodguide-pinglish
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- John Barnette
+- Will Farrington
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-04-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+description: A simple Rack middleware for checking app health.
+email:
+- jbarnette@github.com
+- wfarr@github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- goodguide-pinglish.gemspec
+- lib/pinglish.rb
+- lib/pinglish/check.rb
+- script/bootstrap
+- script/release
+- script/test
+- test/check_test.rb
+- test/helper.rb
+- test/pinglish_test.rb
+homepage: https://github.com/goodguide/pinglish
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: "/_ping your way to freedom."
+test_files:
+- test/check_test.rb
+- test/helper.rb
+- test/pinglish_test.rb
+has_rdoc: