qb 0.3.25 → 0.4.0

data/lib/python/qb/ipc/stdio/__init__.py

@@ -0,0 +1,99 @@
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+import os
+import socket
+
+def path_env_var_name(name):
+    return "QB_STDIO_{}".format(name.upper())
+
+
+class Connection:
+    '''
+    Port of Ruby `QB::IPC::STDIO::Client::Connection` class.
+    '''
+    
+    def __init__(self, name, type):
+        self.name = name
+        self.type = type
+        self.path = None
+        self.socket = None
+        self.env_var_name = path_env_var_name(self.name)
+        self.connected = False
+    
+    def __str__(self):
+        attrs = ' '.join(
+            "{}={}".format(name, getattr(self, name))
+            for name in ('name', 'type', 'path', 'connected')
+        )
+        return "<qb.ipc.stdio.Connection {}>".format(attrs)
+    
+    def get_path(self):
+        if self.env_var_name in os.environ:
+            self.path = os.environ[self.env_var_name]
+        return self.path
+    
+    def connect(self, warnings=None):
+        if self.connected:
+            raise RuntimeError("{} is already connected!".format(self))
+        
+        if self.get_path() is None:
+            return False
+        
+        self.socket = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        
+        try:
+            self.socket.connect(self.path)
+        except socket.error, msg:
+            if warngings is not None:
+                warning = 'Failed to connect to QB STDOUT stream at {}: {}'
+                warning = warning.format(qb_stdout_path, msg)
+                warnings.append(warning)
+            
+            self.socket = None
+            return False
+        
+        self.connected = True
+        
+        return True
+    
+    def disconnect(self):
+        if not self.connected:
+            raise RuntimeError("{} is not connected!".format(self))
+        
+        # if self.type == 'out':
+        #     self.socket.flush()
+        
+        self.socket.close()
+        self.socket = None
+        self.connected = False
+        
+    def println(self, line):
+        if not line.endswith( u"\n" ):
+            line = line + u"\n"
+        self.socket.sendall(line.encode("utf-8"))
+        
+
+class Client:
+    def __init__(self):
+        # I don't think need STDIN or we want to deal with what it means here
+        # self.stdin  = Connection(name='in', type='in')
+        self.stdout = Connection(name='out', type='out')
+        self.stderr = Connection(name='err', type='out')
+        self.log    = Connection(name='log', type='out')
+    
+    def connections(self):
+        return [self.stdout, self.stderr, self.log]
+    
+    def connect(self, warnings=None):
+        for connection in self.connections():
+            if not connection.connected:
+                connection.connect(warnings)
+        return self
+    
+    def disconnect(sefl):
+        for connection in self.connections():
+            if connection.connected:
+                connection.disconnect()
+
+client = Client()

data/lib/python/qb/ipc/stdio/logging.py

