brand_logo 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: da46bcee230e23bbe43d0a20b21c13ef2eab0dd2faebcf8abfcf51ccb4d54fe0
+  data.tar.gz: 7c0888790d4919fa0e8d7cbbbfccdd3f5cbebc457f4206c64f34950f51cf423e
+SHA512:
+  metadata.gz: e589a8a91d7c41349997f0ed68a4f6f9ea3d6f53f2a7f98b796bf6491b3bc91b7301390db0074e200dcdfec21152bc88230d48605d0ec17e9bf7deb55eab4f68
+  data.tar.gz: b0b0763a1ec0a9ee78840997b9b759b0ff13fc94729db0426c24ddd3acb79f52d92c5f37c0d878fb047035f21915136da14b78026e4e2535eead61a73f471f73

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [1.0.0] - 2026-04-15
+
+First public release under the name `brand_logo`.
+
+### Added
+
+- `BrandLogo::Fetcher` entry point — accepts `config:` and `strategies:` keyword
+  arguments.
+- `fetch_all(domain)` on `Fetcher` — returns every icon found across all
+  strategies, deduplicated by URL.
+- **Four strategies**, tried in order:
+  - `ScrapingStrategy` — parses HTML `<link rel="icon">` tags, retries with
+    `https://www.` prefix and `http://` fallback.
+  - `MetaTagStrategy` — reads `og:image`, `twitter:image` meta tags.
+  - `ManifestStrategy` — parses PWA `manifest.json` `icons[]` entries.
+  - `DuckduckgoStrategy` — last-resort DuckDuckGo icon cache fallback.
+- `BrandLogo::Config` — centralises `min_dimensions`, `max_dimensions`,
+  `allow_svg`, `timeout`, `max_hops`.
+- `BrandLogo::Logging` — configurable via any stdlib `Logger`.
+- Typed error hierarchy: `FetchError`, `NoIconFoundError`, `ValidationError`,
+  `ParseError`.
+- Domain validation in `Fetcher#fetch` — raises `ValidationError` for invalid input.
+- Configurable HTTP timeout (default 10 s).
+- Dependency injection for `HttpClient`, `HtmlParser`, `ImageAnalyzer` — strategies are
+  fully testable without network calls.
+- Sorbet `typed: strict` everywhere.
+- RSpec test suite with **100% line coverage** (SimpleCov).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AdVitam (https://www.advitam.fr)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,107 @@
+# brand_logo
+
+[![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.
+
+`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.
+
+## Installation
+
+```ruby
+gem 'brand_logo'
+```
+
+## Usage
+
+```ruby
+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 }
+```
+
+### All icons
+
+```ruby
+icons = fetcher.fetch_all('github.com')
+# Every icon found across all strategies, deduplicated by URL
+```
+
+### 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
+)
+
+fetcher = BrandLogo::Fetcher.new(config: config)
+```
+
+### Custom strategy chain
+
+Strategies are tried in order until one succeeds:
+
+```ruby
+fetcher = BrandLogo::Fetcher.new(
+  strategies: [
+    BrandLogo::Strategies::ScrapingStrategy.new(config: config, ...),
+    BrandLogo::Strategies::DuckduckgoStrategy.new(config: config, ...)
+  ]
+)
+```
+
+Default chain: `ScrapingStrategy → MetaTagStrategy → ManifestStrategy → DuckduckgoStrategy`
+
+### Logging
+
+```ruby
+require 'logger'
+BrandLogo::Logging.logger.level = Logger::DEBUG  # verbose output
+BrandLogo::Logging.logger = MyCustomLogger.new   # inject your own logger
+```
+
+## Strategies
+
+| 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 |
+
+## Error handling
+
+```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
+```
+
+## Requirements
+
+- Ruby >= 3.2
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+<https://github.com/AdVitam/brand_logo>.
+
+## License
+
+Released under the MIT License. See [LICENSE.txt](LICENSE.txt).

data/lib/brand_logo/config.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+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
+    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]),
+        allow_svg: T::Boolean,
+        timeout: Integer,
+        max_hops: 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_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)
+    end
+  end
+end

data/lib/brand_logo/errors.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# typed: strict
+
+module BrandLogo
+  class Error < StandardError; end
+  class FetchError < Error; end
+  class ParseError < Error; end
+  class ValidationError < Error; end
+  class NoIconFoundError < FetchError; end
+end

