e20_ops_middleware 2.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+.bundle
+vendor
+*.gemspec
+pkg

data/Gemfile

@@ -0,0 +1,8 @@
+source :rubyforge
+
+gem "jeweler", "~> 1.4.0"
+gem "rspec", "~> 1.3.0"
+gem "rake", "~> 0.8.7"
+gem "uuid", "~> 2.1.0"
+gem "activesupport", "~> 2.3.8"
+gem "json_pure", "= 1.4.3"

data/Gemfile.lock

@@ -0,0 +1,29 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (2.3.8)
+    gemcutter (0.6.1)
+    git (1.2.5)
+    jeweler (1.4.0)
+      gemcutter (>= 0.1.0)
+      git (>= 1.2.5)
+      rubyforge (>= 2.0.0)
+    json_pure (1.4.3)
+    macaddr (1.0.0)
+    rake (0.8.7)
+    rspec (1.3.0)
+    rubyforge (2.0.4)
+      json_pure (>= 1.1.7)
+    uuid (2.1.1)
+      macaddr (~> 1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 2.3.8)
+  jeweler (~> 1.4.0)
+  json_pure (= 1.4.3)
+  rake (~> 0.8.7)
+  rspec (~> 1.3.0)
+  uuid (~> 2.1.0)

data/History.txt

@@ -0,0 +1,5 @@
+== 2.0.1 / 2010-08-29
+
+* 1 major enhancement
+
+  * First public release!

data/README.md