@@ -0,0 +1,151 @@
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+import logging
+import threading
+import json
+
+import qb.ipc.stdio
+
+
+def getLogger(name, level=logging.DEBUG, io_client=qb.ipc.stdio.client):
+    logger = logging.getLogger(name)
+    if level is not None:
+        logger.setLevel(level)
+    logger.addHandler(Handler(io_client=io_client))
+    return Adapter(logger, {})
+
+
+class Adapter(logging.LoggerAdapter):
+    def process(self, msg, kwds):
+        payload = None
+        if 'payload' in kwds:
+            payload = kwds['payload']
+            del kwds['payload']
+        
+        if payload:
+            try:
+                msg = msg.format(**payload)
+            except:
+                pass
+            
+            if 'extra' not in kwds:
+                kwds['extra'] = {}
+            
+            kwds['extra']['payload'] = payload
+            
+        return msg, kwds
+
+
+class Handler(logging.Handler):
+    """
+    A handler class which writes logging records to the QB master process
+    via it's `QB::IPC::STDIO` system, if available.
+    
+    If QB's STDIO system is not available, discards the logs.
+    
+    Based on the Python stdlib's `SocketHandler`, though it ended up retaining
+    almost nothing from it since it just proxies to
+    :class:`qb.ipc.stdio.Client`, which does all the socket dirty-work.
+    
+    ..  note:
+        This class **does not** connect the :class:`qb.ipc.stdio.Client`
+        instance (which defaults to the 'global' :attr:`qb.ipc.stdio.client`
+        instance - and that's what you should use unless you're testing or
+        doing something weird).
+        
+        You need to connect the client somewhere else (before or after creating
+        loggers is fine).
+    
+    """
+    
+    
+    def __init__(self, io_client=qb.ipc.stdio.client):
+        """
+        Initializes the handler with a :class:`qb.ipc.stdio.Client`, which
+        default to the 'global' one at :attr:`qb.ipc.stdio.client`. This should
+        be fine for everything except testing.
+        
+        See note in class doc about connecting the client.
+        
+        :param io_client:   :class:`qb.ipc.stdio.Client`
+        """
+        
+        logging.Handler.__init__(self)
+        self.io_client = io_client
+        
+        
+    def send(self, string):
+        """
+        Send a string to the :attr:`io_client`.
+        """
+        
+        if not self.io_client.log.connected:
+            return
+        
+        self.io_client.log.println(string)
+    
+    
+    def get_sem_log_level(self, level):
+        """
+        Trade Python log level string for a Ruby SemnaticLogger one.
+        """
+        if level == 'DEBUG' or level == 'INFO' or level == 'ERROR':
+            return level.lower()
+        elif level == 'WARNING':
+            return 'warn'
+        elif level == 'CRITICAL':
+            return 'fatal'
+        else:
+            return 'info'
+    
+    
+    def emit(self, record):
+        """
+        Emit a record.
+        Pickles the record and writes it to the socket in binary format.
+        If there is an error with the socket, silently drop the packet.
+        If there was a problem with the socket, re-establishes the
+        socket.
+        
+        record: https://docs.python.org/2/library/logging.html#logrecord-attributes
+        """
+        
+        try:
+            self.format(record)
+            
+            struct = dict(
+                level   = self.get_sem_log_level(record.levelname),
+                name    = record.name,
+                pid     = record.process,
+                # thread  = threading.current_thread().name,
+                thread  = record.threadName,
+                message = record.message,
+                # timestamp = record.asctime,
+            )
+            
+            # The `logging` stdlib module allows you to add extra values
+            # by providing a `extra` key to the `Logger#debug` call (and
+            # friends), which it just adds to the the keys and values to the
+            # `record` object's `#__dict__` (where they better not conflict
+            # with anything else or you'll be in trouble I guess).
+            # 
+            # We look for a `payload` key in there.
+            # 
+            # Example logging with a payload:
+            # 
+            #       logger.debug("My message", extras=dict(payload=dict(x=1)))
+            # 
+            # Yeah, it sucks... TODO extend Logger or something to make it a
+            # little easier to use?
+            # 
+            if 'payload' in record.__dict__:
+                struct['payload'] = record.__dict__['payload']
+            
+            string = json.dumps(struct)
+            self.send(string)
+        except (KeyboardInterrupt, SystemExit):
+            raise
+        except:
+            raise
+            # self.handleError(record)

data/lib/qb.rb

@@ -7,6 +7,7 @@
 # Deps
 # -----------------------------------------------------------------------
 require 'nrser'
+require 'nrser/core_ext'
 
 # Project / Package
 # -----------------------------------------------------------------------
@@ -15,12 +16,13 @@ require 'qb/python'
 require 'qb/version'
 require 'qb/util'
 require 'qb/path'
+require 'qb/data'
+require 'qb/docker'
 
 
 # Refinements
 # =======================================================================
 
-using NRSER
 using NRSER::Types
 
 
@@ -78,8 +80,6 @@ require 'qb/repo'
 require 'qb/cli'
 
 require 'qb/ansible'
-# Depreciated namespace:
-require 'qb/ansible_module'
 
 require 'qb/package'
 

data/lib/qb/ansible/cmds/playbook.rb

@@ -9,7 +9,7 @@ require 'cmds'
 
 # package
 require 'qb/util/bundler'
-require 'qb/util/stdio'
+require 'qb/ipc/stdio/server'
 
 
 module QB; end
@@ -225,22 +225,13 @@ class QB::Ansible::Cmds::Playbook < ::Cmds
       before_spawn
       
       QB::Util::Bundler.with_clean_env do
