brand_logo 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da46bcee230e23bbe43d0a20b21c13ef2eab0dd2faebcf8abfcf51ccb4d54fe0
-  data.tar.gz: 7c0888790d4919fa0e8d7cbbbfccdd3f5cbebc457f4206c64f34950f51cf423e
+  metadata.gz: 8ca5db19ef68c02172defd8e04ba4a228c5819c32e3f2aa8dd10de412b4889f1
+  data.tar.gz: 6a1bf3a2bda344977f005a0c12ae07c884fa24bc19d5bdabc650ccb57f2e9806
 SHA512:
-  metadata.gz: e589a8a91d7c41349997f0ed68a4f6f9ea3d6f53f2a7f98b796bf6491b3bc91b7301390db0074e200dcdfec21152bc88230d48605d0ec17e9bf7deb55eab4f68
-  data.tar.gz: b0b0763a1ec0a9ee78840997b9b759b0ff13fc94729db0426c24ddd3acb79f52d92c5f37c0d878fb047035f21915136da14b78026e4e2535eead61a73f471f73
+  metadata.gz: ee0e662864b0ede5a0a78b538109468efc96db273c41bb37ccb20c36f808e3869258e5e29792c8dfcb5a7410fc3c4fe45ffa8e9f6a3453197e421abc80a08173
+  data.tar.gz: 74c9c3d4fe4102fdc86bd2070129dc93b9f7b09da79677278c1ea0b3e4bc1cfdc6779195f4b800e0ea9d410c71b0f2d72f89c3ab59354d40b34385bac48557f3

data/CHANGELOG.md

@@ -3,6 +3,62 @@
 All notable changes to this project will be documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [2.0.0] - 2026-10-02
+
+Rewrite focused on picking the right icon, speed and safety. Breaking changes: see *Upgrading*.
+
+### Added
+
+- `JsonLd` strategy: schema.org `Organization` / `Brand` logos (including `@graph` and `ImageObject`).
+- `Browserconfig` strategy (`msapplication-config`) and `msapplication-TileImage` / `og:logo` meta tags.
+- `Google` favicon service fallback, before DuckDuckGo; both can be disabled with `external_fallbacks: []`.
+- `Fetcher#fetch!`, `Fetcher#fetch_many` (concurrent), URL input (`fetch('https://github.com/about')`).
+- Caching: in-memory by default, or any `read`/`write(expires_in:)` store such as `Rails.cache`; misses use `negative_cache_ttl`.
+- Ranking options: `prefer` (`:square`, `:largest`, `:svg`), `target_size`, `color_scheme` (`media` attribute).
+- `deadline` (total time per lookup), `user_agent`, `max_body_bytes`, `concurrency`, `block_private_ips`.
+- `Icon#source`, `#kind`, `#media`, `#width`, `#height`, `#to_h`, `Icon.from_h`.
+
+### Changed
+
+- `fetch` returns the best icon across strategies (stopping early once one is good enough) instead of the first strategy's result.
+- Every candidate is probed: dead links, HTML soft-404s and non-images are dropped; the format comes from the image bytes.
+- The homepage is fetched once per lookup (was up to 7 times); probes are deduplicated, run in parallel and read 64 KB at most.
+- Safari mask icons, monochrome icons and social banners rank last; PWA manifest icons beat `og:image`.
+- Redirects are followed for every request and the final URL (or `<base href>`) is used to resolve relative links.
+- Requests send a browser-like `User-Agent`; `timeout` is now a total per request (default 5 s).
+- `sizes="16x16 32x32"`, uppercase `X` and query strings (`/icon.png?v=2`) are understood.
+- Domain validation accepts URLs and mixed case, rejects malformed labels (`-a.com`, `..com`).
+- `sorbet-runtime` is no longer a runtime dependency; `http` and `nokogiri` versions are bounded.
+
+### Security
+
+- SSRF protection (`block_private_ips`, on by default): private, loopback and link-local addresses are refused at every redirect; only `http`/`https` URLs are fetched.
+
+### Removed
+
+- `ScrapingStrategy` (now `LinkTag`), `MetaTagStrategy`, `ManifestStrategy`, `DuckduckgoStrategy` (now `Strategies::MetaTag`, `Manifest`, `Duckduckgo`).
+- `HttpClient`, `HtmlParser`, `ImageAnalyzer` interfaces: inject a `BrandLogo::Http::Client` instead.
+- `FetchError`, `ParseError`.
+
+### Upgrading from 1.x
+
+| 1.x | 2.0 |
+|---|---|
+| `fetch(domain)` raises `NoIconFoundError` | `fetch` returns `nil`; use `fetch!` to raise |
+| `icon.dimensions[:width]` | `icon.width` (or `icon.dimensions.width`) |
+| `icon.format == 'svg'` | `icon.format == :svg` |
+| `Config.new(min_dimensions: { width: 32, height: 32 })` | `Config.new(min_size: 32)` |
+| `max_dimensions:` | `max_size:` |
+| `Fetcher.new(strategies: [ScrapingStrategy.new(config:, http_client:, …)])` | `Fetcher.new(strategies: [Strategies::LinkTag.new])` |
+| custom strategy: subclass `BaseStrategy`, implement `fetch_all(domain)` | `include Strategies::Base`, implement `stage` and `call(context)` |
+
+## [1.0.1] - 2026-07-23
+
+### Changed
+
+- Publish to RubyGems via trusted publishing (OIDC) instead of a long-lived API key
+- Bump simplecov to 1.0.0, migrate `add_filter` to `skip`
+
 ## [1.0.0] - 2026-04-15
 
 First public release under the name `brand_logo`.

