openbolt 5.6.0 → 9.0.0

data/lib/bolt/transport/choria/command_builders.rb

@@ -23,6 +23,29 @@ module Bolt
         end
       end
 
+      # Build the command that creates a tmpdir. On POSIX it is mkdir -m 700
+      # without -p, so it fails when the directory the tmpdir goes into
+      # doesn't exist, like it does with the SSH transport. The Windows
+      # command leaves the tmpdir open only to the account the agent runs as
+      # and to the Administrators group, which the directories and files in
+      # it inherit, and it fails when it cannot set that.
+      #
+      # @param target [Bolt::Target] Used for platform detection
+      # @param tmpdir [String] Absolute path to the tmpdir on the remote node
+      # @return [String] Shell command
+      def make_tmpdir_command(target, tmpdir)
+        return "mkdir -m 700 #{Shellwords.shellescape(tmpdir)}" unless windows_target?(target)
+
+        "$ErrorActionPreference = 'Stop'; $dir = '#{ps_escape(tmpdir)}'; " \
+          '$null = New-Item -ItemType Directory -Force -Path $dir; ' \
+          '$acl = Get-Acl -LiteralPath $dir; $acl.SetAccessRuleProtection($true, $false); ' \
+          'foreach ($sid in @([Security.Principal.WindowsIdentity]::GetCurrent().User, ' \
+          "(New-Object Security.Principal.SecurityIdentifier('S-1-5-32-544')))) { " \
+          '$acl.AddAccessRule((New-Object Security.AccessControl.FileSystemAccessRule($sid, ' \
+          "'FullControl', 'ContainerInherit, ObjectInherit', 'None', 'Allow'))) }; " \
+          'Set-Acl -LiteralPath $dir -AclObject $acl'
+      end
+
       # Build a chmod +x command. Returns nil on Windows (not needed).
       #
       # @param target [Bolt::Target] Used for platform detection
@@ -43,19 +66,88 @@ module Bolt
           "rm -rf #{Shellwords.shellescape(path)}"
       end
 
+      # Build a command that removes the shell agent's job directories for
+      # the given handles, under the agent's default state path. A handle
+      # without a directory on the target is skipped, so 1 command can
+      # contain the handles of every target it goes to. On Windows a failed
+      # removal stops the command, so it exits 1 like a failed rm does.
+      #
+      # @param target [Bolt::Target] Used for platform detection
+      # @param handles [Array<String>] Job handles, each checked to be a UUID
+      # @return [String] Shell command
+      def remove_job_dirs_command(target, handles)
+        if windows_target?(target)
+          paths = handles.map { |handle| "'C:/ProgramData/mcollective-shell/#{handle}'" }.join(', ')
+          "foreach ($path in @(#{paths})) { if (Test-Path -LiteralPath $path) { " \
+            'Remove-Item -LiteralPath $path -Recurse -Force -ErrorAction Stop } }'
+        else
+          "rm -rf #{handles.map { |handle| "/var/run/mcollective-shell/#{handle}" }.join(' ')}"
+        end
+      end
+
       # Build a command that writes base64-encoded content to a file
       # after decoding the content. Requires base64 CLI on POSIX targets.
       #
       # @param target [Bolt::Target] Used for platform detection
       # @param content_b64 [String] Base64-encoded file content
       # @param dest [String] Absolute destination path on the remote node
+      # @param append [Boolean] Whether to add the content to the end of the file instead of replacing it
       # @return [String] Shell command
-      def upload_file_command(target, content_b64, dest)
-        if windows_target?(target)
+      def upload_file_command(target, content_b64, dest, append: false)
+        if windows_target?(target) && append
+          "$bytes = [Convert]::FromBase64String('#{content_b64}'); " \
+            "$stream = [IO.File]::Open('#{ps_escape(dest)}', 'Append', 'Write'); " \
+            'try { $stream.Write($bytes, 0, $bytes.Length) } finally { $stream.Close() }'
+        elsif windows_target?(target)
           "[IO.File]::WriteAllBytes('#{ps_escape(dest)}', " \
             "[Convert]::FromBase64String('#{content_b64}'))"
         else
