active_sanction 1.0.0

data/lib/active_sanction/validator_store/file_system.rb

@@ -0,0 +1,103 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "fileutils"
+require "json"
+
+module ActiveSanction
+  class ValidatorStore
+    # Validators in one small JSON file, so a sync that runs from cron gets a
+    # 304 on its second run rather than on its second run within one process.
+    #
+    #   ActiveSanction::ValidatorStore::FileSystem.new
+    #   # => ~/.cache/active_sanction/validators.json
+    #
+    # JSON, indented, keyed by the caller's key: this file is the first thing
+    # somebody opens when a sync is downloading more than it should, and it is
+    # a few hundred bytes even with every source in it. It is also the file the
+    # acceptance criterion is about -- deleting it forces a full re-download,
+    # and nothing else is lost with it, because validators are an optimization
+    # and never the record of what a list contained.
+    #
+    # Entries are re-read on every access rather than memoized. The file is
+    # tiny, and a cache that has to be reloaded to see another process's write
+    # is a cache that lies to a sync running beside a CLI command.
+    #
+    # Writes go to a temporary sibling and are renamed into place, so an
+    # interrupted write leaves the previous file rather than a truncated one.
+    # Two processes writing at once still resolve last-writer-wins: the cost is
+    # one avoidable download, which is the right trade for not putting a lock
+    # file in a user's cache directory.
+    class FileSystem < ValidatorStore
+      extend T::Sig
+
+      # @api private
+      DEFAULT_FILENAME = T.let("validators.json", String)
+
+      sig { returns(String) }
+      attr_reader :path
+
+      sig { params(path: T.untyped).void }
+      def initialize(path: nil)
+        @path = T.let(
+          ::File.expand_path((path || ::File.join(ActiveSanction.config.cache_dir, DEFAULT_FILENAME)).to_s), String
+        )
+        super()
+      end
+
+      sig { override.returns(String) }
+      def inspect = "#<#{self.class} #{path} #{size} entr#{size == 1 ? "y" : "ies"}>"
+
+      private
+
+      sig { override.returns(T::Hash[String, Validators]) }
+      def entries
+        raw = read
+        raw.to_h { |key, attributes| [key, Validators.from_h(attributes)] }
+      rescue ArgumentError, TypeError => e
+        raise CorruptStore, "#{path} does not hold validators (#{e.message}). Delete it to re-download in full."
+      end
+
+      sig do
+        override.params(block: T.proc.params(all: T::Hash[String, Validators]).returns(T.untyped))
+                .returns(T.untyped)
+      end
+      def commit(&block)
+        all = entries
+        result = block.call(all)
+        write(all)
+        result
+      end
+
+      # A missing file is an empty store, not an error: it is what a first run
+      # sees, and what deleting the file leaves behind.
+      sig { returns(T::Hash[String, T.untyped]) }
+      def read
+        return {} unless ::File.exist?(path)
+
+        contents = ::File.read(path, encoding: Encoding::UTF_8)
+        return {} if contents.strip.empty?
+
+        parsed = JSON.parse(contents)
+        raise CorruptStore, "#{path} is not a JSON object of validators. Delete it to re-download in full." unless
+          parsed.is_a?(Hash)
+
+        parsed
+      rescue JSON::ParserError => e
+        raise CorruptStore, "#{path} is not valid JSON (#{e.message}). Delete it to re-download in full."
+      end
+
+      sig { params(all: T::Hash[String, Validators]).void }
+      def write(all)
+        FileUtils.mkdir_p(::File.dirname(path))
+        temporary = T.let("#{path}.#{Process.pid}.tmp", T.nilable(String))
+        ::File.write(T.must(temporary), "#{JSON.pretty_generate(all.transform_values(&:to_h))}\n")
+        ::File.rename(T.must(temporary), path)
+      ensure
+        FileUtils.rm_f(temporary) if temporary
+      end
+    end
+  end
+end

data/lib/active_sanction/validator_store/memory.rb

