glazed 0.1.0

data/lib/glazed/plugin_registry.rb

@@ -0,0 +1,70 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'google/protobuf'
+require 'google/protobuf/well_known_types'
+require 'glazed'
+require 'glazed/validation'
+
+module Glazed
+  # Implementations of one kind of plugin, keyed by the full name of the
+  # settings message a config packs into a google.protobuf.Any.
+  #
+  # @example A plugin gem registering an inventory provider
+  #   Glazed::Sources.register(GlazedNetbox::V1::NetboxInventory, GlazedNetbox::Source)
+  class PluginRegistry
+    # Raised when no implementation is registered for a settings type.
+    class UnknownPlugin < Glazed::Error; end
+
+    # @param kind [String] what the plugins implement, for error messages
+    #: (String kind) -> void
+    def initialize(kind)
+      @kind = kind #: String
+      @implementations = {} #: Hash[String, Module[untyped]]
+      @lock = Mutex.new #: Thread::Mutex
+    end
+
+    # Registers the implementation for a settings message type.
+    #
+    # @param settings_class [Class] generated message class of the settings
+    # @param implementation [Module] implementation built from those settings
+    # @return [void]
+    #: (singleton(Google::Protobuf::AbstractMessage) settings_class, Module[untyped] implementation) -> void
+    def register(settings_class, implementation)
+      @lock.synchronize { @implementations[settings_class.descriptor.name] = implementation }
+    end
+
+    # Removes the implementation for a settings message type.
+    #
+    # @param settings_class [Class] generated message class of the settings
+    # @return [void]
+    #: (singleton(Google::Protobuf::AbstractMessage) settings_class) -> void
+    def unregister(settings_class)
+      @lock.synchronize { @implementations.delete(settings_class.descriptor.name) }
+    end
+
+    # Finds the implementation for packed settings and unpacks them.
+    #
+    # @param any [Google::Protobuf::Any] packed settings
+    # @return [Array(Module, Google::Protobuf::MessageExts)] the implementation and the settings message
+    # @raise [UnknownPlugin] when no implementation is registered for the settings type
+    # @raise [InvalidMessage] when the settings break the rules of their schema
+    #: (Google::Protobuf::Any any) -> [Module[untyped], Google::Protobuf::MessageExts]
+    def resolve(any)
+      type = any.type_name.to_s
+      implementation = @lock.synchronize { @implementations[type] }
+      unless implementation
+        raise UnknownPlugin, "no #{@kind} plugin is registered for #{type}; require the gem providing it with `requires`"
+      end
+
+      settings_class = Google::Protobuf::DescriptorPool.generated_pool.lookup(type)&.msgclass
+      settings = settings_class && any.unpack(settings_class)
+      raise UnknownPlugin, "cannot unpack #{type} settings" unless settings.is_a?(Google::Protobuf::MessageExts)
+
+      Validation.validate!(settings, origin: type)
+      [implementation, settings]
+    end
+  end
+end

data/lib/glazed/proto.rb

@@ -0,0 +1,20 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed/v1/config_pb'
+require 'glazed/v1/inventory_pb'
+require 'glazed/v1/orchestrator_pb'
+require 'glazed/v1/redaction_pb'
+require 'glazed/v1/secret_pb'
+require 'glazed/v1/state_pb'
+require 'glazed/v1/steps_pb'
+require 'glazed/v1/storage_pb'
+require 'glazed/v1/workflow_pb'
+
+module Glazed
+  # Message classes generated from proto/glazed/v1 (Glazed::Proto::V1).
+  module Proto
+  end
+end

data/lib/glazed/proto_json.rb

