glazed 0.1.0

data/lib/glazed/steps/publish.rb

@@ -0,0 +1,94 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed/must'
+require 'glazed/proto'
+require 'glazed/steps'
+require 'glazed/storages'
+
+module Glazed
+  module Steps
+    # Batch: writes an artifact of every node into a storage as one change,
+    # such as one commit naming the nodes.
+    #
+    # @example Step definition
+    #   {"name": "publish", "publish": {"input": "redacted", "storage": "team"}}
+    class Publish < BatchStep
+      # Node names listed in a commit message before it is shortened.
+      MESSAGE_NAMES = 5 #: Integer
+
+      # @param name [String] step name
+      # @param input [String] artifact to read from each node
+      # @param storage_name [String] storage to write to, by name
+      # @param output [String, nil] artifact recording the written locations
+      # @param context [StepContext] named storages
+      # @raise [StepContext::UnknownStorage] when the storage is not configured
+      #: (name: String, input: String, storage_name: String, output: String?, context: StepContext) -> void
+      def initialize(name:, input:, storage_name:, output:, context:)
+        super(name:)
+        @input = input #: String
+        @storage_name = storage_name #: String
+        @storage = context.storage(storage_name) #: Storages::Base
+        @output = output #: String?
+        @context = context #: StepContext
+      end
+
+      # Builds the step from {Proto::V1::PublishStep}.
+      #
+      # @param name [String] step name
+      # @param settings [Google::Protobuf::MessageExts] a {Proto::V1::PublishStep}
+      # @param context [StepContext] named storages
+      # @return [Publish] the step
+      #: (String name, Google::Protobuf::MessageExts settings, context: StepContext) -> Publish
+      def self.from_proto(name, settings, context:)
+        publish = Must.be_a(settings, Proto::V1::PublishStep)
+        new(name:, input: publish.input, storage_name: publish.storage, output: publish.output.empty? ? nil : publish.output, context:)
+      end
+
+      # @return [Array<String>] the read artifact
+      #: () -> Array[String]
+      def inputs = [@input]
+
+      # @return [Array<String>] the recorded artifact, if any
+      #: () -> Array[String]
+      def outputs = [@output].compact
+
+      # @param batch [Proto::V1::BatchState] node states holding the input artifact
+      # @return [Proto::V1::BatchState] the states, with the output artifact when configured
+      # @raise [MissingArtifact] when a node lacks the input artifact
+      # @raise [Glazed::Error] when reading or storing fails
+      #: (Proto::V1::BatchState batch) -> Proto::V1::BatchState
+      def call(batch)
+        states = batch.nodes.to_a
+        return batch if states.empty?
+
+        names = {} #: Hash[String, String]
+        files = states.map do |state|
+          node = state.node or raise ArgumentError, "#{name}: state has no node"
+          key = Storages.key_for(node)
+          names[key] = node.name
+          [key, @context.read(artifact(state, @input))] #: Storages::Base::file
+        end
+        results = @storage.write_all(files, message: ->(changed_keys) { message(changed_keys.map { names.fetch(it, it) }) })
+        output = @output
+        return batch unless output
+
+        nodes = states.zip(results).map do |state, result|
+          with_artifacts(state, output => stored(@storage_name, Must.expect(result)))
+        end
+        Proto::V1::BatchState.new(nodes:)
+      end
+
+      # @param names [Array<String>] names of the nodes whose content changed
+      # @return [String] commit message naming the nodes
+      #: (Array[String] names) -> String
+      private def message(names)
+        listed = names.first(MESSAGE_NAMES).join(', ')
+        rest = names.size - MESSAGE_NAMES
+        rest.positive? ? "#{name}: update #{listed} and #{rest} more" : "#{name}: update #{listed}"
+      end
+    end
+  end
+end

data/lib/glazed/steps/redact.rb

