glazed 0.1.0 → 0.2.0

data/lib/glazed/redactor.rb

@@ -15,7 +15,8 @@ module Glazed
   # 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.
+  # up in diffs without being revealed. A pattern with a note adds +:note=...+
+  # before the closing +~]+.
   #
   # @example
   #   Glazed::Redactor.new(patterns: Glazed::Dialects::Ios.sensitive_patterns, mode: :remove).call(config)
@@ -47,27 +48,59 @@ module Glazed
 
     # Builds a redactor from settings.
     #
+    # Secrets of +redaction+ and +global+ both apply. +redaction+ takes precedence
+    # for the mode and the HMAC key when it sets them.
+    #
     # @param redaction [Proto::V1::Redaction] redaction settings
     # @param patterns [Array<Dialect::SensitivePattern>] where secrets appear
+    # @param global [Proto::V1::Redaction, nil] settings shared by every redactor
+    # @param secrets [SecretsResolver] reads the HMAC key and the secrets to hide
     # @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
+    # @raise [InvalidConfiguration] when the mode is unknown, the HMAC key is missing or not base64, or a regexp is invalid
+    # @raise [Secret::Unavailable] when the HMAC key or a secret cannot be read
+    #: (Proto::V1::Redaction redaction, patterns: Array[Dialect::SensitivePattern], secrets: SecretsResolver, ?global: Proto::V1::Redaction?) -> Redactor
+    def self.from_proto(redaction, patterns:, secrets:, global: nil)
+      patterns += ((global&.secrets&.to_a || []) + redaction.secrets.to_a).filter_map { extra_pattern(it, secrets) }
+      mode = redaction.mode == :MODE_UNSPECIFIED && global ? global.mode : redaction.mode
+      case 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}"
+      when :MODE_HMAC then new(patterns:, mode: :hmac, key: hmac_key(redaction.hmac_key || global&.hmac_key, secrets))
+      else raise InvalidConfiguration, "unknown redaction mode #{mode.inspect}"
       end
     end
 
-    # @param redaction [Proto::V1::Redaction] redaction settings
+    # @param extra [Proto::V1::ExtraSecret] secret to hide
+    # @param secrets [SecretsResolver] reads the secret
+    # @return [Dialect::SensitivePattern, nil] pattern locating it, or nil when it has no value
+    # @raise [InvalidConfiguration] when a regexp is invalid
+    # @raise [Secret::Unavailable] when the referenced value cannot be read
+    #: (Proto::V1::ExtraSecret extra, SecretsResolver secrets) -> Dialect::SensitivePattern?
+    private_class_method def self.extra_pattern(extra, secrets)
+      whole_match = ->(match) { match.begin(0)...match.end(0) } #: Dialect::SensitivePattern::determiner
+      note = extra.note.empty? ? nil : extra.note
+      ref = extra.ref or raise InvalidConfiguration, 'redaction secret has no ref'
+      value = secrets.secret(ref).value
+      values = (extra.delimiter.empty? ? [value] : value.split(extra.delimiter)).reject(&:empty?)
+      return nil if values.empty?
+
+      pattern = if extra.regexp
+        Regexp.union(values.map { Regexp.new(it) })
+      else
+        Regexp.union(values.sort_by { -it.size })
+      end
+      Dialect::SensitivePattern.new(pattern:, determiner: whole_match, note:)
+    rescue RegexpError => e
+      raise InvalidConfiguration, "invalid regexp in redaction secrets: #{e.message}"
+    end
+
+    # @param ref [Proto::V1::SecretRef, nil] reference to the base64 key
+    # @param secrets [SecretsResolver] reads the key
     # @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
+    #: (Proto::V1::SecretRef? ref, SecretsResolver secrets) -> String?
+    private_class_method def self.hmac_key(ref, secrets)
+      encoded = secrets.maybe(ref)&.value or return nil
       encoded.unpack1('m0')
     rescue ArgumentError
       raise InvalidConfiguration, 'hmac_key is not base64'
@@ -84,31 +117,33 @@ module Glazed
     #: (String text) -> String
     def call(text)
       result = text.dup
-      secret_ranges(text).reverse_each do |start, finish|
-        result[start...finish] = replacement(text[start...finish] || '')
+      secret_ranges(text).reverse_each do |start, finish, note|
+        result[start...finish] = replacement(text[start...finish] || '', note)
       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]]
+    # @return [Array<Array(Integer, Integer, String?)>] non-overlapping secret start and end offsets, each with the
+    #   note of the pattern that located it, in order
+    #: (String text) -> Array[[Integer, Integer, String?]]
     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))
