shiplog 0.2.0 → 0.3.0

data/app/models/shiplog/entry.rb

@@ -2,7 +2,11 @@ module Shiplog
   class Entry < ApplicationRecord
     class InvalidTransition < StandardError; end
 
+    include Images
+
     belongs_to :subject, polymorphic: true
+    belongs_to :area, class_name: "Shiplog::Area", optional: true
+    has_many :translations, class_name: "Shiplog::EntryTranslation", dependent: :destroy, inverse_of: :entry
 
     enum :kind, %w[roadmap feature change].index_by(&:itself), validate: true
     enum :status, %w[draft approved discarded].index_by(&:itself), default: "draft", validate: true
@@ -10,9 +14,14 @@ module Shiplog
     CHANGELOG_KINDS = %w[feature change].freeze
 
     validates :released_on, presence: true, if: -> { approved? && !roadmap? }
+    validate :area_exists
     validate :kind_change_allowed, on: :update
     validate :kind_free_for_subject, on: :update
 
+    # Approving an entry, or changing the English text of an approved one, translates it into every configured
+    # locale (see TranslateEntryJob). After the commit, so the job reads what was saved.
+    after_commit :enqueue_translations, on: :update, if: :translation_due?
+
     SEARCH_MAX_LENGTH = 100
     SEARCH_MAX_WORDS = 5
 
@@ -22,12 +31,99 @@ module Shiplog
     end
 
     # Entries whose title or body contains every word of the query (case-insensitive, LIKE wildcards escaped).
-    # A blank query leaves the scope unchanged.
-    def self.search(query)
+    # With a configured `locale` other than the default, a word also matches the current translation of that
+    # locale (the text the page shows), not a stale one. A blank query leaves the scope unchanged.
+    def self.search(query, locale: nil)
+      locale = locale.to_s.presence_in(Shiplog.config.locales.map(&:to_s))
       search_terms(query).reduce(all) do |scope, term|
         pattern = "%#{sanitize_sql_like(term)}%"
