tainers 0.0.2 → 0.1.0

data/lib/tainers/specification.rb

@@ -1,89 +1,167 @@
 require 'docker'
 
 module Tainers
+  module Specification
 
-  # 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.
+    # An object representing a container configuration (a "specification"), with
+    # methods for checking and/or ensuring existence (by name).
     #
-    # 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']
+    # 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 Bare
+
+      # 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
 
-      raise ArgumentError, 'An Image is required' unless valid_image? args['Image']
+      # 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
 
-      # Maketh a copyeth of iteth
-      @args = {}.merge(args)
-    end
+      # Creates the container named by this specification, if it does
+      # not already exist.
+      #
+      # Returns true (self, actually) if the invocation resulted in the
+      # creation of a new container; false otherwise.
+      #
+      # A false condition could result from:
+      # - The container already existing
+      # - The container being simultaneously created by another
+      #   actor, with your invocation losing the race.
+      # 
+      # A failure to create due to operational or semantic issues
+      # should result in an exception.  Therefore, any non-exceptional
+      # case should mean that a container of the expected name exists,
+      # though in the false result case there is no firm guarantee
+      # that the existing container has the requested configuration e.
+      def create
+        return false if exists?
+        return self if Tainers::API.create(@args)
+        false
+      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
+      # The name of the container described by this specification.
+      def name
+        @args['name']
+      end
+
+      # The image of the container described by this specification.
+      # Note that this is a string (a tag or image ID) and not a more
+      # complex object.
+      def image
+        @args['Image']
+      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 # class Bare
+
+    module Delegator
+      def self.delegates(method_name)
+        method_name = method_name.to_sym
+        define_method(method_name) do |*args|
+          chain.send(method_name, *args)
+        end
+      end
+
+      def initialize(chain)
+        @chain = chain
+      end
+
+      attr_reader :chain
+
+      delegates :create
+      delegates :ensure
+      delegates :exists?
+      delegates :image
+      delegates :name
     end
 
-    # Creates the container named by this specification, if it does
-    # not already exist.
+    # Tainer specification that automatically pulls the image
+    # as needed prior to container creation operations.
     #
-    # Returns true (self, actually) if the invocation resulted in the
-    # creation of a new container; false otherwise.
+    # Wrap it around a bare specification to use it:
     #
-    # A false condition could result from:
-    # - The container already existing
-    # - The container being simultaneously created by another
-    #   actor, with your invocation losing the race.
-    # 
-    # A failure to create due to operational or semantic issues
-    # should result in an exception.  Therefore, any non-exceptional
-    # case should mean that a container of the expected name exists,
-    # though in the false result case there is no firm guarantee
-    # that the existing container has the requested configuration e.
-    def create
-      return false if exists?
-      return self if Tainers::API.create(@args)
-      false
-    end
-
-    # The name of the container described by this specification.
-    def name
-      @args['name']
-    end
+    #     t1 = Tainers::Specification::Bare.new('Image' =>' foo')
+    #     t2 = Tainers::Specification::ImagePuller.new(t1)
+    #     # This doesn't pull image "foo"
+    #     t1.ensure
+    #     # But this will, if necessary
+    #     t2.ensure
+    #
+    # Note that the #ensure and #create methods have the pulling
+    # behavior; no others do.
+    class ImagePuller
+      include Delegator
+
+      def self.ensure_image(image)
+        if ! Tainers::API.image_exists?(image)
+          Tainers::API.pull_image image
+        end
+        true
+      end
 
-    # True if the container of the appropriate name already exists.  False if not.
-    def exists?
-      ! Tainers::API.get_by_name(name).nil?
+      def self.pulls_and_delegates(method_name)
+        method_name = method_name.to_sym
+        define_method(method_name) do |*args|
+          self.class.ensure_image(chain.image)
+          chain.send(method_name, *args)
+        end
+      end
+      
+      pulls_and_delegates :create
+      pulls_and_delegates :ensure
     end
+  end # module Specification
 
-    private
-
-    def valid_name? name
-      ! (name.nil? or name == '')
+  module API
+    def self.image_exists? name
+      begin
+        return true if Docker::Image.get(name)
+      rescue Docker::Error::NotFoundError
+        return false
+      end
     end
 
-    def valid_image? image
-      ! (image.nil? or image == '')
+    def self.pull_image name
+      Docker::Image.create('fromImage' => name)
     end
-  end
 
-  module API
     def self.get_by_name name
       begin
         Docker::Container.get(name)
@@ -105,10 +183,20 @@ module Tainers
       create params
       true
     end
-  end
+  end # module API
 
+  # Returns an image-pulling container specification
+  # from the given parameters.
+  #
+  # Enforces the naming conventions such that the
+  # name for the container will have prefix, suffix,
+  # and spec-derived hash as documented elsewhere.
+  #
+  # The result will be an instance of Tainers::Specification::ImagePuller.
   def self.specify args={}
-    Specification.new named_parameters_for(args)
+    Specification::ImagePuller.new(
+      Specification::Bare.new named_parameters_for(args)
+    )
   end
 
   def self.named_parameters_for params