@@ -0,0 +1,34 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'google/protobuf'
+
+module Glazed
+  # ProtoJSON codec that keeps proto field names (snake_case) on output and
+  # rejects unknown fields on input.
+  module ProtoJson
+    # Decodes ProtoJSON into a message.
+    #
+    # @param klass [Class<Google::Protobuf::AbstractMessage>] message class
+    # @param json [String] ProtoJSON document
+    # @return [Google::Protobuf::AbstractMessage] decoded message
+    # @raise [Google::Protobuf::ParseError] when the document is malformed or has unknown fields
+    # @example
+    #   Glazed::ProtoJson.load(Glazed::Proto::V1::Node, '{"name": "rt1"}')
+    #: [M < Google::Protobuf::AbstractMessage] (singleton(Google::Protobuf::AbstractMessage) & Class[M] klass, String json) -> M
+    def self.load(klass, json)
+      klass.decode_json(json)
+    end
+
+    # Encodes a message into ProtoJSON.
+    #
+    # @param message [Google::Protobuf::AbstractMessage] message to encode
+    # @return [String] ProtoJSON document
+    #: (Google::Protobuf::AbstractMessage message) -> String
+    def self.dump(message)
+      message.class.encode_json(message, preserve_proto_fieldnames: true)
+    end
+  end
+end

data/lib/glazed/redactor.rb

