glazed 0.1.0

data/lib/glazed/storages/git.rb

@@ -0,0 +1,181 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'fileutils'
+require 'open3'
+require 'glazed'
+require 'glazed/must'
+require 'glazed/proto'
+require 'glazed/storages/base'
+
+module Glazed
+  module Storages
+    # Local git repository driven by the git command. Each write is one commit
+    # on the configured branch, optionally pulled before and pushed after.
+    #
+    # @example
+    #   storage = Glazed::Storages::Git.new(path: '/var/lib/glazed/raw')
+    #   storage.write(key: 'core/rt1', content: config, message: 'rt1')
+    class Git < Base
+      # Raised when a git command fails.
+      class CommandFailed < Glazed::Error; end
+
+      # Branch used when none is configured.
+      DEFAULT_BRANCH = 'main' #: String
+      # Author name used when none is configured.
+      DEFAULT_AUTHOR_NAME = 'glazed' #: String
+      # Author email used when none is configured.
+      DEFAULT_AUTHOR_EMAIL = 'glazed@localhost' #: String
+
+      # @param path [String] working tree, initialised when missing
+      # @param branch [String] branch to commit to
+      # @param remote [String, nil] remote name or URL to pull from and push to
+      # @param author_name [String] commit author and committer name
+      # @param author_email [String] commit author and committer email
+      #: (path: String, ?branch: String, ?remote: String?, ?author_name: String, ?author_email: String) -> void
+      def initialize(path:, branch: DEFAULT_BRANCH, remote: nil, author_name: DEFAULT_AUTHOR_NAME, author_email: DEFAULT_AUTHOR_EMAIL)
+        super()
+        @path = path #: String
+        @branch = branch #: String
+        @remote = remote #: String?
+        @author_name = author_name #: String
+        @author_email = author_email #: String
+        @lock = Mutex.new #: Thread::Mutex
+      end
+
+      # Builds a storage from {Proto::V1::GitStorage}.
+      #
+      # @param settings [Google::Protobuf::MessageExts] a {Proto::V1::GitStorage}
+      # @return [Git] the storage
+      # @raise [Must::Violation] when settings is another message
+      #: (Google::Protobuf::MessageExts settings) -> Git
+      def self.from_proto(settings)
+        git = Must.be_a(settings, Proto::V1::GitStorage)
+        new(
+          path: git.path,
+          branch: git.branch.empty? ? DEFAULT_BRANCH : git.branch,
+          remote: git.remote.empty? ? nil : git.remote,
+          author_name: git.author_name.empty? ? DEFAULT_AUTHOR_NAME : git.author_name,
+          author_email: git.author_email.empty? ? DEFAULT_AUTHOR_EMAIL : git.author_email,
+        )
+      end
+
+      # @return [String] working tree
+      #: String
+      attr_reader :path
+      # @return [String] branch to commit to
+      #: String
+      attr_reader :branch
+      # @return [String, nil] remote name or URL
+      #: String?
+      attr_reader :remote
+
+      # Writes files in one commit. Nothing is committed when no content
+      # changed, and the pointers then name the existing HEAD.
+      #
+      # @param files [Array<Array(String, String)>] keys and contents
+      # @param message [Proc] builds the commit message from the changed keys
+      # @return [Array<WriteResult>] the commit holding each file, and whether the file changed
+      # @raise [InvalidKey] for an unsafe key
+      # @raise [CommandFailed] when a git command fails
+      #: (Array[Base::file] files, message: Base::message_builder) -> Array[WriteResult]
+      def write_all(files, message:)
+        keys = files.map { |key, _| validate_key(key) }
+        @lock.synchronize do
+          prepare
+          files.each do |key, content|
+            file = File.join(path, key)
+            FileUtils.mkdir_p(File.dirname(file))
+            File.write(file, content)
+          end
+          git(['add', '--', *keys])
+          changed = git(['diff', '--cached', '--name-only', '-z', '--', *keys]).split("\0")
+          unless changed.empty?
+            git(['commit', '--quiet', '--no-verify', '-m', message.call(changed)])
+            git(['push', '--quiet', Must.expect(remote), "HEAD:refs/heads/#{branch}"]) if remote
+          end
+          commit = git(%w[rev-parse HEAD]).strip
+          keys.map do |key|
+            WriteResult.new(pointer: pointer_to(Proto::V1::GitLocation.new(path: key, commit:)), changed: changed.include?(key))
+          end
+        end
+      end
+
+      # Reads a file at the commit a pointer names.
+      #
+      # @param pointer [Proto::V1::Pointer] pointer with a git location
+      # @return [String] the content
+      # @raise [ArgumentError] when the pointer is not a git location
+      # @raise [CommandFailed] when the commit or path does not exist
+      #: (Proto::V1::Pointer pointer) -> String
+      def read(pointer)
+        location = location_of(pointer, Proto::V1::GitLocation)
+        git(['show', "#{location.commit}:#{validate_key(location.path)}"])
+      end
+
+      # Initialises the repository when missing, switches to the branch and
+      # pulls it from the remote when it exists there.
+      #
+      # @return [void]
+      # @raise [CommandFailed] when a git command fails
+      #: () -> void
+      private def prepare
+        unless File.exist?(File.join(path, '.git'))
+          FileUtils.mkdir_p(path)
+          git(['init', '--quiet', "--initial-branch=#{branch}"])
+        end
+        unless run_git(%w[symbolic-ref --quiet --short HEAD])[0].strip == branch
+          git_success?(['switch', '--quiet', branch]) || git(['switch', '--quiet', '--create', branch])
+        end
+        pull if remote
+      end
+
+      # @return [void]
+      # @raise [CommandFailed] when the pull fails
+      #: () -> void
+      private def pull
+        remote = Must.expect(self.remote)
+        return unless git_success?(['ls-remote', '--exit-code', '--heads', remote, branch])
+
+        git(['pull', '--quiet', '--ff-only', remote, branch])
+      end
+
+      # @param args [Array<String>] git arguments
+      # @return [String] standard output
+      # @raise [CommandFailed] when git exits non-zero, with its error output
+      #: (Array[String] args) -> String
+      private def git(args)
+        output, status = run_git(args)
+        raise CommandFailed, "git #{args.first} failed in #{path}: #{output.strip}" unless status.success?
+
+        output
+      end
+
+      # @param args [Array<String>] git arguments
+      # @return [Boolean] whether git exits zero
+      #: (Array[String] args) -> bool
+      private def git_success?(args) = run_git(args)[1].success? || false
+
+      # @param args [Array<String>] git arguments
+      # @return [Array(String, Process::Status)] output with errors merged in, and exit status
+      #: (Array[String] args) -> [String, Process::Status]
+      private def run_git(args)
+        output = IO.popen(git_env, ['git', *args], chdir: path, err: %i[child out], &:read)
+        [output, Process.last_status]
+      end
+
+      # @return [Hash{String => String}] environment fixing the identity used for commits
+      #: () -> Hash[String, String]
+      private def git_env
+        {
+          'GIT_AUTHOR_NAME' => @author_name,
+          'GIT_AUTHOR_EMAIL' => @author_email,
+          'GIT_COMMITTER_NAME' => @author_name,
+          'GIT_COMMITTER_EMAIL' => @author_email,
+        }
+      end
+    end
+  end
+end

