openasn 0.2.0

data/lib/openasn/data/seed/manifest.json

@@ -0,0 +1,99 @@
+{
+  "format_version": 1,
+  "edition": "core",
+  "build_id": "2026-07-04T20:36:12Z",
+  "files": [
+    {
+      "name": "openasn-ipv4.bin",
+      "sha256": "724015a457a90572670290641060330b5a11327867b22486566b54abd630fcb4",
+      "bytes": 6351346,
+      "records": 433579
+    },
+    {
+      "name": "openasn-ipv6.bin",
+      "sha256": "753f2c2ff237ac18a32a24c831622754dfef252c2a301a449d8ad24a8bbd353c",
+      "bytes": 4772984,
+      "records": 125604
+    },
+    {
+      "name": "openasn-orgs.bin",
+      "sha256": "61dc40bd72e7d12a68606e091f818474bfce89054c10da55dd70ae0d5284cf77",
+      "bytes": 4060956,
+      "records": 123392
+    },
+    {
+      "name": "asn-categories.csv",
+      "sha256": "d8ed709f56291bd55af399dbb159aff03776e6930f4bc786d3f0cc211c0ee16b",
+      "bytes": 6362920,
+      "records": 123392
+    },
+    {
+      "name": "fetch-manifest.json",
+      "sha256": "aceadec08e2c13992f5667724079da73ef20b7b532e6c0618f9c21fdc31357c6",
+      "bytes": 20760,
+      "records": 0
+    },
+    {
+      "name": "ATTRIBUTION.md",
+      "sha256": "ba4cd2c03117800e068762d2ebe29bdfdea182e82bb2f6dd2bc310074760afdc",
+      "bytes": 2399,
+      "records": 0
+    }
+  ],
+  "sources": [
+    {
+      "id": "sapics-origin-asn",
+      "url": "https://github.com/sapics/ip-location-db",
+      "license": "PDDL-1.0",
+      "license_sha256": "e8756fd515b673f3e868bf8d9aa5cbbb28d4611366c654e36977ea5279e6551a",
+      "fetched_at": "2026-07-04T20:26:23Z"
+    },
+    {
+      "id": "ipverse-as-metadata",
+      "url": "https://github.com/ipverse/as-metadata",
+      "license": "CC0-1.0",
+      "license_sha256": "a2010f343487d3f7618affe54f789f5487602331c0a8d03f49e9a7c547cf0499",
+      "fetched_at": "2026-07-04T20:02:11Z"
+    },
+    {
+      "id": "ipverse-as-ip-blocks",
+      "url": "https://github.com/ipverse/as-ip-blocks",
+      "license": "CC0-1.0",
+      "license_sha256": "a2010f343487d3f7618affe54f789f5487602331c0a8d03f49e9a7c547cf0499",
+      "fetched_at": "2026-07-04T20:36:14Z"
+    },
+    {
+      "id": "x4bnet-lists_vpn",
+      "url": "https://github.com/X4BNet/lists_vpn",
+      "license": "MIT",
+      "license_sha256": "8826b5fbb9d7380264deb636df4adf349eab0e640ca3f2f5481d74cea96ba7a5",
+      "fetched_at": "2026-07-04T20:02:11Z"
+    },
+    {
+      "id": "brianhama-bad-asn-list",
+      "url": "https://github.com/brianhama/bad-asn-list",
+      "license": "MIT",
+      "license_sha256": "67690d0688b2b17b2fb74446e0bf58132a389b2e543d9ba0c4c44a60fedd4e67",
+      "fetched_at": "2026-07-04T20:02:12Z"
+    },
+    {
+      "id": "openasn-overrides",
+      "url": "https://github.com/openasn/openasn",
+      "license": "CC0-1.0",
+      "license_sha256": null,
+      "fetched_at": "2026-07-04T20:36:14Z"
+    }
+  ],
+  "stats": {
+    "layer_counts": {
+      "base_ipv4": 433579,
+      "vpn_ipv4": 6405,
+      "dc_ipv4": 28746,
+      "base_ipv6": 125604
+    },
+    "hosting_asns": 12257,
+    "reference_dc_asns": 899,
+    "reference_coverage": 0.9132
+  },
+  "signature": null
+}