@@ -0,0 +1,158 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'openssl'
+require 'glazed'
+require 'glazed/dialect/sensitive_pattern'
+require 'glazed/proto'
+require 'glazed/secret'
+
+module Glazed
+  # Hides secrets located by a dialect's sensitive patterns.
+  #
+  # Only the secret within each match is replaced, by +[~REDACTED~]+ in :remove
+  # mode or +[~REDACTED:dgst=...~]+ in :hmac mode. The digest is a truncated
+  # HMAC-SHA256 of the secret in unpadded base64url, so a changed secret shows
+  # up in diffs without being revealed.
+  #
+  # @example
+  #   Glazed::Redactor.new(patterns: Glazed::Dialects::Ios.sensitive_patterns, mode: :remove).call(config)
+  class Redactor
+    # Raised when the redaction settings are unusable.
+    class InvalidConfiguration < Glazed::Error; end
+
+    # Replacement in :remove mode.
+    REMOVED = '[~REDACTED~]' #: String
+    # Bytes of the HMAC kept in :hmac mode.
+    HMAC_BYTES = 8 #: Integer
+
+    # Supported modes.
+    MODES = %i[remove hmac].freeze #: Array[Symbol]
+
+    # @param patterns [Array<Dialect::SensitivePattern>] where secrets appear
+    # @param mode [Symbol] :remove or :hmac
+    # @param key [String, nil] HMAC key, required for :hmac
+    # @raise [InvalidConfiguration] when the mode is unknown or :hmac has no key
+    #: (patterns: Array[Dialect::SensitivePattern], mode: Symbol, ?key: String?) -> void
+    def initialize(patterns:, mode:, key: nil)
+      raise InvalidConfiguration, "unknown redaction mode #{mode.inspect}" unless MODES.include?(mode)
+      raise InvalidConfiguration, 'HMAC redaction requires a key' if mode == :hmac && (key.nil? || key.empty?)
+
+      @patterns = patterns #: Array[Dialect::SensitivePattern]
+      @mode = mode #: Symbol
+      @key = key #: String?
+    end
+
+    # Builds a redactor from settings.
+    #
+    # @param redaction [Proto::V1::Redaction] redaction settings
+    # @param patterns [Array<Dialect::SensitivePattern>] where secrets appear
+    # @return [Redactor] the redactor
+    # @raise [InvalidConfiguration] when the mode is unknown, or the HMAC key is missing or not base64
+    # @raise [Secret::Unavailable] when the HMAC key cannot be read
+    #: (Proto::V1::Redaction redaction, patterns: Array[Dialect::SensitivePattern]) -> Redactor
+    def self.from_proto(redaction, patterns:)
+      case redaction.mode
+      when :MODE_UNSPECIFIED, :MODE_REMOVE then new(patterns:, mode: :remove)
+      when :MODE_HMAC then new(patterns:, mode: :hmac, key: hmac_key(redaction))
+      else raise InvalidConfiguration, "unknown redaction mode #{redaction.mode.inspect}"
+      end
+    end
+
+    # @param redaction [Proto::V1::Redaction] redaction settings
+    # @return [String, nil] the HMAC key, decoded from base64
+    # @raise [InvalidConfiguration] when the key is not base64
+    # @raise [Secret::Unavailable] when the key cannot be read
+    #: (Proto::V1::Redaction redaction) -> String?
+    private_class_method def self.hmac_key(redaction)
+      encoded = Secret.maybe(redaction.hmac_key)&.value or return nil
+      encoded.unpack1('m0')
+    rescue ArgumentError
+      raise InvalidConfiguration, 'hmac_key is not base64'
+    end
+
+    # @return [Symbol] :remove or :hmac
+    #: Symbol
+    attr_reader :mode
+
+    # Redacts a configuration.
+    #
+    # @param text [String] configuration text
+    # @return [String] text with every located secret replaced
+    #: (String text) -> String
+    def call(text)
+      result = text.dup
+      secret_ranges(text).reverse_each do |start, finish|
+        result[start...finish] = replacement(text[start...finish] || '')
+      end
+      result
+    end
+
+    # @param text [String] configuration text
+    # @return [Array<Array(Integer, Integer)>] non-overlapping secret start and end offsets, in order
+    #: (String text) -> Array[[Integer, Integer]]
+    private def secret_ranges(text)
+      ranges = @patterns.flat_map do |sensitive|
+        matches(sensitive.pattern, text).filter_map do |match|
+          case (secret = sensitive.determiner.call(match))
+          when Range
+            start = secret.begin
+            finish = secret.exclude_end? ? secret.end : secret.end + 1
+            [start, finish] if finish > start
+          when String then locate(match, secret) unless secret.empty?
+          end
+        end
+      end
+      kept = [] #: Array[[Integer, Integer]]
+      ranges.sort_by { |start, finish| [start, -finish] }.each do |start, finish|
+        last = kept.last
+        kept << [start, finish] if last.nil? || start >= last[1]
+      end
+      kept
+    end
+
+    # @param pattern [Regexp] pattern to scan for
+    # @param text [String] text to scan
+    # @return [Array<MatchData>] every match
+    #: (Regexp pattern, String text) -> Array[MatchData]
+    private def matches(pattern, text)
+      found = [] #: Array[MatchData]
+      position = 0
+      while (match = pattern.match(text, position))
+        found << match
+        position = match.end(0) > match.begin(0) ? match.end(0) : match.end(0) + 1
+        break if position > text.size
+      end
+      found
+    end
+
+    # Finds the secret in a match, preferring the last capture group equal to it,
+    # as secrets follow the names they belong to.
+    #
+    # @param match [MatchData] the match
+    # @param secret [String] secret returned by the determiner
+    # @return [Array(Integer, Integer), nil] start and end offsets of the secret, or nil when it is not in the match
+    #: (MatchData match, String secret) -> [Integer, Integer]?
+    private def locate(match, secret)
+      group = (match.size - 1).downto(1).find { match[it] == secret }
+      start = if group
+        match.begin(group)
+      elsif (offset = match[0]&.rindex(secret))
+        match.begin(0) + offset
+              end
+      [start, start + secret.size] if start
+    end
+
+    # @param secret [String] secret to hide
+    # @return [String] its replacement
+    #: (String secret) -> String
+    private def replacement(secret)
+      return REMOVED unless @mode == :hmac
+
+      digest = OpenSSL::HMAC.digest('SHA256', @key.to_s, secret).byteslice(0, HMAC_BYTES)
+      "[~REDACTED:dgst=#{[digest].pack('m0').tr('+/', '-_').delete('=')}~]"
+    end
+  end
+end

data/lib/glazed/runner.rb