data/lib/glazed/storages/github.rb

@@ -0,0 +1,269 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'digest'
+require 'httpx'
+require 'uri'
+require 'glazed'
+require 'glazed/must'
+require 'glazed/proto'
+require 'glazed/secret'
+require 'glazed/storages/base'
+require 'glazed/version'
+
+module Glazed
+  module Storages
+    # GitHub repository written through the Git Data API. Each write is one
+    # commit on the branch, which is created from the base branch when missing.
+    #
+    # @example
+    #   storage = Glazed::Storages::Github.new(repository: 'org/netconf', branch: 'glazed/auto', token:)
+    #   storage.write(key: 'core/rt1', content: config, message: 'rt1')
+    class Github < Base
+      # Raised when the API answers with an error status.
+      class ApiError < Glazed::Error
+        # @param status [Integer] HTTP status
+        # @param message [String] error description
+        #: (status: Integer, message: String) -> void
+        def initialize(status:, message:)
+          super(message)
+          @status = status #: Integer
+        end
+
+        # @return [Integer] HTTP status
+        #: Integer
+        attr_reader :status
+      end
+
+      # API endpoint used when none is configured.
+      DEFAULT_API_URL = 'https://api.github.com' #: String
+      # Attempts at moving the branch when another writer moved it first.
+      MAX_ATTEMPTS = 3 #: Integer
+      # REST API version requested.
+      API_VERSION = '2022-11-28' #: String
+
+      # @param repository [String] repository as "owner/name"
+      # @param branch [String] branch to commit to
+      # @param token [Secret] token with contents write permission
+      # @param base_branch [String, nil] branch to start a missing branch from; the default branch when nil
+      # @param api_url [String] API endpoint
+      # @param author_name [String, nil] commit author name; the token owner when nil
+      # @param author_email [String, nil] commit author email; the token owner when nil
+      #: (repository: String, branch: String, token: Secret, ?base_branch: String?, ?api_url: String, ?author_name: String?, ?author_email: String?) -> void
+      def initialize(repository:, branch:, token:, base_branch: nil, api_url: DEFAULT_API_URL, author_name: nil, author_email: nil)
+        super()
+        @repository = repository #: String
+        @branch = branch #: String
+        @token = token #: Secret
+        @base_branch = base_branch #: String?
+        @api_url = api_url.chomp('/') #: String
+        @author = (author_name && author_email ? {name: author_name, email: author_email} : nil) #: Hash[Symbol, String]?
+        @http = nil #: HTTPX::Session?
+      end
+
+      # Builds a storage from {Proto::V1::GithubStorage}.
+      #
+      # @param settings [Google::Protobuf::MessageExts] a {Proto::V1::GithubStorage}
+      # @return [Github] the storage
+      # @raise [Must::Violation] when settings is another message
+      # @raise [ArgumentError] when the token is missing
+      #: (Google::Protobuf::MessageExts settings) -> Github
+      def self.from_proto(settings)
+        github = Must.be_a(settings, Proto::V1::GithubStorage)
+        new(
+          repository: github.repository,
+          branch: github.branch,
+          token: Secret.maybe(github.token) || raise(ArgumentError, 'github storage needs a token'),
+          base_branch: github.base_branch.empty? ? nil : github.base_branch,
+          api_url: github.api_url.empty? ? DEFAULT_API_URL : github.api_url,
+          author_name: github.author_name.empty? ? nil : github.author_name,
+          author_email: github.author_email.empty? ? nil : github.author_email,
+        )
+      end
+
+      # @return [String] repository as "owner/name"
+      #: String
+      attr_reader :repository
+      # @return [String] branch to commit to
+      #: String
+      attr_reader :branch
+
+      # Writes the changed files in one commit. Nothing is committed when no
+      # content changed, and the pointers then name the existing head.
+      #
+      # @param files [Array<Array(String, String)>] keys and contents
+      # @param message [Proc] builds the commit message from the changed keys
+      # @return [Array<WriteResult>] the commit holding each file, and whether the file changed
+      # @raise [InvalidKey] for an unsafe key
+      # @raise [ApiError] when the API fails, or the branch keeps moving under concurrent writers
+      #: (Array[Base::file] files, message: Base::message_builder) -> Array[WriteResult]
+      def write_all(files, message:)
+        keys = files.map { |key, _| validate_key(key) }
+        commit, changed = with_retries { commit_files(files, message) }
+        keys.map do |key|
+          pointer = pointer_to(Proto::V1::GithubLocation.new(repository:, path: key, commit:))
+          WriteResult.new(pointer:, changed: changed.include?(key))
+        end
+      end
+
+      # Reads a file at the commit a pointer names.
+      #
+      # @param pointer [Proto::V1::Pointer] pointer with a github location
+      # @return [String] the content
+      # @raise [ArgumentError] when the pointer is not a github location
+      # @raise [ApiError] when the file or commit does not exist
+      #: (Proto::V1::Pointer pointer) -> String
+      def read(pointer)
+        location = location_of(pointer, Proto::V1::GithubLocation)
+        path = "/repos/#{location.repository}/contents/#{escape(validate_key(location.path))}?ref=#{escape(location.commit)}"
+        check(http.get(url(path), headers: {'accept' => 'application/vnd.github.raw+json'})).body.to_s
+      end
+
+      # @yieldreturn [Object] result of one attempt
+      # @return [Object] result of the first attempt that succeeded
+      # @raise [ApiError] when attempts run out
+      #: [T] () { () -> T } -> T
+      private def with_retries(&attempt)
+        attempts = 0
+        begin
+          attempts += 1
+          attempt.call
+        rescue ApiError => e
+          # 422 means the branch moved or appeared between reading and updating it.
+          retry if e.status == 422 && attempts < MAX_ATTEMPTS
+          raise
+        end
+      end
+
+      # @param files [Array<Array(String, String)>] keys and contents
+      # @param message [Proc] builds the commit message from the changed keys
+      # @return [Array(String, Array<String>)] SHA of the commit holding the files, and the changed keys
+      # @raise [ApiError] when the API fails
+      #: (Array[Base::file] files, Base::message_builder message) -> [String, Array[String]]
+      private def commit_files(files, message)
+        head = ref_sha(branch)
+        parent = head || ref_sha(base_branch) || raise(ApiError.new(status: 404, message: "#{repository}: base branch #{base_branch} not found"))
+        base_tree = json(get("/repos/#{repository}/git/commits/#{parent}")).dig('tree', 'sha')
+        existing = blob_shas(base_tree)
+        candidates = existing ? files.reject { |key, content| existing[key] == blob_sha(content) } : files
+
+        commit = parent
+        changed = [] #: Array[String]
+        unless candidates.empty?
+          entries = candidates.map { |key, content| {path: key, mode: '100644', type: 'blob', content:} }
+          tree = json(post("/repos/#{repository}/git/trees", {base_tree:, tree: entries})).fetch('sha')
+          unless tree == base_tree
+            changed = candidates.map(&:first)
+            body = {message: message.call(changed), tree:, parents: [parent], author: @author}.compact
+            commit = json(post("/repos/#{repository}/git/commits", body)).fetch('sha')
+          end
+        end
+
+        if head.nil?
+          post("/repos/#{repository}/git/refs", {ref: "refs/heads/#{branch}", sha: commit})
+        elsif commit != head
+          patch("/repos/#{repository}/git/refs/heads/#{escape(branch)}", {sha: commit, force: false})
+        end
+        [commit, changed]
+      end
+
+      # @param tree [String] tree SHA
+      # @return [Hash{String => String}, nil] blob SHAs by path, or nil when GitHub truncates the listing
+      # @raise [ApiError] when the tree cannot be read
+      #: (String tree) -> Hash[String, String]?
+      private def blob_shas(tree)
+        listing = json(get("/repos/#{repository}/git/trees/#{tree}?recursive=1"))
+        return nil if listing['truncated']
+
+        entries = listing.fetch('tree') #: Array[Hash[String, String]]
+        entries.select { it['type'] == 'blob' }.to_h { [it.fetch('path'), it.fetch('sha')] }
+      end
+
+      # @param content [String] file content
+      # @return [String] git blob SHA-1 of the content
+      #: (String content) -> String
+      private def blob_sha(content) = Digest::SHA1.hexdigest("blob #{content.bytesize}\0".b + content.b)
+
+      # @param name [String] branch name
+      # @return [String, nil] SHA the branch points to, or nil when it does not exist
+      # @raise [ApiError] for errors other than not found
+      #: (String name) -> String?
+      private def ref_sha(name)
+        json(get("/repos/#{repository}/git/ref/heads/#{escape(name)}")).dig('object', 'sha')
+      rescue ApiError => e
+        raise unless e.status == 404
+
+        nil
+      end
+
+      # @return [String] the configured base branch, or the repository default branch
+      # @raise [ApiError] when the repository cannot be read
+      #: () -> String
+      private def base_branch
+        @base_branch ||= json(get("/repos/#{repository}")).fetch('default_branch')
+      end
+
+      # @param path [String] API path
+      # @return [HTTPX::Response] the successful response
+      # @raise [ApiError] for an error status
+      #: (String path) -> HTTPX::Response
+      private def get(path) = check(http.get(url(path)))
+
+      # @param path [String] API path
+      # @param body [Hash] JSON body
+      # @return [HTTPX::Response] the successful response
+      # @raise [ApiError] for an error status
+      #: (String path, Hash[Symbol, untyped] body) -> HTTPX::Response
+      private def post(path, body) = check(http.post(url(path), json: body))
+
+      # @param path [String] API path
+      # @param body [Hash] JSON body
+      # @return [HTTPX::Response] the successful response
+      # @raise [ApiError] for an error status
+      #: (String path, Hash[Symbol, untyped] body) -> HTTPX::Response
+      private def patch(path, body) = check(http.patch(url(path), json: body))
+
+      # @param response [HTTPX::Response] successful response
+      # @return [Hash] its decoded JSON body
+      #: (HTTPX::Response response) -> Hash[String, untyped]
+      private def json(response) = response.json
+
+      # @param response [HTTPX::Response, HTTPX::ErrorResponse] response to check
+      # @return [HTTPX::Response] the response when its status is below 400
+      # @raise [ApiError] for an error status
+      # @raise [HTTPX::Error] for a transport failure
+      #: (HTTPX::Response | HTTPX::ErrorResponse response) -> HTTPX::Response
+      private def check(response)
+        raise response.error if response.is_a?(HTTPX::ErrorResponse)
+        return response if response.status < 400
+
+        raise ApiError.new(status: response.status, message: "#{repository}: #{response.uri.path} returned #{response.status}: #{response.body}")
+      end
+
+      # @param path [String] API path starting with "/"
+      # @return [String] absolute URL
+      #: (String path) -> String
+      private def url(path) = "#{@api_url}#{path}"
+
+      # @param value [String] slash-separated value
+      # @return [String] each segment percent-encoded
+      #: (String value) -> String
+      private def escape(value) = value.split('/', -1).map { URI.encode_uri_component(it) }.join('/')
+
+      # @return [HTTPX::Session] session with authentication headers
+      #: () -> HTTPX::Session
+      private def http
+        @http ||= HTTPX.plugin(:retries).with(
+          headers: {
+            'accept' => 'application/vnd.github+json',
+            'authorization' => "Bearer #{@token.value}",
+            'user-agent' => "glazed/#{Glazed::VERSION}",
+            'x-github-api-version' => API_VERSION,
+          },
+        )
+      end
+    end
+  end
+end

