qb 0.3.25 → 0.4.0

data/lib/qb/docker/image/tag.rb

@@ -0,0 +1,113 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+require 'qb/data'
+
+require 'qb/package/version'
+
+
+# Refinements
+# =======================================================================
+
+require 'nrser/refinements/types'
+using NRSER::Types
+
+
+
+# Namespace
+# ============================================================================
+
+module  QB
+module  Docker
+class   Image < QB::Data::Immutable
+
+# Definitions
+# =======================================================================
+
+# A Docker image tag, with support for paring versions.
+# 
+class Tag   < QB::Data::Immutable
+  
+  include NRSER::Log::Mixin
+  
+  
+  # @todo Document from_s method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.from_s string
+    new source: string
+  end # .from_s
+  
+  
+  # @!group Props
+  # ==========================================================================
+  
+  prop  :string,
+        type: t.non_empty_str,
+        source: :to_s
+  
+  prop  :source,
+        type: t.non_empty_str?,
+        default: nil
+  
+  prop  :version,
+        type: t.maybe( QB::Package::Version ),
+        default: ->( source: ) {
+          begin
+            QB::Package::Version::From.docker_tag source
+          rescue ArgumentError => error
+            nil
+          rescue TypeError => error
+            nil
+          end
+        }
+  
+  # @!endgroup Props # *******************************************************
+  
+  
+  invariant t.attrs( source:  ~t.nil ) |
+            t.attrs( version: ~t.nil )
+  
+  # Instance Methods
+  # ======================================================================
+  
+  def to_s
+    if version
+      version.docker_tag
+    else
+      source
+    end
+  end
+  
+  
+  def dirty?
+    version && version.build_dirty?
+  end
+  
+  
+end # class Tag
+
+
+# /Namespace
+# ============================================================================
+
+end # module  QB
+end # module  Docker
+end # class   Image < QB::Data::Immutable

data/lib/qb/errors.rb

@@ -1,16 +1,30 @@
+# Requirements
+# ========================================================================
+
+# Deps
+# ------------------------------------------------------------------------
+
+require 'nrser/errors/nicer_error'
+
+
+# Definitions
+# ========================================================================
+
 module QB
   # Base class for QB errors.
-  class Error < StandardError; end
+  class Error < StandardError
+    include NRSER::NicerError
+  end
   
   
   # State Errors
   # =====================================================================
   # 
-  # Raised when something - a role, the file system, etc. - is in a state 
+  # Raised when something - a role, the file system, etc. - is in a state
   # that we can't deal with.
   # 
   
-  # Raised when something is in a bad state and no more specific error 
+  # Raised when something is in a bad state and no more specific error
   # subclass applies.
   class StateError < Error; end
   

data/lib/qb/execution.rb

@@ -0,0 +1,83 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Need mutable props mixin
+require 'nrser/props/immutable/instance_variables'
+
+# Need {Time#iso8601_for_idiots}
+require 'nrser/core_ext/time'
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+
+# Declarations
+# =======================================================================
+
+
+# Definitions
+# =======================================================================
+
+
+# An object that encapsulates an execution of the QB program.
+# 
+class QB::Execution
+  
+  # Constants
+  # ========================================================================
+  
+  
+  # Mixins
+  # ========================================================================
+  
+  include NRSER::Props::Mutable::InstanceVariables
+  
+  
+  # Class Methods
+  # ========================================================================
+  
+  
+  # Props
+  # ========================================================================
+  
+  # @!attribute [r]
+  prop  :started_at,
+        type: Time,
+        writer: false,
+        default: -> { Time.current }
+  
+  prop  :pid,
+        type: Fixnum,
+        source: -> { Process.pid }
+  
+  prop  :id,
+        type: String,
+        source: -> { "#{ self.started_at }-pid_#{ self.pid }" }
+  
+  # Construction
+  # ========================================================================
+  
+  # Instantiate a new `QB::Execution`.
+  def initialize values = {}
+    initialize_props values
+  end # #initialize
+  
+  
+  # Instance Methods
+  # ========================================================================
+  
+  
+end # class QB::Execution

data/lib/qb/ipc.rb

@@ -0,0 +1,48 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+
+# Declarations
+# =======================================================================
+
+
+# Definitions
+# =======================================================================
+
+# Module for handling inter-process communication (IPC), which is needed
+# for child processes - Ansible processes and Ansible module processes -
+# to interact with the
+# 
+module QB::IPC
+  
+  
+  # @todo Document is_master_process! method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.is_master_process!
+    
+  end # .is_master_process!
+  
+  
+end # module QB::IPC

data/lib/qb/ipc/stdio.rb

@@ -0,0 +1,32 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Declarations
+# =======================================================================
+
+module QB::IPC; end
+
+# Definitions
+# =======================================================================
+
+# Simple & shitty inter-process communication (IPC) system for passing
+# standard-IO lines, intended and used to move them from Ansible module
+# child processes up to the QB master process for display.
+# 
+module QB::IPC::STDIO
+  
+  # Get the ENV var name that will hold the socket path for a stream name -
+  # `:in`, `:out` or `:err` - when passed from parent to child processes.
+  # 
+  # @example
+  #   path_env_var_name :in
+  #   # => "QB_STDIO_IN"
+  # 
+  # @param [Symbol] name
+  # @return [String]
+  # 
+  def self.path_env_var_name name
+    "QB_STDIO_#{ name.to_s.upcase }"
+  end # .env_key
+  
+end # module QB::IPC::STDIO