+          range = 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
+          [range[0], range[1], sensitive.note] if range
         end
       end
-      kept = [] #: Array[[Integer, Integer]]
-      ranges.sort_by { |start, finish| [start, -finish] }.each do |start, finish|
+      kept = [] #: Array[[Integer, Integer, String?]]
+      ranges.sort_by { |start, finish,| [start, -finish] }.each do |range|
         last = kept.last
-        kept << [start, finish] if last.nil? || start >= last[1]
+        kept << range if last.nil? || range[0] >= last[1]
       end
       kept
     end
@@ -146,13 +181,17 @@ module Glazed
     end
 
     # @param secret [String] secret to hide
+    # @param note [String, nil] note of the pattern that located the secret
     # @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('=')}~]"
+    #: (String secret, String? note) -> String
+    private def replacement(secret, note)
+      fields = [] #: Array[String]
+      if @mode == :hmac
+        digest = OpenSSL::HMAC.digest('SHA256', @key.to_s, secret).byteslice(0, HMAC_BYTES)
+        fields << "dgst=#{[digest].pack('m0').tr('+/', '-_').delete('=')}"
+      end
+      fields << "note=#{note}" if note
+      fields.empty? ? REMOVED : "[~REDACTED:#{fields.join(':')}~]"
     end
   end
 end

data/lib/glazed/secret.rb

@@ -5,28 +5,20 @@
 
 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.
+  # Secret read from a {Proto::V1::SecretRef} through a {SecretsResolver} 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)
+    # @param ref [Proto::V1::SecretRef] reference to read
+    # @param resolver [SecretsResolver] reads the value
+    #: (Proto::V1::SecretRef ref, resolver: SecretsResolver) -> void
+    def initialize(ref, resolver:)
       @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)
+      @resolver = resolver #: SecretsResolver
     end
 
     # @return [Proto::V1::SecretRef] the wrapped reference
@@ -36,39 +28,22 @@ module Glazed
     # Reads the secret value.
     #
     # @return [String] the value
-    # @raise [Unavailable] when the environment variable or file is missing, or no source is set
+    # @raise [Unavailable] when the value cannot be read, 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
+    def value = @resolver.value(ref)
 
     # @return [String] description naming the source but not the value
     #: () -> String
     def inspect
-      case ref.source
+      case (source = ref.source)
+      when :value, nil then "#<#{self.class} value>"
       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>"
+      else "#<#{self.class} #{source}>"
       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/command.rb

@@ -0,0 +1,66 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed'
+require 'glazed/must'
+require 'glazed/proto'
+require 'glazed/secret'
+require 'glazed/secrets'
+require 'glazed/shell_command'
+
+module Glazed
+  module Secrets
+    # Secret printed by a command line run with /bin/sh -c, or by a program
+    # run with its arguments, such as a password manager's CLI. It runs each
+    # time the value is read.
+    #
+    # @example
+    #   Glazed::Secrets::Command.new(run: 'pass show network/enable').value
+    #   Glazed::Secrets::Command.new(run: %w[op read op://network/enable/password]).value
+    class Command < Base
+      # Seconds before the command is killed when the settings set none.
+      DEFAULT_TIMEOUT = 30 #: Integer
+
+      # @param run [String, Array<String>] command line for /bin/sh -c, or program and its arguments
+      # @param timeout [Numeric] seconds before the command is killed
+      #: (run: String | Array[String], ?timeout: Numeric) -> void
+      def initialize(run:, timeout: DEFAULT_TIMEOUT)
+        super()
+        @run = run #: String | Array[String]
+        @timeout = timeout #: Numeric
+      end
+
+      # Builds a source from {Proto::V1::CommandSecret}.
+      #
+      # @param settings [Google::Protobuf::MessageExts] a {Proto::V1::CommandSecret}
+      # @return [Command] the source
+      # @raise [Must::Violation] when settings is another message
+      #: (Google::Protobuf::MessageExts settings) -> Command
+      def self.from_proto(settings)
+        command = Must.be_a(settings, Proto::V1::CommandSecret)
+        new(run: ShellCommand.run_of(command.run, command.exec), timeout: command.timeout_seconds.zero? ? DEFAULT_TIMEOUT : command.timeout_seconds)
+      end
+
+      # @return [String, Array<String>] command line, or program and its arguments
+      #: String | Array[String]
+      attr_reader :run
+
+      # @return [Numeric] seconds before the command is killed
+      #: Numeric
+      attr_reader :timeout
+
+      # Runs the command and reads the value it prints.
+      #
+      # @return [String] stdout without one trailing newline
+      # @raise [Secret::Unavailable] when the command cannot start, exits non-zero or does not finish in time
+      #: () -> String
+      def value
+        ShellCommand.new(run:, env: {}, stdin: '', timeout:).call.delete_suffix("\n")
+      rescue ShellCommand::Failed, TimeoutError => e
+        raise Secret::Unavailable, "secret command failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/glazed/secrets.rb