@@ -0,0 +1,41 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module ActiveSanction
+  class ValidatorStore
+    # Validators for the life of one process, and no longer.
+    #
+    # The default for a caller that builds its own client and does not want a
+    # file appearing under a home directory, and what the suite uses so an
+    # example never depends on -- or leaves behind -- state on disk. A
+    # long-running process that syncs on a schedule still gets the whole
+    # benefit of conditional GET from it; only a fresh boot pays for a full
+    # download.
+    class Memory < ValidatorStore
+      extend T::Sig
+
+      sig { params(entries: T::Hash[T.untyped, T.nilable(Validators)]).void }
+      def initialize(entries = {})
+        @entries = T.let({}, T::Hash[String, Validators])
+        @mutex = T.let(Mutex.new, Mutex)
+        entries.each { |key, validators| self[key] = validators }
+        super()
+      end
+
+      private
+
+      sig { override.returns(T::Hash[String, Validators]) }
+      attr_reader :entries
+
+      sig do
+        override.params(block: T.proc.params(all: T::Hash[String, Validators]).returns(T.untyped))
+                .returns(T.untyped)
+      end
+      def commit(&block)
+        @mutex.synchronize { block.call(@entries) }
+      end
+    end
+  end
+end

data/lib/active_sanction/validator_store.rb

@@ -0,0 +1,119 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/error"
+require "active_sanction/validators"
+
+module ActiveSanction
+  # Where a process remembers what a publisher last said about a list, so the
+  # next fetch can ask "still this?" instead of "give me everything".
+  #
+  #   store = ActiveSanction::ValidatorStore::FileSystem.new
+  #   store[:ofac_sdn]          #=> #<ActiveSanction::Validators ...> or nil
+  #   store.delete(:ofac_sdn)   # next fetch downloads in full
+  #
+  # Keys are the caller's: a URL by default, or a stable source name for an
+  # adapter (#12) whose publisher may move its file. Validators carry the URL
+  # they came from either way, so a moved file is detected rather than sent a
+  # meaningless `If-None-Match`.
+  #
+  # This is a base class rather than an interface document: subclasses supply
+  # the two lines that differ -- how the entries are read and how a change to
+  # them is committed -- and inherit the rest. #24 will do the same for
+  # snapshots, at a scale where the difference matters more.
+  class ValidatorStore
+    extend T::Sig
+
+    # A store whose backing bytes cannot be read as validators. Deliberately
+    # fatal rather than treated as an empty store: silently re-downloading tens
+    # of megabytes on every sync is the kind of failure that hides for months,
+    # and the fix -- delete the file -- is in the message.
+    class CorruptStore < StorageError; end
+
+    # Reads validators, or nil when nothing is stored under the key. Nil is the
+    # answer to "have we ever fetched this?", so it is not conflated with a
+    # record that exists but carries no validators.
+    sig { params(key: T.untyped).returns(T.nilable(Validators)) }
+    def [](key)
+      entries[key!(key)]
+    end
+
+    # Storing nil, or validators the publisher gave nothing to be conditional
+    # with, is a delete: a record that cannot save a download is not worth
+    # keeping, and leaving one behind makes #stale? lie about having a usable
+    # copy.
+    sig { params(key: T.untyped, validators: T.nilable(Validators)).returns(T.nilable(Validators)) }
+    def []=(key, validators)
+      normalized = key!(key)
+      commit do |all|
+        if validators.nil? || validators.empty?
+          all.delete(normalized)
+        else
+          all[normalized] = validators
+        end
+      end
+      validators
+    end
+    alias store []=
+
+    sig { params(key: T.untyped).returns(T.untyped) }
+    def delete(key)
+      normalized = key!(key)
+      commit { |all| all.delete(normalized) }
+    end
+
+    sig { params(key: T.untyped).returns(T::Boolean) }
+    def key?(key) = entries.key?(key!(key))
+
+    sig { returns(T::Array[String]) }
+    def keys = entries.keys
+
+    sig { returns(Integer) }
+    def size = entries.size
+
+    sig { returns(T::Boolean) }
+    def empty? = entries.empty?
+
+    sig { returns(T.self_type) }
+    def clear
+      commit(&:clear)
+      self
+    end
+
+    sig { returns(T::Hash[String, T.untyped]) }
+    def to_h = entries.transform_values(&:to_h)
+
+    sig { returns(String) }
+    def inspect = "#<#{self.class} #{size} entr#{size == 1 ? "y" : "ies"}>"
+
+    private
+
+    # Keys reach here as symbols from source adapters and as URL strings from
+    # ad-hoc callers; both have to survive a round-trip through JSON, which has
+    # only strings.
+    sig { params(key: T.untyped).returns(String) }
+    def key!(key)
+      string = key.to_s.strip
+      raise InvalidArgument, "a validator key is required" if string.empty?
+
+      -string
+    end
+
+    # A hash of key => Validators. Subclasses may rebuild it per call.
+    sig { returns(T::Hash[String, Validators]) }
+    def entries
+      raise UnsupportedError, "#{self.class} must implement #entries"
+    end
+
+    # Yields the current entries for mutation and persists the result.
+    sig { params(_block: T.proc.params(all: T::Hash[String, Validators]).returns(T.untyped)).returns(T.untyped) }
+    def commit(&_block)
+      raise UnsupportedError, "#{self.class} must implement #commit"
+    end
+  end
+end
+
+require "active_sanction/validator_store/memory"
+require "active_sanction/validator_store/file_system"