@@ -0,0 +1,176 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed'
+require 'glazed/proto'
+require 'glazed/steps'
+require 'glazed/workflow'
+
+module Glazed
+  # Runs a workflow in this process. Consecutive per-node steps run for each
+  # node on a thread pool; a node whose step fails is reported and left out of
+  # the rest of the workflow. Batch steps run with the remaining nodes, and
+  # their failures propagate.
+  #
+  # @example
+  #   result = Glazed::Runner.new(workflow:, jobs: 4).call(nodes)
+  #   result.failures.each { warn "#{it.node.name}: #{it.error.message}" }
+  class Runner
+    #: type event_value = String | Integer | bool | Array[String] | nil
+    #: type listener = ^(Hash[Symbol, Runner::event_value] event) -> void
+
+    # A node that failed a step.
+    class Failure
+      # @param node [Proto::V1::Node] the node
+      # @param step [String] name of the failed step
+      # @param error [StandardError] the error
+      #: (node: Proto::V1::Node, step: String, error: StandardError) -> void
+      def initialize(node:, step:, error:)
+        @node = node #: Proto::V1::Node
+        @step = step #: String
+        @error = error #: StandardError
+      end
+
+      # @return [Proto::V1::Node] the node
+      #: Proto::V1::Node
+      attr_reader :node
+      # @return [String] name of the failed step
+      #: String
+      attr_reader :step
+      # @return [StandardError] the error
+      #: StandardError
+      attr_reader :error
+    end
+
+    # Outcome of a run.
+    class Result
+      # @param states [Array<Proto::V1::NodeState>] states of the nodes that completed every step
+      # @param failures [Array<Failure>] nodes that failed a step
+      #: (states: Array[Proto::V1::NodeState], failures: Array[Failure]) -> void
+      def initialize(states:, failures:)
+        @states = states #: Array[Proto::V1::NodeState]
+        @failures = failures #: Array[Failure]
+      end
+
+      # @return [Array<Proto::V1::NodeState>] states of the nodes that completed every step
+      #: Array[Proto::V1::NodeState]
+      attr_reader :states
+      # @return [Array<Failure>] nodes that failed a step
+      #: Array[Failure]
+      attr_reader :failures
+
+      # @return [Array<Proto::V1::NodeState>] states with at least one artifact whose write changed stored content
+      #: () -> Array[Proto::V1::NodeState]
+      def changed = states.select { |state| state.artifacts.values.any?(&:changed) }
+    end
+
+    # @param workflow [Workflow] the workflow
+    # @param jobs [Integer] nodes processed in parallel
+    # @param listener [Proc] receives an event hash per completed or failed step
+    #: (workflow: Workflow, jobs: Integer, ?listener: Runner::listener) -> void
+    def initialize(workflow:, jobs:, listener: ->(_event) {})
+      @workflow = workflow #: Workflow
+      @jobs = jobs #: Integer
+      @listener = listener #: Runner::listener
+      @lock = Mutex.new #: Thread::Mutex
+    end
+
+    # @param nodes [Array<Proto::V1::Node>] nodes to run against
+    # @return [Result] the outcome
+    # @raise [Glazed::Error] when a batch step fails
+    #: (Array[Proto::V1::Node] nodes) -> Result
+    def call(nodes)
+      states = nodes.map { Proto::V1::NodeState.new(node: it) }
+      failures = [] #: Array[Failure]
+      @workflow.steps.chunk_while { |a, b| a.is_a?(Steps::NodeStep) && b.is_a?(Steps::NodeStep) }.each do |chunk|
+        first = chunk.first
+        states = case first
+                 when Steps::BatchStep then run_batch(first, states)
+                 else run_per_node(chunk.grep(Steps::NodeStep), states, failures)
+                 end
+      end
+      Result.new(states:, failures:)
+    end
+
+    # @param step [Steps::BatchStep] the step
+    # @param states [Array<Proto::V1::NodeState>] node states
+    # @return [Array<Proto::V1::NodeState>] node states after the step
+    #: (Steps::BatchStep step, Array[Proto::V1::NodeState] states) -> Array[Proto::V1::NodeState]
+    private def run_batch(step, states)
+      batch = step.call(Proto::V1::BatchState.new(nodes: states))
+      after = batch.nodes.to_a
+      if step.outputs.empty?
+        notify(level: 'info', step: step.name, nodes: after.size, message: 'done')
+      else
+        notify(level: 'info', step: step.name, nodes: after.size, changed: after.count { changed?(it, step) }, message: 'done')
+      end
+      after
+    end
+
+    # @param steps [Array<Steps::NodeStep>] consecutive per-node steps
+    # @param states [Array<Proto::V1::NodeState>] node states
+    # @param failures [Array<Failure>] collects failed nodes
+    # @return [Array<Proto::V1::NodeState>] states of the nodes that completed the steps, in input order
+    #: (Array[Steps::NodeStep] steps, Array[Proto::V1::NodeState] states, Array[Failure] failures) -> Array[Proto::V1::NodeState]
+    private def run_per_node(steps, states, failures)
+      queue = Thread::Queue.new(states.each_with_index.to_a)
+      queue.close
+      results = {} #: Hash[Integer, Proto::V1::NodeState]
+      workers = Array.new([@jobs, states.size].min) do
+        Thread.new do
+          while (item = queue.pop)
+            state, index = item
+            Thread.current.name = state.node&.name
+            result = run_node(steps, state, failures)
+            @lock.synchronize { results[index] = result } if result
+          end
+        end
+      end
+      begin
+        workers.each(&:join)
+      rescue Interrupt
+        workers.select(&:alive?).each do |worker|
+          notify(level: 'error', node: worker.name, message: 'interrupted', backtrace: worker.backtrace || [])
+        end
+        raise
+      end
+      results.sort.map { |_, state| state }
+    end
+
+    # @param steps [Array<Steps::NodeStep>] consecutive per-node steps
+    # @param state [Proto::V1::NodeState] the node's state
+    # @param failures [Array<Failure>] collects the node when it fails
+    # @return [Proto::V1::NodeState, nil] the final state, or nil when a step failed
+    #: (Array[Steps::NodeStep] steps, Proto::V1::NodeState state, Array[Failure] failures) -> Proto::V1::NodeState?
+    private def run_node(steps, state, failures)
+      node = state.node or raise ArgumentError, 'node state has no node'
+      steps.inject(state) do |current, step|
+        begin
+          current = step.call(current)
+        rescue StandardError => e
+          # One unreachable or misbehaving device must not stop the others.
+          @lock.synchronize { failures << Failure.new(node:, step: step.name, error: e) }
+          notify(level: 'error', step: step.name, node: node.name, error: e.class.name, message: e.message)
+          return nil
+        end
+        notify(level: 'info', step: step.name, node: node.name, changed: changed?(current, step), message: 'done')
+        current
+      end
+    end
+
+    # @param state [Proto::V1::NodeState] state after the step
+    # @param step [Steps::Base] the step
+    # @return [Boolean] whether any artifact the step produced changed stored content
+    #: (Proto::V1::NodeState state, Steps::Base step) -> bool
+    private def changed?(state, step) = step.outputs.any? { state.artifacts[it]&.changed }
+
+    # @param event [Hash{Symbol => String, Integer, Boolean, nil}] event fields
+    # @return [void]
+    #: (**Runner::event_value event) -> void
+    private def notify(**event)
+      @lock.synchronize { @listener.call(event) }
+    end
+  end
+end

