openbolt 5.4.0 → 5.5.0

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

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Bolt
+  module Transport
+    class Choria
+      # Platform-aware command builders. These generate the right shell
+      # commands based on whether the target is Windows (PowerShell) or
+      # POSIX (sh). OS is detected during agent discovery via the
+      # os.family fact.
+
+      # Build a mkdir command for one or more directories.
+      #
+      # @param target [Bolt::Target] Used for platform detection
+      # @param paths [Array<String>] Absolute directory paths to create
+      # @return [String] Shell command
+      def make_dir_command(target, *paths)
+        if windows_target?(target)
+          escaped = paths.map { |path| "'#{ps_escape(path)}'" }.join(', ')
+          "New-Item -ItemType Directory -Force -Path #{escaped}"
+        else
+          escaped = paths.map { |path| Shellwords.shellescape(path) }.join(' ')
+          "mkdir -m 700 -p #{escaped}"
+        end
+      end
+
+      # Build a chmod +x command. Returns nil on Windows (not needed).
+      #
+      # @param target [Bolt::Target] Used for platform detection
+      # @param path [String] Absolute path to the file
+      # @return [String, nil] Shell command or nil
+      def make_executable_command(target, path)
+        windows_target?(target) ? nil : "chmod u+x #{Shellwords.shellescape(path)}"
+      end
+
+      # Build a recursive directory removal command.
+      #
+      # @param target [Bolt::Target] Used for platform detection
+      # @param path [String] Absolute path to the directory
+      # @return [String] Shell command
+      def cleanup_dir_command(target, path)
+        windows_target?(target) ?
+          "Remove-Item -Recurse -Force -Path '#{ps_escape(path)}'" :
+          "rm -rf #{Shellwords.shellescape(path)}"
+      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
+      # @return [String] Shell command
+      def upload_file_command(target, content_b64, dest)
+        if 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)}"
+        end
+      end
+
+      # Prepend environment variables to a command string.
+      # Returns the command unchanged if env_vars is nil or empty.
+      #
+      # @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 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}"
+        else
+          env_str = env_vars.map { |key, val| "#{key}=#{Shellwords.shellescape(val)}" }.join(' ')
+          "/usr/bin/env #{env_str} #{command}"
+        end
+      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
+      # @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}"
+        else
+          "printf '%s' #{Shellwords.shellescape(data)} | #{command}"
+        end
+      end
+
+      # Escape a string 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
+      # @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)
+      end
+
+      # Join path segments using the target platform's separator.
+      # Normalizes embedded forward slashes to backslashes on Windows.
+      #
+      # @param target [Bolt::Target] Used for platform detection
+      # @param parts [Array<String>] Path segments to join
+      # @return [String] Joined path
+      def join_path(target, *parts)
+        sep = windows_target?(target) ? '\\' : '/'
+        parts = parts.map { |part| part.tr('/', sep) } if sep != '/'
+        parts.join(sep)
+      end
+
+      # Wrap a PowerShell script for execution via shell agent. Uses
+      # -EncodedCommand with Base64-encoded UTF-16LE (the encoding
+      # Microsoft requires for -EncodedCommand) to avoid all quoting
+      # issues with cmd.exe and PowerShell metacharacters.
+      #
+      # @param script [String] PowerShell script to encode and wrap
+      # @return [String] powershell.exe command with -EncodedCommand
+      def powershell_cmd(script)
+        "powershell.exe -NoProfile -NonInteractive -EncodedCommand #{Base64.strict_encode64(script.encode('UTF-16LE'))}"
+      end
+
+      # Escape single quotes for use inside PowerShell single-quoted strings.
+      #
+      # @param str [String] String to escape
+      # @return [String] String with single quotes doubled
+      def ps_escape(str)
+        str.gsub("'", "''")
+      end
+
+      # Build the full command string for task execution via the shell agent,
+      # handling interpreter selection, environment variable injection, and
+      # stdin piping.
+      #
+      # @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 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)
+        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)
+
+        needs_env = Bolt::Task::ENVIRONMENT_METHODS.include?(input_method)
+        needs_stdin = Bolt::Task::STDIN_METHODS.include?(input_method)
+
+        if needs_env && needs_stdin && windows_target?(target)
+          # On Windows, piping stdin into a multi-statement command
+          # 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)}'" }
+          cmd = stdin_pipe_command(target, arguments.to_json,
+                                   "{ #{set_stmts.join('; ')}; $input | & #{cmd} }")
+        else
+          if needs_env
+            cmd = prepend_env_vars(target, cmd, envify_params(arguments), 'task argument')
+          end
+
+          if needs_stdin
+            cmd = stdin_pipe_command(target, arguments.to_json, cmd)
+          end
+        end
+
+        cmd
+      end
+
+      # Convert task arguments to PT_-prefixed environment variable hash.
+      # Duplicated from Bolt::Shell#envify_params. We don't use Bolt::Shell
+      # classes because they interleave command building with connection-based
+      # execution (IO pipes, sudo prompts). With the Choria transport, we just
+      # need to build the command and send it via RPC so all the shell agents
+      # on the targets can execute it themselves.
+      #
+      # @param params [Hash{String => Object}] Task parameter names to values
+      # @return [Hash{String => String}] Environment variables with PT_ prefix
+      def envify_params(params)
+        params.each_with_object({}) do |(key, val), env|
+          val = val.to_json unless val.is_a?(String)
+          env["PT_#{key}"] = val
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module Bolt
+  module Transport
+    class Choria
+      # Polling interval between rounds, used by poll_task_status
+      # and wait_for_shell_results. Each round makes one batched RPC call
+      # regardless of target count, so a 1-second interval balances
+      # responsiveness against broker load.
+      POLL_INTERVAL_SECONDS = 1
+
+      # Matches Windows absolute paths like C:\temp or D:/foo.
+      # Used by validate_file_name! and Config::Transport::Choria#absolute_path?.
+      WINDOWS_PATH_REGEX = %r{\A[A-Za-z]:[\\/]}
+
+      def target_count(targets)
+        count = targets.is_a?(Hash) ? targets.size : targets.length
+        "#{count} #{count == 1 ? 'target' : 'targets'}"
+      end
+
+      # Shared polling loop for bolt_tasks and shell polling. Handles sleep
+      # timing, round counting, RPC failure retry, and deadline enforcement.
+      #
+      # The block receives the remaining targets each round and returns:
+      #   { done: {target => output_hash}, rpc_failed: bool }
+      #
+      # @param targets [Array, Hash] Initial targets to poll (duped internally)
+      # @param timeout [Numeric] Maximum seconds before exiting
+      # @param context [String] Label for log 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
+      def poll_with_retries(targets, timeout, context)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        remaining = targets.dup
+        completed = {}
+        poll_failures = 0
+        poll_round = 0
+
+        until remaining.empty?
+          sleep(POLL_INTERVAL_SECONDS)
+          poll_round += 1
+          logger.debug { "Poll round #{poll_round}: #{target_count(remaining)} still pending" }
+
+          round = yield(remaining)
+
+          if round[:rpc_failed]
+            poll_failures += 1
+            logger.warn { "#{context} poll failed (attempt #{poll_failures}/#{RPC_FAILURE_RETRIES})" }
+            break if poll_failures >= RPC_FAILURE_RETRIES
+
+            next
+          end
+          poll_failures = 0
+
+          round[:done].each do |target, output|
+            completed[target] = output
+            remaining.delete(target)
+          end
+
+          break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+        end
+
+        { completed: completed, remaining: remaining,
+          rpc_persistent_failure: poll_failures >= RPC_FAILURE_RETRIES }
+      end
+
+      # Build a Bolt::Result from an output hash. Handles both success and
+      # error cases based on the presence of the :error key.
+      #
+      # @param target [Bolt::Target] The target this result belongs to
+      # @param data [Hash] Output hash with keys :stdout, :stderr, :exitcode, and
+      #   optionally :error and :error_kind for failures
+      # @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
+      # @return [Bolt::Result] The constructed result
+      def build_result(target, data, action:, name:, position:)
+        if data[:error]
+          Bolt::Result.from_exception(
+            target, Bolt::Error.new(data[:error], data[:error_kind]),
+            action: action, position: position
+          )
+        elsif action == 'task'
+          Bolt::Result.for_task(target, data[:stdout], data[:stderr],
+                                data[:exitcode], name, position)
+        elsif %w[command script].include?(action)
+          Bolt::Result.for_command(
+            target,
+            { 'stdout' => data[:stdout], 'stderr' => data[:stderr], 'exit_code' => data[:exitcode] },
+            action, name, position
+          )
+        else
+          raise Bolt::Error.new(
+            "Unknown action '#{action}' in build_result",
+            'bolt/choria-unknown-action'
+          )
+        end
+      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.
+      #
+      # @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
+      # @return [Array<Bolt::Result>] Results for all targets in the hash
+      def emit_results(target_outputs, action:, name:, position:, fire_node_start: false, &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
+        end
+      end
+
+      # Build an output hash from command/task output.
+      def output(stdout: nil, stderr: nil, exitcode: nil)
+        { stdout: stdout || '', stderr: stderr || '', exitcode: exitcode || 0 }
+      end
+
+      # Build an error output hash. When actual output is available (e.g.
+      # a command ran but failed), pass it through so the user sees it.
+      def error_output(message, kind, stdout: nil, stderr: nil, exitcode: 1)
+        output(stdout: stdout, stderr: stderr, exitcode: exitcode)
+          .merge(error: message, error_kind: kind)
+      end
+
+      # Extract exit code from RPC response data, defaulting to 1 with a
+      # warning if the agent returned nil.
+      #
+      # @param data [Hash] RPC response data containing :exitcode
+      # @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']
+        if exitcode.nil?
+          logger.warn {
+            "Agent on #{target.safe_name} returned no exit code for #{context}. " \
+            "Defaulting to exit code 1. This usually indicates an agent-level error."
+          }
+          exitcode = 1
+        end
+        exitcode
+      end
+
+      # Validate that a file name does not contain path traversal sequences
+      # or absolute paths. Checks both POSIX and Windows conventions.
+      # Raises Bolt::Error on violations.
+      #
+      # @param name [String] Task file name to validate
+      def validate_file_name!(name)
+        if name.include?("\0")
+          raise Bolt::Error.new(
+            "Invalid null byte in task file name: #{name.inspect}",
+            'bolt/invalid-task-filename'
+          )
+        end
+
+        if name.start_with?('/') || name.match?(WINDOWS_PATH_REGEX)
+          raise Bolt::Error.new(
+            "Absolute path not allowed in task file name: '#{name}'",
+            'bolt/invalid-task-filename'
+          )
+        end
+
+        if name.split(%r{[/\\]}).include?('..')
+          raise Bolt::Error.new(
+            "Path traversal detected in task file name: '#{name}'",
+            'bolt/path-traversal'
+          )
+        end
+      end
+
+      # Validate an environment variable key is safe for shell interpolation.
+      #
+      # @param key [String] Environment variable name to validate
+      # @param context [String] Description for error messages
+      def validate_env_key!(key, context)
+        safe_pattern = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+        return if safe_pattern.match?(key)
+
+        raise Bolt::Error.new(
+          "Unsafe environment variable name '#{key}' in #{context}. " \
+          "Names must match #{safe_pattern.source}",
+          'bolt/invalid-env-var-name'
+        )
+      end
+    end
+  end
+end