-        # boot up stdio out services so that ansible modules can stream to our
-        # stdout and stderr to print stuff (including debug lines) in real-time
-        stdio_out_services = {'out' => $stdout, 'err' => $stderr}.
-          map {|name, dest|
-            QB::Util::STDIO::OutService.new(name, dest).tap { |s| s.open! }
-          }
-        
-        # and an in service so that modules can prompt for user input
-        user_in_service = QB::Util::STDIO::InService.new('in', $stdin).
-          tap { |s| s.open! }
+        # Start the STDIO server
+        stdio_server = QB::IPC::STDIO::Server.new.start!
         
         status = super *args, **kwds, &input_block
         
-        # close the stdio services
-        stdio_out_services.each {|s| s.close! }
-        user_in_service.close!
+        # ...and stop it
+        stdio_server.stop!
         
         # and return the status
         status

data/lib/qb/ansible/env.rb

@@ -48,11 +48,23 @@ class QB::Ansible::Env
   attr_reader :filter_plugins
   
   
-  # @!attribute [r] lookup_plugins
-  #   @return [Array<Pathname>]
+  # Paths to search for Ansible/Jinja2 "Lookup Plugins"
+  # 
+  # @return [Array<Pathname>]
+  # 
   attr_reader :lookup_plugins
   
   
+  # Paths to search for Ansible/Jinja2 "Test Plugins"
+  # 
+  # @return [Array<Pathname>]
+  # 
+  attr_reader :test_plugins
+  
+  
+  attr_reader :python_path
+  
+  
   # `ANSIBLE_CONFIG_<name>=<value>` ENV var values.
   # 
   # @see http://docs.ansible.com/ansible/latest/intro_configuration.html
@@ -80,11 +92,20 @@ class QB::Ansible::Env
     ]
     
     @filter_plugins = [
-      QB::ROOT.join('plugins', 'filter_plugins'),
+      QB::ROOT.join('plugins', 'filter'),
     ]
     
     @lookup_plugins = [
-      QB::ROOT.join('plugins', 'lookup_plugins'),
+      QB::ROOT.join('plugins', 'lookup'),
+    ]
+    
+    @test_plugins = [
+      QB::ROOT.join( 'plugins', 'test' ),
+    ]
+    
+    @python_path = [
+      QB::ROOT.join( 'lib', 'python' ),
+      *(ENV['PYTHONPATH'] || '').split( ':' ),
     ]
     
     @config = {}
@@ -97,7 +118,7 @@ class QB::Ansible::Env
   # @todo Document to_h method.
   # 
   # @param [type] arg_name
-  #   @todo Add name param description.
+  #   @todo Add name param description.''
   # 
   # @return [return_type]
   #   @todo Document return value.
@@ -107,7 +128,8 @@ class QB::Ansible::Env
       :roles_path,
       :library,
       :filter_plugins,
-      :lookup_plugins
+      :lookup_plugins,
+      :test_plugins,
     ].map { |name|
       value = self.send name
       
@@ -120,6 +142,14 @@ class QB::Ansible::Env
       hash[ self.class.to_var_name( "CONFIG_#{ name }" ) ] = value.to_s
     }
     
+    hash[ 'QB_AM_AUTORUN_PATH' ] = \
+      (QB::ROOT / 'load' / 'ansible' / 'module' / 'autorun.rb').to_s
+    
+    hash[ 'QB_AM_SCRIPT_PATH' ] = \
+      (QB::ROOT / 'load' / 'ansible' / 'module' / 'script.rb').to_s
+    
+    hash[ 'PYTHONPATH' ] = python_path.join ':'
+    
     hash
   end # #to_h
   

data/lib/qb/ansible/module.rb

@@ -1,12 +1,25 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
 require 'json'
 require 'pp'
 
+# Deps
+# ----------------------------------------------------------------------------
 
-# Refinements
-# =======================================================================
+require 'nrser'
+require 'nrser/props/immutable/instance_variables'
 
-using NRSER
-using NRSER::Types
+# Project / Package
+# -----------------------------------------------------------------------
+
+require 'qb/ipc/stdio/client'
 
 
 # Declarations
@@ -16,147 +29,358 @@ module QB; end
 module QB::Ansible; end
 
 
+# Refinements
+# =======================================================================
+
+using NRSER::Types
+
+
 # Definitions
 # =====================================================================
 