data/lib/qb/ipc/stdio/client.rb

@@ -0,0 +1,267 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Need {UNIXSocket}
+require 'socket'
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Need logging
+require 'nrser'
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+# Need {QB::IPC::STDIO.path_env_var_name}
+require 'qb/ipc/stdio'
+
+
+# Definitions
+# =======================================================================
+
+# @todo document QB::IPC::STDIO::Client class.
+class QB::IPC::STDIO::Client
+  
+  # Mixins
+  # ========================================================================
+  
+  # Add {.logger} and {#logger} methods
+  include NRSER::Log::Mixin
+  
+  
+  # Classes
+  # ============================================================================
+  
+  # @todo document Connection class.
+  class Connection
+    
+    # Mixins
+    # ========================================================================
+    
+    # Add {.logger} and {#logger} methods
+    include NRSER::Log::Mixin
+    
+    
+    # Attributes
+    # ========================================================================
+    
+    # TODO document `name` attribute.
+    # 
+    # @return [Symbol]
+    #     
+    attr_reader :name
+    
+    
+    # TODO document `type` attribute.
+    # 
+    # @return [:in | :out]
+    #     
+    attr_reader :type
+    
+    
+    # TODO document `path` attribute.
+    # 
+    # @return [Pathname?]
+    #     
+    attr_reader :path
+    
+    
+    # TODO document `socket` attribute.
+    # 
+    # @return [UNIXSocket?]
+    #     
+    attr_reader :socket
+    
+    
+    # TODO document `global_original` attribute.
+    # 
+    # @return [attr_type]
+    #     
+    attr_reader :global_original
+    
+    
+    # TODO document `env_var_name` attribute.
+    # 
+    # @return [String]
+    #     
+    attr_reader :env_var_name
+    
+    
+    # Construction
+    # ========================================================================
+    
+    # Instantiate a new `Connection`.
+    def initialize name:, type:
+      @name = name
+      @type = type
+      @global_original = nil
+      @path = nil
+      @socket = nil
+      @env_var_name = QB::IPC::STDIO.path_env_var_name name
+    end # #initialize
+    
+    
+    # Instance Methods
+    # ========================================================================
+    
+    def connected?
+      !!socket
+    end
+    
+    
+    def connect!
+      if connected?
+        raise "#{ inspect } is already connected!"
+      end
+      
+      if get_path!
+        @global_original = global_get
+        @socket = UNIXSocket.new path.to_s
+        global_set! socket
+      end
+    end
+    
+    
+    def disconnect!
+      return unless connected?
+      
+      logger.debug "Disconnecting...",
+        name: name,
+        socket: socket,
+        global_original: global_original
+      
+      # Restore the original global and `nil` it out (if we have one)
+      if global_original
+        global_set! global_original
+        @global_original = nil
+      end
+      
+      # Flush the socket if it's an out-bound
+      socket.flush if type == :out
+      
+      # And close and `nil` it
+      socket.close
+      @socket = nil
+    end
+    
+    
+    protected
+    # ========================================================================
+      
+      # Get the socket path from the ENV and set `@path` to it (which may be
+      # `nil` if we don't find anything).
+      # 
+      # @return [Pathname?]
+      # 
+      def get_path!
+        @path = ENV[ env_var_name ]
+        @path = path.to_pn if path
+        path
+      end
+      
+      
+      # Get the IO global (`$stdin`, `$stdout`, `$stderr`) if {#name} lines
+      # up for one of those.
+      # 
+      # @return [IO?]
+      # 
+      def global_get
+        case name
+        when :in
+          $stdin
+        when :out
+          $stdout
+        when :err
+          $stderr
+        end
+      end # #global_get
+      
+      
+      # Set the IO global (`$stdin`, `$stdout`, `$stderr`) to `value` if
+      # {#name} lines up for one of those.
+      # 
+      # @param [IO] value
+      # @return [void]
+      # 
+      def global_set! value
+        case name
+        when :in
+          $stdin = value
+        when :out
+          $stdout = value
+        when :err
+          $stderr = value
+        end
+      end
+      
+    public # end protected ***************************************************
+    
+  end # class Connection
+  
+  
+  # Class Methods
+  # ========================================================================
+  
+  
+  # Attributes
+  # ========================================================================
+  
+  # @return [Connection]
+  attr_reader :stdin
+  
+  # @return [Connection]
+  attr_reader :stdout
+  
+  # @return [Connection]
+  attr_reader :stderr
+  
+  # @return [Connection]
+  attr_reader :log
+  
+  
+  # Construction
+  # ========================================================================
+  
+  # Instantiate a new `QB::IPC::STDIO::Client`.
+  def initialize
+    @stdin  = Connection.new name: :in, type: :in
+    @stdout = Connection.new name: :out, type: :out
+    @stderr = Connection.new name: :err, type: :out
+    @log    = Connection.new name: :log, type: :out
+  end # #initialize
+  
+  
+  # Instance Methods
+  # ========================================================================
+  
+  # @return [Array<Connection>]
+  #   The three {Connection} instances.
+  def connections
+    [ @stdin, @stdout, @stderr, @log ]
+  end # #connections
+  
+  
+  # Attempt to connect the three streams.
+  #
+  # @return [self]
+  # 
+  def connect!
+    connections.each &:connect!
+    self
+  end # #start!
+  
+  
+  
+  def disconnect!
+    connections.each &:disconnect!
+    self
+  end
+  
+end # class QB::IPC::STDIO::Client