-          "printf '%s' #{Shellwords.shellescape(content_b64)} | base64 -d > #{Shellwords.shellescape(dest)}"
+          "printf '%s' #{Shellwords.shellescape(content_b64)} | base64 -d #{append ? '>>' : '>'} #{Shellwords.shellescape(dest)}"
+        end
+      end
+
+      # The path of the run file in a tmpdir. A script or task command can
+      # contain arguments, env var values and task parameters, so it goes to
+      # the nodes in this file instead of as the shell agent's start command,
+      # which the agent keeps on disk and returns in shell.list replies.
+      #
+      # @param target [Bolt::Target] Used for platform detection
+      # @param tmpdir [String] Absolute path to the tmpdir on the remote node
+      # @return [String] Absolute path to the run file
+      def run_file_path(target, tmpdir)
+        join_path(target, tmpdir, windows_target?(target) ? 'bolt_run.ps1' : 'bolt_run.sh')
+      end
+
+      # Build the content of a run file. On POSIX it removes itself as soon
+      # as sh starts reading it, which keeps reading from the open file. A
+      # single command then replaces sh through exec, so shell.kill reaches
+      # it. A pipeline doesn't, since exec would run printf as its own
+      # process with the task input in its arguments. On Windows the content
+      # runs in a script block, which would hide a failing last command from
+      # powershell.exe, so it exits 1 then, as the command itself would.
+      #
+      # @param target [Bolt::Target] Used for platform detection
+      # @param command [String] The command the run file contains
+      # @param pipeline [Boolean] Whether the command is a pipeline, default is false
+      # @return [String] File content
+      def run_file_content(target, command, pipeline: false)
+        return "#{command}\nif (-not $?) { exit 1 }" if windows_target?(target)
+
+        "rm -f -- \"$0\"\n#{'exec ' unless pipeline}#{command}\n"
+      end
+
+      # Build the start command that runs a run file. On Windows it reads the
+      # file and removes it before running what was in it.
+      #
+      # @param target [Bolt::Target] Used for platform detection
+      # @param path [String] Absolute path to the run file
+      # @return [String] Shell command
+      def run_file_command(target, path)
+        if windows_target?(target)
+          "$boltRunFile = '#{ps_escape(path)}'; $boltRunScript = [IO.File]::ReadAllText($boltRunFile); " \
+            'Remove-Item -LiteralPath $boltRunFile -Force; & ([ScriptBlock]::Create($boltRunScript))'
+        else
+          "sh #{Shellwords.shellescape(path)}"
         end
       end
 
@@ -64,46 +156,58 @@ module Bolt
       #
       # @param target [Bolt::Target] Used for platform detection
       # @param command [String] The command to prepend env vars to
-      # @param env_vars [Hash{String => String}, nil] Variable names to values
+      # @param env_vars [Hash{String => Object}, nil] Variable names to values, which become strings
       # @param context [String] Description for error messages (e.g., 'task argument')
       # @return [String] Command with env vars prepended
       def prepend_env_vars(target, command, env_vars, context)
         return command unless env_vars&.any?
 
-        env_vars.each_key { |key| validate_env_key!(key, context) }
-
         if windows_target?(target)
-          set_stmts = env_vars.map { |key, val| "$env:#{key} = '#{ps_escape(val)}'" }
-          "#{set_stmts.join('; ')}; & #{command}"
+          "#{powershell_env_statements(env_vars, context)}; #{command}"
         else
+          env_vars.each_key { |key| validate_env_key!(key, context) }
           env_str = env_vars.map { |key, val| "#{key}=#{Shellwords.shellescape(val)}" }.join(' ')
           "/usr/bin/env #{env_str} #{command}"
         end
       end
 