@@ -5,11 +5,14 @@
 
 require 'google/protobuf'
 require 'glazed'
+require 'glazed/finder'
 require 'glazed/must'
 require 'glazed/plugin_registry'
 
 module Glazed
-  # Secret sources implemented by plugins, used by `plugin` secret references.
+  # Secret sources other than a value, an environment variable or a file:
+  # those built for a message field of {Proto::V1::SecretRef}, such as
+  # `command` or glazed-aws's `ssm`, and plugins used by `plugin` references.
   module Secrets
     # A plugin source of one secret value, built from its settings message.
     class Base
@@ -20,13 +23,24 @@ module Glazed
       #: (Google::Protobuf::MessageExts settings) -> Base
       def self.from_proto(settings) = raise NotImplementedError
 
-      # Reads the secret, each time it is used.
+      # Reads the secret, each time it is used. A source that fetches the
+      # value remotely may keep it for a while; the {SecretsResolver} holding
+      # the source bounds how long.
       #
       # @return [String] the secret value
       #: () -> String
       def value = raise NotImplementedError
     end
 
+    # Finds a secret source class by snake_case name.
+    #
+    # @param name [String, Symbol] source name, such as "ssm"
+    # @return [Class<Base>] the source class
+    # @raise [Finder::NotFound] when there is none, for example when the gem providing it is not installed
+    # @raise [Must::Violation] when the name resolves to something other than a secret source
+    #: (String | Symbol name) -> singleton(Base)
+    def self.find(name) = source_class(Finder.find(self, 'glazed/secrets', name))
+
     # Secret sources implemented by plugins, by settings message type.
     PLUGINS = PluginRegistry.new('secret source') #: PluginRegistry
 
@@ -37,7 +51,7 @@ module Glazed
     # @param implementation [Class<Base>] source built with {Base.from_proto}
     # @return [void]
     # @example
-    #   Glazed::Secrets.register(GlazedAws::V1::SsmParameter, GlazedAws::SsmParameterSecret)
+    #   Glazed::Secrets.register(GlazedVault::V1::VaultSecret, GlazedVault::Secret)
     #: (singleton(Google::Protobuf::AbstractMessage) settings_class, singleton(Base) implementation) -> void
     def self.register(settings_class, implementation)
       PLUGINS.register(settings_class, implementation)
@@ -51,9 +65,17 @@ module Glazed
     #: (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
+      source_class(implementation).from_proto(settings)
+    end
+
+    # @param implementation [Module] registered or found implementation
+    # @return [Class<Base>] the implementation as a secret source class
+    # @raise [Must::Violation] when it is not a secret source
+    #: (Module[untyped] implementation) -> singleton(Base)
+    private_class_method def self.source_class(implementation)
+      return implementation if implementation.is_a?(Class) && implementation < Base
 
-      implementation.from_proto(settings)
+      raise Must::Violation, "#{implementation} is not a secret source"
     end
   end
 end

data/lib/glazed/secrets_resolver.rb