data/lib/openasn/dataset.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module OpenASN
+  # Owns the live Snapshot and its lifecycle. Concurrency model (the whole
+  # point of this class — do not "simplify" it):
+  #
+  #   * Readers call #snapshot and get whatever is current. The swap is a
+  #     single ivar assignment — atomic under MRI's GVL — so readers see
+  #     either the old complete snapshot or the new complete snapshot,
+  #     never partial state. No locks on the read path, ever.
+  #   * The lazy first load and explicit reloads are serialized with a
+  #     Mutex so N threads arriving on a cold process build one snapshot,
+  #     not N.
+  #   * Multi-process reality (puma workers): the updater process writes
+  #     new files atomically; OTHER processes notice via a cheap periodic
+  #     freshness probe (#maybe_reload_from_disk — a File.mtime call at
+  #     most every RELOAD_CHECK_INTERVAL seconds, amortized to ~zero) and
+  #     rebuild their in-memory snapshot from disk.
+  class Dataset
+    RELOAD_CHECK_INTERVAL = 300 # seconds
+    STALE_AFTER = 7 * 86_400    # boot-time "kick a refresh" threshold (documented in README "Updates")
+
+    def initialize(config)
+      @config = config
+      @snapshot = nil
+      @load_mutex = Mutex.new
+      @last_disk_check = 0.0
+      @loaded_manifest_mtime = nil
+    end
+
+    def snapshot
+      snap = @snapshot
+      return snap if snap && !disk_check_due?
+
+      snap ? maybe_reload_from_disk : load!
+    end
+
+    def eager_load!
+      load!
+      nil
+    end
+
+    # Called by the updater after it wrote new files: rebuild + swap now.
+    def reload!
+      @load_mutex.synchronize do
+        @snapshot = Snapshot.build(@config)
+        @loaded_manifest_mtime = manifest_mtime
+        @last_disk_check = monotonic_now
+        @snapshot
+      end
+    end
+
+    def loaded? = !@snapshot.nil?
+
+    def stale?
+      snap = snapshot
+      snap.age_seconds > STALE_AFTER
+    end
+
+    def info
+      snap = snapshot
+      {
+        build_id: snap.build_id,
+        built_at: Time.at(snap.build_ts).utc,
+        loaded_at: snap.loaded_at,
+        origin: snap.origin,
+        memory_mode: @config.memory_mode,
+        records: snap.record_counts,
+        tier_b_status: snap.tier_b_status
+      }
+    end
+
+    private
+
+    def load!
+      @load_mutex.synchronize do
+        # Another thread may have loaded while we waited on the mutex.
+        return @snapshot if @snapshot && !disk_check_due?
+
+        @snapshot = Snapshot.build(@config)
+        @loaded_manifest_mtime = manifest_mtime
+        @last_disk_check = monotonic_now
+        @snapshot
+      end
+    end
+
+    def disk_check_due?
+      monotonic_now - @last_disk_check > RELOAD_CHECK_INTERVAL
+    end
+
+    # Cheap cross-process freshness: compare the on-disk manifest mtime to
+    # what this process loaded. Runs at most once per RELOAD_CHECK_INTERVAL
+    # per process; costs one stat() when it does.
+    def maybe_reload_from_disk
+      @load_mutex.synchronize do
+        @last_disk_check = monotonic_now
+        current = manifest_mtime
+        if current != @loaded_manifest_mtime
+          @config.logger.info("openasn: dataset changed on disk — reloading")
+          @snapshot = Snapshot.build(@config)
+          @loaded_manifest_mtime = current
+        end
+        @snapshot
+      end
+    rescue StandardError => e
+      @config.logger.warn("openasn: reload check failed (#{e.message}); keeping current snapshot")
+      @snapshot
+    end
+
+    def manifest_mtime
+      path = File.join(@config.data_dir, "manifest.json")
+      File.exist?(path) ? File.mtime(path) : nil
+    end
+
+    def monotonic_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/openasn/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OpenASN
+  class Error < StandardError; end
+
+  # Raised for unparseable IP input. Inherits ArgumentError so bare
+  # `rescue ArgumentError` in caller code behaves as documented
+  # ("raises on invalid IP").
+  class InvalidIPError < ArgumentError; end
+
+  # Artifact bytes don't match the OASN/OORG format (truncated download,
+  # foreign file, or a format_version this gem doesn't speak).
+  class FormatError < Error; end
+
+  # Canonical refresh failed in a way worth surfacing to the caller of
+  # OpenASN.update! (Tier B sources never raise — they keep stale data).
+  class UpdateError < Error; end
+
+  # A downloaded artifact's SHA-256 didn't match the manifest. The file is
+  # discarded and the previous data stays live.
+  class IntegrityError < UpdateError; end
+end