data/lib/brand_logo/fetcher.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+module BrandLogo
+  # Entry point for brand_logo retrieval.
+  #
+  # Composes a chain of strategies tried in order until one finds a valid icon.
+  # Dependencies (HTTP client, HTML parser, image analyzer) are instantiated once
+  # and shared across all strategies.
+  #
+  # Usage:
+  #   # Default configuration
+  #   icon = BrandLogo::Fetcher.new.fetch('github.com')
+  #
+  #   # Custom config
+  #   config = BrandLogo::Config.new(min_dimensions: { width: 32, height: 32 }, timeout: 5)
+  #   icon = BrandLogo::Fetcher.new(config: config).fetch('github.com')
+  #
+  #   # Custom strategy chain (OCP)
+  #   fetcher = BrandLogo::Fetcher.new(strategies: [MyCustomStrategy.new(config: config)])
+  #
+  #   # All icons from all strategies
+  #   icons = BrandLogo::Fetcher.new.fetch_all('github.com')
+  class Fetcher
+    extend T::Sig
+
+    DOMAIN_PATTERN = T.let(/\A[a-z0-9\-.]+\.[a-z]{2,}\z/i, Regexp)
+
+    sig do
+      params(
+        config: T.nilable(Config),
+        strategies: T.nilable(T::Array[Strategies::BaseStrategy])
+      ).void
+    end
+    def initialize(config: nil, strategies: nil)
+      @config         = T.let(config || Config.new, Config)
+      @http_client    = T.let(RealHttpClient.new(@config), HttpClient)
+      @image_analyzer = T.let(FastimageAnalyzer.new, ImageAnalyzer)
+      @html_parser    = T.let(NokogiriParser.new, HtmlParser)
+      @strategies     = T.let(strategies || build_default_strategies, T::Array[Strategies::BaseStrategy])
+    end
+
+    # Returns the best icon found for the domain across all strategies.
+    # Raises NoIconFoundError if no strategy finds a valid icon.
+    sig { params(domain: String).returns(Icon) }
+    def fetch(domain)
+      validate_domain!(domain)
+      BrandLogo::Logging.logger.debug("Fetching brand_logo for: #{domain}")
+
+      @strategies.each do |strategy|
+        BrandLogo::Logging.logger.debug("Trying #{strategy.class.name}")
+        icon = strategy.fetch(domain)
+        return icon if icon
+      end
+
+      raise NoIconFoundError, "No brand_logo found for #{domain}"
+    end
+
+    # Returns all icons found across every strategy, deduplicated by URL.
+    sig { params(domain: String).returns(T::Array[Icon]) }
+    def fetch_all(domain)
+      validate_domain!(domain)
+
+      @strategies
+        .flat_map { |strategy| strategy.fetch_all(domain) }
+        .uniq(&:url)
+    end
+
+    private
+
+    sig { params(domain: String).void }
+    def validate_domain!(domain)
+      return if domain.match?(DOMAIN_PATTERN)
+
+      raise ValidationError, "Invalid domain: #{domain.inspect}"
+    end
+
+    sig { returns(T::Array[Strategies::BaseStrategy]) }
+    def build_default_strategies
+      [
+        Strategies::ScrapingStrategy.new(
+          config: @config,
+          http_client: @http_client,
+          html_parser: @html_parser,
+          image_analyzer: @image_analyzer
+        ),
+        Strategies::MetaTagStrategy.new(
+          config: @config,
+          http_client: @http_client,
+          html_parser: @html_parser,
+          image_analyzer: @image_analyzer
+        ),
+        Strategies::ManifestStrategy.new(
+          config: @config,
+          http_client: @http_client,
+          html_parser: @html_parser,
+          image_analyzer: @image_analyzer
+        ),
+        Strategies::DuckduckgoStrategy.new(
+          config: @config,
+          http_client: @http_client,
+          image_analyzer: @image_analyzer
+        )
+      ]
+    end
+  end
+end