data/lib/glazed/secret.rb

@@ -0,0 +1,74 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed'
+require 'glazed/proto'
+require 'glazed/secrets'
+
+module Glazed
+  # Secret resolved from a {Proto::V1::SecretRef} on each access. Its value
+  # never appears in #inspect or #to_s.
+  class Secret
+    # Raised when the referenced value cannot be read.
+    class Unavailable < Glazed::Error; end
+
+    # @param ref [Proto::V1::SecretRef] reference to resolve
+    #: (Proto::V1::SecretRef ref) -> void
+    def initialize(ref)
+      @ref = ref #: Proto::V1::SecretRef
+    end
+
+    # Wraps a reference that may be absent.
+    #
+    # @param ref [Proto::V1::SecretRef, nil] reference to wrap
+    # @return [Secret, nil] the secret, or nil when ref is nil
+    #: (Proto::V1::SecretRef? ref) -> Secret?
+    def self.maybe(ref)
+      ref && new(ref)
+    end
+
+    # @return [Proto::V1::SecretRef] the wrapped reference
+    #: Proto::V1::SecretRef
+    attr_reader :ref
+
+    # Reads the secret value.
+    #
+    # @return [String] the value
+    # @raise [Unavailable] when the environment variable or file is missing, or no source is set
+    #: () -> String
+    def value
+      case ref.source
+      when :value then ref.value
+      when :env then ENV.fetch(ref.env) { raise Unavailable, "environment variable #{ref.env} is not set" }
+      when :file then read_file(ref.file)
+      when :plugin then Secrets.build(ref.plugin || raise(Unavailable, 'secret plugin has no settings')).value
+      else raise Unavailable, 'secret has no source'
+      end
+    end
+
+    # @return [String] description naming the source but not the value
+    #: () -> String
+    def inspect
+      case ref.source
+      when :env then "#<#{self.class} env:#{ref.env}>"
+      when :file then "#<#{self.class} file:#{ref.file}>"
+      when :plugin then "#<#{self.class} plugin:#{ref.plugin&.type_name}>"
+      else "#<#{self.class} value>"
+      end
+    end
+
+    alias to_s inspect
+
+    # @param path [String] file to read
+    # @return [String] file contents without one trailing newline
+    # @raise [Unavailable] when the file cannot be read
+    #: (String path) -> String
+    private def read_file(path)
+      File.read(path).delete_suffix("\n")
+    rescue SystemCallError => e
+      raise Unavailable, "cannot read secret file #{path}: #{e.message}"
+    end
+  end
+end