@@ -0,0 +1,77 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed/dialects'
+require 'glazed/must'
+require 'glazed/proto'
+require 'glazed/redactor'
+require 'glazed/steps'
+require 'glazed/storages'
+
+module Glazed
+  module Steps
+    # Per node: hides secrets in an artifact using the node dialect's sensitive
+    # patterns, and stores the result as another artifact.
+    #
+    # @example Step definition
+    #   {"name": "redact", "redact": {"input": "raw", "output": "redacted", "storage": "staging",
+    #    "redaction": {"mode": "MODE_HMAC", "hmac_key": {"env": "GLAZED_HMAC_KEY"}}}}
+    class Redact < NodeStep
+      # @param name [String] step name
+      # @param input [String] artifact to read
+      # @param output [String] artifact to produce
+      # @param storage_name [String] storage to write to, by name
+      # @param redaction [Proto::V1::Redaction] how secrets are hidden
+      # @param context [StepContext] named storages
+      # @raise [StepContext::UnknownStorage] when the storage is not configured
+      #: (name: String, input: String, output: String, storage_name: String, redaction: Proto::V1::Redaction, context: StepContext) -> void
+      def initialize(name:, input:, output:, storage_name:, redaction:, context:)
+        super(name:)
+        @input = input #: String
+        @output = output #: String
+        @storage_name = storage_name #: String
+        @storage = context.storage(storage_name) #: Storages::Base
+        @redaction = redaction #: Proto::V1::Redaction
+        @context = context #: StepContext
+      end
+
+      # Builds the step from {Proto::V1::RedactStep}.
+      #
+      # @param name [String] step name
+      # @param settings [Google::Protobuf::MessageExts] a {Proto::V1::RedactStep}
+      # @param context [StepContext] named storages
+      # @return [Redact] the step
+      #: (String name, Google::Protobuf::MessageExts settings, context: StepContext) -> Redact
+      def self.from_proto(name, settings, context:)
+        redact = Must.be_a(settings, Proto::V1::RedactStep)
+        new(
+          name:, input: redact.input, output: redact.output, storage_name: redact.storage,
+          redaction: redact.redaction || Proto::V1::Redaction.new, context:,
+        )
+      end
+
+      # @return [Array<String>] the read artifact
+      #: () -> Array[String]
+      def inputs = [@input]
+
+      # @return [Array<String>] the produced artifact
+      #: () -> Array[String]
+      def outputs = [@output]
+
+      # @param state [Proto::V1::NodeState] the node and its input artifact
+      # @return [Proto::V1::NodeState] the state with the redacted artifact
+      # @raise [MissingArtifact] when the input artifact is absent
+      # @raise [Glazed::Error] when reading, redacting or storing fails
+      #: (Proto::V1::NodeState state) -> Proto::V1::NodeState
+      def call(state)
+        node = state.node or raise ArgumentError, "#{name}: state has no node"
+        redactor = Redactor.from_proto(@redaction, patterns: Dialects.find(node.dialect).sensitive_patterns)
+        content = redactor.call(@context.read(artifact(state, @input)))
+        result = @storage.write(key: Storages.key_for(node), content:, message: "#{node.name}: #{name}")
+        with_artifacts(state, @output => stored(@storage_name, result))
+      end
+    end
+  end
+end

data/lib/glazed/steps/shell.rb