-        scope.where("#{table_name}.title ILIKE :pattern OR #{table_name}.body ILIKE :pattern", pattern:)
+        english = "#{table_name}.title ILIKE :pattern OR #{table_name}.body ILIKE :pattern"
+        next scope.where(english, pattern:) unless locale
+
+        # One fragment, so the user's value is bound exactly once: the named binds are substituted in a single
+        # pass and the quoted text is never scanned again. Everything else in it is a constant.
+        translations = EntryTranslation.table_name
+        translated = "EXISTS (SELECT 1 FROM #{translations} WHERE #{translations}.entry_id = #{table_name}.id " \
+          "AND #{translations}.locale = :locale AND #{translations}.source_digest = #{TRANSLATION_DIGEST_SQL} " \
+          "AND (#{translations}.title ILIKE :pattern OR #{translations}.body ILIKE :pattern))"
+        scope.where("#{english} OR #{translated}", pattern:, locale:)
+      end
+    end
+
+    # Loads the translations of `entries` for the current locale in one query, and none under a locale that is
+    # not translated (then the entries show English and nothing is queried). Only that locale's rows are loaded
+    # into the `translations` association, so after this call it holds the current locale's rows, not all of them
+    # (use Entry#translation, not `translations`, to read them).
+    def self.preload_translations(entries, locale: I18n.locale)
+      entries = Array(entries).compact
+      return unless entries.any? && translated_locale?(locale)
+
+      ActiveRecord::Associations::Preloader.new(records: entries, associations: :translations,
+        scope: EntryTranslation.where(locale: locale.to_s)).call
+    end
+
+    # Whether pages in this locale show translations: it is one of config.locales.
+    def self.translated_locale?(locale) = Shiplog.config.locales.any? { |configured| configured.to_s == locale.to_s }
+
+    # The SQL twin of #translation_source_digest: SHA-256 of "title\nbody" (a missing text is empty), in hex.
+    TRANSLATION_DIGEST_SQL = "encode(sha256(convert_to(COALESCE(#{table_name}.title, '') || E'\\n' || COALESCE(#{table_name}.body, ''), 'UTF8')), 'hex')".freeze
+
+    UNSEEN_COUNT_CAP = 99
+    SLUG_MAX_LENGTH = 80
+    SLUG_ATTEMPTS = 5
+    # What a slug may look like (the permalink route's constraint, /[a-z0-9-]+/, is the unanchored twin).
+    SLUG_FORMAT = /\A[a-z0-9-]+\z/
+
+    # What the public changelog lists: approved features and changes with a release date.
+    scope :published_changelog, -> { approved.where(kind: CHANGELOG_KINDS).where.not(released_on: nil) }
+    # The changelog's order, newest first. A missing approved_at sorts first within its day, as PostgreSQL
+    # sorts NULLs in a descending order (the neighbour queries rely on it).
+    scope :newest_first, -> { order(released_on: :desc, approved_at: :desc, id: :desc) }
+
+    # The number of approved features and changes approved after `since` (all of them while it is nil), capped
+    # at 99. One COUNT over the (status, approved_at) index. It filters on approved_at, not on released_on (the
+    # list's order): "new since you last looked" is about when an entry appeared, so an entry approved today
+    # with an earlier release date still counts as new.
+    def self.unseen_count(since: nil)
+      scope = approved.where(kind: CHANGELOG_KINDS)
+      scope = scope.where("#{table_name}.approved_at > ?", since) if since
+      scope.limit(UNSEEN_COUNT_CAP).count
+    end
+
+    # Gives every published changelog entry that has no slug one (oldest first, so the oldest keeps the plain
+    # slug on duplicate titles). Returns how many it filled.
+    def self.backfill_slugs
+      published_changelog.where(slug: nil).order(:released_on, :approved_at, :id).to_a.count { |entry| entry.ensure_slug!.present? }
+    end
+
+    # Approved entries with no current translation into `locale`: none at all, or one made from older English text
+    # (compared with the SQL twin of the digest, in one query).
+    def self.missing_translation(locale)
+      translations = EntryTranslation.table_name
+      current = EntryTranslation.where(locale: locale.to_s).where("#{translations}.entry_id = #{table_name}.id")
+        .where("#{translations}.source_digest = #{TRANSLATION_DIGEST_SQL}")
+      approved.where(current.arel.exists.not)
+    end
+
+    # Enqueues a TranslateEntryJob for every approved entry and configured locale that has no current translation,
+    # reading the entries in batches. Repeating it is harmless: the job itself skips a translation that is current.
+    # Returns { approved: how many approved entries, enqueued: { locale => how many jobs } }.
+    def self.enqueue_missing_translations(batch_size: 100)
+      enqueued = Shiplog.config.locales.index_with do |locale|
+        count = 0
+        missing_translation(locale).find_each(batch_size:) do |entry|
+          TranslateEntryJob.perform_later(entry, locale.to_s)
+          count += 1
+        end
+        count
       end
+      { approved: approved.count, enqueued: }
+    end
+
+    # Whether the entry has a slug the permalink route accepts. Entries without one (approved by older code) or
+    # with a stray one render without a link rather than raising.
+    def permalink?
+      slug.is_a?(String) && SLUG_FORMAT.match?(slug)
     end
 
     def changelog_kind = kind
@@ -44,10 +140,30 @@ module Shiplog
 
     def approve!(by:)
       require_status!("approve", from: "draft")
-      update!(status: "approved", approved_at: Time.current, approved_by: by, discard_reason: nil,
-        released_on: released_on || Date.current)
+      retrying_on_slug_conflict do
+        update!(status: "approved", approved_at: Time.current, approved_by: by, discard_reason: nil,
+          released_on: released_on || Date.current, slug: slug_in_database || (generate_slug if permalinked?))
+      end
+    end
+
+    # The slug of a published changelog entry, generated and stored when it has none (entries approved before
+    # 0.3.0). Nil for entries without a permalink: drafts, discarded and roadmap entries. The write only happens
+    # while the slug is still null in the database, so a concurrent writer's slug is never overwritten; the
+    # entry is reloaded to return whichever slug won. Not used by the public pages (they must not write, a GET
+    # may hit a read replica): approve! and `rake shiplog:backfill_slugs` create slugs.
+    def ensure_slug!
+      return slug if slug.present?
+      return unless approved? && permalinked?
+
+      retrying_on_slug_conflict { self.class.where(id:, slug: nil).update_all(slug: generate_slug, updated_at: Time.current) }
+      reload.slug
     end
 
