cartage-rack 1.1 → 2.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f1f756831e081111a68cf696035705057d5b06a8
-  data.tar.gz: 5d02f8976aa4b7433e9c8d96c6ccc3558007e50b
+  metadata.gz: 94047d31b87bd33b0ede49ddc37cf6919449cfd4
+  data.tar.gz: 129d78a6a5cf83122b5a3581efdc446f9462688c
 SHA512:
-  metadata.gz: da2f68e98d8ae476143c955ea2e8e1921b89890491a5b7ed41746bf518c42a8c9c26cb824397bfe4557c67da3686826ffd4f2b24f3023c2d90dd76e002f84d57
-  data.tar.gz: 0515b3f19b46cdd5725ff1650ea4d87b7c354a16e535ccafe7282488558f4de09a159ee560c1f1ed2fa79f25938f4adcb266616ae31609359d78d7a5ea44c9d2
+  metadata.gz: e86abeee60243641fe003a20024e7a54bb756ce7decc1f43e4288f1fb0fc120821c87371d4423f3161e94e3e7f7e156d8a7abb58be343da11ddd250f5074b341
+  data.tar.gz: 24876ea56317cd8ab71d106cc58fc868d185307d4e4b4ff37299de00a33dc167f869909ed0b29523cd449a9e3c1e887a4cf3c9c761488c212b8227f53187f839

data/Contributing.md