data/lib/brand_logo/html_parser.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+require 'nokogiri'
+
+module BrandLogo
+  # Value Object wrapping a parsed HTML document.
+  # Exposes only the subset of the Nokogiri API that strategies need,
+  # preventing strategies from depending on Nokogiri directly.
+  class ParsedDocument
+    extend T::Sig
+
+    sig { params(doc: Nokogiri::HTML::Document).void }
+    def initialize(doc)
+      @doc = T.let(doc, Nokogiri::HTML::Document)
+    end
+
+    # Returns all elements matching the CSS selector.
+    sig { params(selector: String).returns(T::Array[T.untyped]) }
+    def css(selector)
+      @doc.css(selector).to_a
+    end
+
+    # Returns the first element matching the CSS selector, or nil.
+    sig { params(selector: String).returns(T.untyped) }
+    def at(selector)
+      @doc.at(selector)
+    end
+
+    # Returns the href of the <base> tag if present.
+    sig { returns(T.nilable(String)) }
+    def base_href
+      node = @doc.at('base')
+      return nil unless node
+
+      node['href']
+    end
+  end
+
+  # Interface for parsing raw HTML into a ParsedDocument.
+  # Strategies receive this via dependency injection.
+  module HtmlParser
+    extend T::Sig
+    extend T::Helpers
+
+    interface!
+
+    sig { abstract.params(html: String).returns(ParsedDocument) }
+    def parse(html); end
+  end
+
+  # Concrete implementation using the Nokogiri gem.
+  class NokogiriParser
+    extend T::Sig
+    include HtmlParser
+
+    sig { override.params(html: String).returns(ParsedDocument) }
+    def parse(html)
+      ParsedDocument.new(Nokogiri::HTML(html))
+    end
+  end
+end

data/lib/brand_logo/http_client.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+require 'http'
+
+module BrandLogo
+  # Interface for HTTP operations used by strategies.
+  # Decouples strategies from the HTTP gem, enabling injection of test doubles.
+  module HttpClient
+    extend T::Sig
+    extend T::Helpers
+
+    interface!
+
+    # Fetches the body of a URL. Returns nil on any failure (network, non-2xx, timeout).
+    sig { abstract.params(url: String).returns(T.nilable(String)) }
+    def get_body(url); end
+
+    # Returns true if a HEAD request to the URL succeeds (2xx). Returns false on any failure.
+    sig { abstract.params(url: String).returns(T::Boolean) }
+    def head_success?(url); end
+  end
+
+  # Concrete HTTP client using the `http` gem.
+  # Centralizes timeout and redirect configuration previously hardcoded
+  # across ScrapingStrategy, DuckduckgoStrategy, and UrlNormalizer.
+  class RealHttpClient
+    extend T::Sig
+    include HttpClient
+
+    sig { params(config: Config).void }
+    def initialize(config)
+      @timeout  = T.let(config.timeout, Integer)
+      @max_hops = T.let(config.max_hops, Integer)
+    end
+
+    sig { override.params(url: String).returns(T.nilable(String)) }
+    def get_body(url)
+      response = HTTP
+                 .timeout(connect: @timeout, read: @timeout, write: @timeout)
+                 .follow(max_hops: @max_hops)
+                 .get(url)
+      response.status.success? ? response.body.to_s : nil
+    rescue StandardError
+      nil
+    end
+
+    sig { override.params(url: String).returns(T::Boolean) }
+    def head_success?(url)
+      response = HTTP
+                 .timeout(connect: @timeout, read: @timeout, write: @timeout)
+                 .head(url)
+      response.status.success?
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/brand_logo/icon.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+module BrandLogo
+  # Represents a brand_logo icon with its URL, dimensions and format
+  # Used to store and return brand_logo information across the gem
+  class Icon
+    extend T::Sig
+
+    sig { returns(String) }
+    attr_reader :url
+
+    sig { returns(T::Hash[Symbol, T.nilable(Integer)]) }
+    attr_reader :dimensions
+
+    sig { returns(String) }
+    attr_reader :format
+
+    sig do
+      params(
+        url: String,
+        dimensions: T::Hash[Symbol, T.nilable(Integer)],
+        format: String
+      ).void
+    end
+    def initialize(url:, dimensions:, format:)
+      @url = url
+      @dimensions = dimensions
+      @format = format
+    end
+  end
+end

data/lib/brand_logo/image_analyzer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+require 'fastimage'
+
+module BrandLogo
+  # Interface for extracting image dimensions from a URL.
+  # Implementations are injected into strategies, enabling testing without network calls.
+  module ImageAnalyzer
+    extend T::Sig
+    extend T::Helpers
+
+    interface!
+
+    sig { abstract.params(url: String).returns(T::Hash[Symbol, T.nilable(Integer)]) }
+    def dimensions(url); end
+  end
+
+  # Concrete implementation using the FastImage gem.
+  # Avoids downloading the full image by parsing only the header bytes.
+  class FastimageAnalyzer
+    extend T::Sig
+    include ImageAnalyzer
+
+    sig { override.params(url: String).returns(T::Hash[Symbol, T.nilable(Integer)]) }
+    def dimensions(url)
+      result = FastImage.size(url)
+      return { width: nil, height: nil } unless result
+
+      { width: result[0], height: result[1] }
+    rescue StandardError
+      { width: nil, height: nil }
+    end
+  end
+end