+    # The entries right after and before this one in the changelog's order, among the published ones.
+    def newer_changelog_entry = changelog_neighbour(">", :asc)
+
+    def older_changelog_entry = changelog_neighbour("<", :desc)
+
     def discard!(reason:)
       require_status!("discard", from: "draft")
       update!(status: "discarded", discard_reason: reason)
@@ -58,18 +174,101 @@ module Shiplog
       update!(status: "draft", discard_reason: nil)
     end
 
+    # The digest of the English title and body, stored in a translation made from them. A translation whose digest
+    # differs from it is stale.
+    def translation_source_digest
+      Digest::SHA256.hexdigest([ title, body ].join("\n"))
+    end
+
+    # The current translation for a locale (the request's by default): nil under a locale that is not configured,
+    # when none exists, and when it is stale. Reads the preloaded translations (see Entry.preload_translations)
+    # and asks the database only when they were not loaded.
+    def translation(locale = I18n.locale)
+      return unless self.class.translated_locale?(locale)
+
+      found = translations.loaded? ? translations.find { |record| record.locale == locale.to_s } : translations.find_by(locale: locale.to_s)
+      found if found && found.source_digest == translation_source_digest
+    end
+
+    # What public pages show: the translation for the request's locale when there is a current one, else English.
+    def display_title(locale = I18n.locale) = translation(locale)&.title || title
+
+    # The translated body, or the English one when the translation's body is blank and the English one is not
+    # (a blank body is never published in place of text).
+    def display_body(locale = I18n.locale)
+      translated = translation(locale)&.body
+      translated.blank? && body.present? ? body : (translated || body)
+    end
+
     def source_changed?
       source_digest.present? && source_digest != self.class.digest_for(subject)
     end
 
     private
 
+    def translation_due?
+      approved? && Shiplog.config.locales.any? && (saved_change_to_status? || saved_change_to_title? || saved_change_to_body?)
+    end
+
+    def enqueue_translations
+      Shiplog.config.locales.each { |locale| TranslateEntryJob.perform_later(self, locale) }
+    end
+
+    def permalinked? = CHANGELOG_KINDS.include?(kind)
+
+    # The title parameterized and cut at 80 characters, made unique with -2, -3, ...; entry-<id> when the title
+    # has nothing left. The uniqueness check can lose a race, which the unique index catches (see
+    # retrying_on_slug_conflict).
+    def generate_slug
+      base = dashed_title.first(SLUG_MAX_LENGTH).gsub(/\A-+|-+\z/, "").presence || "entry-#{id}"
+      candidate = base
+      suffix = 2
+      while self.class.where(slug: candidate).where.not(id:).exists?
+        tail = "-#{suffix}"
+        candidate = "#{base.first(SLUG_MAX_LENGTH - tail.length).delete_suffix("-")}#{tail}"
+        suffix += 1
+      end
+      candidate
+    end
+
+    # The title as [a-z0-9-] only: parameterized (which keeps underscores), underscores turned into dashes,
+    # repeated dashes squeezed, dashes at both ends stripped.
+    def dashed_title
+      title.to_s.parameterize.tr("_", "-").squeeze("-").gsub(/\A-+|-+\z/, "")
+    end
+
+    # Runs the block in a savepoint (a unique violation aborts the surrounding PostgreSQL transaction otherwise)
+    # and runs it again, with a fresh slug, when another entry took the slug first.
+    def retrying_on_slug_conflict
+      attempts = 0
+      begin
+        self.class.transaction(requires_new: true) { yield }
+      rescue ActiveRecord::RecordNotUnique
+        attempts += 1
+        retry if attempts < SLUG_ATTEMPTS
+        raise
+      end
+    end
+
+    # The published entry next to this one: `operator` compares the (released_on, approved_at, id) keys of
+    # the changelog order, with a missing approved_at as the largest value, as the descending order puts it.
+    def changelog_neighbour(operator, direction)
+      key = "(released_on, COALESCE(approved_at, 'infinity'::timestamp), id)"
+      self.class.published_changelog
+        .where("#{key} #{operator} (SELECT released_on, COALESCE(approved_at, 'infinity'::timestamp), id FROM #{self.class.table_name} WHERE id = ?)", id)
+        .reorder(released_on: direction, approved_at: direction, id: direction).first
+    end
+
     def kind_free_for_subject
       return unless will_save_change_to_kind? && self.class.where(subject_type:, subject_id:, kind:).where.not(id:).exists?
 
       errors.add(:changelog_kind, :taken)
     end
 