@@ -0,0 +1,107 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed/must'
+require 'glazed/proto'
+require 'glazed/proto_json'
+require 'glazed/shell_command'
+require 'glazed/steps'
+require 'glazed/storages'
+
+module Glazed
+  module Steps
+    # Per node: runs a command with /bin/sh -c. The input artifact's content is
+    # on stdin and stdout becomes the output artifact; both are optional.
+    #
+    # @example Step definition
+    #   {"name": "normalize", "shell": {"run": "sed -e '/^ntp clock-period/d'",
+    #    "input": "raw", "output": "normalized", "storage": "staging"}}
+    class Shell < NodeStep
+      # Seconds a command may run when the definition sets none.
+      DEFAULT_TIMEOUT = 300 #: Integer
+
+      # @param name [String] step name
+      # @param run [String] command line
+      # @param input [String, nil] artifact written to stdin
+      # @param output [String, nil] artifact produced from stdout
+      # @param storage_name [String, nil] storage for the output, by name
+      # @param context [StepContext] named storages
+      # @param timeout [Numeric] seconds before the command is killed
+      # @raise [StepContext::UnknownStorage] when the storage is not configured
+      #: (name: String, run: String, input: String?, output: String?, storage_name: String?, context: StepContext, ?timeout: Numeric) -> void
+      def initialize(name:, run:, input:, output:, storage_name:, context:, timeout: DEFAULT_TIMEOUT)
+        super(name:)
+        @run = run #: String
+        @input = input #: String?
+        @output = output #: String?
+        @storage_name = storage_name #: String?
+        @storage = (context.storage(storage_name) if storage_name) #: Storages::Base?
+        @context = context #: StepContext
+        @timeout = timeout #: Numeric
+      end
+
+      # Builds the step from {Proto::V1::ShellStep}.
+      #
+      # @param name [String] step name
+      # @param settings [Google::Protobuf::MessageExts] a {Proto::V1::ShellStep}
+      # @param context [StepContext] named storages
+      # @return [Shell] the step
+      #: (String name, Google::Protobuf::MessageExts settings, context: StepContext) -> Shell
+      def self.from_proto(name, settings, context:)
+        shell = Must.be_a(settings, Proto::V1::ShellStep)
+        new(
+          name:, run: shell.run, context:,
+          input: shell.input.empty? ? nil : shell.input,
+          output: shell.output.empty? ? nil : shell.output,
+          storage_name: shell.storage.empty? ? nil : shell.storage,
+          timeout: shell.timeout_seconds.zero? ? DEFAULT_TIMEOUT : shell.timeout_seconds,
+        )
+      end
+
+      # @return [Array<String>] the artifact written to stdin, if any
+      #: () -> Array[String]
+      def inputs = [@input].compact
+
+      # @return [Array<String>] the artifact produced from stdout, if any
+      #: () -> Array[String]
+      def outputs = [@output].compact
+
+      # @param state [Proto::V1::NodeState] the node and its artifacts
+      # @return [Proto::V1::NodeState] the state, with the output artifact when configured
+      # @raise [ShellCommand::Failed] when the command exits non-zero
+      # @raise [TimeoutError] when the command does not finish in time
+      # @raise [MissingArtifact] when the input artifact is absent
+      #: (Proto::V1::NodeState state) -> Proto::V1::NodeState
+      def call(state)
+        node = state.node or raise ArgumentError, "#{name}: state has no node"
+        input = @input
+        stdin = input ? @context.read(artifact(state, input)) : ''
+        stdout = ShellCommand.new(run: @run, env: env(node), stdin:, timeout: @timeout).call
+
+        output = @output
+        storage = @storage
+        storage_name = @storage_name
+        return state unless output && storage && storage_name
+
+        result = storage.write(key: Storages.key_for(node), content: stdout, message: "#{node.name}: #{name}")
+        with_artifacts(state, output => stored(storage_name, result))
+      end
+
+      # @param node [Proto::V1::Node] the node
+      # @return [Hash{String => String}] environment describing the step and node
+      #: (Proto::V1::Node node) -> Hash[String, String]
+      private def env(node)
+        {
+          'GLAZED_STEP' => name,
+          'GLAZED_NODE_NAME' => node.name,
+          'GLAZED_NODE_GROUP' => node.group,
+          'GLAZED_NODE_DIALECT' => node.dialect,
+          'GLAZED_NODE_HOST' => node.host.empty? ? node.name : node.host,
+          'GLAZED_NODE' => ProtoJson.dump(node),
+        }
+      end
+    end
+  end
+end

data/lib/glazed/steps.rb