+module QB
+module Ansible
 class QB::Ansible::Module
   
-  # Class Variables
-  # =====================================================================
-  
-  @@arg_types = {}
+  # Sub-Tree Requirements
+  # ============================================================================
+
+  require_relative './module/response'
   
   
-  # Class Methods
-  # =====================================================================
+  # Mixins
+  # ============================================================================
   
-  def self.stringify_keys hash
-    hash.map {|k, v| [k.to_s, v]}.to_h
-  end
+  include NRSER::Props::Immutable::InstanceVariables
   
+  include NRSER::Log::Mixin
   
-  def self.arg name, type
-    @@arg_types[name.to_sym] = type
-  end
   
-  
-  # Construction
+  # Class Methods
   # =====================================================================
   
-  def initialize
-    @changed = false
-    # @input_file = ARGV[0]
-    # @input = File.read @input_file
-    # @args = JSON.load @input
-    init_set_args!
-    
-    @facts = {}
-    @warnings = []
-    
-    @qb_stdio_out = nil
-    @qb_stdio_err = nil
-    @qb_stdio_in = nil
-    
-    # debug "HERE!"
-    # debug ENV
-    
-    # if QB_STDIO_ env vars are set send stdout and stderr
-    # to those sockets to print in the parent process
-    
-    if ENV['QB_STDIO_ERR']
-      @qb_stdio_err = $stderr = UNIXSocket.new ENV['QB_STDIO_ERR']
+  module Formatters
+    class Processor < SemanticLogger::Formatters::Default
+      
+      def backtrace_to_s
+        lines = log.backtrace_to_s.lines
+        
+        if lines.length > 42
+          lines = [
+            *lines[0..21],
+            "\n# ...\n\n",
+            *lines[-21..-1]
+          ]
+        end
+        
+        lines.join
+      end
       
-      debug "Connected to QB stderr stream at #{ ENV['QB_STDIO_ERR'] } #{ @qb_stdio_err.path }."
+      # Exception
+      def exception
+        "-- Exception: #{log.exception.class}: #{log.exception.message}\n#{backtrace_to_s}" if log.exception
+      end
     end
     
-    if ENV['QB_STDIO_OUT']
-      @qb_stdio_out = $stdout = UNIXSocket.new ENV['QB_STDIO_OUT']
+    class JSON < SemanticLogger::Formatters::Raw
+      # Default JSON time format is ISO8601
+      def initialize  time_format: :iso_8601,
+                      log_host: true,
+                      log_application: true,
+                      time_key: :timestamp
+        super(
+          time_format: time_format,
+          log_host: log_host,
+          log_application: log_application,
+          time_key: time_key,
+        )
+      end
       
-      debug "Connected to QB stdout stream at #{ ENV['QB_STDIO_OUT'] }."
+      def call log, logger
+        raw = super( log, logger )
+        
+        begin
+          raw.to_json
+        rescue Exception => error
+          # SemanticLogger::Processor.instance.appender.logger.warn \
+          #   "Unable to JSON encode for logging", raw: raw
+          
+          $stderr.puts "Unable to JSON encode log"
+          $stderr.puts raw.pretty_inspect
+          
+          raise
+        end
+      end
     end
+  end
+  
+  
+  def self.setup_io!
+    # Initialize
+    $qb_stdio_client ||= QB::IPC::STDIO::Client.new.connect!
     
-    if ENV['QB_STDIO_IN']
-      @qb_stdio_in = UNIXSocket.new ENV['QB_STDIO_IN']
+    if $qb_stdio_client.log.connected? && NRSER::Log.appender.nil?
+      # SemanticLogger::Processor.logger = \
       
-      debug "Connected to QB stdin stream at #{ ENV['QB_STDIO_IN'] }."
+      SemanticLogger::Processor.instance.appender.logger = \
+        SemanticLogger::Appender::File.new(
+          io: $stderr,
+          level: :warn,
+          formatter: Formatters::Processor.new,
+        )
+      
+      NRSER::Log.setup! \
+        application: 'qb',
+        sync: true,
+        dest: {
+          io: $qb_stdio_client.log.socket,
+          formatter: Formatters::JSON.new,
+        }
     end
     