data/lib/glazed/secrets.rb

@@ -0,0 +1,59 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'google/protobuf'
+require 'glazed'
+require 'glazed/must'
+require 'glazed/plugin_registry'
+
+module Glazed
+  # Secret sources implemented by plugins, used by `plugin` secret references.
+  module Secrets
+    # A plugin source of one secret value, built from its settings message.
+    class Base
+      # Builds the source from its settings message.
+      #
+      # @param settings [Google::Protobuf::MessageExts] settings unpacked from the reference
+      # @return [Base] the source
+      #: (Google::Protobuf::MessageExts settings) -> Base
+      def self.from_proto(settings) = raise NotImplementedError
+
+      # Reads the secret, each time it is used.
+      #
+      # @return [String] the secret value
+      #: () -> String
+      def value = raise NotImplementedError
+    end
+
+    # Secret sources implemented by plugins, by settings message type.
+    PLUGINS = PluginRegistry.new('secret source') #: PluginRegistry
+
+    # Registers a plugin secret source, selected by `plugin` references whose
+    # settings are of the given type.
+    #
+    # @param settings_class [Class] generated message class of the source settings
+    # @param implementation [Class<Base>] source built with {Base.from_proto}
+    # @return [void]
+    # @example
+    #   Glazed::Secrets.register(GlazedAws::V1::SsmParameter, GlazedAws::SsmParameterSecret)
+    #: (singleton(Google::Protobuf::AbstractMessage) settings_class, singleton(Base) implementation) -> void
+    def self.register(settings_class, implementation)
+      PLUGINS.register(settings_class, implementation)
+    end
+
+    # Builds the source for packed settings.
+    #
+    # @param packed [Google::Protobuf::Any] settings from a secret reference
+    # @return [Base] the source
+    # @raise [PluginRegistry::UnknownPlugin] when no plugin is registered for the settings type
+    #: (Google::Protobuf::Any packed) -> Base
+    def self.build(packed)
+      implementation, settings = PLUGINS.resolve(packed)
+      raise Must::Violation, "#{implementation} is not a secret source" unless implementation.is_a?(Class) && implementation < Base
+
+      implementation.from_proto(settings)
+    end
+  end
+end