data/lib/glazed/storages/memory.rb

@@ -0,0 +1,125 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'digest'
+require 'glazed'
+require 'glazed/must'
+require 'glazed/proto'
+require 'glazed/storages/base'
+
+module Glazed
+  module Storages
+    # Memory of the running process, for content that must not be persisted,
+    # such as raw configuration when only the redacted copy is kept. Content
+    # lives until the process exits, so only steps of the same run can read it.
+    #
+    # @example Storage config
+    #   {"memory": {}}
+    class Memory < Base
+      # Raised when a pointer names content this process does not hold.
+      class MissingContent < Glazed::Error; end
+
+      #: () -> void
+      def initialize
+        super
+        @contents = {} #: Hash[String, String]
+        @latest = {} #: Hash[String, String]
+        @lock = Mutex.new #: Thread::Mutex
+      end
+
+      # Builds a storage from {Proto::V1::MemoryStorage}.
+      #
+      # @param settings [Google::Protobuf::MessageExts] a {Proto::V1::MemoryStorage}
+      # @return [Memory] the storage
+      # @raise [Must::Violation] when settings is another message
+      #: (Google::Protobuf::MessageExts settings) -> Memory
+      def self.from_proto(settings)
+        Must.be_a(settings, Proto::V1::MemoryStorage)
+        new
+      end
+
+      # Keeps each file in memory. A file is changed unless this process
+      # already wrote the same content under its key.
+      #
+      # @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 key and digest, and whether it 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|
+          sha256 = Digest::SHA256.hexdigest(content)
+          changed = @lock.synchronize do
+            @contents[sha256] = content.dup.freeze
+            previous = @latest[key]
+            @latest[key] = sha256
+            previous != sha256
+          end
+          WriteResult.new(pointer: pointer_to(Proto::V1::MemoryLocation.new(key:, sha256:)), changed:)
+        end
+      end
+
+      # @return [Boolean] true; versions are content digests
+      #: () -> bool
+      def conditional? = true
+
+      # @param key [String] file key
+      # @return [String, nil] SHA-256 of the latest content, or nil when nothing was written
+      # @raise [InvalidKey] for an unsafe key
+      #: (String key) -> String?
+      def version_of(key)
+        validate_key(key)
+        @lock.synchronize { @latest[key] }
+      end
+
+      # @param key [String] file key
+      # @return [Versioned, nil] the latest content and its SHA-256, or nil when nothing was written
+      # @raise [InvalidKey] for an unsafe key
+      #: (String key) -> Versioned?
+      def read_versioned(key)
+        validate_key(key)
+        @lock.synchronize do
+          sha256 = @latest[key]
+          Versioned.new(content: @contents.fetch(sha256), version: sha256) if sha256
+        end
+      end
+
+      # @param key [String] file key
+      # @param content [String] new content
+      # @param expected_version [String, nil] SHA-256 read earlier; nil to create a missing key only
+      # @return [String] SHA-256 of the content
+      # @raise [Conflict] when the key holds other content
+      # @raise [InvalidKey] for an unsafe key
+      #: (key: String, content: String, expected_version: String?) -> String
+      def write_if(key:, content:, expected_version:)
+        validate_key(key)
+        sha256 = Digest::SHA256.hexdigest(content)
+        @lock.synchronize do
+          current = @latest[key]
+          raise Conflict, "#{key} is at #{current || 'nothing'}, not #{expected_version || 'nothing'}" unless current == expected_version
+
+          @contents[sha256] = content.dup.freeze
+          @latest[key] = sha256
+        end
+        sha256
+      end
+
+      # Reads content written earlier by this process.
+      #
+      # @param pointer [Proto::V1::Pointer] pointer with a memory location
+      # @return [String] the content
+      # @raise [ArgumentError] when the pointer is not a memory location
+      # @raise [MissingContent] when this process did not write the content, for
+      #   example when the pointer comes from another process
+      #: (Proto::V1::Pointer pointer) -> String
+      def read(pointer)
+        location = location_of(pointer, Proto::V1::MemoryLocation)
+        content = @lock.synchronize { @contents[location.sha256] }
+        content or raise MissingContent, "#{location.key} is not held in this process; memory storage only works within one glazed run"
+      end
+    end
+  end
+end