-    @@arg_types.each {|key, type|
-      var_name = "@#{ key.to_s }"
+  end # .setup_logging
+  
+  
+  # Wrap a "run" call with error handling.
+  # 
+  # @private
+  # 
+  # @param [Proc<() => RESULT] &block
+  # 
+  # @return [RESULT]
+  #   On success, returns the result of `&block`.
+  # 
+  # @raise [SystemExit]
+  #   Any exception raised in `&block` is logged at `fatal` level, then
+  #   `exit false` is called, raising a {SystemExit} error.
+  #   
+  #   The only exception: if `&block` raises a {SystemExit} error, that error
+  #   is simply re-raised without any logging. This should allow nesting
+  #   {.handle_run_error} calls, since the first `rescue` will log any
+  #   error and raise {SystemExit}, which will then simply be bubbled-up
+  #   by {.handle_run_error} wrappers further up the call chain.
+  # 
+  def self.handle_run_error &block
+    begin
+      block.call
+    rescue SystemExit => error
+      # Bubble {SystemExit} up to exit normally
+      raise
+    rescue Exception => error
+      # Everything else is unexpected, and needs to be logged in a way that's
+      # more useful than the JSON-ified crap Ansible would normally print
       
-      unless instance_variable_get(var_name).nil?
-        raise ArgumentError.new NRSER.squish <<-END
-          an instance variable named #{ var_name } exists
-          with value #{ instance_variable_get(var_name).inspect }
-        END
+      # If we don't have a logger setup, log to real `STDERR` so we get
+      # *something* back in the Ansible output, even if it's JSON mess
+      if NRSER::Log.appender.nil?
+        NRSER::Log.setup! application: 'qb', dest: STDERR
       end
       
-      value = type.check( @args[key.to_s] ) do |type:, value:|
-        all_args = @args
-        
-        binding.erb <<-END
-          Value
-          
-              <%= value.pretty_inspect %>
-          
-          for argument <%= key.inspect %> is not valid for type
-          
-              <%= type %>
-          
-          Arguments:
-          
-              <%= all_args.pretty_inspect %>
-          
-        END
-      end
+      # Log it out
+      logger.fatal error
       
-      instance_variable_set var_name, value
-    }
-  end
+      # And GTFO
+      exit false
+    end
+  end # .handle_run_error
+  
+  private_class_method :handle_run_error
+  
+  
+  # Is the module being run from Ansible via it's "WANT_JSON" mode?
+  # 
+  # Tests if `argv` is a single string argument that is a file path.
+  # 
+  # @see http://docs.ansible.com/ansible/latest/dev_guide/developing_program_flow_modules.html#non-native-want-json-modules
+  # 
+  # @param [Array<String>] argv
+  #   The CLI argument strings.
+  # 
+  # @return [Boolean]
+  #   `true` if `argv` looks like it came from Ansible's "WANT_JSON" mode.
+  # 
+  def self.WANT_JSON_mode? argv = ARGV
+    ARGV.length == 1 && File.file?( ARGV[0] )
+  end # .WANT_JSON_mode?
   
   
-  protected
-  # ========================================================================
+  # Load args from a file in JSON format.
+  # 
+  # @param [String | Pathname] file_path
+  #   File path to load from.
+  # 
+  # @return [Array<(Hash, Hash?)>]
+  #   Tuple of:
+  #   
+  #   1.  `args:`
+  #       -   `Hash<String, *>`
+  #   2.  `args_source:`
+  #       -   `nil | Hash{ type: :file, path: String, contents: String }`
+  # 
+  def self.load_args_from_JSON_file file_path
+    file_contents = File.read file_path
+
+    args = JSON.load( file_contents ).with_indifferent_access
+
+    t.hash_( keys: t.str ).check( args ) do |type:, value:|
+      binding.erb <<~END
+        JSON file contents must load into a `Hash<String, *>`
+        
+        Loaded value (of class <%= value.class %>):
+        
+            <%= value.pretty_inspect %>
+        
+      END
+    end
     