+      # Build the PowerShell statements that set environment variables,
+      # after validating each name.
+      #
+      # @param env_vars [Hash{String => Object}] Variable names to values, which become strings
+      # @param context [String] Description for error messages (e.g., 'task argument')
+      # @return [String] The statements joined with '; '
+      def powershell_env_statements(env_vars, context)
+        env_vars.each_key { |key| validate_env_key!(key, context) }
+        env_vars.map { |key, val| "$env:#{key} = '#{ps_escape(val.to_s)}'" }.join('; ')
+      end
+
       # Build a command that pipes data to another command via stdin.
       #
       # @param target [Bolt::Target] Used for platform detection
       # @param data [String] Data to pipe (typically JSON task arguments)
-      # @param command [String] The command to receive stdin
+      # @param command [String] The command to receive stdin, which on Windows must
+      #   be a PowerShell command such as one from executable_command
       # @return [String] Shell command with stdin piping
       def stdin_pipe_command(target, data, command)
         if windows_target?(target)
           # Use a here-string (@'...'@) to avoid escaping issues with
-          # large JSON payloads. Content between @' and '@ is literal.
-          "@'\n#{data}\n'@ | & #{command}"
+          # large JSON payloads. Its content is literal as long as no line
+          # starts with a single quote character and @, which single-line
+          # JSON never does.
+          "@'\n#{data}\n'@ | #{command}"
         else
           "printf '%s' #{Shellwords.shellescape(data)} | #{command}"
         end
       end
 
-      # Escape a string for use as a shell argument on the target platform.
+      # Escape a value for use as a shell argument on the target platform.
       #
       # @param target [Bolt::Target] Used for platform detection
-      # @param str [String] The string to escape
+      # @param str [Object] The value to escape, turned into a string first
       # @return [String] Escaped string (single-quoted on Windows, sh-escaped on POSIX)
       def escape_arg(target, str)
-        windows_target?(target) ? "'#{ps_escape(str)}'" : Shellwords.shellescape(str)
+        windows_target?(target) ? "'#{ps_escape(str.to_s)}'" : Shellwords.shellescape(str)
       end
 
       # Join path segments using the target platform's separator.
@@ -132,9 +236,22 @@ module Bolt
       # Escape single quotes for use inside PowerShell single-quoted strings.
       #
       # @param str [String] String to escape
-      # @return [String] String with single quotes doubled
+      # @return [String] String with every single quote character doubled
       def ps_escape(str)
-        str.gsub("'", "''")
+        Bolt::Util.escape_powershell_single_quotes(str)
+      end
+
+      # Build the command that runs an executable, through the interpreter
+      # when one is given. On Windows it starts with the call operator,
+      # since PowerShell treats a quoted path as a string.
+      #
+      # @param target [Bolt::Target] Used for platform detection
+      # @param path [String] Absolute path to the executable on the remote node
+      # @param interpreter [String, Array<String>, nil] Interpreter command, or nil to run the file directly
+      # @return [String] Shell command
+      def executable_command(target, path, interpreter)
+        command = (Array(interpreter) + [path]).map { |part| escape_arg(target, part) }.join(' ')
+        windows_target?(target) ? "& #{command}" : command
       end
 
       # Build the full command string for task execution via the shell agent,
@@ -144,14 +261,19 @@ module Bolt
       # @param target [Bolt::Target] Target (used for platform detection)
       # @param remote_task_path [String] Absolute path to the task executable on the remote node
       # @param arguments [Hash] Task parameter names to values
-      # @param input_method [String] How to pass arguments: 'stdin', 'environment', or 'both'
+      # @param input_method [String] How to pass arguments: 'stdin', 'environment', 'both', or 'powershell'
       # @param interpreter_options [Hash{String => String}] File extension to interpreter path mapping
       # @return [String] The fully constructed shell command
       def build_task_command(target, remote_task_path, arguments, input_method, interpreter_options)
+        if input_method == 'powershell' && windows_target?(target) && File.extname(remote_task_path).casecmp?('.ps1')
+          # The arguments become the script's named parameters, like they
+          # do with the WinRM transport
+          return Bolt::Shell::Powershell::Snippets.json_functions +
+                 Bolt::Shell::Powershell::Snippets.ps_task(remote_task_path, arguments)
+        end
+
         interpreter = select_interpreter(remote_task_path, interpreter_options)
