qb 0.3.25 → 0.4.0

data/lib/qb/ansible/module/response.rb

@@ -0,0 +1,195 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Deps
+# -----------------------------------------------------------------------
+
+require 'nrser/props/mutable/stash'
+
+# Need the experimental {NRSER::Stash} class that lets us intercept hash
+# writes.
+require 'nrser/labs/stash'
+
+
+# Refinements
+# =======================================================================
+
+using NRSER::Types
+
+
+# Definitions
+# =======================================================================
+
+
+# Encapsulation of data that an Ansible module responds to Ansible with.
+# 
+# Ansible calls this a module's "return value".
+# 
+# @see http://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html
+# 
+class QB::Ansible::Module::Response < NRSER::Stash
+  
+  # Mixins
+  # ========================================================================
+  
+  include NRSER::Props::Mutable::Stash
+  
+  
+  # @!group Props
+  # ==========================================================================
+  
+  # "Common" Values
+  # --------------------------------------------------------------------------
+  
+  # For those modules that implement backup=no|yes when manipulating files,
+  # a path to the backup file created.
+  # 
+  # The file must exist if provided.
+  # 
+  prop  :backup_file,
+        type: t.file_path?
+  
+  
+  # A boolean indicating if the task had to make changes.
+  # 
+  prop  :changed,
+        type: t.bool,
+        default: false
+  
+  
+  # A boolean that indicates if the task was failed or not.
+  # 
+  prop  :failed,
+        type: t.bool,
+        default: false
+  
+  # Ansible says "Information on how the module was invoked."
+  # 
+  # I have no idea what that means and couldn't find anywhere it was being
+  # set in a quick search of their module sources.
+  # 
+  prop  :invocation,
+        type: t.any
+  
+  
+  # A string with a generic message relayed to the user.
+  # 
+  prop  :msg,
+        type: t.str?
+  
+  
+  # A return (exit) code, if one makes sense, I guess.
+  # 
+  # Ansible says:
+  # 
+  # > Some modules execute command line utilities or are geared for executing
+  # > commands directly (raw, shell, command, etc), this field contains
+  # > ‘return code’ of these utilities.
+  # 
+  prop  :rc,
+        type: t.unsigned?
+  
+  
+  # "Internal Use" (Consumed by Ansible)
+  # --------------------------------------------------------------------------
+  
+  # This key should contain a dictionary which will be appended to the facts
+  # assigned to the host.
+  # 
+  # These will be directly accessible and don’t require using a registered
+  # variable.
+  # 
+  prop  :ansible_facts,
+        aliases: [ :facts ],
+        type: t.hash_( keys: t.non_empty_str ),
+        default: -> { HashWithIndifferentAccess.new },
+        from_data: :with_indifferent_access.to_proc
+  
+  
+  # This key can contain traceback information caused by an exception in a
+  # module. It will only be displayed [to the user] on high verbosity (-vvv).
+  # 
+  # Unclear what the value type is, guessing string...
+  # 
+  prop  :exception,
+        type: t.str?
+  
+  
+  # @!attribute [rw] warnings
+  #   This key contains a list of strings that will be presented to the user.
+  #   
+  #   @return [Array<String>]
+  #     Non-empty string warning messages to return to Ansible.
+  # 
+  prop  :warnings,
+        type: t.array( t.non_empty_str ),
+        default: -> { [] }
+  
+  
+  # @!attribute [rw] depreciations
+  #   This key contains a list of dictionaries that will be presented to the
+  #   user. Keys of the dictionaries are msg and version, values are string,
+  #   value for the version key can be an empty string.
+  #   
+  #   @return [Array<{ msg: String, version: String }>]
+  # 
+  prop  :depreciations,
+        type: t.array(
+          t.shape( msg: t.non_empty_str, version: t.non_empty_str )
+        ),
+        default: ->{ [] }
+  
+  
+  metadata.freeze
+  
+  # @!endgroup Props # *******************************************************
+  
+  
+  # Constructor
+  # ======================================================================
+  
+  # Instantiate a new `QB::Ansible::Module::Response`.
+  def initialize values = {}
+    super()
+    initialize_props values
+  end # #initialize
+  
+  
+  # Instance Methods
+  # ======================================================================
+  
+  # Uses {Symbol} keys, and they can not be empty. Will convert non-empty
+  # strings to their symbols.
+  # 
+  # @param [Symbol | String] key
+  # @return [Symbol]
+  #   
+  def convert_key key
+    t.match key,
+      t.non_empty_str, :to_sym.to_proc,
+      t.non_empty_sym, key
+  end
+  
+  
+  # Create a new response to represent a failure, copying the stuff that makes
+  # sense to keep from this one.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def to_failure msg:, warnings: [], depreciations: [], **values
+    self.class.new \
+      failed: true,
+      msg: msg,
+      warnings: (self.warnings + warnings),
+      depreciations: (self.depreciations + depreciations)
+  end # #to_failure
+  
+  
+end # class QB::Ansible::Module::Response