-  def init_set_args!
-    if ARGV.length == 1 && File.file?( ARGV[0] )
-      # "Standard" Ansible-invoked mode, where the args written in JSON format
-      # to a file and the path is provided as the only CLI argument
-      # 
-      @input_file = ARGV[0]
-      @input = File.read @input_file
-      @args = JSON.load @input
-      
+    [ args, { type: :file,
+              path: file_path.to_s,
+              contents: file_contents,
+            } ]
+  end
+  
+  
+  # Load the raw arguments.
+  # 
+  def self.load_args
+    if WANT_JSON_mode?
+      load_args_from_JSON_file ARGV[0]
     else
-      # QB-specific "fiddle-mode": if we don't have a single valid file path
-      # as CLI arguments, parse the CLI options we have in the common
-      # 
-      #     `--name=value`
-      # 
-      # format into the `@args` hash.
-      # 
-      # This lets us run the module file **directly** from the terminal, which
-      # is just a quick and dirty way of flushing things out.
-      # 
-      @fiddle_mode = true
-      @args = {}
+      load_args_from_CLI_options
+    end
+  end
+  
+  
+  # Run the module!
+  # 
+  # @return (see #run!)
+  # 
+  def self.run!
+    handle_run_error do
+      setup_io!
       
-      ARGV.each do |arg|
-        if arg.start_with? '--'
-          key, value = arg[2..-1].split( '=', 2 )
-          
-          @args[key] = begin
-            JSON.load value
-          rescue
-            value
-          end
-        end
-      end
+      args, args_source = load_args
+      run_from_args! args, args_source: args_source
     end
-  end # #init_set_args!
+  end # .run!
+  
+  
+  # Create and run an instance and populate it's args by loading JSON from a
+  # file path.
+  # 
+  # Used to run via Ansible's "WANT_JSON" mode.
+  # 
+  # @see http://docs.ansible.com/ansible/latest/dev_guide/developing_program_flow_modules.html#non-native-want-json-modules
+  # 
+  # @param [String | Pathname] file_path
+  #   Path to the JSON file containing the args.
+  # 
+  # @return (see #run!)
+  # 
+  def self.run_from_JSON_args_file! file_path
+    file_contents = File.read file_path
     
-  # end protected
-  public
+    args = JSON.load file_contents
+    
+    t.hash_( keys: t.str ).check( args ) do |type:, value:|
+      binding.erb <<~END
+        JSON file contents must load into a `Hash<String, *>`
+        
+        Loaded value (of class <%= value.class %>):
+        
+            <%= value.pretty_inspect %>
+        
+      END
+    end
+    
+    run_from_args!  args,
+                    args_source: {
+                      type: :file,
+                      path: file_path,
+                      contents: file_contents,
+                    }
+  end # .run_from_JSON_args_file!
+  
+  
+  # Run from a hash-like of argument names mapped to values, with optional
+  # info about the source of the arguments.
+  # 
+  # @param [#each_pair] args
+  #   Argument names (String or Symbol) mapped to their value data.
+  # 
+  # @return (see #run!)
+  # 
+  def self.run_from_args! args, args_source: nil
+    logger.trace "Running from args",
+      args: args,
+      args_source: args_source
+    
+    instance = self.from_data args
+    instance.args_source = args_source
+    instance.args = args
+    instance.run!
+  end # .run_from_args!
+  
+  
+  # @todo Document arg method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.arg *args, **opts
+    name, opts = t.match args.length,
+      # Normal {.prop} form
+      1, ->( _ ){ [ args[0], opts ] },
+      
+      # Backwards-compatible form
+      2, ->( _ ){ [ args[0], opts.merge( type: args[1] ) ]  }
+    
+    prop name, **opts
+  end # .arg
+  
+  
+  # Attributes
+  # ==========================================================================
+  
+  # Optional information on the source of the arguments.
+  # 
+  # @return [nil | Hash<Symbol, Object>]
+  #     
+  attr_accessor :args_source
+  
+  
+  # The raw parsed arguments. Used for backwards-compatibility with how
+  # {QB::Ansible::Module} used to work before {NRSER::Props} and {#arg}.
+  # 
+  # @todo
+  #   May want to get rid of this once using props is totally flushed out.
+  #   
+  #   It should at least be deal with in the constructor somehow so this
+  #   can be changed to an `attr_reader`.
+  # 
+  # @return [Hash<String, VALUE>]
+  #     
+  attr_accessor :args
+  
+  
+  # The response that will be returned to Ansible (JSON-encoded and written
+  # to `STDOUT`).
+  # 
+  # @return [QB::Ansible::Module::Response]
+  #     
+  attr_reader :response
+  
+  
+  # Construction
+  # =====================================================================
+  
+  def initialize values = {}
+    initialize_props values
+    @response = QB::Ansible::Module::Response.new
+  end
   
   
   # Instance Methods