-        cmd = interpreter ?
-          "#{Array(interpreter).map { |part| escape_arg(target, part) }.join(' ')} #{escape_arg(target, remote_task_path)}" :
-          escape_arg(target, remote_task_path)
+        cmd = executable_command(target, remote_task_path, interpreter)
 
         needs_env = Bolt::Task::ENVIRONMENT_METHODS.include?(input_method)
         needs_stdin = Bolt::Task::STDIN_METHODS.include?(input_method)
@@ -161,11 +283,9 @@ module Bolt
           # requires a script block. Pipeline data doesn't automatically
           # flow through a script block to inner commands, so we
           # explicitly forward $input via a pipe.
-          env_params = envify_params(arguments)
-          env_params.each_key { |key| validate_env_key!(key, 'task argument') }
-          set_stmts = env_params.map { |key, val| "$env:#{key} = '#{ps_escape(val)}'" }
+          env_statements = powershell_env_statements(envify_params(arguments), 'task argument')
           cmd = stdin_pipe_command(target, arguments.to_json,
-                                   "{ #{set_stmts.join('; ')}; $input | & #{cmd} }")
+                                   "& { #{env_statements}; $input | #{cmd} }")
         else
           if needs_env
             cmd = prepend_env_vars(target, cmd, envify_params(arguments), 'task argument')