data/lib/qb/ansible/modules.rb

@@ -0,0 +1,42 @@
+
+module QB
+module Ansible
+# QB's built-in Ansible modules (that are written in Ruby).
+# 
+# Putting them here seems better than in `//library` 'cause we want to support
+# composing modules, something Ansible either totally doesn't support or at
+# least doesn't advertise or encourage. This means we want our Ruby modules
+# in the load path, and here seemed like a decent spot.
+# 
+# None of these are required with `require 'qb'` - they need to be required
+# individually.
+# 
+# I created a "super module" to run them without needed to create executables
+# for each one:
+# 
+#     - name: >-
+#         Run me some QB module...
+#       
+#       qb.module:
+#         
+#         # The module's relative path from `//lib/qb/ansible/modules`
+#         #
+#         # You can also use "relative" class name like `Docker::Image` or
+#         # "absolute" like `::QB::Some::Other::Module` to reach classes
+#         # *not* in `//lib/qb/ansible/modules`
+#         #
+#         name: docker/image
+#         
+#         # The arguments for the module
+#         args:
+#           path: /path/to/image/source
+#           # ...
+#           
+# Check out `//library/qb.module.rb` for the source.
+# 
+# This will also let us do other "super-level" stuff like provide common
+# result-value-to-fact binding or whatever (just an idea).
+# 
+# 
+# 
+module Modules; end; end; end

data/lib/qb/ansible/modules/docker/image.rb