@@ -0,0 +1,83 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed'
+require 'glazed/finder'
+require 'glazed/must'
+require 'glazed/plugin_registry'
+require 'glazed/proto'
+require 'glazed/step_context'
+require 'glazed/steps/base'
+require 'glazed/validation'
+
+module Glazed
+  # Units of work in a workflow. Each takes and returns a protobuf state
+  # ({Proto::V1::NodeState} or {Proto::V1::BatchState}), so a coordinator can
+  # pass them between processes as ProtoJSON.
+  module Steps
+    # Raised when a step definition is incomplete.
+    class InvalidStep < Glazed::Error; end
+
+    # Finds a step class by snake_case name.
+    #
+    # @param name [String, Symbol] step kind, such as "fetch"
+    # @return [Class<Base>] the step 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 step
+    #: (String | Symbol name) -> singleton(Base)
+    def self.find(name)
+      found = Finder.find(self, 'glazed/steps', name)
+      return found if found.is_a?(Class) && found < Base && found != NodeStep && found != BatchStep
+
+      raise Must::Violation, "#{found} is not a step"
+    end
+
+    # Steps implemented by plugins, by settings message type.
+    PLUGINS = PluginRegistry.new('step') #: PluginRegistry
+
+    # Registers a plugin step, selected by `plugin` steps whose settings are of the given type.
+    #
+    # @param settings_class [Class] generated message class of the step settings
+    # @param implementation [Class<NodeStep>, Class<BatchStep>] step built with {Base.from_proto}
+    # @return [void]
+    #: (singleton(Google::Protobuf::AbstractMessage) settings_class, singleton(Base) implementation) -> void
+    def self.register(settings_class, implementation)
+      PLUGINS.register(settings_class, implementation)
+    end
+
+    # Builds the step a definition selects.
+    #
+    # @param step [Proto::V1::Step] step definition
+    # @param context [StepContext] named storages the step refers to
+    # @return [Base] the step
+    # @raise [InvalidMessage] when the definition breaks the rules of its schema
+    # @raise [StepContext::UnknownStorage] when the step names an unknown storage
+    # @raise [PluginRegistry::UnknownPlugin] when no plugin is registered for the settings type
+    #: (Proto::V1::Step step, context: StepContext) -> Base
+    def self.build(step, context:)
+      Validation.validate!(step)
+      action = step.action or raise InvalidStep, "step #{step.name.inspect} sets no action"
+      if (packed = step.plugin)
+        implementation, settings = PLUGINS.resolve(packed)
+        return step_class(implementation).from_proto(step.name, settings, context:)
+      end
+
+      settings = Must.be_a(step[action.to_s], Google::Protobuf::MessageExts)
+      find(action).from_proto(step.name, settings, context:)
+    end
+
+    # @param implementation [Module] registered implementation
+    # @return [Class<Base>] the implementation as a step class
+    # @raise [Must::Violation] when it is not a per-node or batch step
+    #: (Module[untyped] implementation) -> singleton(Base)
+    private_class_method def self.step_class(implementation)
+      if implementation.is_a?(Class) && (implementation < NodeStep || implementation < BatchStep)
+        return implementation
+      end
+
+      raise Must::Violation, "#{implementation} is not a step"
+    end
+  end
+end

data/lib/glazed/storages/base.rb