@@ -0,0 +1,66 @@
+## Contributing
+
+We value any contribution to cartage-rack you can provide: a bug report, a
+feature request, or code contributions. cartage-rack is reasonably complex
+code, so there are a few contribution guidelines:
+
+*   Changes *will* *not* be accepted without tests. The test suite is written
+    with [Minitest][].
+*   Match our coding style.
+*   Use a thoughtfully-named topic branch that contains your change. Rebase
+    your commits into logical chunks as necessary.
+*   Use [quality commit messages][].
+*   Do not change the version number; when your patch is accepted and a release
+    is made, the version will be updated at that point.
+*   Submit a GitHub pull request with your changes.
+
+### Test Dependencies
+
+cartage-rack uses Ryan Davis’s [Hoe][] to manage the release process, which
+adds a number of rake tasks. You will mostly be interested in:
+
+    $ rake
+
+which runs the tests the same way that:
+
+    $ rake test
+    $ rake travis
+
+will do.
+
+To assist with the installation of the development dependencies for
+cartage-rack, I have provided the simplest possible Gemfile pointing to the
+(generated) `cartage-rack.gemspec` file. This will permit you to do:
+
+    $ bundle install
+
+to get the development dependencies. If you aleady have `hoe` installed, you
+can accomplish the same thing with:
+
+    $ rake newb
+
+This task will install any missing dependencies, run the tests/specs, and
+generate the RDoc.
+
+### Workflow
+
+Here's the most direct way to get your work merged into the project:
+
+*   Fork the project.
+*   Clone down your fork (`git clone git://github.com/KineticCafe/cartage-rack.git`).
+*   Create a topic branch to contain your change (`git checkout -b my_awesome_feature`).
+*   Hack away, add tests. Not necessarily in that order.
+*   Make sure everything still passes by running `rake`.
+*   If necessary, rebase your commits into logical chunks, without errors.
+*   Push the branch up (`git push origin my_awesome_feature`).
+*   Create a pull request against KineticCafe/cartage-rack and describe
+    what your change does and the why you think it should be merged.
+
+### Contributors
+
+*   Austin Ziegler created cartage-rack.
+
+[Minitest]: https://github.com/seattlerb/minitest
+[quality commit messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+[Hoe]: https://github.com/seattlerb/hoe
+[kccoc]: https://github.com/KineticCafe/code-of-conduct

data/History.md

@@ -0,0 +1,46 @@
+### 2.0 / 2016-05-DD
+
+*   Rewrote for compatibility with cartage 2.0.
+
+    *   Renamed Cartage::Rack to Cartage::Rack::Simple and created a *new*
+        Cartage::Rack that returns more information.
+
+    *   Extracted metadata gathering out of Cartage::Rack and into
+        Cartage::Rack::Metadata.
+
+    *   Deprecated Cartage::Rack.mount in favour of Cartage::Rack() and
+        Cartage::Rack::Simple() methods.
+
+*   1 governance change
+
+    *   cartage-rack is now under the Kinetic Cafe Open Source [Code of
+        Conduct][kccoc].
+
+### 1.1 / 2015-04-11
+
+*   2 minor enhancements
+
+    *   Implemented Cartage::Rack#inspect to prevent `rake routes` from
+        presenting badly.
+
+    *   Preparing for a future Cartage change to the contents of the
+        `release_hashref` file. The future `release_hashref` will be two lines:
+
+            hashref
+            timestamp
+
+        If `release_hashref` has two lines, the timestamp will be included in
+        the response. A timestamp will not be included if there is no
+        `release_hashref` file.
+
+*   1 development change
+
+    *   Implemented tests for Cartage::Rack.
+
+### 1.0 / 2015-03-20
+
+*   1 major enhancement
+
+    *   Birthday!
+
+[kccoc]: https://github.com/KineticCafe/code-of-conduct

data/{Licence.rdoc → Licence.md}

@@ -1,8 +1,8 @@
-== Licence
+## Licence
 
 This software is available under an MIT-style licence.
 
-* Copyright 2015 Kinetic Cafe
+*   Copyright 2015–2016 Kinetic Cafe
 
 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
@@ -11,9 +11,9 @@ 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 names of its contributors may not be used to endorse or promote
-  products derived from this software without specific prior written
-  permission.
+*   The names of its contributors may not be used to endorse or promote
+    products derived from this software without specific prior written
+    permission.
 
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.

data/Manifest.txt

@@ -1,14 +1,13 @@
-.autotest
-.gemtest
-.minitest.rb
-.travis.yml
-Contributing.rdoc
-Gemfile
-History.rdoc
-Licence.rdoc
+Contributing.md
+History.md
+Licence.md
 Manifest.txt
 README.rdoc
 Rakefile
 lib/cartage/rack.rb
+lib/cartage/rack/metadata.rb
+lib/cartage/rack/simple.rb
 test/minitest_config.rb
 test/test_cartage_rack.rb
+test/test_cartage_rack_metadata.rb
+test/test_cartage_rack_simple.rb

data/README.rdoc

@@ -7,7 +7,7 @@ continuous integration :: {<img src="https://travis-ci.org/KineticCafe/cartage-r
 == Description
 
 cartage-rack is a plug-in for {cartage}[https://github.com/KineticCafe/cartage]
-to provide a Rack application.
+to provide a Rack application that reports on release metadata.
 
 Cartage provides a repeatable means to create a package for a Rails application
 that can be used in deployment with a configuration tool like Ansible, Chef,
@@ -17,58 +17,123 @@ control rules and without requiring development tool access.
 
 == Synopsis
 
-Cartage::Rack provides a Rack application generator to read and return the
-+release_hashref+ from an endpoint to verify that the server was deployed. This
-endpoint supports both JSON and plaintext output. To add this to a Rails
-application, simply mount it in +config/routes.rb+:
+cartage-rack provides a generator method that instantiates a Rack application
+that reports on release metadata, which will assist in verifying application
+deploys.
+
+To add the default generator to a Rails application, simply mount it in
++config/routes.rb+:
 
     require 'cartage/rack'
 
     Rails.application.routes.draw do
-      get '/release' => Cartage::Rack.mount(Rails.root)
+      get '/release' => Cartage::Rack::Simple(Rails.root)
     end
 
-Or map it in a normal Rack application in +config.ru+:
+To map it in a normal Rack application in +config.ru+:
 
     require 'cartage/rack'
     map('/release') do
-      run Cartage::Rack.mount(Dir.pwd)
+      run Cartage::Rack::Simple(Dir.pwd)
     end
 
-It can then be queried easily:
+Once mounted, it can then be queried easily:
 
     % rails start
     % curl localhost:3000/release
     development: (git) main
-    % curl localhost:3000/release.json | jshon
+    % curl localhost:3000/release.json | jq .
     {
       "env" : "development",
       "release_hashref" : "(git) main"
     }
 
-If there is a +release_hashref+ file, the value returned will be from this
-file. There are two versions of +release_hashref+ files supported; the original
-format (Cartage 1.0 and 1.1) has one line (just the hashref of the release).
-The new format has two lines, the hashref of the release and the timestamp of
-the release.
+== \Metadata
+
+The core of cartage-rack is Cartage::Rack::Metadata, which collects data from
+<tt>release-metadata.json</tt>, +release_hashref+, or the runtime environment
+(if Cartage::Rack.require_metadata is +false+). You may instantiate the class
+yourself if you wish to have a different sort of report for the release.
+
+== \Metadata Reporters
+
+There are two \Rack applications provided in cartage-rack 2.0 to report on
+release metadata. \Metadata is pulled from <tt>release-metadata.json</tt>,
++release_hashref+, or the current environment (which allows Cartage::Rack
+verification in development).
+
+When reading +release_hashref+, the first line is the hashref of the release; a
+second line, if present, is the Cartage timestamp of the release (an integer
+value of the form +YYYYmmddHHMMSS+).
+
+If a metadata file (<tt>release-metadata.json</tt> or <tt>release_hashref</tt>)
+exists, it will be read on application creation and cached for the lifetime of
+the Rack application. cartage-rack may be configured to throw an exception if a
+metadata file cannot be found:
+
+   Cartage::Rack.require_metadata false
+
+All reporters support JSON and plain text formats.
+
+=== Cartage::Rack
+
+A full metadata reporter. This reporter may include information that is
+considered *private* (including the source repository URL), so it is only
+recommended for use on protected endpoints. The default report format is JSON.
+
+The data returned is what is recorded in <tt>release-metadata.json</tt>, plus
+the name of the environment.
 
-    % curl localhost:3000/release.json | jshon
     {
-      "env" : "production",
-      "release_hashref" : "134458c3e3c02dd7c1cac8d5d41d85ce1e4decab"
-      "timestamp" : "20150411001143"
+      "env": {
+        "name": "production",
+      },
+      "package": {
+        "name": "package-name",
+        "repo": {
+          "type": "git",
+          "url": "git:git@github.com/KineticCafe/cartage-rack.git"
+        },
+        hashref: "decafbad",
+        timestamp: "19851027024200"
+      }
     }
 
+Mount this reporter with <tt>Cartage::Rack(Rails.root)</tt>. The data may be
+filtered out by providing a block to <tt>Cartage::Rack()</tt> which modifies
+the +metadata+ in place.
+
+    Cartage::Rack(Rails.root) do |metadata|
+      unless Rails.env.development?
+        # Remove the repo data before returning
+        metadata[:package].delete(:repo)
+      end
+    end
+
+=== Cartage::Rack::Simple
+
+A simplified metadata reporter, including only the information that was
+provided in cartage-rack 1.x (the environment, the hashref, and optionally a
+timestamp). The default report format is plain text.
+
+Mount this reporter with <tt>Cartage::Rack::Simple(Rails.root)</tt>. For
+backwards compatibility, this reporter may also be mounted with
+<tt>Cartage::Rack.mount(Rails.root)</tt>. The Simple reporter does not support
+filtering.
+
 == Install
 
 Add cartage-rack to your Gemfile:
 
-    gem 'cartage-rack', '~> 1.1'
+    gem 'cartage-rack', '~> 2.0'
 
 Or manually install:
 
   % gem install cartage-rack
 
+cartage-rack should be in the main section of your Gemfile, unlike Cartage
+itself.
+
 == cartage-rack Semantic Versioning
 
 cartage-rack uses a {Semantic Versioning}[http://semver.org/] scheme with one
@@ -79,6 +144,10 @@ change:
 cartage-rack will generally track cartage for major versions to ensure plugin API
 compatibility.
 
-:include: Contributing.rdoc
+== Community and Contributing
 
-:include: Licence.rdoc
+cartage-rack welcomes your contributions as described in
+{Contributing.md}[https://github.com/KineticCafe/cartage-rack/blob/master/Contributing.md].
+This project, like all Kinetic Cafe {open source
+projects}[https://github.com/KineticCafe], is under the Kinetic Cafe Open
+Source {Code of Conduct}[https://github.com/KineticCafe/code-of-conduct].

data/Rakefile

@@ -1,11 +1,11 @@
-# -*- ruby -*-
+# frozen_string_literal: true
 
 require 'rubygems'
 require 'hoe'
-require 'pathname'
+require 'rake/clean'
 
 Hoe.plugin :doofus
-Hoe.plugin :email unless ENV['CI'] or ENV['TRAVIS']
+Hoe.plugin :email unless ENV['CI'] || ENV['TRAVIS']
 Hoe.plugin :gemspec2
 Hoe.plugin :git
 Hoe.plugin :minitest
@@ -15,46 +15,55 @@ Hoe.plugin :travis
 spec = Hoe.spec 'cartage-rack' do
   developer('Austin Ziegler', 'aziegler@kineticcafe.com')
 
-  self.history_file = 'History.rdoc'
+  self.history_file = 'History.md'
   self.readme_file = 'README.rdoc'
-  self.extra_rdoc_files = FileList['*.rdoc'].to_a
 
   license 'MIT'
 
-  self.extra_dev_deps << ['rake', '~> 10.0']
-  self.extra_dev_deps << ['rack-test', '~> 0.6']
-  self.extra_dev_deps << ['hoe-doofus', '~> 1.0']
-  self.extra_dev_deps << ['hoe-gemspec2', '~> 1.1']
-  self.extra_dev_deps << ['hoe-git', '~> 1.5']
-  self.extra_dev_deps << ['hoe-travis', '~> 1.2']
-  self.extra_dev_deps << ['minitest', '~> 5.4']
-  self.extra_dev_deps << ['minitest-autotest', '~> 1.0']
-  self.extra_dev_deps << ['minitest-bisect', '~> 1.2']
-  self.extra_dev_deps << ['minitest-focus', '~> 1.1']
-  self.extra_dev_deps << ['minitest-moar', '~> 0.0']
-  self.extra_dev_deps << ['minitest-pretty_diff', '~> 0.1']
-  self.extra_dev_deps << ['simplecov', '~> 0.7']
+  ruby20!
+
+  # This gem *explicitly* does not have a hard link to cartage.
+
+  extra_dev_deps << ['rake', '>= 10.0']
+  extra_dev_deps << ['rdoc', '~> 4.2']
+  extra_dev_deps << ['rack-test', '~> 0.6']
+  extra_dev_deps << ['hoe-doofus', '~> 1.0']
+  extra_dev_deps << ['hoe-gemspec2', '~> 1.1']
+  extra_dev_deps << ['hoe-git', '~> 1.5']
+  extra_dev_deps << ['hoe-travis', '~> 1.2']
+  extra_dev_deps << ['minitest', '~> 5.4']
+  extra_dev_deps << ['minitest-autotest', '~> 1.0']
+  extra_dev_deps << ['minitest-bisect', '~> 1.2']
+  extra_dev_deps << ['minitest-bonus-assertions', '~> 2.0']
+  extra_dev_deps << ['minitest-focus', '~> 1.1']
+  extra_dev_deps << ['minitest-hooks', '~> 1.4']
+  extra_dev_deps << ['minitest-moar', '~> 0.0']
+  extra_dev_deps << ['minitest-pretty_diff', '~> 0.1']
+  extra_dev_deps << ['timecop', '~> 0.8']
+  extra_dev_deps << ['simplecov', '~> 0.7']
 end
 
-module Hoe::Publish
-  alias_method :original_make_rdoc_cmd, :make_rdoc_cmd
+ENV['RUBYOPT'] = '-W0'
+
+module Hoe::Publish #:nodoc:
+  alias __make_rdoc_cmd__cartage__ make_rdoc_cmd
 
   def make_rdoc_cmd(*extra_args) # :nodoc:
-    spec.extra_rdoc_files.reject! { |f| f == 'Manifest.txt' }
-    original_make_rdoc_cmd(*extra_args)
+    spec.extra_rdoc_files.delete_if { |f| f == 'Manifest.txt' }
+    __make_rdoc_cmd__cartage__(*extra_args)
   end
 end
 
 namespace :test do
-  task :coverage do
-    prelude = <<-EOS
-require 'simplecov'
-SimpleCov.start('test_frameworks') { command_name 'Minitest' }
-gem 'minitest'
-    EOS
-    spec.test_prelude = prelude.split($/).join('; ')
-    Rake::Task['test'].execute
+  if File.exist?('.simplecov-prelude.rb')
+    task :coverage do
+      spec.test_prelude = 'load ".simplecov-prelude.rb"'
+
+      Rake::Task['test'].execute
+    end
   end
+
+  CLOBBER << 'coverage'
 end
 
-# vim: syntax=ruby
+CLOBBER << 'tmp'

data/lib/cartage/rack.rb

@@ -1,76 +1,105 @@
+# frozen_string_literal: true
+
 require 'pathname'
 require 'json'
 
 # Cartage, a package builder.
-class Cartage; end
-
-# Cartage::Rack is a simple application that reads an application’s
-# +release_hashref+ and returns it as a +text/plain+ string, or as
-# +application/json+ if it is called with +.json+.
-#
-# If +release_hashref+ does not exist, Cartage::Rack will read the hash of the
-# current HEAD.
-class Cartage::Rack
-  VERSION = '1.1' #:nodoc:
-
-  # Creates a new version of the Cartage::Rack application to the specified
-  # +root_path+, or +Dir.pwd+.
-  def self.mount(root_path = nil)
-    new(root_path || Dir.pwd)
+class Cartage
+  # Generate and mount the full metadata reporter, Cartage::Rack.
+  def self.Rack(root_path = nil, &filter)
+    Cartage::Rack.send(:new, root_path, &filter)
   end
 
-  # Sets the root path for Cartage::Rack.
-  def initialize(root_path)
-    @root_path = Pathname(root_path)
-  end
+  # Cartage::Rack is a simple application that reads an application's static
+  # release metadata and returns it as an (optionally filtered)
+  # +application/json+ value, or as a +text/plain+ string if called with
+  # +.text+ or +.txt+.
+  class Rack
+    VERSION = '2.0.rc1' #:nodoc:
+
+    class << self
+      # When +true+, Cartage::Rack and Cartage::Rack::Simple will raise an
+      # exception if there is no metadata file (<tt>release-metadata.json</tt> or
+      # +release_hashref+). May be explicitly turned off.
+      #
+      # Defaults to +true+ except in development or test environments (based on
+      # <tt>$RAILS_ENV</tt> and <tt>$RACK_ENV</tt>).
+      def require_metadata(value = (arg = false; nil)) # rubocop:disable Style/Semicolon
+        @require_metadata = value unless arg == false
+        @require_metadata || default_require_metadata
+      end
 
-  # The Rack application method.
-  def call(env)
-    content = {
-      env:             application_env,
-      release_hashref: release_hashref,
-      timestamp:       timestamp
-    }.delete_if(&->(_, v) { v.nil? })
-
-    case env['PATH_INFO']
-    when /\.json\z/
-      type = 'application/json'
-      body = content.to_json
-    else
-      type = 'text/plain'
-      body = "#{content[:env]}: #{content[:release_hashref]}"
-      body += " (#{content[:timestamp]})" if content[:timestamp]
+      private
+
+      def default_require_metadata
+        (ENV['RAILS_ENV'] || ENV['RACK_ENV']).to_s !~ /\A(?:development|test)\z/i
+      end
     end
 
-    [ '200', { 'Content-Type' => type }, [ body ] ]
-  end
+    def initialize(root_path = nil, &filter) # :nodoc:
+      @metadata = Cartage::Rack::Metadata.new(root_path, filter: filter)
+    end
 
-  def inspect
-    %Q(#{self.class} for #{@root_path.expand_path.basename})
-  end
+    def call(env) #:nodoc:
+      type, body = resolve_content(env)
+      [ '200', { 'Content-Type' => type }, [ body ] ]
+    end
 
-  private
-  def application_env
-    ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'UNKNOWN'
-  end
+    def inspect #:nodoc:
+      "#{self.class} for #{@metadata.inspect}"
+    end
 
-  def release_hashref
-    file = @root_path.join('release_hashref')
-    if file.exist?
-      file.read.split($/).first.chomp
-    elsif @root_path.join('.git').directory?
-      "(git) #{%x(git rev-parse --abbrev-ref HEAD).chomp}"
-    else
-      'UNKNOWN - no release_hashref or .git directory'
+    private
+
+    def resolve_content(env)
+      content = @metadata.resolve
+
+      case env['PATH_INFO']
+      when /\.te?xt\z/
+        type = 'text/plain'
+        body = [
+          "name: #{dig(content, 'package', 'name')}",
+          "environment: #{dig(content, 'env', 'name')}",
+          "hashref: #{dig(content, 'package', 'hashref')}"
+        ]
+
+        value = dig(content, 'package', 'timestamp')
+        body << "timestamp: #{value}" if value
+
+        repo = dig(content, 'package', 'repo')
+        body << "#{repo['type']}: #{repo['url']}" if repo
+        body = body.join("\n")
+      else
+        type = 'application/json'
+        body = content.to_json
+      end
+
+      [ type, body ]
     end
-  end
 
-  def timestamp
-    file = @root_path.join('release_hashref')
-    if file.exist?
-      stamp = file.read.split($/, 2)[1]
-      stamp = nil if stamp && stamp.empty?
-      stamp.chomp if stamp
+    attr_reader :metadata
+
+    #:nocov:
+    def dig(hash, key, *rest)
+      if hash.respond_to?(:dig)
+        hash.dig(key, *rest)
+      else
+        DIGGER.call(hash, key, *rest)
+      end
     end
+
+    DIGGER = ->(h, k, *r) { #:nodoc:
+      v = h[k]
+      if v.nil? || r.empty?
+        v
+      else
+        DIGGER.call(v, *r)
+      end
+    }
+    private_constant :DIGGER
+    #:nocov:
   end
 end
+
+require_relative 'rack/simple'
+require_relative 'rack/metadata'