data/spec/{specification_spec.rb → container_specifications/bare_spec.rb}

@@ -22,13 +22,13 @@ shared_examples_for 'container creator' do
 end
 
 
-RSpec.describe Tainers::Specification do
+RSpec.describe Tainers::Specification::Bare do
   it 'requires a name' do
-    expect { Tainers::Specification.new 'Image' => 'foo/image:latest' }.to raise_error(/name is required/)
+    expect { Tainers::Specification::Bare.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/)
+    expect { Tainers::Specification::Bare.new 'name' => 'something' }.to raise_error(/Image is required/)
   end
 
   context 'for a container' do
@@ -38,7 +38,15 @@ RSpec.describe Tainers::Specification do
     let(:specification_args) { container_args.merge('name' => name) }
 
     subject do
-      Tainers::Specification.new specification_args
+      Tainers::Specification::Bare.new specification_args
+    end
+
+    it 'has a name' do
+      expect(subject.name).to equal(name)
+    end
+
+    it 'has an image' do
+      expect(subject.image).to equal(image)
     end
 
     context 'that does not exist' do

data/spec/container_specifications/image_puller_spec.rb

@@ -0,0 +1,96 @@
+require 'rspec_helper'
+
+shared_examples_for 'specification delegator' do |method|
+  let(:callable) do
+    subject.method(method.to_sym)
+  end
+
+  it "passes through to underlying method" do
+    expect(wrapped).to receive(method.to_sym).with(no_args).and_return(result = double)
+    expect(callable.call).to be(result)
+  end
+
+  it "passes arguments through to underlying method" do
+    args = [double, double, double]
+    expect(wrapped).to receive(method.to_sym).with(*args).and_return(result = double)
+    expect(callable.call(*args)).to be(result)
+  end
+end
+
+shared_examples_for 'pulling delegator' do |method|
+  let(:callable) do
+    subject.method(method.to_sym)
+  end
+
+  let(:image) do
+    "image-#{double.to_s}-foo"
+  end
+
+  before do
+    allow(wrapped).to receive(:image).with(no_args).and_return(image)
+  end
+
+  describe "with no existing image" do
+    before do
+      expect(Docker::Image).to receive(:get).with(image).and_raise(Docker::Error::NotFoundError)
+    end
+
+    describe 'and successful pull' do
+      let(:api_image) { double }
+
+      before do
+        expect(Docker::Image).to receive(:create).with('fromImage' => image).and_return(api_image)
+      end
+
+      it_behaves_like 'specification delegator', method
+    end
+
+    describe 'and failed pull' do
+      before do
+        # Just a general exception on this rather than a specific type;
+        # the docker-api gem doesn't give a pretty exception here.
+        expect(Docker::Image).to receive(:create).with('fromImage' => image).and_raise("Pull failed!")
+        expect(wrapped).to receive(method.to_sym).never
+      end
+
+      it "propagates the pull failure exception" do
+        expect { callable.call }.to raise_error("Pull failed!")
+      end
+    end
+  end
+
+  describe "with an existing image" do
+    before do
+      expect(Docker::Image).to receive(:get).with(image).and_return(double)
+      expect(Docker::Image).to receive(:create).never
+    end
+
+    it_behaves_like 'specification delegator', method
+  end
+end
+
+describe Tainers::Specification::ImagePuller do
+  let(:wrapped) { double }
+
+  subject { Tainers::Specification::ImagePuller.new wrapped }
+
+  describe '#image method' do
+    it_behaves_like 'specification delegator', :image
+  end
+
+  describe '#name method' do
+    it_behaves_like 'specification delegator', :name
+  end
+
+  describe '#exists? method' do
+    it_behaves_like 'specification delegator', :exists?
+  end
+
+  describe '#create method' do
+    it_behaves_like 'pulling delegator', :create
+  end
+
+  describe '#ensure method' do
+    it_behaves_like 'pulling delegator', :ensure
+  end
+end

data/spec/specify_spec.rb

@@ -3,7 +3,10 @@ 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)
+    # Assemble the bare specification from the parameters.
+    expect(Tainers::Specification::Bare).to receive(:new).with(base_args.dup.update('name' => name)).and_return(bare = double)
+    # And wrap it with image puller behavior so the easy case is for images to get automatically pulled down as needed.
+    expect(Tainers::Specification::ImagePuller).to receive(:new).with(bare).and_return(s = double)
     expect(Tainers.specify specify_args).to eq(s)
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tainers
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -71,12 +71,13 @@ files:
 - lib/tainers/hash.rb
 - lib/tainers.rb
 - spec/hashing_spec.rb
+- spec/container_specifications/bare_spec.rb
+- spec/container_specifications/image_puller_spec.rb
 - spec/commands/exists_spec.rb
 - spec/commands/ensure_spec.rb
 - spec/commands/common_examples.rb
 - spec/commands/create_spec.rb
 - spec/commands/name_spec.rb
-- spec/specification_spec.rb
 - spec/rspec_helper.rb
 - spec/specify_spec.rb
 - bin/tainers