@@ -0,0 +1,167 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'google/protobuf'
+require 'glazed'
+require 'glazed/must'
+require 'glazed/proto'
+
+module Glazed
+  module Storages
+    # Store of configuration files addressed by slash-separated keys, such as
+    # "core/rt1". Subclasses implement {.from_proto}, {#write_all} and {#read},
+    # and those reporting {#conditional?} also {#version_of}, {#read_versioned}
+    # and {#write_if}.
+    class Base
+      # Raised for a key that is empty or could escape the storage root.
+      class InvalidKey < Glazed::Error; end
+      # Raised by {#write_if} when the key no longer holds the expected version.
+      class Conflict < Glazed::Error; end
+
+      #: type file = [String, String]
+      #: type message_builder = ^(Array[String] changed_keys) -> String
+
+      # Outcome of writing one file.
+      class WriteResult
+        # @param pointer [Proto::V1::Pointer] location holding the content
+        # @param changed [Boolean] whether the content differs from what the key held before
+        #: (pointer: Proto::V1::Pointer, changed: bool) -> void
+        def initialize(pointer:, changed:)
+          @pointer = pointer #: Proto::V1::Pointer
+          @changed = changed #: bool
+        end
+
+        # @return [Proto::V1::Pointer] location holding the content; the existing one when unchanged
+        #: Proto::V1::Pointer
+        attr_reader :pointer
+
+        # @return [Boolean] whether the content differs from what the key held before
+        #: () -> bool
+        def changed? = @changed
+      end
+
+      # Content of a key together with the version that identifies it.
+      class Versioned
+        # @param content [String] the content
+        # @param version [String] opaque version, such as an ETag
+        #: (content: String, version: String) -> void
+        def initialize(content:, version:)
+          @content = content #: String
+          @version = version #: String
+        end
+
+        # @return [String] the content
+        #: String
+        attr_reader :content
+
+        # @return [String] opaque version, such as an ETag
+        #: String
+        attr_reader :version
+      end
+
+      # Builds a storage from its settings message.
+      #
+      # @param settings [Google::Protobuf::MessageExts] backend settings from {Proto::V1::StorageConfig}
+      # @return [Base] the storage
+      #: (Google::Protobuf::MessageExts settings) -> Base
+      def self.from_proto(settings) = raise NotImplementedError
+
+      # Writes one file.
+      #
+      # @param key [String] file key
+      # @param content [String] file content
+      # @param message [String] description of the change, such as a commit message
+      # @return [WriteResult] where the content is and whether it changed
+      # @raise [InvalidKey] for an unsafe key
+      #: (key: String, content: String, message: String) -> WriteResult
+      def write(key:, content:, message:)
+        write_all([[key, content]], message: ->(_changed_keys) { message }).fetch(0)
+      end
+
+      # Writes several files as one change where the storage supports it. Files
+      # whose content equals what their key holds are not written again.
+      #
+      # @param files [Array<Array(String, String)>] keys and contents
+      # @param message [Proc] builds the description of the change, such as a
+      #   commit message, from the keys whose content changed; not called when none did
+      # @return [Array<WriteResult>] results, in the order of files
+      # @raise [InvalidKey] for an unsafe key
+      #: (Array[Base::file] files, message: Base::message_builder) -> Array[WriteResult]
+      def write_all(files, message:) = raise NotImplementedError
+
+      # Reads content written earlier.
+      #
+      # @param pointer [Proto::V1::Pointer] location returned by a write
+      # @return [String] the content
+      #: (Proto::V1::Pointer pointer) -> String
+      def read(pointer) = raise NotImplementedError
+
+      # Whether the storage implements {#version_of}, {#read_versioned} and
+      # {#write_if}, so a single key can be updated by optimistic concurrency.
+      #
+      # @return [Boolean] true when supported
+      #: () -> bool
+      def conditional? = false
+
+      # Version the key currently holds, without reading the content.
+      #
+      # @param key [String] file key
+      # @return [String, nil] the version, or nil when the key is absent
+      # @raise [InvalidKey] for an unsafe key
+      #: (String key) -> String?
+      def version_of(key) = raise NotImplementedError
+
+      # Reads the current content of a key.
+      #
+      # @param key [String] file key
+      # @return [Versioned, nil] the content and its version, or nil when the key is absent
+      # @raise [InvalidKey] for an unsafe key
+      #: (String key) -> Versioned?
+      def read_versioned(key) = raise NotImplementedError
+
+      # Writes a key only if it still holds the expected version.
+      #
+      # @param key [String] file key
+      # @param content [String] new content
+      # @param expected_version [String, nil] version read earlier; nil to create a missing key only
+      # @return [String] version of the written content
+      # @raise [Conflict] when the key holds another version, or exists when nil was expected
+      # @raise [InvalidKey] for an unsafe key
+      #: (key: String, content: String, expected_version: String?) -> String
+      def write_if(key:, content:, expected_version:) = raise NotImplementedError
+
+      # Wraps a location in a pointer.
+      #
+      # @param location [Google::Protobuf::MessageExts] storage-specific location
+      # @return [Proto::V1::Pointer] the pointer
+      #: (Google::Protobuf::MessageExts location) -> Proto::V1::Pointer
+      private def pointer_to(location) = Proto::V1::Pointer.new(location: Google::Protobuf::Any.pack(location))
+
+      # Unwraps the location of a pointer.
+      #
+      # @param pointer [Proto::V1::Pointer] the pointer
+      # @param location_class [Class] location message this storage writes
+      # @return [Google::Protobuf::MessageExts] the location
+      # @raise [ArgumentError] when the pointer holds another kind of location
+      #: [L] (Proto::V1::Pointer pointer, Class[L] location_class) -> L
+      private def location_of(pointer, location_class)
+        any = pointer.location or raise ArgumentError, 'pointer has no location'
+        location = any.unpack(location_class) or raise ArgumentError, "#{self.class.name} cannot read a pointer to #{any.type_name}"
+        Must.be_a(location, location_class)
+      end
+
+      # @param key [String] key to check
+      # @return [String] the key
+      # @raise [InvalidKey] when the key is empty, absolute, or has empty, "." or ".." segments
+      #: (String key) -> String
+      private def validate_key(key)
+        segments = key.split('/', -1)
+        raise InvalidKey, "invalid storage key #{key.inspect}" if segments.empty? || segments.any? { ['', '.', '..'].include?(it) }
+
+        key
+      end
+    end
+  end
+end