data/README.md

@@ -3,11 +3,24 @@
 [![Gem Version](https://badge.fury.io/rb/brand_logo.svg)](https://badge.fury.io/rb/brand_logo)
 [![Test](https://github.com/AdVitam/brand_logo/actions/workflows/main.yml/badge.svg)](https://github.com/AdVitam/brand_logo/actions/workflows/main.yml)
 
-Fetch the best logo or icon for any website from its domain.
+**Give it a domain, get back the best logo that site has to offer.**
 
-`brand_logo` chains several strategies (favicon tags, Open Graph / Twitter meta
-images, PWA web app manifests, DuckDuckGo fallback) and returns the best icon
-based on format and dimensions.
+```ruby
+BrandLogo::Fetcher.new.fetch('github.com').url # => "https://github.com/fluidicon.png"
+```
+
+Perfect for company directories, CRM enrichment, link previews or any list of brands that
+deserves real logos instead of blurry 16 px favicons.
+
+- **The right icon, not the first one** — favicon links, `apple-touch-icon`, schema.org JSON-LD
+  logos, Open Graph tags, PWA manifest and `browserconfig.xml` are compared by their *real*
+  size and format. Square, crisp and SVG wins; Safari mask icons and social banners lose.
+- **Fast** — one homepage request, image probes run in parallel and read 64 KB at most,
+  the lookup stops as soon as a good icon is found, and results are cached (`Rails.cache` ready).
+- **Never empty-handed** — Google and DuckDuckGo favicon services as a last resort.
+- **Safe on untrusted input** — SSRF protection on every redirect, bounded timeouts and body sizes.
+- **Tunable** — prefer square, largest or SVG, target a size, pick dark-mode icons.
+- **Light** — no `sorbet-runtime` dependency, thread-safe, batch lookups with `fetch_many`.
 
 ## Installation
 
@@ -21,78 +34,95 @@ gem 'brand_logo'
 require 'brand_logo'
 
 fetcher = BrandLogo::Fetcher.new
-icon = fetcher.fetch('github.com')
 
-icon.url        # => "https://github.com/favicon.svg"
-icon.format     # => "svg"
-icon.dimensions # => { width: nil, height: nil }
+icon = fetcher.fetch('github.com')        # => BrandLogo::Icon or nil
+icon.url     # => "https://github.com/fluidicon.png"
+icon.format  # => :png
+icon.width   # => 512
+icon.source  # => :link_tag
+icon.kind    # => :icon
+icon.to_h    # => { url:, format:, width:, height:, source:, kind:, media: }
+
+fetcher.fetch!('https://github.com/about')  # URLs are accepted; raises NoIconFoundError when nothing is found
+fetcher.fetch_all('github.com')             # every valid icon, best first
+fetcher.fetch_many(%w[github.com ruby-lang.org]) # => { 'github.com' => Icon, 'ruby-lang.org' => Icon }
 ```
 
-### All icons
+A `Fetcher` is thread-safe and meant to be reused (it holds the cache).
 
-```ruby
-icons = fetcher.fetch_all('github.com')
-# Every icon found across all strategies, deduplicated by URL
-```
-
-### Configuration
+## Configuration
 
 ```ruby
 config = BrandLogo::Config.new(
-  min_dimensions: { width: 32, height: 32 },   # ignore tiny icons
-  max_dimensions: { width: 512, height: 512 }, # ignore oversized images
-  allow_svg:      true,                        # prefer SVG when available
-  timeout:        10,                          # HTTP timeout in seconds
-  max_hops:       5                            # max redirects to follow
+  min_size: 32,                        # Integer, { width:, height: } or BrandLogo::Dimensions
+  max_size: { width: 1024, height: 1024 },
+  allow_svg: true,
+  prefer: :square,                     # :square, :largest or :svg
+  target_size: 192,                    # pick the icon closest to (and preferably above) this size
+  color_scheme: :dark,                 # favour <link media="(prefers-color-scheme: dark)"> icons
+  timeout: 5,                          # seconds per request
+  deadline: 15,                        # seconds per lookup; the best icon found so far is returned
+  max_hops: 5,                         # redirects per request
+  max_body_bytes: 2_000_000,
+  user_agent: 'MyApp/1.0',
+  concurrency: 4,                      # parallel probes and fetch_many lookups
+  block_private_ips: true,             # SSRF protection, see below
+  external_fallbacks: %i[google duckduckgo], # [] to never contact third parties
+  cache: Rails.cache,                  # anything with read(key) / write(key, value, expires_in:); nil disables
+  cache_ttl: 86_400,
+  negative_cache_ttl: 3_600
 )
 
 fetcher = BrandLogo::Fetcher.new(config: config)
+other = BrandLogo::Fetcher.new(config: config.with(prefer: :largest))
 ```
 
-### Custom strategy chain
+Invalid settings raise `BrandLogo::ValidationError`. The default cache is an in-memory store
+per `Fetcher`. Lookups that hit the deadline without a result are not cached.
 
-Strategies are tried in order until one succeeds:
+### Custom strategies
 
 ```ruby
-fetcher = BrandLogo::Fetcher.new(
-  strategies: [
-    BrandLogo::Strategies::ScrapingStrategy.new(config: config, ...),
-    BrandLogo::Strategies::DuckduckgoStrategy.new(config: config, ...)
-  ]
-)
-```
+class MyStrategy
+  include BrandLogo::Strategies::Base
 
-Default chain: `ScrapingStrategy → MetaTagStrategy → ManifestStrategy → DuckduckgoStrategy`
+  def stage = :document
 
-### Logging
+  def call(context)
+    page = context.page or return []
+    url = page.resolve(page.document.at('img.logo')&.[]('src')) or return []
+    [BrandLogo::Icon.new(url: url, source: :my_strategy, kind: :logo)]
+  end
+end
 
-```ruby
-require 'logger'
-BrandLogo::Logging.logger.level = Logger::DEBUG  # verbose output
-BrandLogo::Logging.logger = MyCustomLogger.new   # inject your own logger
+BrandLogo::Fetcher.new(strategies: [MyStrategy.new, BrandLogo::Strategies::LinkTag.new])
 ```
 
-## Strategies
+## Input
+
+`fetch` accepts a hostname or a URL (`"GitHub.com "`, `"https://github.com/about"`).
+Internationalized domains must be given in punycode (`xn--…`); IP addresses are rejected.
 
-| Strategy | Source | Notes |
-|---|---|---|
-| `ScrapingStrategy` | HTML `<link rel="icon">` tags | Primary — tries `https://`, `https://www.`, `http://` |
-| `MetaTagStrategy` | `og:image`, `twitter:image` | High-res images, filter via `max_dimensions` |
-| `ManifestStrategy` | PWA `manifest.json` `icons[]` | Best for progressive web apps |
-| `DuckduckgoStrategy` | DuckDuckGo icon cache | Last-resort fallback |
+## Security
 
-## Error handling
+The gem fetches URLs chosen by third-party pages. With `block_private_ips: true` (default),
+every request — including each redirect — is refused unless its host resolves only to public
+addresses, and only `http`/`https` URLs are fetched. A DNS answer that changes between the check
+and the connection (DNS rebinding) is not covered; run lookups from a network without access to
+sensitive internal services if inputs are untrusted.
+
+## Logging
 
 ```ruby
-begin
-  icon = fetcher.fetch('example.com')
-rescue BrandLogo::NoIconFoundError
-  # no icon found by any strategy
-rescue BrandLogo::ValidationError => e
-  # invalid domain format: e.message
-end
+BrandLogo::Logging.logger.level = Logger::DEBUG
+BrandLogo::Logging.logger = Rails.logger
 ```
 
+## Sorbet
+
+The gem is typed with Sorbet but does not depend on `sorbet-runtime`: signatures are checked
+statically in CI, and at runtime the gem uses `sorbet-runtime` only if your bundle already has it.
+
 ## Requirements
 
 - Ruby >= 3.2
@@ -102,6 +132,13 @@ end
 Bug reports and pull requests are welcome on GitHub at
 <https://github.com/AdVitam/brand_logo>.
 
+```bash
+bundle exec rspec
+bundle exec rubocop
+bundle exec srb tc
+E2E=1 bundle exec rspec --tag e2e   # hits real websites
+```
+
 ## License
 
 Released under the MIT License. See [LICENSE.txt](LICENSE.txt).

data/lib/brand_logo/cache.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# typed: strict
+
+module BrandLogo
+  # Duck-typed on read / write(expires_in:) so Rails.cache can be passed as is.
+  module Cache
+    class Memory
+      extend T::Sig
+
+      sig { params(max_entries: Integer).void }
+      def initialize(max_entries: 1_000)
+        @max_entries = max_entries
+        @entries = T.let({}, T::Hash[String, [T.untyped, Float]])
+        @mutex = T.let(Mutex.new, Mutex)
+      end
+
+      sig { params(key: String).returns(T.untyped) }
+      def read(key)
+        @mutex.synchronize do
+          entry = @entries[key]
+          return nil unless entry
+
+          value, expires_at = entry
+          return value if now < expires_at
+
+          @entries.delete(key)
+          nil
+        end
+      end
+
+      sig { params(key: String, value: T.untyped, expires_in: T.any(Integer, Float)).void }
+      def write(key, value, expires_in:)
+        @mutex.synchronize do
+          @entries.delete(key)
+          @entries[key] = [value, now + expires_in]
+          @entries.shift while @entries.size > @max_entries
+        end
+      end
+
+      private
+
+      sig { returns(Float) }
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC).to_f
+      end
+    end
+  end
+end

data/lib/brand_logo/concurrency.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+# typed: strict
+
+module BrandLogo
+  module Concurrency
+    extend T::Sig
+
+    sig do
+      type_parameters(:I, :O)
+        .params(
+          items: T::Array[T.type_parameter(:I)],
+          size: Integer,
+          block: T.proc.params(item: T.type_parameter(:I)).returns(T.type_parameter(:O))
+        )
+        .returns(T::Array[T.type_parameter(:O)])
+    end
+    def self.map(items, size:, &block)
+      return items.map(&block) if items.size <= 1 || size <= 1
+
+      results = T.let(Array.new(items.size), T::Array[T.untyped])
+      failures = Queue.new
+      queue = Queue.new(items.each_index.to_a).close
+
+      spawn([size, items.size].min) { work(queue, failures) { |index| results[index] = yield(items.fetch(index)) } }
+      raise failures.pop unless failures.empty?
+
+      results
+    end
+
+    sig { params(count: Integer, block: T.proc.void).void }
+    def self.spawn(count, &block)
+      Array.new(count) do
+        Thread.new do
+          Thread.current.report_on_exception = false
+          yield
+        end
+      end.each(&:join)
+    end
+
+    sig { params(queue: Thread::Queue, failures: Thread::Queue, block: T.proc.params(index: Integer).void).void }
+    def self.work(queue, failures, &block)
+      while (index = queue.pop)
+        begin
+          yield(index)
+        rescue StandardError => e
+          failures << e
+          queue.clear
+        end
+      end
+    end
+    private_class_method :spawn, :work
+  end
+end

data/lib/brand_logo/config.rb

@@ -1,60 +1,112 @@
 # frozen_string_literal: true
 # typed: strict
 
-require 'sorbet-runtime'
+require 'digest'
 
 module BrandLogo
-  # Immutable configuration object for the gem.
-  # Centralizes all runtime parameters, replacing the 4 primitive kwargs
-  # previously duplicated across every strategy constructor.
-  #
-  # Usage:
-  #   config = BrandLogo::Config.new(min_dimensions: { width: 32, height: 32 }, timeout: 5)
-  class Config
+  Config = Data.define(
+    :min_size, :max_size, :allow_svg, :prefer, :target_size, :color_scheme,
+    :timeout, :deadline, :max_hops, :max_body_bytes, :user_agent, :concurrency,
+    :block_private_ips, :external_fallbacks, :cache, :cache_ttl, :negative_cache_ttl
+  ) do
     extend T::Sig
 
-    DEFAULT_TIMEOUT      = T.let(10, Integer)
-    DEFAULT_MAX_HOPS     = T.let(5, Integer)
-    DEFAULT_MIN_DIMENSIONS = T.let({ width: 0, height: 0 }.freeze, T::Hash[Symbol, Integer])
-    DEFAULT_DIMENSIONS   = T.let({ width: 16, height: 16 }.freeze, T::Hash[Symbol, Integer])
-    DEFAULT_FAVICON_PATH = T.let('/favicon.ico', String)
-
-    sig { returns(T::Hash[Symbol, Integer]) }
-    attr_reader :min_dimensions
-
-    sig { returns(T.nilable(T::Hash[Symbol, Integer])) }
-    attr_reader :max_dimensions
-
-    sig { returns(T::Boolean) }
-    attr_reader :allow_svg
-
-    sig { returns(Integer) }
-    attr_reader :timeout
-
-    sig { returns(Integer) }
-    attr_reader :max_hops
-
     sig do
       params(
-        min_dimensions: T::Hash[Symbol, Integer],
-        max_dimensions: T.nilable(T::Hash[Symbol, Integer]),
+        min_size: T.untyped,
+        max_size: T.untyped,
         allow_svg: T::Boolean,
-        timeout: Integer,
-        max_hops: Integer
+        prefer: Symbol,
+        target_size: T.nilable(Integer),
+        color_scheme: T.nilable(Symbol),
+        timeout: Numeric,
+        deadline: Numeric,
+        max_hops: Integer,
+        max_body_bytes: Integer,
+        user_agent: String,
+        concurrency: Integer,
+        block_private_ips: T::Boolean,
+        external_fallbacks: T::Array[Symbol],
+        cache: T.untyped,
+        cache_ttl: Integer,
+        negative_cache_ttl: Integer
       ).void
     end
     def initialize(
-      min_dimensions: DEFAULT_MIN_DIMENSIONS,
-      max_dimensions: nil,
-      allow_svg: true,
-      timeout: DEFAULT_TIMEOUT,
-      max_hops: DEFAULT_MAX_HOPS
+      min_size: nil, max_size: nil, allow_svg: true, prefer: :square, target_size: nil, color_scheme: nil,
+      timeout: 5, deadline: 15, max_hops: 5, max_body_bytes: 2_000_000, user_agent: Config::USER_AGENT,
+      concurrency: 4, block_private_ips: true, external_fallbacks: Config::EXTERNAL_FALLBACKS, cache: Cache::Memory.new,
+      cache_ttl: 86_400, negative_cache_ttl: 3_600
     )
-      @min_dimensions = T.let(min_dimensions, T::Hash[Symbol, Integer])
-      @max_dimensions = T.let(max_dimensions, T.nilable(T::Hash[Symbol, Integer]))
-      @allow_svg      = T.let(allow_svg, T::Boolean)
-      @timeout        = T.let(timeout, Integer)
-      @max_hops       = T.let(max_hops, Integer)
+      super(
+        min_size: Dimensions.coerce(min_size), max_size: Dimensions.coerce(max_size), allow_svg: allow_svg,
+        prefer: prefer, target_size: target_size, color_scheme: color_scheme, timeout: timeout,
+        deadline: deadline, max_hops: max_hops, max_body_bytes: max_body_bytes, user_agent: user_agent,
+        concurrency: concurrency, block_private_ips: block_private_ips,
+        external_fallbacks: external_fallbacks.dup.freeze, cache: cache, cache_ttl: cache_ttl,
+        negative_cache_ttl: negative_cache_ttl
+      )
+      validate!
+    end
+
+    # Data#with skips initialize before Ruby 3.3, which would bypass coercion and validation.
+    sig { params(changes: T.untyped).returns(Config) }
+    def with(**changes)
+      self.class.new(**to_h, **changes)
+    end
+
+    # Identifies the settings that change which icon wins, so cached results never leak across them.
+    sig { returns(String) }
+    def cache_digest
+      Digest::SHA256.hexdigest(
+        [min_size, max_size, allow_svg, prefer, target_size, color_scheme, external_fallbacks,
+         block_private_ips].inspect
+      )[0, 12].to_s
+    end
+
+    private
+
+    sig { void }
+    def validate!
+      validate_choices!
+      validate_numbers!
+      check(cache.nil? || (cache.respond_to?(:read) && cache.respond_to?(:write)), 'cache must respond to read/write')
+      check(!(min_size && max_size) || T.must(max_size).at_least?(T.must(min_size)), 'max_size must be >= min_size')
+    end
+
+    sig { void }
+    def validate_choices!
+      check(Config::PREFERENCES.include?(prefer), "prefer must be one of #{Config::PREFERENCES}")
+      check(color_scheme.nil? || Config::COLOR_SCHEMES.include?(color_scheme),
+            "color_scheme must be nil or one of #{Config::COLOR_SCHEMES}")
+      check((external_fallbacks - Config::EXTERNAL_FALLBACKS).empty?,
+            "external_fallbacks must be within #{Config::EXTERNAL_FALLBACKS}")
+    end
+
+    sig { void }
+    def validate_numbers!
+      size = target_size
+      check(size.nil? || size.positive?, 'target_size must be positive')
+      %i[timeout deadline max_body_bytes concurrency].each do |key|
+        check(public_send(key).positive?, "#{key} must be positive")
+      end
+      %i[max_hops cache_ttl negative_cache_ttl].each { |key| check(!public_send(key).negative?, "#{key} must be >= 0") }
     end
+
+    sig { params(condition: T::Boolean, message: String).void }
+    def check(condition, message)
+      raise ValidationError, message unless condition
+    end
+  end
+
+  # Reopened because constants defined inside a Data.define block would land on BrandLogo.
+  class Config
+    PREFERENCES = T.let(%i[square largest svg].freeze, T::Array[Symbol])
+    COLOR_SCHEMES = T.let(%i[light dark].freeze, T::Array[Symbol])
+    EXTERNAL_FALLBACKS = T.let(%i[google duckduckgo].freeze, T::Array[Symbol])
+    USER_AGENT = T.let(
+      'Mozilla/5.0 (compatible; BrandLogo/2; +https://github.com/AdVitam/brand_logo)',
+      String
+    )
   end
 end

data/lib/brand_logo/context.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'uri'
+
+module BrandLogo
+  class Context
+    extend T::Sig
+
+    sig { returns(String) }
+    attr_reader :domain
+
+    sig { returns(Config) }
+    attr_reader :config
+
+    sig { returns(Deadline) }
+    attr_reader :deadline
+
+    sig { params(domain: String, config: Config, http: Http::Client, deadline: T.nilable(Deadline)).void }
+    def initialize(domain:, config:, http:, deadline: nil)
+      @domain = domain
+      @config = config
+      @http = http
+      @deadline = T.let(deadline || Deadline.new(config.deadline), Deadline)
+      @lock = T.let(Mutex.new, Mutex)
+      @page = T.let(nil, T.nilable(Page))
+      @page_loaded = T.let(false, T::Boolean)
+      @probes = T.let({}, T::Hash[String, T.nilable(ImageProbe::Result)])
+    end
+
+    sig { params(url: String, max_bytes: T.nilable(Integer), range: T.nilable(T::Range[Integer])).returns(T.nilable(Http::Response)) }
+    def get(url, max_bytes: nil, range: nil)
+      @http.get(url, deadline: @deadline, max_bytes: max_bytes || @config.max_body_bytes, range: range)
+    end
+
+    sig { returns(T.nilable(Page)) }
+    def page
+      @lock.synchronize do
+        unless @page_loaded
+          @page = Page.fetch(self)
+          @page_loaded = true
+        end
+        @page
+      end
+    end
+
+    sig { params(url: String).returns(T.nilable(ImageProbe::Result)) }
+    def probe(url)
+      return @probes[url] if @lock.synchronize { @probes.key?(url) }
+
+      body = url.start_with?('data:') ? decode_data_uri(url) : get(url, max_bytes: ImageProbe::BYTES, range: 0...ImageProbe::BYTES)&.body
+      result = body && ImageProbe.analyze(body)
+      @lock.synchronize { @probes[url] = result }
+    end
+
+    private
+
+    sig { params(url: String).returns(T.nilable(String)) }
+    def decode_data_uri(url)
+      header, payload = url.split(',', 2)
+      return nil unless header && payload
+
+      header.end_with?(';base64') ? payload.unpack1('m') : URI.decode_www_form_component(payload)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/brand_logo/deadline.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+# typed: strict
+
+module BrandLogo
+  class Deadline
+    extend T::Sig
+
+    sig { params(seconds: Numeric).void }
+    def initialize(seconds)
+      @expires_at = T.let(now + seconds.to_f, Float)
+    end
+
+    sig { returns(Float) }
+    def remaining
+      [@expires_at - now, 0.0].max
+    end
+
+    sig { returns(T::Boolean) }
+    def expired?
+      remaining.zero?
+    end
+
+    private
+
+    sig { returns(Float) }
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC).to_f
+    end
+  end
+end