data/lib/glazed/storages.rb

@@ -0,0 +1,88 @@
+# 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/storages/base'
+require 'glazed/validation'
+
+module Glazed
+  # Namespace of storage implementations, looked up by name.
+  module Storages
+    # Raised when a storage config names no backend.
+    class MissingBackend < Glazed::Error; end
+
+    # Finds a storage class by snake_case name.
+    #
+    # @param name [String, Symbol] storage name, such as "git"
+    # @return [Class<Base>] the storage 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 storage
+    #: (String | Symbol name) -> singleton(Base)
+    def self.find(name)
+      found = Finder.find(self, 'glazed/storages', name)
+      return found if found.is_a?(Class) && found < Base
+
+      raise Must::Violation, "#{found} is not a storage"
+    end
+
+    # Storages implemented by plugins, by settings message type.
+    PLUGINS = PluginRegistry.new('storage') #: PluginRegistry
+
+    # Registers a plugin storage, selected by `plugin` configs whose settings
+    # are of the given type. Its pointers carry their own location message in
+    # the `plugin` case of {Proto::V1::Pointer}.
+    #
+    # @param settings_class [Class] generated message class of the storage settings
+    # @param implementation [Class<Base>] storage 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 storage a config selects.
+    #
+    # @param config [Proto::V1::StorageConfig] storage settings
+    # @return [Base] the storage
+    # @raise [InvalidMessage] when the config breaks the rules of its schema
+    # @raise [Finder::NotFound] when the backend is not available
+    # @raise [PluginRegistry::UnknownPlugin] when no plugin is registered for the settings type
+    #: (Proto::V1::StorageConfig config) -> Base
+    def self.build(config)
+      Validation.validate!(config)
+      backend = config.backend or raise MissingBackend, 'storage config sets no backend'
+      if (packed = config.plugin)
+        implementation, settings = PLUGINS.resolve(packed)
+        return storage_class(implementation).from_proto(settings)
+      end
+
+      settings = Must.be_a(config[backend.to_s], Google::Protobuf::MessageExts)
+      find(backend).from_proto(settings)
+    end
+
+    # @param implementation [Module] registered implementation
+    # @return [Class<Base>] the implementation as a storage class
+    # @raise [Must::Violation] when it is not a storage
+    #: (Module[untyped] implementation) -> singleton(Base)
+    private_class_method def self.storage_class(implementation)
+      return implementation if implementation.is_a?(Class) && implementation < Base
+
+      raise Must::Violation, "#{implementation} is not a storage"
+    end
+
+    # Storage key of a node, "group/name" or just "name" without a group.
+    #
+    # @param node [Proto::V1::Node] the node
+    # @return [String] the key
+    #: (Proto::V1::Node node) -> String
+    def self.key_for(node)
+      node.group.empty? ? node.name : "#{node.group}/#{node.name}"
+    end
+  end
+end