data/lib/glazed/storages/filesystem.rb

@@ -0,0 +1,144 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'digest'
+require 'fileutils'
+require 'securerandom'
+require 'glazed'
+require 'glazed/must'
+require 'glazed/proto'
+require 'glazed/storages/base'
+
+module Glazed
+  module Storages
+    # Local directory holding the latest content of each key, for scripts and
+    # tools that read plain files. It keeps no history.
+    #
+    # @example
+    #   storage = Glazed::Storages::Filesystem.new(path: '/var/lib/glazed/latest')
+    #   storage.write(key: 'core/rt1', content: config, message: 'rt1')
+    class Filesystem < Base
+      # Raised when a file no longer holds the content its pointer names.
+      class StaleContent < Glazed::Error; end
+
+      # @param path [String] directory holding the files, created when missing
+      #: (path: String) -> void
+      def initialize(path:)
+        super()
+        @path = path #: String
+      end
+
+      # Builds a storage from {Proto::V1::FilesystemStorage}.
+      #
+      # @param settings [Google::Protobuf::MessageExts] a {Proto::V1::FilesystemStorage}
+      # @return [Filesystem] the storage
+      # @raise [Must::Violation] when settings is another message
+      #: (Google::Protobuf::MessageExts settings) -> Filesystem
+      def self.from_proto(settings)
+        filesystem = Must.be_a(settings, Proto::V1::FilesystemStorage)
+        new(path: filesystem.path)
+      end
+
+      # @return [String] directory holding the files
+      #: String
+      attr_reader :path
+
+      # Writes each changed file in place. A file is replaced atomically, so
+      # readers see either the old or the new content.
+      #
+      # @param files [Array<Array(String, String)>] keys and contents
+      # @param message [Proc] builds a description of the change, unused
+      # @return [Array<WriteResult>] the content's location and digest, and whether the file changed
+      # @raise [InvalidKey] for an unsafe key
+      #: (Array[Base::file] files, message: Base::message_builder) -> Array[WriteResult]
+      def write_all(files, message:)
+        files.each { |key, _| validate_key(key) }
+        files.map do |key, content|
+          file = ::File.join(path, key)
+          changed = !(::File.file?(file) && ::File.binread(file) == content.b)
+          replace(file, content) if changed
+          pointer = pointer_to(Proto::V1::FilesystemLocation.new(path: key, sha256: Digest::SHA256.hexdigest(content)))
+          WriteResult.new(pointer:, changed:)
+        end
+      end
+
+      # Reads the file a pointer names.
+      #
+      # @param pointer [Proto::V1::Pointer] pointer with a filesystem location
+      # @return [String] the content
+      # @raise [ArgumentError] when the pointer is not a filesystem location
+      # @raise [StaleContent] when the file has been rewritten with other content since
+      # @raise [Errno::ENOENT] when the file is gone
+      #: (Proto::V1::Pointer pointer) -> String
+      def read(pointer)
+        location = location_of(pointer, Proto::V1::FilesystemLocation)
+        content = ::File.read(::File.join(path, validate_key(location.path)))
+        unless Digest::SHA256.hexdigest(content) == location.sha256
+          raise StaleContent, "#{location.path} in #{path} no longer holds the content written"
+        end
+
+        content
+      end
+
+      # @return [Boolean] true; versions are content digests
+      #: () -> bool
+      def conditional? = true
+
+      # @param key [String] file key
+      # @return [String, nil] SHA-256 of the file, or nil when it is missing
+      # @raise [InvalidKey] for an unsafe key
+      #: (String key) -> String?
+      def version_of(key) = read_versioned(key)&.version
+
+      # @param key [String] file key
+      # @return [Versioned, nil] the content and its SHA-256, or nil when the file is missing
+      # @raise [InvalidKey] for an unsafe key
+      #: (String key) -> Versioned?
+      def read_versioned(key)
+        content = ::File.binread(::File.join(path, validate_key(key)))
+        Versioned.new(content:, version: Digest::SHA256.hexdigest(content))
+      rescue Errno::ENOENT
+        nil
+      end
+
+      # Replaces the file while holding an exclusive lock on a sibling lock
+      # file, which every conditional writer of the key takes.
+      #
+      # @param key [String] file key
+      # @param content [String] new content
+      # @param expected_version [String, nil] SHA-256 read earlier; nil to create a missing file only
+      # @return [String] SHA-256 of the content
+      # @raise [Conflict] when the file holds other content
+      # @raise [InvalidKey] for an unsafe key
+      #: (key: String, content: String, expected_version: String?) -> String
+      def write_if(key:, content:, expected_version:)
+        file = ::File.join(path, validate_key(key))
+        FileUtils.mkdir_p(::File.dirname(file))
+        ::File.open(::File.join(::File.dirname(file), ".#{::File.basename(file)}.lock"), ::File::RDWR | ::File::CREAT, 0o644) do |lock|
+          lock.flock(::File::LOCK_EX)
+          current = version_of(key)
+          raise Conflict, "#{key} in #{path} is at #{current || 'nothing'}, not #{expected_version || 'nothing'}" unless current == expected_version
+
+          replace(file, content)
+        end
+        Digest::SHA256.hexdigest(content)
+      end
+
+      # @param file [String] file to replace
+      # @param content [String] new content
+      # @return [void]
+      #: (String file, String content) -> void
+      private def replace(file, content)
+        dir = ::File.dirname(file)
+        FileUtils.mkdir_p(dir)
+        temporary = ::File.join(dir, ".#{::File.basename(file)}.#{SecureRandom.hex(8)}.tmp")
+        ::File.binwrite(temporary, content)
+        ::File.rename(temporary, file)
+      ensure
+        ::File.unlink(temporary) if temporary && ::File.exist?(temporary)
+      end
+    end
+  end
+end