@@ -0,0 +1,85 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'google/protobuf'
+require 'glazed'
+require 'glazed/must'
+require 'glazed/proto'
+require 'glazed/secret'
+require 'glazed/secrets'
+
+module Glazed
+  # Reads the values of {Proto::V1::SecretRef}s. Sources other than a value,
+  # an environment variable or a file are built once per reference and kept
+  # here, so a source that caches what it fetches, such as glazed-aws's
+  # `ssm`, does so for as long as this resolver lives.
+  #
+  # @example
+  #   secrets = Glazed::SecretsResolver.new
+  #   secrets.secret(node.password).value
+  class SecretsResolver
+    #: () -> void
+    def initialize
+      @sources = {} #: Hash[String, Secrets::Base]
+      @lock = Mutex.new #: Thread::Mutex
+    end
+
+    # @param ref [Proto::V1::SecretRef] reference to wrap
+    # @return [Secret] the secret, read through this resolver
+    #: (Proto::V1::SecretRef ref) -> Secret
+    def secret(ref) = Secret.new(ref, resolver: self)
+
+    # @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 maybe(ref) = ref && secret(ref)
+
+    # Reads a secret value.
+    #
+    # @param ref [Proto::V1::SecretRef] reference to read
+    # @return [String] the value
+    # @raise [Secret::Unavailable] when the value cannot be read, or no source is set
+    # @raise [Finder::NotFound] when the source is provided by a gem that is not installed
+    # @raise [PluginRegistry::UnknownPlugin] when no plugin is registered for the settings type
+    #: (Proto::V1::SecretRef ref) -> String
+    def value(ref)
+      case ref.source
+      when :value then ref.value
+      when :env then ENV.fetch(ref.env) { raise Secret::Unavailable, "environment variable #{ref.env} is not set" }
+      when :file then read_file(ref.file)
+      when nil then raise Secret::Unavailable, 'secret has no source'
+      else source(ref).value
+      end
+    end
+
+    # @param ref [Proto::V1::SecretRef] reference with a plugin or gem-provided source
+    # @return [Secrets::Base] the source, built on first use
+    #: (Proto::V1::SecretRef ref) -> Secrets::Base
+    private def source(ref)
+      key = Proto::V1::SecretRef.encode(ref)
+      @lock.synchronize { @sources[key] ||= build(ref) }
+    end
+
+    # @param ref [Proto::V1::SecretRef] reference with a plugin or gem-provided source
+    # @return [Secrets::Base] the source
+    #: (Proto::V1::SecretRef ref) -> Secrets::Base
+    private def build(ref)
+      kind = Must.because(ref.source) { 'value reads only references with a source' }
+      return Secrets.build(Must.because(ref.plugin) { 'plugin is the selected source' }) if kind == :plugin
+
+      Secrets.find(kind).from_proto(Must.be_a(ref[kind.to_s], Google::Protobuf::MessageExts))
+    end
+
+    # @param path [String] file to read
+    # @return [String] file contents without one trailing newline
+    # @raise [Secret::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 Secret::Unavailable, "cannot read secret file #{path}: #{e.message}"
+    end
+  end
+end

data/lib/glazed/shell_command.rb

@@ -7,10 +7,12 @@ require 'open3'
 require 'glazed'
 
 module Glazed
-  # Runs a command line with /bin/sh -c, feeding stdin and capturing stdout.
+  # Runs a command line with /bin/sh -c, or a program with its arguments
+  # without a shell, feeding stdin and capturing stdout.
   #
   # @example
   #   Glazed::ShellCommand.new(run: 'sort', env: {}, stdin: "b\na\n", timeout: 10).call #=> "a\nb\n"
+  #   Glazed::ShellCommand.new(run: %w[sort -r], env: {}, stdin: "a\nb\n", timeout: 10).call #=> "b\na\n"
   class ShellCommand
     # Raised when the command exits non-zero or is killed by a signal.
     class Failed < Glazed::Error; end
@@ -20,13 +22,22 @@ module Glazed
     # Seconds between SIGTERM and SIGKILL when the command overruns.
     KILL_GRACE = 5 #: Integer
 
-    # @param run [String] command line
+    # Picks what to run from settings holding a `run` command line and an
+    # `exec` argument list, of which one is set.
+    #
+    # @param run [String] command line for /bin/sh -c
+    # @param exec [Enumerable<String>] program and its arguments
+    # @return [String, Array<String>] exec, when set, or the command line
+    #: (String run, Enumerable[String] exec) -> (String | Array[String])
+    def self.run_of(run, exec) = exec.none? ? run : exec.to_a
+
+    # @param run [String, Array<String>] command line for /bin/sh -c, or program and its arguments
     # @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
+    #: (run: String | Array[String], env: Hash[String, String], stdin: String, timeout: Numeric) -> void
     def initialize(run:, env:, stdin:, timeout:)
-      @run = run #: String
+      @run = run #: String | Array[String]
       @env = env #: Hash[String, String]
       @stdin = stdin #: String
       @timeout = timeout #: Numeric
@@ -35,11 +46,11 @@ module Glazed
     # Runs the command to completion.
     #
     # @return [String] stdout
-    # @raise [Failed] when the command exits non-zero or is killed by a signal
+    # @raise [Failed] when the command cannot start, 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)
+      stdin, stdout, stderr, waiter = spawn
       begin
         writer = Thread.new do
           stdin.write(@stdin)
@@ -67,6 +78,30 @@ module Glazed
       end
     end
 
