openasn 0.2.0

data/lib/openasn/snapshot.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module OpenASN
+  # An immutable, fully-loaded dataset: canonical artifacts (both address
+  # families) + org names + Tier B overlays, plus the metadata to explain
+  # where it all came from. Snapshots are built off the hot path and
+  # swapped in with a single ivar assignment (see Dataset) — readers never
+  # see partial state, and there are no locks anywhere near lookups.
+  class Snapshot
+    SEED_DIR = File.expand_path("data/seed", __dir__)
+
+    Family = Struct.new(:base, :vpn, :dc, :relay, keyword_init: true)
+
+    attr_reader :v4, :v6, :orgs, :overlays, :build_id, :build_ts, :loaded_at,
+                :origin, :tier_b_status, :record_counts
+
+    # Build from the best available data:
+    #   1. data_dir artifacts (downloaded by the updater) when present+valid
+    #   2. the gem's bundled seed otherwise (first boot, corrupted dir, …)
+    # A corrupt downloaded artifact NEVER crashes boot — parsing happens
+    # INSIDE the fallback boundary (a truncated download that still reads
+    # fine must not take the app down); we log and fall back to the seed,
+    # and the next update cycle re-downloads. If the bundled seed itself
+    # fails to parse, the gem is broken and raising IS correct.
+    def self.build(config)
+      data_dir = config.data_dir
+      mode = config.memory_mode
+
+      origin = :data_dir
+      begin
+        v4_bytes, v6_bytes, manifest = read_artifacts(data_dir)
+        raise Errno::ENOENT, "no artifacts in data_dir" unless v4_bytes
+
+        v4_parsed, v6_parsed = parse_pair(v4_bytes, v6_bytes, mode)
+      rescue StandardError => e
+        unless e.is_a?(Errno::ENOENT)
+          config.logger.warn("openasn: data_dir artifacts unusable (#{e.message}); falling back to bundled seed")
+        end
+        origin = :seed
+        v4_bytes = File.binread(File.join(SEED_DIR, "openasn-ipv4.bin"))
+        v6_bytes = File.binread(File.join(SEED_DIR, "openasn-ipv6.bin"))
+        manifest = JSON.parse(File.read(File.join(SEED_DIR, "manifest.json")))
+        v4_parsed, v6_parsed = parse_pair(v4_bytes, v6_bytes, mode)
+      end
+
+      orgs = load_orgs(data_dir, config)
+      store = OverlayStore.new(data_dir)
+      overlays = store.load(config.enabled_tier_b_source_ids, mode)
+
+      new(v4_parsed, v6_parsed, orgs, overlays, manifest, origin, store)
+    end
+
+    def self.parse_pair(v4_bytes, v6_bytes, mode)
+      v4_parsed = BinaryFormat.parse_artifact(v4_bytes, mode: mode)
+      v6_parsed = BinaryFormat.parse_artifact(v6_bytes, mode: mode)
+      raise FormatError, "openasn-ipv4.bin is not an IPv4 artifact" unless v4_parsed[:family] == :ipv4
+      raise FormatError, "openasn-ipv6.bin is not an IPv6 artifact" unless v6_parsed[:family] == :ipv6
+
+      [v4_parsed, v6_parsed]
+    end
+
+    def self.read_artifacts(data_dir)
+      v4 = File.join(data_dir, "openasn-ipv4.bin")
+      v6 = File.join(data_dir, "openasn-ipv6.bin")
+      mf = File.join(data_dir, "manifest.json")
+      return nil unless File.exist?(v4) && File.exist?(v6)
+
+      manifest = File.exist?(mf) ? JSON.parse(File.read(mf)) : {}
+      verify_manifest_hashes!(manifest, "openasn-ipv4.bin" => v4, "openasn-ipv6.bin" => v6)
+      [File.binread(v4), File.binread(v6), manifest]
+    end
+
+    def self.verify_manifest_hashes!(manifest, files)
+      by_name = (manifest["files"] || []).to_h { |f| [f["name"], f] }
+      return if by_name.empty? # legacy/manual installs without checksums still parse through FORMAT.md.
+
+      files.each do |name, path|
+        expected = by_name.dig(name, "sha256")
+        raise IntegrityError, "manifest missing checksum for #{name}" if expected.to_s.empty?
+
+        actual = Digest::SHA256.file(path).hexdigest
+        next if actual == expected
+
+        # Updater writes manifest.json last as the commit marker. If a
+        # process dies during the final rename loop, a fresh boot can see
+        # new artifact bytes next to the old manifest. Reject that mixed
+        # set here and fall back to the bundled seed instead of serving a
+        # cross-build IPv4/IPv6 pair.
+        raise IntegrityError, "#{name} checksum does not match manifest"
+      end
+    end
+
+    def self.load_orgs(data_dir, config)
+      path = File.join(data_dir, "openasn-orgs.bin")
+      return nil unless File.exist?(path)
+
+      BinaryFormat::OrgIndex.load(path)
+    rescue StandardError => e
+      config.logger.warn("openasn: openasn-orgs.bin unusable (#{e.message}); as_org will be nil until next update")
+      nil
+    end
+
+    def initialize(v4_parsed, v6_parsed, orgs, overlays, manifest, origin, store)
+      @v4 = Family.new(base: v4_parsed[:base], vpn: v4_parsed[:vpn], dc: v4_parsed[:dc], relay: v4_parsed[:relay])
+      @v6 = Family.new(base: v6_parsed[:base], vpn: v6_parsed[:vpn], dc: v6_parsed[:dc], relay: v6_parsed[:relay])
+      @orgs = orgs
+      @overlays = overlays.freeze
+      @build_id = manifest["build_id"]
+      @build_ts = v4_parsed[:build_ts]
+      @loaded_at = Time.now.utc
+      @origin = origin
+      @record_counts = {
+        base_ipv4: @v4.base.count, vpn_ipv4: @v4.vpn.count, dc_ipv4: @v4.dc.count,
+        base_ipv6: @v6.base.count
+      }.freeze
+      @tier_b_status = build_tier_b_status(store)
+      # Precomputed (family, maps_to) -> [[entry, layer], ...] index. The old
+      # per-lookup filter_map was fine at 8 overlays but allocation-heavy at
+      # 18+ (measured: 42us/lookup vs 15us overlay-less with 11 overlays -
+      # most of the gap was these throwaway arrays, not the binary searches).
+      # The snapshot is immutable, so build the index exactly once.
+      @overlay_index = {}
+      @overlays.each do |o|
+        { ipv4: o.v4, ipv6: o.v6 }.each do |fam, layer|
+          next unless layer
+
+          (@overlay_index[[fam, o.maps_to]] ||= []) << [o, layer].freeze
+        end
+      end
+      @overlay_index.each_value(&:freeze)
+      @overlay_index.freeze
+      freeze
+    end
+
+    def family(fam) = fam == :ipv4 ? @v4 : @v6
+
+    EMPTY_OVERLAYS = [].freeze
+
+    # Overlays for one family in a stable order (executor wrote them; order
+    # among same-precedence overlays doesn't affect verdicts, only which
+    # provider gets attribution on exotic multi-overlay hits).
+    def overlays_for(fam, maps_to)
+      @overlay_index.fetch([fam, maps_to], EMPTY_OVERLAYS)
+    end
+
+    def org_name(asn)
+      asn && @orgs ? @orgs.name(asn) : nil
+    end
+
+    def age_seconds
+      Time.now.to_i - @build_ts
+    end
+
+    private
+
+    def build_tier_b_status(store)
+      state = store.state["sources"]
+      @overlays.to_h do |o|
+        s = state[o.id] || {}
+        [o.id.to_sym, {
+          maps_to: o.maps_to, fetched_at: s["fetched_at"],
+          records: { ipv4: s["records_ipv4"], ipv6: s["records_ipv6"] },
+          last_error: s["last_error"]
+        }]
+      end.freeze
+    end
+  end
+end