+    def area_exists
+      errors.add(:area, :invalid) if area_id && will_save_change_to_area_id? && area.nil?
+    end
+
     def kind_change_allowed
       return unless will_save_change_to_kind?
 

data/app/models/shiplog/entry_translation.rb

@@ -0,0 +1,15 @@
+module Shiplog
+  # An entry's title and body in one locale (config.locales), published with the English text. `source_digest`
+  # is the digest of the English title and body it was made from (Entry#translation_source_digest); once the
+  # English text differs, the row is stale and the public pages show English instead. `edited_by_admin` marks a
+  # text an admin changed, which a new translation only replaces when the English text changed.
+  class EntryTranslation < ApplicationRecord
+    belongs_to :entry, class_name: "Shiplog::Entry", inverse_of: :translations
+
+    validates :locale, :title, :source_digest, presence: true
+    validates :locale, uniqueness: { scope: :entry_id }
+
+    # Whether the English text has changed since this translation was made.
+    def stale? = source_digest != entry.translation_source_digest
+  end
+end

data/app/models/shiplog/image_fetcher/downloader.rb

@@ -0,0 +1,98 @@
+require "net/http"
+
+module Shiplog
+  class ImageFetcher
+    # Downloads one allowed image URL: five seconds to connect and five to read, 15 seconds in total (checked
+    # on a monotonic clock while streaming and between redirect hops), at most three redirects (each hop is
+    # checked against the allowlist again), at most 5 MB (raw bytes: the response is requested uncompressed, and
+    # counted while streaming, the download stops past it). The body of a redirect is read with the same cap
+    # and thrown away. The GitHub token is sent to github.com only, never to another host. Returns a Download,
+    # or nil (logged) when anything goes wrong or the bytes aren't a PNG, JPEG, GIF or WebP of at most 10,000
+    # pixels a side and 40 megapixels (see ImageType).
+    class Downloader
+      TIMEOUT = 5
+      TOTAL_DEADLINE = 15
+      MAX_REDIRECTS = 3
+      Download = Data.define(:body, :content_type, :width, :height)
+      Rejected = Class.new(StandardError)
+
+      # Seconds on the monotonic clock, which wall-clock changes don't move.
+      def self.now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def initialize(token: nil)
+        @token = token
+      end
+
+      # `budget` is the seconds the caller has left; the deadline is the smaller of that and TOTAL_DEADLINE.
+      def call(url, budget: nil)
+        deadline = self.class.now + [ TOTAL_DEADLINE, budget ].compact.min
+        body = fetch(Sources.parse(url), MAX_REDIRECTS, deadline)
+        info = ImageType.analyze(body) # type by magic bytes, size from the header, both limits enforced
+
+        Download.new(body:, content_type: info.content_type, width: info.width, height: info.height)
+      rescue StandardError => error
+        Rails.logger&.warn("[shiplog] Skipped image #{safe(url)}: #{error.class}: #{error.message}")
+        nil
+      end
+
+      private
+
+      def fetch(uri, redirects_left, deadline)
+        raise Rejected, "host or scheme not allowed" unless uri && Sources.allowed?(uri)
+
+        check_deadline!(deadline)
+        body = +"".b
+        location = nil
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = http.read_timeout = [ TIMEOUT, deadline - self.class.now ].min
+        http.request(build_request(uri)) do |response|
+          case response
+          when Net::HTTPSuccess then body = read(response, deadline)
+          when Net::HTTPRedirection
+            location = response["location"].to_s
+            read(response, deadline, keep: false)
+          else raise Rejected, "HTTP #{response.code}"
+          end
+        end
+        return body unless location
+
+        raise Rejected, "too many redirects" if redirects_left.zero?
+
+        fetch(Sources.parse(URI.join(uri.to_s, location).to_s), redirects_left - 1, deadline)
+      end
+
+      # Streams the body under the size cap and the deadline. Without `keep` the bytes are counted and dropped
+      # (Net::HTTP would otherwise read what is left of the body into memory, uncapped, when the block returns).
+      def read(response, deadline, keep: true)
+        raise Rejected, "larger than #{ImageType::MAX_BYTES} bytes" if response["content-length"].to_i > ImageType::MAX_BYTES
+
+        body = +"".b
+        size = 0
+        response.read_body do |chunk|
+          check_deadline!(deadline)
+          size += chunk.bytesize
+          raise Rejected, "larger than #{ImageType::MAX_BYTES} bytes" if size > ImageType::MAX_BYTES
+
+          body << chunk if keep
+        end
+        body
+      end
+
+      def check_deadline!(deadline)
+        raise Rejected, "deadline of #{TOTAL_DEADLINE} seconds exceeded" if self.class.now > deadline
+      end
+
+      def build_request(uri)
+        Net::HTTP::Get.new(uri).tap do |request|
+          request["User-Agent"] = "shiplog/#{Shiplog::VERSION}"
+          request["Accept-Encoding"] = "identity" # raw bytes only: the cap can't be overshot by inflation
+          request["Authorization"] = "Bearer #{@token}" if @token.present? && uri.host.to_s.downcase == Sources::ATTACHMENTS_HOST
+        end
+      end
+
+      # A URL for the log without its query string (signed URLs carry a credential there).
+      def safe(url) = url.to_s.sub(/[?#].*\z/m, "").first(200)
+    end
+  end
+end

data/app/models/shiplog/image_fetcher/sources.rb

@@ -0,0 +1,41 @@
+require "nokogiri"
+
+module Shiplog
+  class ImageFetcher
+    # Which images of a GitHub body (its rendered HTML) may be downloaded: <img src> URLs on GitHub's own image
+    # hosts (raw. and objects.githubusercontent.com too: GitHub serves attachments and redirects from them),
+    # https only, matched on the exact host (so user-images.githubusercontent.com.evil.com is out).
+    module Sources
+      HOSTS = %w[
+        private-user-images.githubusercontent.com user-images.githubusercontent.com camo.githubusercontent.com
+        raw.githubusercontent.com objects.githubusercontent.com
+      ].freeze
+      ATTACHMENTS_HOST = "github.com".freeze
+      # Exactly /user-attachments/assets/<id>: the id is letters, digits and dashes, so no dot, no slash and no
+      # percent-encoding (%2e%2e, %2f) can walk out of the directory.
+      ATTACHMENTS_PATH = %r{\A/user-attachments/assets/[A-Za-z0-9-]+\z}
+
+      # The allowed, distinct image URLs of the HTML, in document order, at most `limit`.
+      def self.urls(html, limit:)
+        Nokogiri::HTML.fragment(html.to_s).css("img[src]").filter_map { |img| parse(img["src"]) }
+          .select { |uri| allowed?(uri) }.map(&:to_s).uniq.first(limit)
+      end
+
+      # Whether a URI may be requested: also checked on every redirect hop.
+      def self.allowed?(uri)
+        return false unless uri.is_a?(URI::HTTPS) && uri.userinfo.nil? && uri.port == 443
+
+        host = uri.host.to_s.downcase
+        return true if HOSTS.include?(host)
+
+        host == ATTACHMENTS_HOST && ATTACHMENTS_PATH.match?(uri.path)
+      end
+
+      def self.parse(value)
+        URI.parse(value.to_s.strip)
+      rescue URI::InvalidURIError
+        nil
+      end
+    end
+  end
+end

data/app/models/shiplog/image_fetcher.rb

@@ -0,0 +1,72 @@
+module Shiplog
+  # Attaches the screenshots of a draft's GitHub issue or pull request to the entry. Runs when a draft is
+  # written (Shiplog::RewriteEntryJob), only for a draft without images: an approved entry's images are never
+  # changed automatically. Every failure (GitHub, network, validation) is logged and skipped; it never raises.
+  class ImageFetcher
+    # Seconds for all the images of one entry together; the rest are skipped (and logged) once it is spent.
+    FETCH_BUDGET = 45
+
+    def self.call(entry) = new(entry).call
+
+    def initialize(entry)
+      @entry = entry
+    end
+
+    # Returns how many images were attached.
+    def call
+      return 0 unless eligible?
+
+      html = body_html
+      urls = Sources.urls(html, limit: Shiplog.config.max_images_per_entry)
+      return 0 if urls.empty?
+
+      files = download_all(urls)
+      files.empty? ? 0 : attach(files)
+    rescue StandardError => error
+      Rails.logger&.warn("[shiplog] Fetching images for entry #{@entry.id} failed: #{error.class}: #{error.message}")
+      0
+    end
+
+    private
+
+    # The files of the URLs that downloaded, in order. Once FETCH_BUDGET seconds are spent, the rest are skipped.
+    def download_all(urls)
+      downloader = Downloader.new(token: Shiplog.config.resolved_github_token)
+      started = Downloader.now
+      files = []
+      urls.each_with_index do |url, index|
+        remaining = FETCH_BUDGET - (Downloader.now - started)
+        if remaining <= 0
+          Rails.logger&.warn("[shiplog] Entry #{@entry.id}: the image budget of #{FETCH_BUDGET}s is spent, skipped #{urls.size - index} remaining image(s)")
+          break
+        end
+
+        download = downloader.call(url, budget: remaining)
+        files << file_for(download, index) if download
+      end
+      files
+    end
+
+    def file_for(download, index)
+      { io: StringIO.new(download.body), filename: "screenshot-#{index + 1}.#{ImageType::EXTENSIONS.fetch(download.content_type)}",
+        content_type: download.content_type, metadata: { width: download.width, height: download.height } }
+    end
+
+    def eligible?
+      Shiplog.images? && Shiplog.config.max_images_per_entry.positive? && @entry.draft? &&
+        Entry::CHANGELOG_KINDS.include?(@entry.kind) && !@entry.images.attached? && node_id.present?
+    end
+
+    def node_id = @entry.subject.try(:node_id)
+
+    def body_html
+      Github::Client.new.query(Github::Queries::BODY_HTML, id: node_id).dig("node", "bodyHTML")
+    end
+
+    # Uploaded before the entry's row lock is taken; under the lock, so two jobs cannot both attach, the state is
+    # checked again (still a draft, still without images), otherwise the uploaded blobs are purged.
+    def attach(files)
+      @entry.add_images(files) { @entry.draft? && !@entry.images.attached? }.size
+    end
+  end
+end

data/app/models/shiplog/image_type.rb

@@ -0,0 +1,111 @@
+module Shiplog
+  # What an entry image may be: PNG, JPEG, GIF or WebP, recognised by the file's first bytes (never by its
+  # extension or a declared content type), at most 5 MB, at most 10,000 pixels on a side and 40 megapixels. The
+  # pixel size is read from the header, without decoding anything, before an image processor ever sees the file
+  # (a decompression bomb is a tiny file declaring a huge size).
+  module ImageType
+    MAX_BYTES = 5 * 1024 * 1024
+    MAX_SIDE = 10_000
+    MAX_PIXELS = 40_000_000
+    # Bytes needed to tell the types apart.
+    SNIFF_LENGTH = 12
+    EXTENSIONS = { "image/png" => "png", "image/jpeg" => "jpg", "image/gif" => "gif", "image/webp" => "webp" }.freeze
+
+    Invalid = Class.new(StandardError)
+    Info = Data.define(:content_type, :width, :height)
+
+    # JPEG frame headers (SOF0..SOF15) are the markers 0xC0..0xCF except these three, which are not frames.
+    JPEG_NOT_FRAME = [ 0xC4, 0xC8, 0xCC ].freeze # DHT, JPG, DAC
+
+    # The content type of the data starting with `head` (a binary String), or nil for anything else (SVG, HTML...).
+    def self.detect(head)
+      head = head.to_s.b
+      if head.start_with?("\x89PNG\r\n\x1A\n".b) then "image/png"
+      elsif head.start_with?("\xFF\xD8\xFF".b) then "image/jpeg"
+      elsif head.start_with?("GIF87a".b, "GIF89a".b) then "image/gif"
+      elsif head.bytesize >= SNIFF_LENGTH && head.byteslice(0, 4) == "RIFF".b && head.byteslice(8, 4) == "WEBP".b then "image/webp"
+      end
+    end
+
+    # The type and pixel size of the image `data` (a String of at most MAX_BYTES), or raises Invalid: not one of
+    # the four types, a size that can't be read from the header, or a size over the limits.
+    def self.analyze(data)
+      data = data.to_s.b
+      content_type = detect(data.byteslice(0, SNIFF_LENGTH)) or raise Invalid, "not a PNG, JPEG, GIF or WebP image"
+      width, height = dimensions(data, content_type)
+      raise Invalid, "the image's dimensions can't be read" unless width&.positive? && height&.positive?
+      raise Invalid, "#{width}x#{height} pixels is too large (at most #{MAX_SIDE} on a side and #{MAX_PIXELS / 1_000_000} megapixels)" if width > MAX_SIDE || height > MAX_SIDE || width * height > MAX_PIXELS
+
+      Info.new(content_type:, width:, height:)
+    end
+
+    # [width, height] read from the header of `data`, or nil when the header is truncated or malformed.
+    def self.dimensions(data, content_type)
+      case content_type
+      when "image/png" then png_dimensions(data)
+      when "image/gif" then gif_dimensions(data)
+      when "image/webp" then webp_dimensions(data)
+      when "image/jpeg" then jpeg_dimensions(data.byteslice(0, MAX_BYTES))
+      end
+    end
+
+    # The IHDR chunk comes first: 8 bytes of signature, length, "IHDR", then width and height (big-endian).
+    def self.png_dimensions(data)
+      data.byteslice(16, 8).unpack("NN") if data.bytesize >= 24 && data.byteslice(12, 4) == "IHDR".b
+    end
+
+    # The logical screen descriptor follows the 6-byte signature: width and height (little-endian).
+    def self.gif_dimensions(data)
+      data.byteslice(6, 4).unpack("vv") if data.bytesize >= 10
+    end
+
+    # The first chunk, at byte 12, says which kind of WebP it is.
+    def self.webp_dimensions(data)
+      case data.byteslice(12, 4)
+      when "VP8 ".b # lossy: frame tag (3 bytes), start code 9D 01 2A, 14-bit width and height
+        data.byteslice(26, 4).unpack("vv").map { |value| value & 0x3FFF } if data.bytesize >= 30 && data.byteslice(23, 3) == "\x9D\x01\x2A".b
+      when "VP8L".b # lossless: signature 0x2F, then 14 bits of width - 1 and 14 bits of height - 1
+        if data.bytesize >= 25 && data.getbyte(20) == 0x2F
+          bits = data.byteslice(21, 4).unpack1("V")
+          [ (bits & 0x3FFF) + 1, ((bits >> 14) & 0x3FFF) + 1 ]
+        end
+      when "VP8X".b # extended: flags, then the canvas size - 1 on 24 bits each
+        if data.bytesize >= 30
+          width, height = (data.byteslice(24, 3) + "\x00".b).unpack1("V"), (data.byteslice(27, 3) + "\x00".b).unpack1("V")
+          [ width + 1, height + 1 ]
+        end
+      end
+    end
+
+    # Walks the segments from the start until a frame header (SOF0..SOF15, but not DHT, DAC and JPG). Stops at the
+    # scan (SOS) or the end of the image: a frame header comes before both. Each step moves forward at least two
+    # bytes, over data already capped at MAX_BYTES.
+    def self.jpeg_dimensions(data)
+      position = 2
+      size = data.bytesize
+      while position < size
+        return unless data.getbyte(position) == 0xFF
+
+        position += 1 while position < size && data.getbyte(position) == 0xFF # fill bytes
+        marker = data.getbyte(position)
+        position += 1
+        return if marker.nil? || marker == 0xD9 || marker == 0xDA # end of image, start of scan
+        next if marker.zero? || marker == 0x01 || marker.between?(0xD0, 0xD8) # no length
+
+        return if position + 2 > size
+
+        length = data.byteslice(position, 2).unpack1("n")
+        return if length < 2
+
+        if marker.between?(0xC0, 0xCF) && !JPEG_NOT_FRAME.include?(marker)
+          return unless position + 7 <= size
+
+          height, width = data.byteslice(position + 3, 4).unpack("nn")
+          return [ width, height ]
+        end
+        position += length
+      end
+      nil
+    end
+  end
+end