data/lib/glazed/shell_command.rb

@@ -0,0 +1,90 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'open3'
+require 'glazed'
+
+module Glazed
+  # Runs a command line with /bin/sh -c, feeding stdin and capturing stdout.
+  #
+  # @example
+  #   Glazed::ShellCommand.new(run: 'sort', env: {}, stdin: "b\na\n", timeout: 10).call #=> "a\nb\n"
+  class ShellCommand
+    # Raised when the command exits non-zero or is killed by a signal.
+    class Failed < Glazed::Error; end
+
+    # Bytes of stderr kept in error messages.
+    STDERR_TAIL = 1000 #: Integer
+    # Seconds between SIGTERM and SIGKILL when the command overruns.
+    KILL_GRACE = 5 #: Integer
+
+    # @param run [String] command line
+    # @param env [Hash{String => String}] environment added to the inherited one
+    # @param stdin [String] data written to stdin
+    # @param timeout [Numeric] seconds before the command is killed
+    #: (run: String, env: Hash[String, String], stdin: String, timeout: Numeric) -> void
+    def initialize(run:, env:, stdin:, timeout:)
+      @run = run #: String
+      @env = env #: Hash[String, String]
+      @stdin = stdin #: String
+      @timeout = timeout #: Numeric
+    end
+
+    # Runs the command to completion.
+    #
+    # @return [String] stdout
+    # @raise [Failed] when the command exits non-zero or is killed by a signal
+    # @raise [TimeoutError] when the command does not finish in time; its process group is killed
+    #: () -> String
+    def call
+      stdin, stdout, stderr, waiter = Open3.popen3(@env, '/bin/sh', '-c', @run, pgroup: true)
+      begin
+        writer = Thread.new do
+          stdin.write(@stdin)
+        rescue Errno::EPIPE
+          # The command exited or closed stdin without reading all of it.
+          nil
+        ensure
+          stdin.close
+        end
+        out = Thread.new { stdout.read }
+        err = Thread.new { stderr.read }
+
+        unless waiter.join(@timeout.to_f)
+          terminate(waiter)
+          raise TimeoutError, "#{@run.inspect} did not finish in #{@timeout}s"
+        end
+        writer.join
+        status = waiter.value #: Process::Status
+        output = out.value.to_s
+        return output if status.success?
+
+        raise Failed, "#{@run.inspect} #{describe(status)}: #{err.value.to_s[-STDERR_TAIL..] || err.value}"
+      ensure
+        [stdin, stdout, stderr].each { it.close unless it.closed? }
+      end
+    end
+
+    # Stops the command and everything it started, gracefully first.
+    #
+    # @param waiter [Process::Waiter] thread waiting on the process group leader
+    # @return [void]
+    #: (Process::Waiter waiter) -> void
+    private def terminate(waiter)
+      Process.kill('TERM', -waiter.pid)
+      Process.kill('KILL', -waiter.pid) unless waiter.join(KILL_GRACE)
+    rescue Errno::ESRCH
+      # Already gone.
+      nil
+    end
+
+    # @param status [Process::Status] exit status
+    # @return [String] how the command ended
+    #: (Process::Status status) -> String
+    private def describe(status)
+      status.signaled? ? "was killed by signal #{status.termsig}" : "exited with #{status.exitstatus}"
+    end
+  end
+end