data/lib/openasn/special_ranges.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module OpenASN
+  # Hardcoded special-purpose ranges, checked before any data layer.
+  # These are IANA facts, not data: they never change with dataset updates.
+  module SpecialRanges
+    def self.table(cidrs)
+      cidrs.map do |(cidr, verdict, rule)|
+        r = IPAddr.new(cidr).to_range
+        [r.first.to_i, r.last.to_i, verdict, rule].freeze
+      end.freeze
+    end
+
+    V4 = table([
+      ["0.0.0.0/8",      :private, :special_reserved],
+      ["10.0.0.0/8",     :private, :special_rfc1918],
+      ["100.64.0.0/10",  :cgnat,   :special_cgnat],      # RFC 6598 shared address space
+      ["127.0.0.0/8",    :private, :special_loopback],
+      ["169.254.0.0/16", :private, :special_link_local],
+      ["172.16.0.0/12",  :private, :special_rfc1918],
+      ["192.168.0.0/16", :private, :special_rfc1918],
+      ["224.0.0.0/4",    :private, :special_multicast],
+      ["240.0.0.0/4",    :private, :special_reserved]
+    ]).freeze
+
+    V6 = table([
+      ["::1/128",   :private, :special_loopback],
+      ["fc00::/7",  :private, :special_ula],
+      ["fe80::/10", :private, :special_link_local]
+    ]).freeze
+
+    # -> [verdict, rule] | nil. Linear scan is optimal here: 9 rows max,
+    # sorted so RFC1918/loopback hits early; measured faster than any
+    # cleverer structure at this size.
+    def self.match(ip_int, family)
+      (family == :ipv4 ? V4 : V6).each do |(s, e, verdict, rule)|
+        return [verdict, rule] if ip_int >= s && ip_int <= e
+      end
+      nil
+    end
+  end
+end

