tainers 0.0.1

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gem 'docker-api', '~> 1.15.0'
+
+group(:development, :test) do
+  gem 'rspec', '~> 3.1.0'
+end
+

data/Gemfile.lock

@@ -0,0 +1,30 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    archive-tar-minitar (0.5.2)
+    diff-lcs (1.2.5)
+    docker-api (1.15.0)
+      archive-tar-minitar
+      excon (>= 0.38.0)
+      json
+    excon (0.41.0)
+    json (1.8.1)
+    rspec (3.1.0)
+      rspec-core (~> 3.1.0)
+      rspec-expectations (~> 3.1.0)
+      rspec-mocks (~> 3.1.0)
+    rspec-core (3.1.7)
+      rspec-support (~> 3.1.0)
+    rspec-expectations (3.1.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.1.0)
+    rspec-mocks (3.1.3)
+      rspec-support (~> 3.1.0)
+    rspec-support (3.1.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  docker-api (~> 1.15.0)
+  rspec (~> 3.1.0)

data/bin/tainers

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+# vim: set filetype=ruby:
+
+require 'tainers'
+
+exit Tainers::CLI.run(ARGV)

data/lib/tainers.rb

@@ -0,0 +1,9 @@
+require 'digest'
+require 'json'
+
+module Tainers
+end
+
+require 'tainers/cli'
+require 'tainers/hash'
+require 'tainers/specification'

data/lib/tainers/cli.rb

@@ -0,0 +1,128 @@
+require 'optparse'
+require 'json'
+
+module Tainers
+  module CLI
+    def self.run parameters
+      spec, parameters = parse(parameters)
+      cmd = Command.new(spec)
+      cmd_name = parameters.shift
+      cmd.send("#{cmd_name}_command".to_sym, *parameters)
+    end
+
+    def self.parse parameters
+      options = {}
+      options[:spec_source] = from_stdin
+      opt_parser = OptionParser.new do |opts|
+        opts.banner = "Usage: tainers [opts] COMMAND"
+        opts.separator ""
+        opts.separator "Manipulate Tainer-managed containers, taking their specification in JSON (from STDIN by default)."
+        opts.separator ""
+        opts.separator "Specific options:"
+
+        opts.on('-j JSON', '--json JSON', String, "Take container specification from the given JSON parameter.") do |j|
+          options[:spec_source] = from_json(j)
+        end
+
+        opts.on('-f FILEPATH', '--file FILEPATH', String, "Take container specification from JSON in the given file.") do |f|
+          options[:spec_source] = from_file(f)
+        end
+
+        opts.on('-p PREFIX', '--prefix PREFIX', String, "Use PREFIX as container name prefix (overriding whatever is in spec)") do |p|
+          options['prefix'] = p
+        end
+
+        opts.on('-s SUFFIX', '--suffix SUFFIX', String, "Use SUFFIX as container name suffix (overriding whatever is in spec)") do |s|
+          options['suffix'] = s
+        end
+
+        opts.on('-h', '--help') do
+          print opts
+          exit 0
+        end
+
+        opts.separator ""
+        opts.separator "Commands:"
+        Command.commands.each do |name, help|
+          opts.separator ""
+          opts.separator "    #{name}"
+          opts.separator "          #{help}" if help.size > 0
+        end
+      end
+
+      # Stop on first non-option param
+      non_param = []
+      args = opt_parser.order(parameters) {|p| non_param << p; opt_parser.terminate}
+      spec = options.delete(:spec_source).call
+      spec.update(options)
+      [spec, non_param + args]
+    end
+
+    def self.from_stdin
+      Proc.new do
+        JSON.parse(STDIN.read)
+      end
+    end
+
+    def self.from_file file
+      Proc.new do
+        File.open(file, "r") do |f|
+          JSON.parse(f.read)
+        end
+      end
+    end
+
+    def self.from_json json
+      Proc.new do
+        JSON.parse json
+      end
+    end
+
+    class Command
+      attr_reader :specification
+
+      def initialize(spec={})
+        @specification = Tainers.specify(spec)
+      end
+
+      def self.commands
+        cmds = instance_methods.collect {|m| m.to_s}.find_all {|m| m.to_s =~ /_command$/}.collect {|n| n.to_s[0..-9] }
+        cmds.collect do |name|
+          helper = "#{name}_help".to_sym
+          if respond_to? helper
+            [name, send(helper)]
+          else
+            [name, '']
+          end
+        end
+      end
+
+      def ensure_command
+        return 0 if specification.ensure
+        255
+      end
+
+      def self.ensure_help
+        "Ensures specified container exists, by name."
+      end
+
+      def exists_command
+        return 0 if specification.exists?
+        1
+      end
+
+      def self.exists_help
+        "Exits with 0 (true) if specified container exists, by name; 1 (false) if not."
+      end
+
+      def name_command
+        STDOUT.print "#{specification.name}\n"
+        0
+      end
+
+      def self.name_help
+        "Prints the specified container's name on stdout."
+      end
+    end
+  end
+end

data/lib/tainers/hash.rb

@@ -0,0 +1,44 @@
+module Tainers
+  # call-seq:
+  #     Tainers.hash(structure) => consistent hash hexdigest
+  #
+  # Produces a consistent hash hexdigest string for the input
+  # structure, handling arrays, hashes, strings, numbers, nesting
+  # of such structures, etc.
+  #
+  # Hash keys are sorted prior to computing the digest, to ensure
+  # that hashes that would be regarded as equal produce the same
+  # digest.
+  #
+  #     Tainers.hash({"a" => "foo", "b" => "bar"})  #=> "5427f704439548cae1911616e2bec3b7cc2dd11c"
+  #
+  def self.hash structure
+    str = structured_string(structure)
+    Digest::SHA1.hexdigest str
+  end
+
+  private
+
+  def self.consistent_structure structure
+    if Hash === structure
+      s = structure.keys.sort.inject(["{"]) do |a, key|
+        a << consistent_structure(key)
+        a << consistent_structure(structure[key])
+        a
+      end
+      s << "}"
+      s
+    elsif Array === structure
+      s = structure.collect {|item| consistent_structure item}
+      s.unshift "["
+      s << "]"
+      s
+    else
+      structure
+    end
+  end
+
+  def self.structured_string structure
+    consistent_structure(structure).to_json
+  end
+end

data/lib/tainers/specification.rb

@@ -0,0 +1,106 @@
+require 'docker'
+
+module Tainers
+
+  # An object representing a container configuration (a "specification"), with
+  # methods for checking and/or ensuring existence (by name).
+  #
+  # While this can be used directly, it is not intended for direct instantiation,
+  # instead designed to be used via Tainers::specify, which provides name determination
+  # logic for organizing containers by their configuration.
+  class Specification
+
+    # Creates a new container specification that uses the same parameters supported
+    # by the Docker::Container::create singleton method.  These parameters align
+    # with that of the docker daemon remote API.
+    #
+    # Note that it requires a container name, and an Image.  Without an Image, there's
+    # nothing to build.  The name is essential to the purpose of the entire Tainers project.
+    def initialize args={}
+      raise ArgumentError, 'A name is required' unless valid_name? args['name']
+
+      raise ArgumentError, 'An Image is required' unless valid_image? args['Image']
+
+      # Maketh a copyeth of iteth
+      @args = {}.merge(args)
+    end
+
+    # Ensures that the container named by this specification exists, creating the
+    # container if necessary.
+    #
+    # Note that this only ensures that a container with the proper name exists; it does not
+    # ensure that the existing container has a matching configuration.
+    #
+    # Returns true if the container reliably exists (it has been shown to exist, or was
+    # successfully created, or failed to create due to a name conflict).  All other cases
+    # should result in exceptions.
+    def ensure
+      return self if exists?
+      return self if Tainers::API.create_or_conflict(@args)
+      return nil
+    end
+
+    # The name of the container described by this specification.
+    def name
+      @args['name']
+    end
+
+    # True if the container of the appropriate name already exists.  False if not.
+    def exists?
+      ! Tainers::API.get_by_name(name).nil?
+    end
+
+    private
+
+    def valid_name? name
+      ! (name.nil? or name == '')
+    end
+
+    def valid_image? image
+      ! (image.nil? or image == '')
+    end
+  end
+
+  module API
+    def self.get_by_name name
+      begin
+        Docker::Container.get(name)
+      rescue Docker::Error::NotFoundError
+        nil
+      end
+    end
+
+    def self.create_or_conflict params
+      begin
+        Docker::Container.create(params.dup)
+        return true
+      rescue Excon::Errors::Conflict
+        return true
+      end
+      false
+    end
+  end
+
+  def self.specify args={}
+    Specification.new named_parameters_for(args)
+  end
+
+  def self.named_parameters_for params
+    p = params.dup
+    prefix = p.delete('prefix')
+    prefix = if prefix.nil? || prefix == ''
+               'Tainers'
+             else
+               prefix.downcase
+             end
+    suffix = p.delete('suffix')
+    suffix = if suffix.nil?
+               ''
+             else
+               "-#{suffix.downcase}"
+             end
+    digest = hash(p)
+    p['name'] = "#{prefix}-#{digest}#{suffix}"
+    p
+  end
+end

data/spec/commands/common_examples.rb

@@ -0,0 +1,129 @@
+require 'rspec_helper'
+require 'json'
+require 'tempfile'
+
+shared_examples_for 'prefix and suffix' do |command_group|
+  let(:param_prefix) { "opt-" + double.object_id.to_s }
+  let(:param_suffix) { "opt-" + double.object_id.to_s }
+
+  context 'with --prefix' do
+    before do
+      args << '--prefix'
+      args << param_prefix
+      expected_specification['prefix'] = param_prefix
+    end
+
+    it_behaves_like command_group
+
+    context 'and --suffix' do
+      before do
+        args << '--suffix'
+        args << param_suffix
+        expected_specification['suffix'] = param_suffix
+      end
+
+      it_behaves_like command_group
+    end
+  end
+
+  context 'with --suffix' do
+    before do
+      args << '--suffix'
+      args << param_suffix
+      expected_specification['suffix'] = param_suffix
+    end
+
+    it_behaves_like command_group
+  end
+end
+
+shared_examples_for 'a command' do |command_group|
+  let :provided_specification do
+    {
+      'Image' => double.object_id.to_s,
+      double.to_s => double.to_s,
+      'prefix' => "spec-" + double.object_id.to_s,
+      'suffix' => "spec-" + double.object_id.to_s
+    }
+  end
+
+  let :expected_specification do
+    provided_specification.dup
+  end
+
+  let(:args) { [] }
+
+  let(:json) { provided_specification.to_json }
+
+  let(:specification) { double }
+
+  let :command_run do
+    Tainers::CLI.run args
+  end
+
+  before do
+    expect(Tainers).to receive(:specify).with(expected_specification).and_return(specification)
+  end
+
+  context 'given JSON specification in parameters' do
+    context 'via -j' do
+      before do
+        args << '-j'
+        args << json
+      end
+
+      it_behaves_like "prefix and suffix", command_group
+    end
+
+    context 'via --json' do
+      before do
+        args << '--json'
+        args << json
+      end
+
+      it_behaves_like "prefix and suffix", command_group
+    end
+  end
+
+  context 'given JSON specification in a file' do
+    let(:file) do 
+      f = Tempfile.new('tainers-test-spec')
+      f.write(json)
+      f.close
+      f
+    end
+
+    let(:path) { file.path }
+
+    after do
+      file.unlink
+    end
+
+    context 'via -f' do
+      before do
+        args << '-f'
+        args << path
+      end
+
+      it_behaves_like "prefix and suffix", command_group
+    end
+
+    context 'via --file' do
+      before do
+        args << '--file'
+        args << path
+      end
+
+      it_behaves_like "prefix and suffix", command_group
+    end
+  end
+
+  context 'given JSON specification on STDIN' do
+    before do
+      expect(STDIN).to receive(:read).and_return(json)
+    end
+
+    it_behaves_like "prefix and suffix", command_group
+  end
+end
+

data/spec/commands/ensure_spec.rb

@@ -0,0 +1,17 @@
+require_relative 'common_examples'
+
+shared_examples_for 'ensure command' do
+  before do
+    args << 'ensure'
+  end
+
+  it "ensures container and exits appropriately" do
+    expect(specification).to receive(:ensure).with(no_args).and_return(true)
+    expect(command_run).to eq(0)
+  end
+end
+
+describe 'tainers ensure' do
+  it_behaves_like "a command", "ensure command"
+end
+

data/spec/commands/exists_spec.rb

@@ -0,0 +1,22 @@
+require_relative 'common_examples'
+
+shared_examples_for 'exists command' do
+  before do
+    args << 'exists'
+  end
+
+  it 'returns 0 for an existing container' do
+    expect(specification).to receive(:exists?).with(no_args).and_return(true)
+    expect(command_run).to eq(0)
+  end
+
+  it 'returns 1 for a non-existent container' do
+    expect(specification).to receive(:exists?).with(no_args).and_return(false)
+    expect(command_run).to eq(1)
+  end
+end
+
+describe 'tainers exists' do
+  it_behaves_like 'a command', 'exists command'
+end
+

data/spec/commands/name_spec.rb

@@ -0,0 +1,18 @@
+require_relative 'common_examples'
+
+shared_examples_for 'name command' do
+  before do
+    args << 'name'
+  end
+
+  it "writes the name of the container to stdout" do
+    expect(specification).to receive(:name).with(no_args).and_return(name = "some-name-" + double.object_id.to_s)
+    expect(STDOUT).to receive(:print).with("#{name}\n")
+    expect(command_run).to eq(0)
+  end
+end
+
+describe 'tainers name' do
+  it_behaves_like 'a command', 'name command'
+end
+

data/spec/hashing_spec.rb

@@ -0,0 +1,87 @@
+require 'rspec_helper'
+require 'digest'
+
+def hashit str
+  Digest::SHA1.hexdigest(str)
+end
+
+RSpec.describe 'Tainers.hash' do
+  let(:test_number) { self.object_id }
+  let(:test_string) { "something-#{self.object_id.to_s}-blah" }
+
+  it 'handles a simple string' do
+    expect(Tainers.hash test_string).to eq(hashit('"' + test_string + '"'))
+  end
+
+  it 'handles a simple number' do
+    expect(Tainers.hash test_number).to eq(hashit(test_number.to_s))
+  end
+
+  it 'handles an array of mixed simple type' do
+    expected_ary = ['[', test_string, test_number, ']'].to_json
+    expect(Tainers.hash [test_string, test_number]).to eq(hashit expected_ary)
+  end
+
+  it 'handles a hash of mixed simple type' do
+    expected = ["{", "a", test_number, "b", test_string, "c", test_number + 1, "d", test_string + "z", "}"].to_json
+    expect(Tainers.hash "c" => test_number + 1,
+                        "a" => test_number,
+                        "d" => test_string + "z",
+                        "b" => test_string).to eq(hashit expected)
+  end
+
+  it 'handles a complex structure' do
+    expected = [
+      "[",
+      test_number,
+      [
+        '{',
+        'first', [
+          '{',
+          1, 'one',
+          2, 'two',
+          '}',
+        ],
+        'second', [
+          '[',
+          'a',
+          'b',
+          ']',
+        ],
+        '}',
+      ],
+      test_string,
+      [
+        '{',
+        'fourth', [
+          '[',
+          1000,
+          500,
+          ']',
+        ],
+        'third', [
+          '{',
+          ['[', 'a', 'b', ']'], 'ey',
+          ['[', 'b', 'a', ']'], 'bee',
+          '}',
+        ],
+        '}',
+      ],
+      "]",
+    ].to_json
+    struct = [
+      test_number,
+      {
+        'first' => {2 => 'two', 1 => 'one'},
+        'second' => ['a', 'b'],
+      },
+      test_string,
+      {
+        'third' => {['b','a'] => 'bee', ['a','b'] => 'ey'},
+        'fourth' => [1000, 500],
+      },
+    ]
+    expect(Tainers.hash struct).to eq(hashit expected)
+  end
+end
+

data/spec/rspec_helper.rb

@@ -0,0 +1,3 @@
+require 'rspec'
+require 'tainers'
+

data/spec/specification_spec.rb

@@ -0,0 +1,63 @@
+require 'rspec_helper'
+
+RSpec.describe Tainers::Specification do
+  it 'requires a name' do
+    expect { Tainers::Specification.new 'Image' => 'foo/image:latest' }.to raise_error(/name is required/)
+  end
+
+  it 'requires an image' do
+    expect { Tainers::Specification.new 'name' => 'something' }.to raise_error(/Image is required/)
+  end
+
+  context 'for a container' do
+    let(:name) { "something-#{object_id.to_s}-foo" }
+    let(:image) { "some.#{object_id.to_s}.repo:5000/some-image/#{object_id.to_s[0..5]}" }
+    let(:container_args) { {'Image' => image, double.to_s => double.to_s } }
+    let(:specification_args) { container_args.merge('name' => name) }
+
+    subject do
+      Tainers::Specification.new specification_args
+    end
+
+    context 'that does not exist' do
+      it 'indicates non-existence' do
+        expect(Docker::Container).to receive(:get).with(name).and_raise(Docker::Error::NotFoundError)
+        expect(subject.exists?).to be false
+      end
+
+      context '#ensure' do
+        before do
+          expect(subject).to receive(:exists?).and_return(false)
+        end
+
+        it 'uses Docker::Container for creation' do
+          expect(Docker::Container).to receive(:create).with(specification_args).and_return(container = double)
+          expect(subject.ensure).to be(subject)
+        end
+
+        it 'is okay with a conflict result' do
+          expect(Docker::Container).to receive(:create).with(specification_args).and_raise(Excon::Errors::Conflict, "Pickles")
+          expect(subject.ensure).to be(subject)
+        end
+
+        it 'does not handle other exceptions' do
+          expect(Docker::Container).to receive(:create).with(specification_args).and_raise(Exception, "You suck.")
+          expect { subject.ensure }.to raise_error("You suck.")
+        end
+      end
+    end
+
+    context 'that exists' do
+      it 'indicates existence' do
+        expect(Docker::Container).to receive(:get).with(name).and_return(double)
+        expect(subject.exists?).to be true
+      end
+
+      it 'does a no-op for #ensure' do
+        expect(subject).to receive(:exists?).and_return(true)
+        expect(Docker::Container).to receive(:create).never
+        expect(subject.ensure).to be(subject)
+      end
+    end
+  end
+end

data/spec/specify_spec.rb

@@ -0,0 +1,79 @@
+require 'rspec_helper'
+
+shared_examples_for 'a named specification' do
+  it 'produces a deterministically named specification' do
+    expect(Tainers).to receive(:hash).with(base_args.dup).and_return(hash)
+    expect(Tainers::Specification).to receive(:new).with(base_args.dup.update('name' => name)).and_return(s = double)
+    expect(Tainers.specify specify_args).to eq(s)
+  end
+end
+
+describe 'Tainers::specify' do
+  let(:prefix) { nil }
+  let(:suffix) { nil }
+
+  let(:base_args) { { double.to_s => double.to_s, double.to_s => double.to_s } }
+
+  let(:specify_args) {
+    [['prefix', prefix], ['suffix', suffix]].inject(base_args.dup) do |a, item|
+      if item[1].nil?
+        a
+      else
+        a.merge(item[0] => item[1])
+      end
+    end
+  }
+
+  let(:hash) { double.object_id.to_s }
+
+  let(:name) {
+    pre = if prefix.nil?
+            'Tainers'
+          else
+              prefix.downcase
+          end
+    pre = 'Tainers' if pre.nil?
+    suf = if suffix.nil?
+            ''
+          else
+            '-' + suffix.downcase
+          end
+    "#{pre}-#{hash}#{suf}"
+  }
+
+  context 'with a prefix' do
+    let(:prefix) { "pre#{double.object_id.to_s[0..5]}" }
+
+    it_behaves_like 'a named specification'
+
+    context 'of mixed case' do
+      let(:prefix) { "PrE#{double.object_id.to_s[0..5]}" }
+
+      it_behaves_like 'a named specification'
+
+      context 'and a suffix' do
+        let(:suffix) { "#{double.object_id.to_s[0..5]}sfx" }
+        
+        it_behaves_like 'a named specification'
+
+        context 'of mixed case' do
+          let(:suffix) { "#{double.object_id.to_s[0..5]}SfX" }
+
+          it_behaves_like 'a named specification'
+        end
+      end
+    end
+  end
+
+  context 'with a suffix' do
+    let(:suffix) { "#{double.object_id.to_s[1..6]}suffy" }
+
+    it_behaves_like 'a named specification'
+
+    context 'of mixed case' do
+      let(:suffix) { "#{double.object_id.to_s[1..6]}sUFFy" }
+
+      it_behaves_like 'a named specification'
+    end
+  end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: tainers
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Ethan Rowe
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-11-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: docker-api
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.15.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.15.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.7.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.7.6
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+description: Config-driven management of docker containers
+email: ethan@the-rowes.com
+executables:
+- tainers
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/tainers/cli.rb
+- lib/tainers/specification.rb
+- lib/tainers/hash.rb
+- lib/tainers.rb
+- spec/hashing_spec.rb
+- spec/commands/exists_spec.rb
+- spec/commands/ensure_spec.rb
+- spec/commands/common_examples.rb
+- spec/commands/name_spec.rb
+- spec/specification_spec.rb
+- spec/rspec_helper.rb
+- spec/specify_spec.rb
+- bin/tainers
+- Gemfile
+- Gemfile.lock
+homepage: http://github.com/ethanrowe/ruby-tainers
+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'
+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: Manage docker containers based on deterministic naming derived from container
+  configuration
+test_files: []