@@ -176,7 +400,7 @@ class QB::Ansible::Module
   # listen to, and we provide those file paths via environment variables
   # so modules can pick those up and interact with those streams, allowing
   # them to act like regular scripts inside Ansible-world (see
-  # QB::Util::STDIO for details and implementation).
+  # QB::IPC::STDIO for details and implementation).
   # 
   # We use those channels if present to provide logging mechanisms.
   # 
@@ -187,37 +411,54 @@ class QB::Ansible::Module
   # @param args see QB.debug
   # 
   def debug *args
-    if @qb_stdio_err
-      header = "<QB::Ansible::Module #{ self.class.name }>"
-      
-      if args[0].is_a? String
-        header += " " + args.shift
-      end
-      
-      QB.debug header, *args
-    end
+    logger.debug payload: args
   end
   
+  
+  # Old logging function - use `#logger.info` instead.
+  # 
+  # @deprecated
+  # 
   def info msg
-    if @qb_stdio_err
-      $stderr.puts msg
-    end
+    logger.info msg
   end
   
-  # Append a warning message to @warnings.
+  
+  # Append a warning message to the {#response}'s {Response#warnings}
+  # array and log it.
+  # 
+  # @todo
+  #   Should be incorporated into {#logger}? Seems like it would need one of:
+  #   
+  #   1.  `on_...` hooks, like `Logger#on_warn`, etc.
+  #       
+  #       This might be nice but I'd rather hold off on throwing more shit
+  #       into {NRSER::Log::Logger} for the time being if possible.
+  #       
+  #   2.  Adding a custom appender when we run a module that has a ref to
+  #       the module instance and so it's {Response}.
+  #       
+  # 
+  # @param [String] msg
+  #   Non-empty string.
+  # 
+  # @return [nil]
+  # 
   def warn msg
-    @warnings << msg
+    logger.warn msg
+    response.warnings << msg
+    nil
   end
   
   
-  def run
+  def run!
     result = main
     
     case result
     when nil
       # pass
     when Hash
-      @facts.merge! result
+      response.facts.merge! result
     else
       raise "result of #main should be nil or Hash, found #{ result.inspect }"
     end
@@ -225,40 +466,43 @@ class QB::Ansible::Module
     done
   end
   
+  
   def changed! facts = {}
-    @changed = true
-    @facts.merge! facts
+    response.changed = true
+    
+    unless facts.empty?
+      response.facts.merge! facts
+    end
+    
     done
   end
   
+  
   def done
-    exit_json changed: @changed,
-              ansible_facts: self.class.stringify_keys(@facts),
-              warnings: @warnings
+    exit_json response.to_data( add_class: false ).compact
   end
   
+  
   def exit_json hash
     # print JSON response to process' actual STDOUT (instead of $stdout,
     # which may be pointing to the qb parent process)
-    STDOUT.print JSON.pretty_generate(self.class.stringify_keys(hash))
-    
-    [
-      [:stdin, @qb_stdio_in],
-      [:stdout, @qb_stdio_out],
-      [:stderr, @qb_stdio_err],
-    ].each do |name, socket|
-      if socket
-        debug "Flushing socket #{ name }."
-        socket.flush
-        debug "Closing #{ name } socket at #{ socket.path.to_s }."
-        socket.close
-      end
-    end
+    STDOUT.print JSON.pretty_generate( hash.stringify_keys )
     
-    exit 0
+    exit true
   end
   
-  def fail msg
-    exit_json failed: true, msg: msg, warnings: @warnings
+  
+  def fail msg, **values
+    fail_response = QB::Ansible::Module::Response.new \
+      failed: true,
+      msg: msg.to_s,
+      warnings: response.warnings,
+      depreciations: response.depreciations
+    
+    STDOUT.print \
+      JSON.pretty_generate( fail_response.to_data( add_class: false ).compact )
+    
+    exit false
   end
-end # class QB::Ansible::Module
+  
+end; end; end # class QB::Ansible::Module