data/lib/openasn/tier_b.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "thread"
+require "timeout"
+
+module OpenASN
+  # Executes fetch-manifest.json: pulls each enabled Tier B source from its
+  # ORIGINAL authority (Apple, the Tor Project, AWS…), parses, merges, and
+  # packs it into the local overlay store.
+  #
+  # Prime directives (each encodes a production lesson):
+  #   * Per-source isolation: one source failing NEVER touches the others
+  #     and NEVER raises out of the executor. Failures keep last-good data
+  #     ("keep_stale") and are recorded in state.json — visible via
+  #     OpenASN.dataset_info[:tier_b_status].
+  #   * Honor cadence_hours: a 12h source isn't refetched on every deploy's
+  #     update run. `force: true` overrides (manual OpenASN.update!(force:)).
+  #   * Unknown source ids / parser ids are skipped with a warning — old
+  #     gem versions must survive fetch-manifest evolution.
+  #   * Every request carries the descriptive User-Agent. These are mostly
+  #     free/volunteer endpoints; being a good citizen is part of the deal.
+  class TierB
+    DEFAULT_DNS_THREADS = 16
+    MAX_DNS_THREADS = 32
+    DNS_TIMEOUT_SECONDS = 4
+
+    class << self
+      attr_accessor :dns_resolver
+    end
+    self.dns_resolver = lambda do |hostname|
+      Socket.getaddrinfo(hostname, nil, Socket::AF_UNSPEC, Socket::SOCK_STREAM).map { |entry| entry[3] }.uniq
+    end
+
+    def initialize(config, http)
+      @config = config
+      @http = http
+      @logger = config.logger
+      @store = OverlayStore.new(config.data_dir)
+    end
+
+    # -> true when any overlay changed (snapshot reload needed)
+    def execute(force: false)
+      manifest = load_manifest
+      return false unless manifest
+
+      enabled = @config.enabled_tier_b_source_ids
+      changed = false
+      (manifest["sources"] || []).each do |source|
+        id = source["id"]
+        next unless enabled.include?(id)
+
+        unless Parsers.known?(source["parser"])
+          @logger.warn("openasn: tier B source #{id} uses unknown parser #{source['parser'].inspect} — " \
+                       "skipping (update the openasn gem to pick it up)")
+          next
+        end
+
+        changed |= refresh_source(source, force: force)
+      end
+      changed
+    end
+
+    private
+
+    # Freshest available manifest: data_dir (mirrored on canonical update)
+    # -> bundled copy from gem release time.
+    def load_manifest
+      [File.join(@config.data_dir, "fetch-manifest.json"),
+       File.join(Snapshot::SEED_DIR, "fetch-manifest.json")].each do |path|
+        next unless File.exist?(path)
+
+        return JSON.parse(File.read(path))
+      rescue JSON::ParserError => e
+        @logger.warn("openasn: unreadable fetch-manifest at #{path} (#{e.message})")
+      end
+      nil
+    end
+
+    def refresh_source(source, force:)
+      id = source["id"]
+      unless force || due?(id, source["cadence_hours"])
+        return false
+      end
+
+      urls = resolve_urls(source)
+      if urls.empty?
+        @store.record_failure(id, "could not resolve source URL")
+        return false
+      end
+
+      etag = urls.length == 1 && !force ? @store.source_state(id)["etag"] : nil
+      tokens = []
+      new_etag = nil
+      not_modified = false
+
+      urls.each do |url|
+        response = fetch_source_url(source, url, etag)
+        if response == :not_modified
+          not_modified = true
+          break
+        end
+        new_etag = response.etag if urls.length == 1
+        tokens.concat(Parsers.parse(source["parser"], response.body))
+      end
+      tokens = resolve_hostnames(tokens, source)
+
+      if not_modified
+        @store.record_fresh(id)
+        return false
+      end
+
+      ranges = CidrUtils.ranges_by_family(tokens)
+      total = ranges[:ipv4].length + ranges[:ipv6].length
+      if total.zero?
+        # An empty security list is far more likely upstream breakage than
+        # reality — keep whatever we had (keep_stale), record loudly.
+        @store.record_failure(id, "parsed 0 ranges — upstream format changed? keeping stale data")
+        return false
+      end
+
+      @store.write(id, maps_to: source["maps_to"], provider: source["provider"],
+                       etag: new_etag, ranges_by_family: ranges)
+      @logger.info("openasn: tier B #{id}: #{ranges[:ipv4].length} v4 + #{ranges[:ipv6].length} v6 ranges")
+      true
+    rescue StandardError => e
+      # keep_stale: failure is recorded, previous overlay files stay live.
+      @store.record_failure(id, "#{e.class}: #{e.message}")
+      @logger.warn("openasn: tier B #{id} failed (#{e.message}); keeping stale data")
+      false
+    end
+
+    def fetch_source_url(source, url, etag)
+      if source["method"].to_s.upcase == "POST"
+        @http.post_form(url, source["form"] || {})
+      else
+        @http.get(url, etag: etag)
+      end
+    end
+
+    def due?(id, cadence_hours)
+      last = @store.fetched_at(id)
+      return true unless last
+
+      (Time.now - last) >= (cadence_hours || 24) * 3600 * 0.99 # 1% slack so daily jobs don't skip-drift
+    end
+
+    def resolve_urls(source)
+      urls = []
+      if source["resolver"] == "azure_download_page"
+        url = resolve_azure(source["page_url"])
+        urls << url if url
+      elsif source["url"]
+        urls << source["url"]
+      end
+      urls.concat(source["urls"]) if source["urls"].is_a?(Array)
+      urls << source["url_ipv6"] if source["url_ipv6"]
+      urls
+    end
+
+    def resolve_hostnames(tokens, source)
+      return tokens unless source["resolve_hostnames"]
+
+      direct = []
+      hosts = []
+      tokens.each do |token|
+        token = token.to_s.strip
+        next if token.empty?
+
+        if CidrUtils.parse(token)
+          direct << token
+        elsif hostname?(token)
+          hosts << token.downcase
+        end
+      end
+      hosts.uniq!
+      return direct if hosts.empty?
+
+      resolved = resolve_hosts(hosts, source)
+      @logger.info("openasn: tier B #{source['id']}: resolved #{resolved.length} IPs from #{hosts.length} hostnames")
+      direct + resolved
+    end
+
+    def resolve_hosts(hosts, source)
+      threads = [[source["dns_threads"] || DEFAULT_DNS_THREADS, MAX_DNS_THREADS].min, hosts.length].min
+      queue = Queue.new
+      hosts.each { |host| queue << host }
+      resolved = []
+      mutex = Mutex.new
+
+      workers = threads.times.map do
+        Thread.new do
+          loop do
+            host = queue.pop(true)
+            ips = Timeout.timeout(DNS_TIMEOUT_SECONDS) { self.class.dns_resolver.call(host) }
+            mutex.synchronize { resolved.concat(ips) }
+          rescue ThreadError
+            break
+          rescue StandardError
+            next
+          end
+        end
+      end
+      workers.each(&:join)
+      resolved.uniq
+    end
+
+    def hostname?(token)
+      token.match?(/\A(?=.{1,253}\z)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}\z/i)
+    end
+
+    # Azure's actual JSON URL rotates weekly behind the download page.
+    # Scrape it; on any failure return nil (-> keep stale, try tomorrow).
+    def resolve_azure(page_url)
+      html = @http.get(page_url).body
+      html[%r{https://download\.microsoft\.com/download/[^"'\s]+ServiceTags_Public_\d+\.json}]
+    rescue StandardError => e
+      @logger.warn("openasn: azure page resolution failed (#{e.message})")
+      nil
+    end
+  end
+end

data/lib/openasn/update_job.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Defined only when ActiveJob is available (required from the Railtie, or
+# require it yourself in non-Rails ActiveJob apps AFTER loading ActiveJob).
+#
+# Scheduling is app-side — with Solid Queue (Rails 8 default), in
+# config/recurring.yml:
+#
+#   production:
+#     openasn_update:
+#       class: OpenASN::UpdateJob
+#       schedule: every day at 4:12am UTC   # off-hour on purpose: be kind
+#                                           # to the volunteer-run upstreams
+#
+# (The install generator wires this for you.) Data freshness NEVER flows
+# through gem releases — this job is the only moving part.
+if defined?(ActiveJob::Base)
+  module OpenASN
+    class UpdateJob < ActiveJob::Base
+      queue_as :default
+
+      # Transient network trouble self-heals on the next run; a persistent
+      # failure surfaces via logs + dataset_info staleness, not via a
+      # crashed-job pile-up.
+      retry_on OpenASN::UpdateError, wait: 5.minutes, attempts: 3
+
+      def perform(force: false)
+        OpenASN.update!(force: force)
+      end
+    end
+  end
+end

data/lib/openasn/updater.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+
+module OpenASN
+  # The data refresh cycle (what OpenASN.update! / UpdateJob runs):
+  #
+  #   1. Canonical: GET {release_url}manifest.json (ETag-conditional).
+  #      When it changed, download each artifact, VERIFY ITS SHA-256
+  #      against the manifest, write to *.tmp, File.rename into place
+  #      (atomic on POSIX — a crashed update can never leave a torn file),
+  #      then write manifest.json LAST — it is the commit marker other
+  #      processes watch for (Dataset#maybe_reload_from_disk).
+  #   2. Tier B: execute the fetch-manifest for enabled sources (TierB).
+  #      Per-source failures keep stale data and never fail the update.
+  #   3. Swap the in-process snapshot.
+  #
+  # Concurrency: a non-blocking flock serializes updaters across processes
+  # (first puma worker wins; the rest skip — they'll pick up the files via
+  # the freshness probe). Never raises for "someone else is updating".
+  class Updater
+    CANONICAL_FILES = %w[openasn-ipv4.bin openasn-ipv6.bin openasn-orgs.bin].freeze
+
+    def initialize(config, dataset)
+      @config = config
+      @dataset = dataset
+      @http = HttpClient.new(user_agent: config.user_agent, logger: config.logger)
+      @logger = config.logger
+    end
+
+    # -> :updated | :tier_b_only | :unchanged | :locked
+    def run(force: false)
+      FileUtils.mkdir_p(@config.data_dir)
+      with_lock do
+        canonical_changed = refresh_canonical(force: force)
+        tier_b_changed = TierB.new(@config, @http).execute(force: force)
+
+        if canonical_changed || tier_b_changed
+          @dataset.reload!
+          notify(canonical_changed ? :updated : :tier_b_only)
+          canonical_changed ? :updated : :tier_b_only
+        else
+          :unchanged
+        end
+      end
+    end
+
+    private
+
+    def refresh_canonical(force:)
+      state = read_state
+      begin
+        response = @http.get("#{@config.release_url}manifest.json",
+                             etag: force ? nil : state["manifest_etag"])
+      rescue StandardError => e
+        # No manifest, no update — but never crash the job: keep-last-good
+        # is the contract (the seed or previous download keeps serving).
+        raise UpdateError, "could not fetch manifest: #{e.message}" if force
+
+        @logger.warn("openasn: manifest fetch failed (#{e.message}); keeping current data")
+        return false
+      end
+      return false if response == :not_modified
+
+      manifest = JSON.parse(response.body)
+      if !force && manifest["build_id"] && manifest["build_id"] == current_local_build_id
+        # Same build re-served (ETag miss, mirror change…): record the new
+        # ETag, skip the downloads.
+        write_state(state.merge("manifest_etag" => response.etag))
+        return false
+      end
+
+      by_name = (manifest["files"] || []).to_h { |f| [f["name"], f] }
+      downloads = CANONICAL_FILES.filter_map do |name|
+        meta = by_name[name]
+        # Manifest without a required artifact = upstream problem; orgs is
+        # optional richness, the .bin artifacts are not.
+        if meta.nil?
+          raise UpdateError, "release manifest is missing #{name}" unless name == "openasn-orgs.bin"
+
+          next
+        end
+        [name, meta]
+      end
+
+      # Two-phase install: download + verify EVERYTHING first, then rename
+      # all files in one tight loop. A crash mid-download therefore can't
+      # leave a mixed set (new ipv4 + old ipv6) on disk; renames are so
+      # close together that the mixed window is effectively gone.
+      verified = downloads.map do |(name, meta)|
+        body = @http.get("#{@config.release_url}#{name}").body
+        actual = Digest::SHA256.hexdigest(body)
+        unless actual == meta["sha256"]
+          raise IntegrityError,
+                "#{name} SHA-256 mismatch (expected #{meta['sha256'][0, 12]}…, got #{actual[0, 12]}…) — " \
+                "refusing to install; previous data stays live"
+        end
+
+        tmp = File.join(@config.data_dir, "#{name}.tmp")
+        File.binwrite(tmp, body)
+        [tmp, File.join(@config.data_dir, name)]
+      end
+      verified.each { |(tmp, final)| File.rename(tmp, final) }
+
+      # Also mirror the fetch-manifest so Tier B follows the release's
+      # current source list (falls back to the bundled copy when absent).
+      begin
+        fm = @http.get("#{@config.release_url}fetch-manifest.json").body
+        JSON.parse(fm) # only install valid JSON
+        tmp = File.join(@config.data_dir, "fetch-manifest.json.tmp")
+        File.write(tmp, fm)
+        File.rename(tmp, File.join(@config.data_dir, "fetch-manifest.json"))
+      rescue StandardError => e
+        @logger.warn("openasn: fetch-manifest refresh failed (#{e.message}); using previous/bundled copy")
+      end
+
+      # Commit marker LAST: other processes treat manifest.json's mtime as
+      # "new data is fully in place".
+      tmp = File.join(@config.data_dir, "manifest.json.tmp")
+      File.write(tmp, response.body)
+      File.rename(tmp, File.join(@config.data_dir, "manifest.json"))
+
+      write_state(read_state.merge("manifest_etag" => response.etag,
+                                   "updated_at" => Time.now.utc.iso8601))
+      @logger.info("openasn: canonical data updated to build #{manifest['build_id']}")
+      true
+    end
+
+    def current_local_build_id
+      path = File.join(@config.data_dir, "manifest.json")
+      return nil unless File.exist?(path)
+
+      JSON.parse(File.read(path))["build_id"]
+    rescue JSON::ParserError
+      nil
+    end
+
+    def read_state
+      path = File.join(@config.data_dir, "update-state.json")
+      File.exist?(path) ? JSON.parse(File.read(path)) : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    def write_state(state)
+      path = File.join(@config.data_dir, "update-state.json")
+      File.write("#{path}.tmp", JSON.pretty_generate(state))
+      File.rename("#{path}.tmp", path)
+    end
+
+    def with_lock
+      lock_path = File.join(@config.data_dir, ".update.lock")
+      File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |f|
+        unless f.flock(File::LOCK_EX | File::LOCK_NB)
+          @logger.info("openasn: another process is updating — skipping")
+          return :locked
+        end
+        yield
+      end
+    end
+
+    def notify(kind)
+      return unless defined?(ActiveSupport::Notifications)
+
+      ActiveSupport::Notifications.instrument("openasn.updated", kind: kind,
+                                                                 info: @dataset.info)
+    rescue StandardError => e
+      @logger.warn("openasn: notification hook failed (#{e.message})")
+    end
+  end
+end

data/lib/openasn/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OpenASN
+  VERSION = "0.2.0"
+end