data/lib/bolt/transport/choria/file_transfer.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Bolt
+  module Transport
+    class Choria
+      # Upload and download through the file_transfer agent. The transfers
+      # themselves are done by the client library the agent's Puppet module
+      # installs on the controller, MCollective::Util::FileTransfer. This file
+      # maps targets, options and results onto it.
+
+      # The library's outcome kinds as this transport's error kinds. A kind
+      # a later library adds is reported as a transfer failure.
+      FILE_TRANSFER_ERROR_KINDS = {
+        no_response: 'bolt/choria-no-response',
+        rpc_error: 'bolt/choria-rpc-error',
+        rpc_failed: 'bolt/choria-rpc-failed',
+        transfer_failed: 'bolt/choria-file-transfer-failed',
+        payload_too_large: 'bolt/choria-payload-too-large',
+        checksum_mismatch: 'bolt/choria-checksum-mismatch'
+      }.freeze
+
+      # Upload one file to the capable targets through the library.
+      def batch_upload(targets, source, destination, _options = {}, position = [], &callback)
+        result_opts = { action: 'upload', name: source, position: position }
+        capable, results = prepare_targets(targets, 'file_transfer', result_opts, &callback)
+        return results if capable.empty?
+
+        logger.debug { "Uploading #{source} to #{destination} on #{target_count(capable)}" }
+        results + transfer(capable, result_opts, callback) do |client|
+          outcomes = client.upload(source, destination, identities_of(capable))
+          file_transfer_results(capable, outcomes, result_opts, callback) do |target|
+            Bolt::Result.for_upload(target, source, destination)
+          end
+        end
+      end
+
+      # Download a path from each capable target into its own directory.
+      def batch_download(targets, source, destination, _options = {}, position = [], &callback)
+        directories = targets.to_h { |target| [target, download_dir(destination, target)] }
+        download_into(directories, source, position, &callback)
+      end
+
+      # Download a path from each capable target into the directory given
+      # for it.
+      #
+      # @param directories [Hash{Bolt::Target => String}] Each target and the local directory its download goes into
+      # @param source [String] The path to download from each target
+      # @param position [Array] Positional info for result tracking
+      # @param callback [Proc] Called with :node_start and :node_result events
+      # @return [Array<Bolt::Result>]
+      def download_into(directories, source, position, &callback)
+        result_opts = { action: 'download', name: source, position: position }
+        capable, results = prepare_targets(directories.keys, 'file_transfer', result_opts, &callback)
+        return results if capable.empty?
+
+        logger.debug { "Downloading #{source} from #{target_count(capable)}" }
+        # The library takes one directory per identity, so targets behind one
+        # identity share the last one's directory.
+        destination_dirs = capable.to_h { |target| [choria_identity(target), directories.fetch(target)] }
+        results + transfer(capable, result_opts, callback) do |client|
+          outcomes = client.download(source, destination_dirs)
+          file_transfer_results(capable, outcomes, result_opts, callback) do |target, outcome|
+            Bolt::Result.for_download(target, source, destination_dirs.fetch(choria_identity(target)), outcome.path)
+          end
+        end
+      end
+
+      # Runs one transfer for the targets with a library client and returns a
+      # result per target. A library that isn't installed on this host, or an
+      # error raised for what the controller contains, such as a source that
+      # can't be read, is a result for each of the targets.
+      #
+      # @param targets [Array<Bolt::Target>] The capable targets of one batch
+      # @param result_opts [Hash] Options passed through to emit_results (:action, :name, :position)
+      # @param callback [Proc, nil] Called with :node_result events
+      # @yield [MCollective::Util::FileTransfer::Client] The client for the targets
+      # @return [Array<Bolt::Result>]
+      def transfer(targets, result_opts, callback)
+        yield file_transfer_client(targets)
+      rescue Bolt::Error => e
+        failures = targets.to_h { |target| [target, error_output(e.message, e.kind)] }
+        emit_results(failures, **result_opts, &callback)
+      rescue SystemCallError, ArgumentError => e
+        logger.warn { "The file transfer raised #{e.class} on the controller: #{e.message}" }
+        logger.debug { e.backtrace.join("\n") }
+        message = "#{e.message} (#{e.class} on the controller)"
+        failures = targets.to_h { |target| [target, error_output(message, FILE_TRANSFER_ERROR_KINDS[:transfer_failed])] }
+        emit_results(failures, **result_opts, &callback)
+      end
+
+      # A library client for the targets, with the batch's options. The
+      # library builds its connection from the options this transport's own
+      # clients get and the RPC mutex every other call in the process takes.
+      # A timeout or size the batch does not set is left to the library's
+      # default.
+      def file_transfer_client(targets)
+        load_file_transfer_library
+        options = targets.first.options
+        settings = { rpc_timeout: options['file-transfer-timeout'], message_data_size: options['message-data-size'],
+                     upload_batch_size: options['upload-batch-size'] }
+        MCollective::Util::FileTransfer::Client.new(client_options(targets), mutex: @rpc_mutex, logger: logger, **settings.compact)
+      end
+
+      # The library is a client file of the agent's Puppet module under the
+      # libdir the Choria client config names, which loading that config in
+      # configure_client put on the load path.
+      def load_file_transfer_library
+        require 'mcollective/util/file_transfer'
+      rescue LoadError => e
+        raise Bolt::Error.new(
+          'The file_transfer client library is not installed on this host. Apply the mcollective_agent_file_transfer ' \
+          "module with client => true where OpenBolt runs, which installs it under the Choria libdir (#{e.class}: #{e.message}).",
+          'bolt/choria-file-transfer-library'
+        )
+      end
+
+      # A result per target from the outcomes by identity, firing
+      # node_result for each. The block builds the result of a success.
+      def file_transfer_results(targets, outcomes, result_opts, callback)
+        targets.map do |target|
+          outcome = outcomes.fetch(choria_identity(target))
+          result = if outcome.success?
+                     yield(target, outcome)
+                   else
+                     kind = FILE_TRANSFER_ERROR_KINDS.fetch(outcome.error_kind, FILE_TRANSFER_ERROR_KINDS[:transfer_failed])
+                     build_result(target, error_output(outcome.error_message, kind), **result_opts)
+                   end
+          callback&.call(type: :node_result, result: result)
+          result
+        end
+      end
+    end
+  end
+end

data/lib/bolt/transport/choria/helpers.rb

@@ -14,7 +14,7 @@ module Bolt
       WINDOWS_PATH_REGEX = %r{\A[A-Za-z]:[\\/]}
 
       def target_count(targets)
-        count = targets.is_a?(Hash) ? targets.size : targets.length
+        count = targets.size
         "#{count} #{count == 1 ? 'target' : 'targets'}"
       end
 
@@ -26,11 +26,11 @@ module Bolt
       #
       # @param targets [Array, Hash] Initial targets to poll (duped internally)
       # @param timeout [Numeric] Maximum seconds before exiting