@@ -0,0 +1,273 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+
+# Requirements
+# ========================================================================
+
+# Project / Package
+# ------------------------------------------------------------------------
+
+require 'qb'
+require 'qb/docker/image'
+
+
+# Namespace
+# ========================================================================
+
+module QB
+module Ansible
+module Modules
+module Docker
+
+
+# Definitions
+# =======================================================================
+
+# Build a Docker image if needed. Features to deal with version-tagging.
+# 
+class Image < QB::Ansible::Module
+  
+  # Arguments
+  # ========================================================================
+  
+  arg :name,
+      type: QB::Docker::Image::Name
+  
+  arg :path,
+      type: t.dir_path
+      # FIXME ( from_s: ->( s ) { Pathname.new( s ).expand_path } )
+  
+  arg :from_image,
+      type: QB::Docker::Image::Name
+  
+  arg :fact_name,
+      type: t.non_empty_str?
+  
+  arg :build_arg,
+      type: t.hash_,
+      aliases: [ :build_args, :buildargs ],
+      reader: {
+        build_args: false,
+        buildargs: false,
+      },
+      default: ->{ {} }
+  
+  arg :include_from_image_build,
+      type: t.bool,
+      default: true
+  
+  # @!attribute [r] now
+  #   The time to use as now. Defaults to get the current time, but here so
+  #   that it can be provided externally so if you're doing a bunch of work
+  #   you can make all the timestamps sync up. Pls don't abuse.
+  #   
+  #   @return [Time]
+  #     UTC {Time} to use as now.
+  # 
+  arg :now,
+      type: Time,
+      default: ->{ Time.now.utc }
+  
+  
+  # Helpers
+  # ========================================================================
+  
+  # 'openresty/openresty:1.11.2.4-xenial'
+  #   =>  repository: 'openresty'
+  #       name: 'openresty'
+  #       tag: {
+  #         major: 1,
+  #         minor: 11,
+  #         patch: 2,
+  #         revision: [4],
+  #         prerelease: ['xenial'],
+  #       }
+  #   =>  ['openresty--openresty', 1, 11, 2, 4, 'xenial']
+  # 
+  #   which eventually becomes the Docker tag
+  #   
+  #       <semver>_openresty.openresty.1.11.2.4.xenial.<build_info?>
+  # 
+  def build_segments_for_from_image
+    return [] unless include_from_image_build
+    
+    [
+      [
+        (from_image.repository == 'beiarea' ? nil : from_image.repository),
+        from_image.name,
+      ].
+        compact.
+        map { |name| name.gsub( '_', '-' ) }.
+        join( '-' ),
+      *from_image.tag.version.to_a.flatten,
+    ]
+  end
+  
+  
+  def git
+    lazy_var :@git do
+      QB::Repo::Git.from_path path
+    end
+  end
+  
+  
+  def source_base_version
+    lazy_var :@source_base_version do
+      QB::Package::Version.from_string (path.to_pn / 'VERSION').read
+    end
+  end
+  
+  
+  def source_dev_version
+    lazy_var :@source_dev_version do
+      source_base_version.build_version \
+        branch: git.branch,
+        ref: git.head_short,
+        dirty: !git.clean?
+        # time: now
+    end
+  end
+  
+  
+  def source_version
+    lazy_var :@source_version do
+      if source_base_version.dev?
+        source_dev_version
+      else
+        source_non_dev_version
+      end
+    end
+  end
+  
+  
+  def source_non_dev_version
+    tag = "v#{ source_base_version.semver }"
+    
+    # We check...
+    # 
+    # 1.  Repo is clean
+    unless git.clean?
+      raise "Can't build #{ source_base_version.level } version from " \
+            "dirty repo"
+    end
+    
+    # 2.  Tag exists
+    unless git.tags.include? tag
+      raise "Tag #{ tag } not found"
+    end
+    
+    # 3.  Tag points to current commit
+    tag_commit = Cmds.
+      new( "git rev-list -n 1 %s", chdir: path ).
+      out!( tag ).
+      chomp
+    
+    unless tag_commit == git.head
+      raise "Repo is not at tag #{ tag } commit #{ tag_commit }"
+    end
+    
+    # Ok, we just use the version in the file!
+    source_base_version
+  end
+  
+  
+  def image_version
+    lazy_var :@image_version do
+      source_version.merge \
+        build: [
+          *build_segments_for_from_image,
+          *source_version.build
+        ]
+    end
+  end
+  
+  
+  def image_name
+    lazy_var :@image_name do
+      name.merge \
+        source: nil, # NEED this!
+        tag: QB::Docker::Image::Tag.from_s(
+          image_version.docker_tag
+        )
+    end
+  end
+  
+  
+  def repo_clean?
+    lazy_var :@repo_clean do
+      git.clean?
+    end
+  end
+  
+  
+  def repo_dirty?
+    !repo_clean?
+  end
+  
+  
+  def force?
+    source_base_version.dev? && repo_dirty?
+  end
+  
+  
+  # Execution
+  # ==========================================================================
+  
+  # Entry point for the module. invoked by {#run!}.
+  # 
+  # @return [nil | {Symbol => #to_json}]
+  #   when returning:
+  #   
+  #   -   `nil`: module will successfully exit with no additional changes.
+  #       
+  #   -   `{Symbol => #to_json}`: Hash will be merged over @facts that
+  #       are returned by the module to be set in the Ansible runtime and
+  #       the module will exit successfully.
+  #       
+  def main
+    logger.info \
+      "Starting `_image`...",
+      path: path,
+      from_image: from_image.to_s,
+      build_arg: build_arg,
+      fact_name: fact_name
+      
+    
+    QB::Docker::Image.ensure_present! \
+      name: image_name,
+      pull: !image_version.dev?,
+      build: {
+        path: path,
+        build_arg: {
+          from_image: from_image.string,
+          image_version: image_version.semver,
+          **build_arg.to_options,
+        },
+      },
+      # Don't push dev images
+      push: !image_version.dev?,
+      force: force?
+    
+    response[:image] = {
+      name: image_name,
+      version: image_version,
+    }
+    
+    if fact_name
+      response.facts[fact_name] = response[:image]
+    end
+    
+    return nil
+  end # #main
+  
+end # class Image
+
+
+# /Namespace
+# ========================================================================
+
+end # module Docker
+end # module Modules
+end # module Ansible
+end # module QB