active_sanction 1.0.0

data/lib/active_sanction/storage/file_system.rb

@@ -0,0 +1,373 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "fileutils"
+require "json"
+require "securerandom"
+require "zlib"
+require "active_sanction/configuration"
+require "active_sanction/snapshot"
+require "active_sanction/sources"
+require "active_sanction/storage"
+require "active_sanction/storage/base"
+require "active_sanction/storage/meta"
+
+module ActiveSanction
+  module Storage
+    # Snapshots as gzipped JSON in a directory. The default adapter, and the
+    # reason this gem screens a name without an application having provisioned
+    # anything first.
+    #
+    #   store = ActiveSanction::Storage::FileSystem.new           # ~/.active_sanction
+    #   store = ActiveSanction::Storage::FileSystem.new(root: "/srv/lists")
+    #
+    #   store.write_snapshot(ActiveSanction::Sources[:ofac_sdn].new.sync)
+    #   store.snapshot_meta(:ofac_sdn).age   # without opening the list
+    #   store.read_snapshot(:ofac_sdn)       # => Snapshot, checksum verified
+    #
+    # Nothing here is required. `zlib` and `json` are stdlib, so the cost of
+    # persisting 19,015 OFAC records is a directory -- which is what makes this
+    # usable from a cron job, a CLI (#36), a CI run, and an air-gapped host
+    # that only ever gets a copied directory. Storage::ActiveRecord (#25) is
+    # for an installation that already has a database and wants to query the
+    # lists; it is not a prerequisite for using this library.
+    #
+    # ### The layout is private
+    #
+    # Under #62 the contents of `root` are `@api private`. What is on disk is
+    # optimized for reading and rewriting locally, and it is expected to change
+    # -- the portable, cross-machine, signature-verified representation is the
+    # bundle format (#57), which has its own stability contract and is specified
+    # in docs/bundle_format.md. An application that reads these files itself
+    # makes every future storage optimization a breaking change for it.
+    #
+    # As it stands:
+    #
+    #     root/ofac_sdn/meta.json
+    #     root/ofac_sdn/snapshot-sha256-9f86d081884c7d65....json.gz
+    #
+    # ### Why the snapshot file is named after its checksum
+    #
+    # Because "a sync interrupted mid-write leaves the previous good snapshot
+    # intact" cannot be honoured by two files at fixed names. Replacing a list
+    # means replacing both the list and the sidecar describing it, and whatever
+    # order those two renames happen in, a process killed between them leaves a
+    # snapshot and a meta that do not describe each other -- the new list under
+    # the old checksum, or a sidecar advertising records that are not there.
+    # Either way the previous list is gone and the source is unreadable until
+    # the next successful sync.
+    #
+    # Naming the list file after the content it holds removes the conflict. A
+    # new list is written to a name nothing else occupies, so it cannot destroy
+    # the list already there, and `meta.json` -- one small file, replaced by one
+    # atomic rename -- is the single point at which the new generation becomes
+    # the live one. Interrupt anywhere before that rename and the store is
+    # exactly as it was, plus a stray file the next write sweeps. Interrupt
+    # after it and the new list is live and complete. There is no third state.
+    #
+    # This is the pattern PayloadCache uses for raw payloads, for the same
+    # reason and with the same tradeoff: a brief second copy on disk.
+    #
+    # ### What it refuses to do
+    #
+    # Return anything it cannot prove. `Snapshot.from_h` re-derives the
+    # checksum from the records that came back and construction fails if it
+    # does not match what was stored, so a truncated file, an edited file and a
+    # half-written file all raise CorruptSnapshot instead of screening against
+    # a list that is missing records. A schema version this code does not know
+    # raises UnsupportedSchema *before* the list is parsed, since a snapshot
+    # from a newer gem will usually deserialize into a valid-looking, quietly
+    # wrong record set.
+    #
+    # ### Concurrency
+    #
+    # Many readers and one writer, across processes, which is the arrangement
+    # it exists for: a scheduled sync replacing a list while web workers screen
+    # against it. Committing is a rename, so a reader sees the whole previous
+    # generation or the whole new one; a reader that had already read the old
+    # `meta.json` when the new one landed re-reads it if the file it was sent
+    # to has since been swept.
+    #
+    # Two processes writing the *same* source at once is not supported and is
+    # not made safe by anything here -- run one sync.
+    class FileSystem < Base
+      extend T::Sig
+
+      # The sidecar, and the commit point. Its presence is what makes a
+      # directory a stored source, and replacing it is what publishes a write.
+      #
+      # @api private
+      META_FILENAME = T.let("meta.json", String)
+
+      # @api private
+      SNAPSHOT_PREFIX = T.let("snapshot-", String)
+      # @api private
+      SNAPSHOT_EXTENSION = T.let(".json.gz", String)
+
+      # Snapshot versions this code can read. Anything above the version it
+      # writes was produced by a newer gem; anything at or below it round-trips
+      # through Snapshot.from_h, which folds the version into the checksum it
+      # verifies, so a list cannot be read under a schema it was not written
+      # under without the mismatch being caught.
+      #
+      # @api private
+      READABLE_SCHEMA_VERSIONS = T.let(1..Snapshot::SCHEMA_VERSION, T::Range[Integer])
+
+      # Zlib's default, not its best. A parsed OFAC list is tens of megabytes
+      # of highly repetitive JSON that gzip already reduces by better than 90%;
+      # the last few points cost several seconds of a sync and buy a rounding
+      # error of disk.
+      #
+      # @api private
+      COMPRESSION_LEVEL = T.let(Zlib::DEFAULT_COMPRESSION, Integer)
+
+      # A checksum becomes a filename, so it is matched rather than sanitized:
+      # this is the one place a value read back off disk is joined to a path,
+      # and `sha256:<64 hex>` is the only shape allowed through.
+      #
+      # @api private
+      CHECKSUM_PATTERN = T.let(/\A#{Snapshot::ALGORITHM}:(\h{64})\z/, Regexp)
+
+      # A directory is only a source if it is named like one. Held to the rule
+      # source keys are held to everywhere, so an unrelated directory a user
+      # left under `root` is not reported as a sanctions list.
+      #
+      # @api private
+      SOURCE_PATTERN = T.let(Sources::Definition::KEY_PATTERN, Regexp)
+
+      # How long a `.part` file from a killed write is left alone before the
+      # next write sweeps it. Well past any real write and short of leaving
+      # abandoned megabytes on disk forever.
+      #
+      # @api private
+      ORPHAN_GRACE = T.let(3600, Integer)
+
+      # The directory every source is filed under. Its layout is private --
+      # see the class comment.
+      sig { returns(String) }
+      attr_reader :root
+
+      sig { params(root: T.untyped).void }
+      def initialize(root: nil)
+        @root = T.let(-::File.expand_path((root || ActiveSanction.config.storage_dir).to_s), String)
+        super()
+      end
+
+      # Writes the list, then publishes it by replacing `meta.json`. The
+      # previous generation stays readable until that rename lands and is swept
+      # immediately after it.
+      sig { override.params(snapshot: T.untyped).returns(Snapshot) }
+      def write_snapshot(snapshot)
+        stored = snapshot!(snapshot)
+        directory = directory_for(source_key!(stored.source))
+        FileUtils.mkdir_p(directory)
+
+        path = snapshot_path(directory, stored.checksum)
+        write_atomically(path) { |file| compress(JSON.generate(stored.to_h), file) }
+        commit(directory, Meta.from_snapshot(stored))
+        prune(directory, path)
+        stored
+      end
+
+      sig { override.params(source: T.untyped).returns(T.nilable(Snapshot)) }
+      def read_snapshot(source)
+        key = source_key!(source)
+        directory = directory_for(key)
+        meta = read_meta(directory)
+        meta, json = read_list(directory, meta) if meta
+        return nil if json.nil? || meta.nil?
+
+        build(key, meta, json, snapshot_path(directory, meta.checksum))
+      end
+
+      # Off the sidecar, without opening the list. What makes `sources` in the
+      # CLI (#36) and the per-source summary in sync (#34) cheap: printing how
+      # old six lists are reads six small JSON files rather than inflating and
+      # deserializing tens of megabytes.
+      sig { override.params(source: T.untyped).returns(T.nilable(Meta)) }
+      def snapshot_meta(source) = read_meta(directory_for(source_key!(source)))
+
+      sig { override.params(source: T.untyped).returns(T::Boolean) }
+      def delete_snapshot(source)
+        directory = directory_for(source_key!(source))
+        stored = ::File.file?(::File.join(directory, META_FILENAME))
+        FileUtils.rm_rf(directory)
+        stored
+      end
+
+      # Every directory under `root` holding a committed sidecar. Deliberately
+      # does not parse them: this is what `stored?`, `empty?` and `clear` are
+      # built on, and one unreadable list must not make the store impossible to
+      # inspect or to repair.
+      sig { override.returns(T::Array[Symbol]) }
+      def sources
+        return [] unless ::File.directory?(root)
+
+        Dir.children(root)
+           .select { |name| name.match?(SOURCE_PATTERN) && ::File.file?(::File.join(root, name, META_FILENAME)) }
+           .map(&:to_sym).sort
+      end
+
+      sig { override.returns(String) }
+      def inspect = "#<#{self.class} #{root} #{list}>"
+
+      private
+
+      sig { params(key: T.untyped).returns(String) }
+      def directory_for(key) = ::File.join(root, key.to_s)
+
+      sig { params(directory: String, checksum: T.untyped).returns(String) }
+      def snapshot_path(directory, checksum)
+        ::File.join(directory, "#{SNAPSHOT_PREFIX}#{checksum_slug!(checksum)}#{SNAPSHOT_EXTENSION}")
+      end
+
+      sig { params(checksum: T.untyped).returns(String) }
+      def checksum_slug!(checksum)
+        match = CHECKSUM_PATTERN.match(checksum.to_s)
+        raise CorruptSnapshot, "#{checksum.inspect} is not a #{Snapshot::ALGORITHM} checksum" if match.nil?
+
+        "#{Snapshot::ALGORITHM}-#{T.must(match[1]).downcase}"
+      end
+
+      # Bytes go to a `.part` sibling, are flushed to the platter, and only
+      # then take the real name. A rename within a directory is atomic, so no
+      # reader ever opens a partially written file -- it sees the previous one
+      # or the new one.
+      sig { params(path: String, block: T.proc.params(file: ::File).void).void }
+      def write_atomically(path, &block)
+        temporary = T.let("#{path}.#{Process.pid}-#{SecureRandom.hex(8)}.part", T.nilable(String))
+        ::File.open(T.must(temporary), "wb") do |file|
+          block.call(file)
+          file.flush
+          file.fsync
+        end
+        ::File.rename(T.must(temporary), path)
+      ensure
+        FileUtils.rm_f(temporary) if temporary
+      end
+
+      # The rename that publishes a write. Everything the new generation needs
+      # is already on disk and fsynced by the time this runs, so the list a
+      # reader gets is whole whichever side of it they arrive on.
+      sig { params(directory: String, meta: Meta).void }
+      def commit(directory, meta)
+        write_atomically(::File.join(directory, META_FILENAME)) do |file|
+          file.write("#{JSON.pretty_generate(meta.to_h)}\n")
+        end
+      end
+
+      sig { params(json: String, sink: ::File).void }
+      def compress(json, sink)
+        gzip = Zlib::GzipWriter.new(sink, COMPRESSION_LEVEL)
+        begin
+          gzip.write(json)
+        ensure
+          gzip.finish
+        end
+      end
+
+      # The list `meta` names and the meta it actually came from, or nil when
+      # the source is gone. A missing file is not corruption on its own:
+      # another process can have committed a new generation and swept this one
+      # between our reading the sidecar and our opening what it pointed at, so
+      # the sidecar is read again before the absence is believed -- and the
+      # generation that read finds is the one the caller is answered with.
+      sig { params(directory: String, meta: Meta).returns(T.nilable([Meta, String])) }
+      def read_list(directory, meta)
+        json = inflate(snapshot_path(directory, meta.checksum))
+        return [meta, json] unless json.nil?
+
+        current = read_meta(directory)
+        return nil if current.nil?
+
+        path = snapshot_path(directory, current.checksum)
+        [current,
+         inflate(path) || raise(CorruptSnapshot, corrupt(path, "the sidecar names a list that is not there"))]
+      end
+
+      sig { params(path: String).returns(T.nilable(String)) }
+      def inflate(path)
+        Zlib.gunzip(::File.binread(path))
+      rescue Errno::ENOENT
+        nil
+      rescue Zlib::Error => e
+        raise CorruptSnapshot, corrupt(path, e.message)
+      end
+
+      sig { params(directory: String).returns(T.nilable(Meta)) }
+      def read_meta(directory)
+        path = T.let(::File.join(directory, META_FILENAME), T.nilable(String))
+        hash = JSON.parse(::File.read(T.must(path)))
+        raise CorruptSnapshot, corrupt(T.must(path), "it does not hold a JSON object") unless hash.is_a?(Hash)
+
+        schema_version!(hash["schema_version"], T.must(path))
+        Meta.from_h(hash)
+      rescue Errno::ENOENT
+        nil
+      rescue JSON::ParserError, ArgumentError, TypeError => e
+        # `T.must` because Sorbet reads a `rescue` as reachable before the
+        # first assignment in the body; `path` is that assignment.
+        raise CorruptSnapshot, corrupt(T.must(path), e.message)
+      end
+
+      # Checked against the sidecar before a byte of the list is inflated, so
+      # an unreadable schema costs a small read rather than tens of megabytes,
+      # and so it is caught before Snapshot.from_h has a chance to build
+      # plausible records out of a shape this version does not understand.
+      sig { params(value: T.untyped, path: String).returns(Integer) }
+      def schema_version!(value, path)
+        # `exception: false` answers nil for anything unparseable, which the
+        # stdlib RBI does not say -- hence the nilable annotation.
+        version = T.let(Integer(value, exception: false), T.nilable(Integer))
+        return version if !version.nil? && READABLE_SCHEMA_VERSIONS.cover?(version)
+
+        raise UnsupportedSchema,
+              "#{path} was written under snapshot schema_version #{value.inspect}; active_sanction #{VERSION} " \
+              "reads #{READABLE_SCHEMA_VERSIONS.first}-#{READABLE_SCHEMA_VERSIONS.last}. Upgrade the gem, or " \
+              "delete the directory and re-sync the source."
+      end
+
+      # Snapshot.from_h recomputes the checksum over the records that came back
+      # and refuses to build if it does not match the one stored with them,
+      # which is what catches a truncated or edited list. The two checks after
+      # it catch the pair coming apart: a sidecar describing a different
+      # generation than the file it points at, or a list filed under the wrong
+      # source.
+      sig { params(key: Symbol, meta: Meta, json: String, path: String).returns(Snapshot) }
+      def build(key, meta, json, path)
+        snapshot = Snapshot.from_h(JSON.parse(json))
+        wrong_generation = "it holds #{snapshot.checksum}, not the #{meta.checksum} recorded in #{META_FILENAME}"
+        raise CorruptSnapshot, corrupt(path, wrong_generation) if snapshot.checksum != meta.checksum
+        raise CorruptSnapshot, corrupt(path, "it is #{snapshot.source}, filed under #{key}") if snapshot.source != key
+
+        snapshot
+      rescue JSON::ParserError, ArgumentError, TypeError, Snapshot::ChecksumMismatch => e
+        raise CorruptSnapshot, corrupt(path, e.message)
+      end
+
+      sig { params(path: String, detail: String).returns(String) }
+      def corrupt(path, detail)
+        "#{path} cannot be trusted to be the list it says it is (#{detail}). Nothing partial is returned from " \
+          "storage -- delete #{::File.dirname(path)} and re-sync the source to replace it."
+      end
+
+      # Everything the committed generation does not need: the list files of
+      # generations it replaced, and `.part` files old enough to be from a
+      # write that died rather than one in flight.
+      sig { params(directory: String, keep: String).void }
+      def prune(directory, keep)
+        Dir.glob(::File.join(directory, "#{SNAPSHOT_PREFIX}*#{SNAPSHOT_EXTENSION}")).each do |path|
+          FileUtils.rm_f(path) unless path == keep
+        end
+        cutoff = Time.now - ORPHAN_GRACE
+        Dir.glob(::File.join(directory, "*.part")).each do |path|
+          FileUtils.rm_f(path) if ::File.mtime(path) < cutoff
+        rescue Errno::ENOENT
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/active_sanction/storage/memory.rb

@@ -0,0 +1,67 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/storage/base"
+
+module ActiveSanction
+  module Storage
+    # Snapshots for the life of one process, and no longer.
+    #
+    #   store = ActiveSanction::Storage::Memory.new
+    #   store.write_snapshot(source.sync)
+    #
+    #   ActiveSanction::Storage::Memory.new([ofac, un])   # seeded, for a spec
+    #
+    # Two jobs, and the second is the one that keeps it honest. It is a real
+    # storage adapter -- a process that syncs and screens without wanting to
+    # own a directory should use it, and pays only a full download on each
+    # boot. It is also the test double for storage everywhere in this suite,
+    # which is why it is written as a subclass of Base implementing the same
+    # four methods as everything else rather than as a Hash a spec passes
+    # around: a double that is not held to the contract stops describing what
+    # the real adapters do, usually a release or two before anybody notices.
+    #
+    # Snapshots are frozen by construction, so what is handed back is the
+    # object that was stored and nothing has to be copied to keep a caller from
+    # editing the list underneath the store. The hash itself is guarded by a
+    # mutex: a web process screens on many threads (#33) while a scheduled sync
+    # replaces a list under them, and a replacement has to be atomic from a
+    # reader's point of view -- a thread mid-screen holds the snapshot it
+    # started with and finishes against a consistent list.
+    class Memory < Base
+      extend T::Sig
+
+      sig { params(snapshots: T.untyped).void }
+      def initialize(snapshots = [])
+        @snapshots = T.let({}, T::Hash[Symbol, Snapshot])
+        @mutex = T.let(Mutex.new, Mutex)
+        Array(snapshots).each { |snapshot| write_snapshot(snapshot) }
+        super()
+      end
+
+      sig { override.params(snapshot: T.untyped).returns(Snapshot) }
+      def write_snapshot(snapshot)
+        stored = snapshot!(snapshot)
+        @mutex.synchronize { @snapshots[stored.source] = stored }
+        stored
+      end
+
+      sig { override.params(source: T.untyped).returns(T.nilable(Snapshot)) }
+      def read_snapshot(source)
+        key = source_key!(source)
+        @mutex.synchronize { @snapshots[key] }
+      end
+
+      sig { override.params(source: T.untyped).returns(T::Boolean) }
+      def delete_snapshot(source)
+        key = source_key!(source)
+        @mutex.synchronize { !@snapshots.delete(key).nil? }
+      end
+
+      sig { override.returns(T::Array[Symbol]) }
+      def sources = @mutex.synchronize { @snapshots.keys.sort }
+    end
+  end
+end

data/lib/active_sanction/storage/meta.rb

@@ -0,0 +1,188 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "time"
+require "active_sanction/snapshot"
+require "active_sanction/storage"
+
+module ActiveSanction
+  module Storage
+    # What a store can say about a stored list without reading the list.
+    #
+    #   store.snapshot_meta(:ofac_sdn)
+    #   # => #<ActiveSanction::Storage::Meta ofac_sdn 19015 entities sha256:1f3b... 3h old>
+    #
+    # Every field here is small and every field a snapshot holds besides these
+    # is not: OFAC's is 19,015 entities and tens of megabytes of JSON. The
+    # questions an operator and a sync actually ask -- when was this last
+    # fetched, how old is it now, how many records are on it, is it still the
+    # version we screened against in January -- are all answerable from these
+    # six values, so they are worth being able to answer separately.
+    #
+    # That separation is what makes the two things downstream cheap:
+    #
+    # - `sources` in the CLI (#36) and the per-source summary in sync
+    #   orchestration (#34) print an age per list. A store that had to
+    #   deserialize every snapshot to print a table would make the cheapest
+    #   command in the library the slowest.
+    # - Storage::FileSystem (#24) writes exactly this beside each snapshot as
+    #   `meta.json`, so `#to_h` is that file's contents and `.from_h` reads it
+    #   back. Base derives a Meta from the snapshot for adapters that have
+    #   nothing cheaper; an adapter with a sidecar or a metadata row overrides
+    #   `#snapshot_meta` and never opens the list.
+    #
+    # `checksum` is the one that outlives the rest. A match result cites it
+    # (#33), so "which list version cleared this customer" is answered by
+    # comparing a stored meta against a checksum in an audit record -- without
+    # loading either list.
+    #
+    # Instances are frozen on construction and compare by value.
+    class Meta
+      extend T::Sig
+
+      # @api private
+      MEMBERS = T.let(
+        %i[source fetched_at checksum record_count schema_version source_version].freeze,
+        T::Array[Symbol]
+      )
+
+      sig { returns(Symbol) }
+      attr_reader :source
+
+      sig { returns(Time) }
+      attr_reader :fetched_at
+
+      # The one field that outlives the rest: a match result cites it, so a
+      # stored meta answers "which list version cleared this customer".
+      sig { returns(String) }
+      attr_reader :checksum
+
+      sig { returns(Integer) }
+      attr_reader :record_count
+
+      sig { returns(Integer) }
+      attr_reader :schema_version
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :source_version
+
+      # The metadata of a snapshot already in hand. What a store that keeps no
+      # separate record of it answers `#snapshot_meta` with.
+      sig { params(snapshot: Snapshot).returns(T.attached_class) }
+      def self.from_snapshot(snapshot)
+        new(source: snapshot.source, fetched_at: snapshot.fetched_at, checksum: snapshot.checksum,
+            record_count: snapshot.record_count, schema_version: snapshot.schema_version,
+            source_version: snapshot.source_version)
+      end
+
+      # Rebuilds from #to_h output, accepting string keys so a sidecar survives
+      # the round-trip through JSON.
+      sig { params(hash: T.untyped).returns(T.attached_class) }
+      def self.from_h(hash)
+        attributes = hash.to_h.transform_keys(&:to_sym)
+        unknown = attributes.keys - MEMBERS
+        raise InvalidArgument, "unknown Meta attribute(s): #{unknown.join(", ")}" if unknown.any?
+
+        # `new(**hash)` past required keyword parameters is one of the few
+        # things Sorbet cannot check statically. #initialize validates what
+        # arrives, which is where a bad sidecar is caught.
+        T.unsafe(self).new(**attributes)
+      end
+
+      sig do
+        params(source: T.untyped, fetched_at: T.untyped, checksum: T.untyped, record_count: T.untyped,
+               schema_version: T.untyped, source_version: T.untyped).void
+      end
+      def initialize(source:, fetched_at:, checksum:, record_count:, schema_version: Snapshot::SCHEMA_VERSION,
+                     source_version: nil)
+        @source = T.let(symbol!(:source, source), Symbol)
+        @fetched_at = T.let(time!(fetched_at), Time)
+        @checksum = T.let(string!(:checksum, checksum), String)
+        @record_count = T.let(count!(record_count), Integer)
+        @schema_version = T.let(Integer(schema_version), Integer)
+        @source_version = T.let(source_version.nil? ? nil : -source_version.to_s, T.nilable(String))
+        freeze
+      end
+
+      # How long ago this list was fetched, in seconds. Sync (#34) reports it
+      # per source: a list that failed to refresh keeps its previous snapshot,
+      # which is the right call and only safe if the age of what is being
+      # screened against is visible.
+      sig { params(now: Time).returns(Integer) }
+      def age(now = Time.now) = now.to_i - fetched_at.to_i
+
+      # Whether this is the same list content as another meta, or as a snapshot
+      # about to be written. Ignores when either was fetched, because a refetch
+      # of an unchanged list is not a new version of it.
+      sig { params(other: T.untyped).returns(T::Boolean) }
+      def same_content?(other) = !other.nil? && other.checksum == checksum
+
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def to_h
+        {
+          source: source,
+          fetched_at: fetched_at.iso8601,
+          checksum: checksum,
+          record_count: record_count,
+          schema_version: schema_version,
+          source_version: source_version
+        }
+      end
+
+      sig { params(other: T.untyped).returns(T::Boolean) }
+      def ==(other)
+        return false unless other.instance_of?(self.class)
+
+        to_h == other.to_h
+      end
+      alias eql? ==
+
+      sig { returns(Integer) }
+      def hash = [self.class, to_h].hash
+
+      sig { returns(String) }
+      def inspect
+        "#<#{self.class} #{source} #{record_count} entities #{checksum} fetched_at=#{fetched_at.iso8601}>"
+      end
+
+      private
+
+      # Truncated to the second, the precision #to_h serializes, so a meta read
+      # back off disk is equal to the one that was written.
+      sig { params(value: T.untyped).returns(Time) }
+      def time!(value)
+        time = case value
+               when Time then value
+               when String then Time.parse(value)
+               else raise InvalidArgument, "fetched_at is not a time: #{value.inspect}"
+               end
+        Time.at(time.to_i).utc
+      end
+
+      sig { params(member: Symbol, value: T.untyped).returns(Symbol) }
+      def symbol!(member, value)
+        raise InvalidArgument, "#{member} is required" if value.nil? || value.to_s.empty?
+
+        value.to_sym
+      end
+
+      sig { params(member: Symbol, value: T.untyped).returns(String) }
+      def string!(member, value)
+        string = value.to_s.strip
+        raise InvalidArgument, "#{member} is required" if string.empty?
+
+        -string
+      end
+
+      sig { params(value: T.untyped).returns(Integer) }
+      def count!(value)
+        integer = Integer(value)
+        raise InvalidArgument, "record_count cannot be negative, got #{integer}" if integer.negative?
+
+        integer
+      end
+    end
+  end
+end