-      # @param context [String] Label for log messages
+      # @param context [String] Label for log and error messages
       # @return [Hash] with keys:
-      #   - :completed [Hash{Target => Hash}] All finished target outputs
-      #   - :remaining [Array, Hash] Targets still pending when the loop exited
-      #   - :rpc_persistent_failure [Boolean] True if loop exited due to persistent RPC failures
+      #   - :completed [Hash{Target => Hash}] All finished target outputs, plus a poll
+      #     error for each pending target after RPC_FAILURE_RETRIES failed polls in a row
+      #   - :remaining [Array, Hash] Targets still pending at the deadline
       def poll_with_retries(targets, timeout, context)
         deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
         remaining = targets.dup
@@ -62,8 +62,17 @@ module Bolt
           break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
         end
 
-        { completed: completed, remaining: remaining,
-          rpc_persistent_failure: poll_failures >= RPC_FAILURE_RETRIES }
+        if poll_failures >= RPC_FAILURE_RETRIES
+          (remaining.is_a?(Hash) ? remaining.keys : remaining).each do |target|
+            completed[target] = error_output(
+              "RPC requests to poll #{context} on #{target.safe_name} failed persistently",
+              'bolt/choria-poll-failed'
+            )
+          end
+          remaining.clear
+        end
+
+        { completed: completed, remaining: remaining }
       end
 
       # Build a Bolt::Result from an output hash. Handles both success and
@@ -100,19 +109,16 @@ module Bolt
       end
 
       # Convert a hash of { target => output } into Results, fire callbacks,
-      # and return the Results array. When fire_node_start is true, fires a
-      # :node_start callback before each :node_result.
+      # and return the Results array.
       #
       # @param target_outputs [Hash{Bolt::Target => Hash}] Map of targets to output hashes
       # @param action [String] One of 'task', 'command', or 'script'
       # @param name [String] Task/command/script name for result metadata
       # @param position [Array] Positional info for result tracking
-      # @param fire_node_start [Boolean] Whether to emit :node_start before each result
-      # @param callback [Proc] Called with :node_start and :node_result events
+      # @param callback [Proc] Called with :node_result events
       # @return [Array<Bolt::Result>] Results for all targets in the hash
-      def emit_results(target_outputs, action:, name:, position:, fire_node_start: false, &callback)
+      def emit_results(target_outputs, action:, name:, position:, &callback)
         target_outputs.map do |target, data|
-          callback&.call(type: :node_start, target: target) if fire_node_start
           result = build_result(target, data, action: action, name: name, position: position)
           callback&.call(type: :node_result, result: result)
           result
@@ -120,8 +126,8 @@ module Bolt
       end
 
       # Build an output hash from command/task output.
-      def output(stdout: nil, stderr: nil, exitcode: nil)
-        { stdout: stdout || '', stderr: stderr || '', exitcode: exitcode || 0 }
+      def output(stdout:, stderr:, exitcode:)
+        { stdout: stdout || '', stderr: stderr || '', exitcode: exitcode }
       end
 
       # Build an error output hash. When actual output is available (e.g.
@@ -131,15 +137,14 @@ module Bolt
           .merge(error: message, error_kind: kind)
       end
 
-      # Extract exit code from RPC response data, defaulting to 1 with a
+      # Return the exit code an agent reported, defaulting to 1 with a
       # warning if the agent returned nil.
       #
-      # @param data [Hash] RPC response data containing :exitcode
+      # @param exitcode [Integer, nil] The exit code from the RPC response data
       # @param target [Bolt::Target] Target for logging context
       # @param context [String] Human-readable label for the log message
-      # @return [Integer] The exit code from the data, or 1 if nil
-      def exitcode_from(data, target, context)
-        exitcode = data[:exitcode] || data['exitcode']
+      # @return [Integer] The exit code, or 1 if nil
+      def exitcode_from(exitcode, target, context)
         if exitcode.nil?
           logger.warn {
             "Agent on #{target.safe_name} returned no exit code for #{context}. " \