data/lib/brand_logo/logging.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'logger'
+require 'sorbet-runtime'
+
+module BrandLogo
+  # Centralized logging for the gem.
+  # Replaces the DebugLogger module's debug boolean pattern.
+  #
+  # Usage:
+  #   BrandLogo::Logging.logger.level = Logger::DEBUG  # enable verbose output
+  #   BrandLogo::Logging.logger = MyCustomLogger.new   # inject custom logger
+  module Logging
+    extend T::Sig
+
+    @logger = T.let(::Logger.new($stderr, level: ::Logger::WARN), ::Logger)
+
+    sig { returns(::Logger) }
+    def self.logger
+      @logger
+    end
+
+    sig { params(logger: ::Logger).void }
+    def self.logger=(logger)
+      @logger = logger
+    end
+  end
+end

data/lib/brand_logo/strategies/base_strategy.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+module BrandLogo
+  module Strategies
+    # Abstract base class implementing the Template Method pattern.
+    #
+    # Subclasses implement `fetch_all` (the customization point).
+    # `fetch` is the common algorithm: fetch_all → filter valid → select best.
+    # This eliminates duplicated selection/validation logic across strategies.
+    class BaseStrategy
+      extend T::Sig
+      extend T::Helpers
+
+      abstract!
+
+      UNKNOWN_DIMENSION_SCORE = T.let(-1, Integer)
+
+      sig { params(config: Config).void }
+      def initialize(config:)
+        @config = T.let(config, Config)
+      end
+
+      # Returns ALL icons found for the domain (unfiltered).
+      # Subclasses must implement this method.
+      sig { abstract.params(domain: String).returns(T::Array[Icon]) }
+      def fetch_all(domain); end
+
+      # Returns the best valid icon for the domain, or nil if none found.
+      # Delegates to fetch_all, filters by validity, then selects the best.
+      sig { params(domain: String).returns(T.nilable(Icon)) }
+      def fetch(domain)
+        valid_icons = fetch_all(domain).select { |icon| valid_icon?(icon) }
+        select_best_icon(valid_icons)
+      end
+
+      protected
+
+      sig { params(icon: Icon).returns(T::Boolean) }
+      def valid_icon?(icon)
+        valid_dimensions?(icon) && valid_format?(icon)
+      end
+
+      private
+
+      sig { params(icon: Icon).returns(T::Boolean) }
+      def valid_dimensions?(icon)
+        return true if svg_icon?(icon)
+        return true if missing_dimensions?(icon)
+
+        meets_minimum_dimensions?(icon) && within_maximum_dimensions?(icon)
+      end
+
+      sig { params(icon: Icon).returns(T::Boolean) }
+      def valid_format?(icon)
+        return true if icon.format != 'svg'
+
+        @config.allow_svg
+      end
+
+      sig { params(icons: T::Array[Icon]).returns(T.nilable(Icon)) }
+      def select_best_icon(icons)
+        return nil if icons.empty?
+
+        if @config.allow_svg
+          svg_icon = icons.find { |icon| icon.format == 'svg' }
+          return svg_icon if svg_icon
+        end
+
+        icons.max_by { |icon| icon_score(icon) }
+      end
+
+      sig { params(icon: Icon).returns(Integer) }
+      def icon_score(icon)
+        width  = icon.dimensions[:width]
+        height = icon.dimensions[:height]
+        return UNKNOWN_DIMENSION_SCORE if width.nil? || height.nil?
+
+        width * height
+      end
+
+      sig { params(icon: Icon).returns(T::Boolean) }
+      def svg_icon?(icon)
+        @config.allow_svg && icon.format == 'svg'
+      end
+
+      sig { params(icon: Icon).returns(T::Boolean) }
+      def missing_dimensions?(icon)
+        icon.dimensions[:width].nil? || icon.dimensions[:height].nil?
+      end
+
+      sig { params(icon: Icon).returns(T::Boolean) }
+      def meets_minimum_dimensions?(icon)
+        min = @config.min_dimensions
+        width  = icon.dimensions[:width]
+        height = icon.dimensions[:height]
+        return false if width.nil? || height.nil?
+
+        width >= min[:width] && height >= min[:height]
+      end
+
+      sig { params(icon: Icon).returns(T::Boolean) }
+      def within_maximum_dimensions?(icon)
+        max = @config.max_dimensions
+        return true if max.nil?
+
+        width  = icon.dimensions[:width]
+        height = icon.dimensions[:height]
+        return true if width.nil? || height.nil?
+
+        width <= max[:width] && height <= max[:height]
+      end
+    end
+  end
+end