data/lib/openasn/http_client.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module OpenASN
+  # Minimal stdlib HTTP client for the updater and Tier B executor.
+  #
+  # * Always sends a descriptive User-Agent (some endpoints 403 UA-less
+  #   clients; it's also basic politeness toward the volunteer-run sources
+  #   this gem depends on).
+  # * Follows redirects across hosts — GitHub release downloads ALWAYS
+  #   redirect to objects.githubusercontent.com / release-assets.…; if your
+  #   egress is allowlisted, those hosts must be on the list too.
+  # * Supports conditional GET via ETag (returns :not_modified).
+  # * Never talks to api.github.com (60 req/hr unauthenticated limit);
+  #   releases/download/<tag>/ asset URLs redirect fine without auth.
+  class HttpClient
+    MAX_REDIRECTS = 5
+    OPEN_TIMEOUT = 10
+    READ_TIMEOUT = 120 # artifacts are ~6MB; Apple's relay CSV ~10MB
+
+    Response = Struct.new(:body, :etag, keyword_init: true)
+
+    def initialize(user_agent:, logger:)
+      @user_agent = user_agent
+      @logger = logger
+    end
+
+    # -> Response | :not_modified. Raises on HTTP errors / timeouts.
+    def get(url, etag: nil)
+      headers = { "User-Agent" => @user_agent, "Accept-Encoding" => "identity" }
+      headers["If-None-Match"] = etag if etag
+
+      response = request(Net::HTTP::Get, url, headers, MAX_REDIRECTS)
+      case response
+      when Net::HTTPNotModified then :not_modified
+      when Net::HTTPSuccess then Response.new(body: response.body, etag: response["etag"])
+      else raise UpdateError, "HTTP #{response.code} for #{url}"
+      end
+    end
+
+    def post_form(url, form)
+      headers = { "User-Agent" => @user_agent,
+                  "Accept-Encoding" => "identity",
+                  "Content-Type" => "application/x-www-form-urlencoded" }
+      response = request(Net::HTTP::Post, url, headers, MAX_REDIRECTS, URI.encode_www_form(form))
+      case response
+      when Net::HTTPSuccess then Response.new(body: response.body, etag: response["etag"])
+      else raise UpdateError, "HTTP #{response.code} for #{url}"
+      end
+    end
+
+    private
+
+    def request(method, url, headers, redirects_left, body = nil)
+      raise UpdateError, "too many redirects for #{url}" if redirects_left.zero?
+
+      uri = URI(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = OPEN_TIMEOUT
+      http.read_timeout = READ_TIMEOUT
+
+      request = method.new(uri, headers)
+      request.body = body if body
+      response = http.request(request)
+      # Ruby models 304 Not Modified as a 3xx response, but it is not a
+      # redirect and correctly has no Location header. Return it to #get so
+      # conditional GETs are clean :not_modified events instead of noisy
+      # keep-stale failures.
+      if response.is_a?(Net::HTTPRedirection) && !response.is_a?(Net::HTTPNotModified)
+        location = response["location"]
+        raise UpdateError, "redirect without Location from #{url}" if location.nil?
+
+        location = URI.join(url, location).to_s unless location.start_with?("http")
+        # Conditional headers stay on the ORIGINAL url's cache identity;
+        # redirect targets are one-off signed URLs. Keep method headers such
+        # as Content-Type for POST-form provider endpoints.
+        redirect_headers = headers.reject { |key, _| key.casecmp("If-None-Match").zero? }
+        return request(method, location, redirect_headers, redirects_left - 1, body)
+      end
+      response
+    end
+  end
+end

data/lib/openasn/ip.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module OpenASN
+  # IP input parsing. Hot path: dotted-quad IPv4 strings (the overwhelming
+  # majority of real lookups) are parsed by hand — ~6x faster than
+  # IPAddr.new, which matters when the whole lookup budget is ~20µs.
+  # Everything else (IPv6, IPAddr instances, mapped addresses) goes through
+  # IPAddr for correctness.
+  module IP
+    module_function
+
+    # -> [family(:ipv4 | :ipv6), Integer]
+    # Raises OpenASN::InvalidIPError (an ArgumentError) on anything else.
+    def parse(input)
+      case input
+      when IPAddr
+        from_ipaddr(input)
+      when String
+        fast_v4(input) || from_string(input)
+      else
+        raise InvalidIPError, "expected an IP address String or IPAddr, got #{input.class}"
+      end
+    end
+
+    def fast_v4(str)
+      parts = str.split(".")
+      return nil unless parts.length == 4
+
+      int = 0
+      parts.each do |p|
+        # Reject empty octets, leading zeros ("01" is ambiguous octal in
+        # many parsers — safer to fall through to IPAddr, which rejects it),
+        # non-digits, and >255.
+        return nil if p.empty? || p.length > 3 || (p.length > 1 && p.start_with?("0"))
+
+        n = 0
+        p.each_char do |c|
+          d = c.ord - 48
+          return nil if d.negative? || d > 9
+
+          n = n * 10 + d
+        end
+        return nil if n > 255
+
+        int = (int << 8) | n
+      end
+      [:ipv4, int]
+    end
+
+    def from_string(str)
+      from_ipaddr(IPAddr.new(str))
+    rescue IPAddr::Error
+      raise InvalidIPError, "invalid IP address: #{str.inspect}"
+    end
+
+    def from_ipaddr(ip)
+      if ip.ipv4?
+        [:ipv4, ip.to_i]
+      elsif ip.ipv4_mapped?
+        # ::ffff:1.2.3.4 arrives on dual-stack sockets constantly; classify
+        # as the embedded IPv4 — that's the address doing the talking.
+        [:ipv4, ip.native.to_i]
+      else
+        [:ipv6, ip.to_i]
+      end
+    end
+  end
+end

data/lib/openasn/middleware.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module OpenASN
+  # Rack middleware: classifies the request IP once and exposes the result
+  # at env["openasn.result"] (nil when the IP is missing/unparseable —
+  # never raises into the request cycle).
+  #
+  #   use OpenASN::Middleware
+  #   # then anywhere downstream:
+  #   request.env["openasn.result"]&.infrastructure?
+  #
+  # THE CLASSIC INTEGRATION BUG (read this before filing "everything is
+  # :private/:hosting"): if your app sits behind a proxy/load balancer and
+  # trusted proxies aren't configured, the IP you classify is your own
+  # infrastructure's. Inside Rails we use ActionDispatch's remote_ip
+  # (which honors config.action_dispatch.trusted_proxies); bare Rack falls
+  # back to REMOTE_ADDR. Behind Cloudflare or a CDN, make sure the real
+  # client IP reaches Rails (e.g. cloudflare-rails gem or equivalent
+  # trusted_proxies setup) BEFORE trusting these verdicts.
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      env["openasn.result"] = classify(env)
+      @app.call(env)
+    end
+
+    private
+
+    def classify(env)
+      ip = if defined?(ActionDispatch::Request)
+             ActionDispatch::Request.new(env).remote_ip
+           else
+             env["REMOTE_ADDR"]
+           end
+      return nil if ip.nil? || ip.empty?
+
+      OpenASN.lookup(ip)
+    rescue InvalidIPError
+      nil
+    rescue StandardError => e
+      # Never let classification break a request; log and move on.
+      OpenASN.configuration.logger.warn("openasn middleware: #{e.class}: #{e.message}")
+      nil
+    end
+  end
+end

data/lib/openasn/overlay_store.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module OpenASN
+  # On-disk store for Tier B overlays under {data_dir}/overlays/.
+  #
+  # Files: {source_id}-ipv4.bin / {source_id}-ipv6.bin — raw concatenated
+  # big-endian (start, end) pairs, sorted and merged. No header: these are
+  # internal files owned by this gem, versioned by the `schema` field in
+  # state.json, and always written atomically (tmp + rename) so a reader
+  # process can never observe a torn file.
+  #
+  # state.json tracks per-source metadata: what it maps to, when it was
+  # fetched, ETag for conditional GETs, and the last error (keep-stale
+  # semantics: a failing source keeps serving its previous data, loudly).
+  class OverlayStore
+    SCHEMA = 1
+
+    Entry = Struct.new(:id, :maps_to, :provider, :v4, :v6, keyword_init: true)
+
+    def initialize(data_dir)
+      @dir = File.join(data_dir, "overlays")
+      @state_path = File.join(@dir, "state.json")
+    end
+
+    def state
+      return { "schema" => SCHEMA, "sources" => {} } unless File.exist?(@state_path)
+
+      parsed = JSON.parse(File.read(@state_path))
+      # Unknown future schema: treat as empty rather than misread it.
+      parsed["schema"] == SCHEMA ? parsed : { "schema" => SCHEMA, "sources" => {} }
+    rescue JSON::ParserError
+      { "schema" => SCHEMA, "sources" => {} }
+    end
+
+    def source_state(id) = state.dig("sources", id) || {}
+
+    # ranges_by_family: { ipv4: [[s,e],...] (sorted, merged), ipv6: [...] }
+    def write(id, maps_to:, provider: nil, etag: nil, ranges_by_family:)
+      FileUtils.mkdir_p(@dir)
+      counts = {}
+      %i[ipv4 ipv6].each do |family|
+        ranges = ranges_by_family[family] || []
+        counts[family] = ranges.length
+        packed = ranges.map { |(s, e)| BinaryFormat.pack_addr(s, family) + BinaryFormat.pack_addr(e, family) }.join
+        path = file_path(id, family)
+        File.binwrite("#{path}.tmp", packed)
+        File.rename("#{path}.tmp", path)
+      end
+      update_state(id) do |entry|
+        entry.merge(
+          "maps_to" => maps_to.to_s, "provider" => provider, "etag" => etag,
+          "fetched_at" => Time.now.utc.iso8601,
+          "records_ipv4" => counts[:ipv4], "records_ipv6" => counts[:ipv6],
+          "last_error" => nil
+        )
+      end
+    end
+
+    def record_failure(id, error_message)
+      update_state(id) do |entry|
+        entry.merge("last_error" => error_message, "last_attempt_at" => Time.now.utc.iso8601)
+      end
+    end
+
+    def record_fresh(id)
+      update_state(id) do |entry|
+        entry.merge("fetched_at" => Time.now.utc.iso8601, "last_error" => nil)
+      end
+    end
+
+    def fetched_at(id)
+      ts = source_state(id)["fetched_at"]
+      ts && Time.parse(ts)
+    rescue ArgumentError
+      nil
+    end
+
+    # Load every stored overlay among enabled_ids into memory.
+    def load(enabled_ids, mode)
+      sources = state["sources"]
+      enabled_ids.filter_map do |id|
+        meta = sources[id]
+        next unless meta
+
+        v4 = load_family(id, :ipv4, mode)
+        v6 = load_family(id, :ipv6, mode)
+        next unless v4 || v6
+
+        Entry.new(id: id, maps_to: meta["maps_to"], provider: meta["provider"],
+                  v4: v4, v6: v6)
+      end
+    end
+
+    def clear!(id)
+      %i[ipv4 ipv6].each { |f| FileUtils.rm_f(file_path(id, f)) }
+    end
+
+    private
+
+    def file_path(id, family) = File.join(@dir, "#{id}-#{family}.bin")
+
+    def load_family(id, family, mode)
+      path = file_path(id, family)
+      return nil unless File.exist?(path)
+
+      bytes = File.binread(path)
+      # A torn/odd-sized file would corrupt binary search: drop the tail.
+      rec = BinaryFormat.overlay_rec_size(family)
+      bytes = bytes[0, bytes.bytesize - (bytes.bytesize % rec)] if (bytes.bytesize % rec).positive?
+      BinaryFormat::OverlayLayer.build(bytes, family, mode)
+    end
+
+    def update_state(id)
+      FileUtils.mkdir_p(@dir)
+      current = state
+      current["sources"][id] = yield(current["sources"][id] || {})
+      File.write("#{@state_path}.tmp", JSON.pretty_generate(current))
+      File.rename("#{@state_path}.tmp", @state_path)
+    end
+  end
+end