+    # @return [Array(IO, IO, IO, Process::Waiter)] stdin, stdout, stderr and the waiter
+    # @raise [Failed] when the program cannot be executed
+    #: () -> [IO, IO, IO, Process::Waiter]
+    private def spawn
+      # Sorbet cannot check a splat against popen3's keyword options (7019).
+      open3 = Open3 #: untyped
+      open3.popen3(@env, *argv, pgroup: true)
+    rescue SystemCallError => e
+      raise Failed, "#{@run.inspect} could not start: #{e.message}"
+    end
+
+    # @return [Array] arguments for Open3.popen3
+    #: () -> Array[String | [String, String]]
+    private def argv
+      run = @run
+      return ['/bin/sh', '-c', run] if run.is_a?(String)
+
+      program, *args = run
+      raise ArgumentError, 'empty command' unless program
+
+      # A lone string would be run by a shell, so the program goes as [path, argv0].
+      [[program, program], *args]
+    end
+
     # Stops the command and everything it started, gracefully first.
     #
     # @param waiter [Process::Waiter] thread waiting on the process group leader

data/lib/glazed/sources/command.rb

@@ -21,12 +21,12 @@ module Glazed
       # Seconds before the command is killed when the settings set none.
       DEFAULT_TIMEOUT = 300 #: Integer
 
-      # @param run [String] command line, run by /bin/sh -c
+      # @param run [String, Array<String>] command line for /bin/sh -c, or program and its arguments
       # @param timeout [Numeric] seconds before the command is killed
-      #: (run: String, ?timeout: Numeric) -> void
+      #: (run: String | Array[String], ?timeout: Numeric) -> void
       def initialize(run:, timeout: DEFAULT_TIMEOUT)
         super()
-        @run = run #: String
+        @run = run #: String | Array[String]
         @timeout = timeout #: Numeric
       end
 
@@ -38,11 +38,11 @@ module Glazed
       #: (Google::Protobuf::MessageExts settings) -> Command
       def self.from_proto(settings)
         command = Must.be_a(settings, Proto::V1::CommandInventory)
-        new(run: command.run, timeout: command.timeout_seconds.zero? ? DEFAULT_TIMEOUT : command.timeout_seconds)
+        new(run: ShellCommand.run_of(command.run, command.exec), timeout: command.timeout_seconds.zero? ? DEFAULT_TIMEOUT : command.timeout_seconds)
       end
 
-      # @return [String] command line
-      #: String
+      # @return [String, Array<String>] command line, or program and its arguments
+      #: String | Array[String]
       attr_reader :run
 
       # @return [Numeric] seconds before the command is killed
@@ -59,9 +59,12 @@ module Glazed
       #: () -> Array[Proto::V1::Node]
       def nodes = nodes_from_json(ShellCommand.new(run:, env: {}, stdin: '', timeout:).call, origin: description)
 
-      # @return [String] the command line
+      # @return [String] the command line, or the program and its arguments
       #: () -> String
-      def description = "command #{run}"
+      def description
+        run = self.run
+        "command #{run.is_a?(String) ? run : run.join(' ')}"
+      end
     end
   end
 end

data/lib/glazed/state_backends/base.rb

@@ -13,7 +13,8 @@ module Glazed
     # Records change only through read-modify-write blocks, which a backend may
     # run more than once when another process changed the records meanwhile,
     # so a block must compute its result from the record it is given alone.
-    # Subclasses implement {.from_proto}, {#update_all}, {#list_due} and {#list}.
+    # Subclasses implement {.from_proto}, {#update_all}, {#list_due}, {#list}
+    # and {#update_wakeup}.
     class Base
       #: type updater = ^(String node, Proto::V1::NodeSchedule? record) -> Proto::V1::NodeSchedule?
 
@@ -62,6 +63,15 @@ module Glazed
       #: (String workflow) -> Array[Proto::V1::NodeSchedule]
       def list(workflow) = raise NotImplementedError
 
+      # Replaces the record of the waiting coordinator execution with what the
+      # block returns, with the same guarantees as {#update_all}.
+      #
+      # @yieldparam record [Proto::V1::Wakeup, nil] the current record, or nil when there is none
+      # @yieldreturn [Proto::V1::Wakeup, nil] the new record, or nil to delete it
+      # @return [Proto::V1::Wakeup, nil] the record held afterwards
+      #: () { (Proto::V1::Wakeup? record) -> Proto::V1::Wakeup? } -> Proto::V1::Wakeup?
+      def update_wakeup(&) = raise NotImplementedError
+
       # Releases resources held by the backend.
       #
       # @return [void]