@@ -0,0 +1,144 @@
+Efficiency 2.0 Ops Middleware
+=============================
+
+A collection of useful middleware for exposing information about deployed Rack
+applications. Efficiency 2.0 uses this to track distributed transactions
+across its Ruby-based service oriented architecture.
+
+Features
+--------
+
+* Adds a `X-Served-By` header with the hostname of the server that processed
+  the request.
+* Adds a `X-Transaction` header with a unique ID for the web request.
+* Adds a `X-Revision` header with the running Git revision.
+* Adds an endpoint of `/system/revision` for easily checking the running
+  revision. This can be leveraged in a post-deployment sanity check to ensure
+  the application servers restarted properly.
+
+Install
+-------
+
+### Rails ###
+
+Add to your `Gemfile`:
+
+    gem "e20_ops_middleware"
+
+Install the gem:
+
+    $ bundle install
+
+Create a `config/initializers/ops_middleware.rb` with the following:
+
+    ActionController::Dispatcher.middleware.with_options :logger => Rails.logger do |m|
+      m.use E20::Ops::Middleware::RevisionMiddleware
+      m.use E20::Ops::Middleware::HostnameMiddleware
+      m.use E20::Ops::Middleware::TransactionIdMiddleware
+    end
+
+### Rack ###
+
+In `config.ru`, add:
+
+    use E20::Ops::Middleware::RevisionMiddleware
+    use E20::Ops::Middleware::HostnameMiddleware
+    use E20::Ops::Middleware::TransactionIdMiddleware
+
+Usage
+-----
+
+The information exposed by the middleware can be viewed manually with `curl`
+and will also be logged to the provided logger (or STDOUT). Additionally,
+we've found it useful to log this information when receiving responses from
+REST web services.
+
+### Revision Middleware ###
+
+Revisions can be queried directly by using the `/system/revision` endpoint:
+
+    $ curl http://instance/system/revision
+    fe09f24b4a927b6eab5db66b6a89fe960e2ff03b
+
+The current revision will be passed as an HTTP header for other requests:
+
+    $ curl -I http://instance/
+    HTTP/1.1 200 OK
+    Content-Type: text/html; charset=utf-8
+    Content-Length: 3304
+    X-Revision: fe09f24b4a927b6eab5db66b6a89fe960e2ff03b
+
+The current revision will also be logged upon application start:
+
+    $ grep RevisionMiddleware log/production.log
+    [E20::Ops::Middleware::RevisionMiddleware] Running: fe09f24b4a927b6eab5db66b6a89fe960e2ff03b
+
+### Hostname Middleware ###
+
+The hostname of the system that processed the request will be passed as an
+HTTP header:
+
+    $ curl -I http://instance/
+    HTTP/1.1 200 OK
+    Content-Type: text/html; charset=utf-8
+    Content-Length: 3304
+    X-Served-By: fulton
+    
+The hostname will also be logged upon application start:
+
+    $ grep HostnameMiddleware log/production.log
+    [E20::Ops::Middleware::HostnameMiddleware] Running on: fulton
+
+### Transaction ID Middleware ###
+
+A transaction ID will be logged for each incoming request:
+
+    $ grep TransactionIdMiddleware log/production.log
+    [E20::Ops::Middleware::TransactionIdMiddleware] Transaction ID: 111d3180-91f4-012d-ce1a-549a20d01d99
+
+The transaction ID will also be passed as an HTTP header:
+
+    $ curl -I http://instance/
+    HTTP/1.1 200 OK
+    Content-Type: text/html; charset=utf-8
+    Content-Length: 3304
+    X-Transaction: 111d3180-91f4-012d-ce1a-549a20d01d99
+
+Thanks
+------
+
+Thanks to Efficiency 2.0 ([http://efficiency20.com](http://efficiency20.com))
+for sponsoring development of this gem.
+
+Development
+-----------
+
+To run the tests:
+
+    $ bundle install
+    $ rake
+
+License
+-------
+
+(The MIT License)
+
+Copyright © 2010 Efficiency 2.0, LLC
+
+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,25 @@
+require "rubygems"
+require "bundler"
+Bundler.setup
+
+require 'jeweler'
+
+Jeweler::Tasks.new do |gem|
+  gem.name = "e20_ops_middleware"
+  gem.summary = "Collection of useful middleware for exposing information about deployed Rack applications"
+  gem.email = "tech@efficiency20.com"
+  gem.homepage = "http://github.com/efficiency20/ops_middleware"
+  gem.description = "Adds middleware for debugging purposes"
+  gem.authors = ["Efficiency 2.0"]
+  gem.add_dependency "uuid", "~> 2.1.0"
+  gem.add_development_dependency "rspec", "~> 1.3.0"
+end
+
+require "spec/rake/spectask"
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new("spec") do |t|
+  t.spec_files = FileList["spec/**/*_spec.rb"]
+end
+
+task :default => :spec

data/VERSION

@@ -0,0 +1 @@
+2.0.1

data/ci.rb

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+["bundle install vendor/bundle",
+ "rake"
+].each do |stage|
+  exit 1 unless system(stage)
+end

data/lib/e20/ops/hostname.rb

@@ -0,0 +1,11 @@
+module E20
+  module Ops
+    class Hostname
+
+      def to_s
+        @hostname ||= `hostname`.strip
+      end
+
+    end
+  end
+end

data/lib/e20/ops/middleware/hostname_middleware.rb

@@ -0,0 +1,24 @@
+module E20
+  module Ops
+    module Middleware
+      class HostnameMiddleware
+
+        def initialize(app, options = {})
+          @app = app
+          @hostname = options[:hostname] || Hostname.new
+
+          if (logger = options[:logger])
+            logger.info "[#{self.class.name}] Running on: #{@hostname}"
+          end
+        end
+
+        def call(env)
+          status, headers, body = @app.call(env)
+          headers["X-Served-By"] = @hostname.to_s
+          [status, headers, body]
+        end
+
+      end
+    end
+  end
+end

data/lib/e20/ops/middleware/revision_middleware.rb

@@ -0,0 +1,29 @@
+module E20
+  module Ops
+    module Middleware
+      class RevisionMiddleware
+
+        def initialize(app, options = {})
+          @app = app
+          @revision = options[:revision] || Revision.new
+
+          if (logger = options[:logger])
+            logger.info "[#{self.class.name}] Running: #{@revision}"
+          end
+        end
+
+        def call(env)
+          if env["PATH_INFO"] == "/system/revision"
+            body = "#{@revision}\n"
+            [200, { "Content-Type" => "text/plain", "Content-Length" => body.size.to_s }, body]
+          else
+            status, headers, body = @app.call(env)
+            headers["X-Revision"] = @revision.to_s
+            [status, headers, body]
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/e20/ops/middleware/transaction_id_middleware.rb

@@ -0,0 +1,27 @@
+require "uuid"
+require "logger"
+
+module E20
+  module Ops
+    module Middleware
+      class TransactionIdMiddleware
+
+        def initialize(app, options = {})
+          @app = app
+          @uuid_generator = options[:uuid_generator] || UUID.new
+          @logger = options[:logger] || Logger.new(STDOUT)
+        end
+
+        def call(env)
+          uuid = @uuid_generator.generate
+          @logger.info "[#{self.class.name}] Transaction ID: #{uuid}"
+
+          status, headers, body = @app.call(env)
+          headers["X-Transaction"] = uuid
+          [status, headers, body]
+        end
+
+      end
+    end
+  end
+end

data/lib/e20/ops/middleware.rb

@@ -0,0 +1,12 @@
+module E20
+  module Ops
+    autoload :Revision, "e20/ops/revision"
+    autoload :Hostname, "e20/ops/hostname"
+
+    module Middleware
+      autoload :HostnameMiddleware, "e20/ops/middleware/hostname_middleware"
+      autoload :RevisionMiddleware, "e20/ops/middleware/revision_middleware"
+      autoload :TransactionIdMiddleware, "e20/ops/middleware/transaction_id_middleware"
+    end
+  end
+end

data/lib/e20/ops/revision.rb

@@ -0,0 +1,35 @@
+require "active_support"
+
+module E20
+  module Ops
+    class Revision
+
+      def initialize(root = Pathname.new(Dir.pwd))
+        @root = root
+      end
+
+      def to_s
+        @revision ||= begin
+          if revision_file.exist?
+            revision_file.read.strip
+          elsif revision_from_git.present?
+            revision_from_git
+          else
+            "unknown"
+          end
+        end
+      end
+
+    private
+
+      def revision_from_git
+        @revision_from_git ||= `git rev-parse HEAD`.strip
+      end
+
+      def revision_file
+        @root.join("REVISION")
+      end
+
+    end
+  end
+end

data/spec/ops/hostname_spec.rb

@@ -0,0 +1,9 @@
+require "spec_helper"
+
+describe E20::Ops::Hostname do
+  it "returns the hostname" do
+    hostname = E20::Ops::Hostname.new
+    hostname.should_receive(:`).with("hostname").and_return("Computer.local\n")
+    hostname.to_s.should == "Computer.local"
+  end
+end

data/spec/ops/middleware/hostname_middleware_spec.rb

@@ -0,0 +1,27 @@
+require "spec_helper"
+
+describe E20::Ops::Middleware::HostnameMiddleware do
+  let(:app) { Proc.new { |env| [200, {}, "OK!"] } }
+
+  it "is initialized with an app" do
+    E20::Ops::Middleware::HostnameMiddleware.new(app)
+  end
+
+  it "delegates to the app" do
+    middleware = E20::Ops::Middleware::HostnameMiddleware.new(app)
+    status, headers, body = middleware.call({})
+    body.should == "OK!"
+  end
+
+  it "logs the hostname when initialized" do
+    log_io = StringIO.new
+    E20::Ops::Middleware::HostnameMiddleware.new(app, :logger => Logger.new(log_io))
+    log_io.string.should include("[E20::Ops::Middleware::HostnameMiddleware] Running on: ")
+  end
+
+  it "sets an X-Served-By header" do
+    middleware = E20::Ops::Middleware::HostnameMiddleware.new(app, :hostname => "Computer.local")
+    status, headers, body = middleware.call({})
+    headers["X-Served-By"].should == "Computer.local"
+  end
+end

data/spec/ops/middleware/revision_middleware_spec.rb

@@ -0,0 +1,37 @@
+require "spec_helper"
+
+describe E20::Ops::Middleware::RevisionMiddleware do
+  let(:app) { Proc.new { |env| [200, {}, "OK!"] } }
+
+  it "is initialized with an app" do
+    E20::Ops::Middleware::RevisionMiddleware.new(app)
+  end
+
+  context "/system/revision" do
+    it "returns the current running revision" do
+      middleware = E20::Ops::Middleware::RevisionMiddleware.new(app, :revision => "rev")
+      status, headers, body = middleware.call({"PATH_INFO" => "/system/revision"})
+      body.should == "rev\n"
+    end
+  end
+
+  context "any other endpoint" do
+    it "delegates to the app" do
+      middleware = E20::Ops::Middleware::RevisionMiddleware.new(app)
+      status, headers, body = middleware.call({})
+      body.should == "OK!"
+    end
+
+    it "logs the running revision when initialized" do
+      log_io = StringIO.new
+      E20::Ops::Middleware::RevisionMiddleware.new(app, :revision => "rev", :logger => Logger.new(log_io))
+      log_io.string.should include("[E20::Ops::Middleware::RevisionMiddleware] Running: rev")
+    end
+
+    it "sets an X-Revision header" do
+      middleware = E20::Ops::Middleware::RevisionMiddleware.new(app, :revision => "the_revision", :logger => nil)
+      status, headers, body = middleware.call({})
+      headers["X-Revision"].should == "the_revision"
+    end
+  end
+end

data/spec/ops/middleware/transaction_id_middleware_spec.rb

@@ -0,0 +1,30 @@
+require "spec_helper"
+
+describe E20::Ops::Middleware::TransactionIdMiddleware do
+  let(:app)    { Proc.new { |env| [200, {}, "OK!"] } }
+  let(:uuid)   { stub(:generate => "abc123") }
+  let(:logger) { Logger.new(StringIO.new) }
+
+  it "is initialized with an app" do
+    E20::Ops::Middleware::TransactionIdMiddleware.new(app)
+  end
+
+  it "delegates to the app" do
+    middleware = E20::Ops::Middleware::TransactionIdMiddleware.new(app, :logger => logger)
+    status, headers, body = middleware.call({})
+    body.should == "OK!"
+  end
+
+  it "sets an X-Transaction header" do
+    middleware = E20::Ops::Middleware::TransactionIdMiddleware.new(app, :uuid_generator => uuid, :logger => logger)
+    status, headers, body = middleware.call({})
+    headers["X-Transaction"].should == "abc123"
+  end
+
+  it "logs a line for each request" do
+    log_io = StringIO.new
+    middleware = E20::Ops::Middleware::TransactionIdMiddleware.new(app, :uuid_generator => uuid, :logger => Logger.new(log_io))
+    middleware.call({})
+    log_io.string.should include("[E20::Ops::Middleware::TransactionIdMiddleware] Transaction ID: abc123")
+  end
+end

data/spec/ops/revision_spec.rb

@@ -0,0 +1,27 @@
+require "spec_helper"
+
+describe E20::Ops::Revision do
+  context "when a REVISION file is present" do
+    it "adds a X-Revision header with the REVISION" do
+      tmp_path = Pathname.new(Dir.tmpdir)
+      tmp_path.join("REVISION").open("w") { |f| f.write "hello\n" }
+      E20::Ops::Revision.new(tmp_path).to_s.should == "hello"
+    end
+  end
+
+  context "when a REVISION file is not present" do
+    it "adds a X-Revision header with the git rev-parse HEAD" do
+      revision = E20::Ops::Revision.new
+      revision.should_receive(:`).with("git rev-parse HEAD").and_return("abc123")
+      revision.to_s.should == "abc123"
+    end
+  end
+
+  context "when neither a REVISION file or a git revision are available" do
+    it "adds a X-Revision header of 'unknown'" do
+      revision = E20::Ops::Revision.new
+      revision.stub(:` => "")
+      revision.to_s.should == "unknown"
+    end
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require "spec"
+require "e20/ops/middleware"

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification 
+name: e20_ops_middleware
+version: !ruby/object:Gem::Version 
+  hash: 13
+  prerelease: false
+  segments: 
+  - 2
+  - 0
+  - 1
+  version: 2.0.1
+platform: ruby
+authors: 
+- Efficiency 2.0
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-29 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :runtime
+  name: uuid
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 2
+        - 1
+        - 0
+        version: 2.1.0
+  requirement: *id001
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :development
+  name: rspec
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  requirement: *id002
+description: Adds middleware for debugging purposes
+email: tech@efficiency20.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- History.txt
+- README.md
+- Rakefile
+- VERSION
+- ci.rb
+- lib/e20/ops/hostname.rb
+- lib/e20/ops/middleware.rb
+- lib/e20/ops/middleware/hostname_middleware.rb
+- lib/e20/ops/middleware/revision_middleware.rb
+- lib/e20/ops/middleware/transaction_id_middleware.rb
+- lib/e20/ops/revision.rb
+- spec/ops/hostname_spec.rb
+- spec/ops/middleware/hostname_middleware_spec.rb
+- spec/ops/middleware/revision_middleware_spec.rb
+- spec/ops/middleware/transaction_id_middleware_spec.rb
+- spec/ops/revision_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/efficiency20/ops_middleware
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Collection of useful middleware for exposing information about deployed Rack applications
+test_files: 
+- spec/ops/hostname_spec.rb
+- spec/ops/middleware/hostname_middleware_spec.rb
+- spec/ops/middleware/revision_middleware_spec.rb
+- spec/ops/middleware/transaction_id_middleware_spec.rb
+- spec/ops/revision_spec.rb
+- spec/spec_helper.rb