data/lib/active_sanction/validators.rb

@@ -0,0 +1,195 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "time"
+require "active_sanction/error"
+
+module ActiveSanction
+  # The cache validators a publisher handed back with a list, plus enough
+  # context to know whether they still apply.
+  #
+  #   validators.request_headers
+  #   # => { "If-None-Match" => "\"0953154d0fb5aff918c5ec1daf6e9c0e\"",
+  #   #      "If-Modified-Since" => "Fri, 28 Aug 2026 14:02:55 GMT" }
+  #
+  # Every launch source serves both, verified live -- OFAC's SDN.CSV, the UN's
+  # consolidated.xml and Canada's sema-lmes.xml -- so a routine sync of lists
+  # that change daily at most costs three 304s instead of tens of megabytes.
+  #
+  # Both values are stored and echoed back verbatim. An `ETag` is an opaque
+  # string that only its origin server can interpret, and `Last-Modified` is an
+  # HTTP-date whose formatting is the server's business; parsing either one to
+  # re-render it is how a working conditional GET turns into a full download
+  # nobody notices.
+  #
+  # `url` is the URL that was *requested*, not the one that finally answered:
+  # OFAC redirects to blob storage, and the hop it lands on is not stable
+  # enough to key a cache by. It is kept so validators can be discarded when a
+  # publisher moves its file -- sending a previous file's ETag to a new URL
+  # invites a 304 that means nothing.
+  #
+  # Instances are frozen on construction and compare by value.
+  class Validators
+    extend T::Sig
+
+    # @api private
+    MEMBERS = T.let(%i[url etag last_modified checked_at updated_at].freeze, T::Array[Symbol])
+
+    # The URL that was requested, not the one that finally answered -- see the
+    # class comment.
+    sig { returns(String) }
+    attr_reader :url
+
+    # Opaque, and echoed back verbatim: only the origin server can interpret
+    # either of them.
+    sig { returns(T.nilable(String)) }
+    attr_reader :etag
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :last_modified
+
+    sig { returns(Time) }
+    attr_reader :checked_at
+
+    sig { returns(Time) }
+    attr_reader :updated_at
+
+    # `url` is the caller's URL rather than `response.uri` for the reason in
+    # the class comment: the response may have come from a redirect target.
+    sig { params(response: T.untyped, url: T.untyped, at: T.untyped).returns(T.attached_class) }
+    def self.from_response(response, url:, at: nil)
+      new(url: url, etag: response.etag, last_modified: response.last_modified, checked_at: at)
+    end
+
+    # Rebuilds from #to_h output, accepting string keys so validators survive
+    # the round-trip through the JSON the store writes.
+    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 Validators attribute(s): #{unknown.join(", ")}" if unknown.any?
+
+      # `new(**hash)` past a required keyword parameter is one of the few
+      # things Sorbet cannot check statically. #initialize validates what
+      # arrives, which is where a bad round-trip is caught.
+      T.unsafe(self).new(**attributes)
+    end
+
+    # `checked_at` is when the publisher last confirmed this copy, whether by
+    # 200 or by 304; `updated_at` is when the bytes themselves last changed.
+    # Staleness follows the first, because "when did we last ask?" is the
+    # question a sync schedule answers; the second is what a human wants when
+    # reading why a list looks old.
+    sig do
+      params(url: T.untyped, etag: T.untyped, last_modified: T.untyped, checked_at: T.untyped,
+             updated_at: T.untyped).void
+    end
+    def initialize(url:, etag: nil, last_modified: nil, checked_at: nil, updated_at: nil)
+      @url = T.let(url!(url), String)
+      @etag = T.let(string_or_nil(etag), T.nilable(String))
+      @last_modified = T.let(string_or_nil(last_modified), T.nilable(String))
+      @checked_at = T.let(time!(checked_at), Time)
+      @updated_at = T.let(updated_at.nil? ? @checked_at : time!(updated_at), Time)
+      freeze
+    end
+
+    # True when the publisher gave us nothing to be conditional with. Such a
+    # record is still worth storing -- it says we looked -- but it cannot save
+    # a download, so callers treat it as no validators at all.
+    sig { returns(T::Boolean) }
+    def empty? = etag.nil? && last_modified.nil?
+
+    sig { returns(T::Boolean) }
+    def present? = !empty?
+
+    # Both are sent when both are known. RFC 9110 has the server prefer
+    # `If-None-Match` and ignore the date, but a cache in front of it may only
+    # honour one, and the second header costs 40 bytes on a request that is
+    # trying to avoid 126 MB.
+    sig { returns(T::Hash[String, String]) }
+    def request_headers
+      headers = {}
+      headers["If-None-Match"] = etag if etag
+      headers["If-Modified-Since"] = last_modified if last_modified
+      headers.freeze
+    end
+
+    # Validators belong to the URL they came from. A publisher that moves its
+    # file gets a full download rather than a 304 from whatever is now at the
+    # old address.
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def for?(other) = url == other.to_s
+
+    # What to store after the publisher answered 304. The copy is unchanged,
+    # so `updated_at` stands; only the moment we confirmed it moves. A 304 is
+    # allowed to carry a fresh ETag, and when it does that value is the one to
+    # send next time.
+    sig { params(response: T.untyped, at: T.untyped).returns(Validators) }
+    def confirmed_by(response, at: nil)
+      self.class.new(url: url, etag: response.etag || etag,
+                     last_modified: response.last_modified || last_modified,
+                     checked_at: at, updated_at: updated_at)
+    end
+
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def to_h
+      {
+        url: url,
+        etag: etag,
+        last_modified: last_modified,
+        checked_at: checked_at.iso8601,
+        updated_at: updated_at.iso8601
+      }
+    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} #{url} etag=#{etag.inspect} last_modified=#{last_modified.inspect} " \
+        "checked_at=#{checked_at.iso8601}>"
+    end
+
+    private
+
+    sig { params(value: T.untyped).returns(String) }
+    def url!(value)
+      string = value.to_s.strip
+      raise InvalidArgument, "url is required" if string.empty?
+
+      -string
+    end
+
+    # Truncated to the second, which is the precision #to_h serializes, so a
+    # stored record reloads to a value equal to the one that was written.
+    sig { params(value: T.untyped).returns(Time) }
+    def time!(value)
+      time = case value
+             when nil then Time.now
+             when Time then value
+             when String then Time.parse(value)
+             else raise InvalidArgument, "not a time: #{value.inspect}"
+             end
+      Time.at(time.to_i).utc
+    end
+
+    sig { params(value: T.untyped).returns(T.nilable(String)) }
+    def string_or_nil(value)
+      return nil if value.nil?
+
+      string = value.to_s.strip
+      string.empty? ? nil : -string
+    end
+  end
+end

data/lib/active_sanction/version.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ActiveSanction
+  # The gem version, and what CHANGELOG.md is about. Moves under SemVer for a
+  # new source adapter, a storage fix or a documentation release -- none of
+  # which change what a name scores. MATCHER_VERSION, below, is the one that
+  # answers that question.
+  VERSION = "1.0.0"
+
+  # Which matching pipeline scored a decision, stamped onto every MatchResult
+  # and bumped whenever a change to the normalizer, the index, the similarity
+  # algorithms or the scorer could move a score.
+  #
+  # Deliberately not VERSION. The gem version moves for a new source adapter,
+  # a storage fix, a documentation release -- none of which change what a name
+  # scores -- and an auditor asking "would this screening come out the same
+  # today?" needs the answer to that question rather than a release number
+  # that also answers several others. Its companions on the record are the
+  # weights and the snapshot checksum; between the three, a past decision is
+  # re-derivable.
+  MATCHER_VERSION = "1"
+end