opf 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 731442c9df097ae3a58ededf90d0d9e3d76a74f61fef679e3528ac32ed54b8ea
+  data.tar.gz: cde4c1fe0d2324f469c14e22620353e1dbd03e7bf793dcc98df9fdc72b5cb62e
+SHA512:
+  metadata.gz: 1113c851bf4373d1d483a50246e24d49047278267a0b5cd84fc7e1454ee8d4d665556a7ea27794722377bb4fa5fddb49f28241bf0d99ab512fc359ceb9706f1d
+  data.tar.gz: 664c47d1dd6464313f14c3cf8cc79b6e437aa2ee68f380aac2f8c5593e0cf64e83a323dc8ea18c6425dbae68e4ac9f221da7298d586f61774c1c872ba39a9b13

data/.envrc

@@ -0,0 +1 @@
+use flake

data/.gitignore

@@ -0,0 +1,15 @@
+# Nix
+.nix-gems/
+.direnv/
+
+# Bundler / RubyGems
+/.bundle/
+/pkg/
+/tmp/
+
+# Docs and coverage
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/spec/reports/

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+## [Unreleased]
+
+### Added
+
+- `Opf.fetch(url)`: fetches a page and returns an `Opf::Page` with `title`, `description`, `images` (plus `image` shortcut) and `favicon`, resolved from OpenGraph tags with HTML fallbacks
+- Typed errors: `Opf::InvalidURLError` and `Opf::FetchError`
+
+## [0.1.0] - 2026-10-11
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"opf" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at [santiago.fgonz@gmail.com](mailto:santiago.fgonz@gmail.com).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 iagus
+
+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,51 @@
+# Opf
+
+Opf fetches OpenGraph metadata — title, description and images — plus the site favicon, from user-provided URLs. To experiment with that code, run `bin/console` for an interactive prompt.
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+## Usage
+
+```ruby
+require "opf"
+
+page = Opf.fetch("https://ogp.me")
+
+page.title       # => og:title (falls back to the HTML <title>)
+page.description # => og:description (falls back to <meta name="description">)
+page.images      # => every declared og:image URL
+page.image       # => the primary image (first og:image)
+page.favicon     # => the site's favicon URL
+page.url         # => final URL after following redirects
+```
+
+`Opf.fetch` raises typed errors on failure:
+
+- `Opf::InvalidURLError` — malformed URLs or non http/https schemes
+- `Opf::FetchError` — network failures, redirect loops, error statuses or non HTML responses
+
+Pages lacking OpenGraph tags simply return `nil`/`[]` for the missing fields.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1791662279,
+        "narHash": "sha256-xI8L+UwJLIg75yVJwLPsY+AUEP1teCT3FyuvodyJu2Y=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "6fcc160353f63555b560f25588925133c8f61f2a",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-26.05",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

data/flake.nix

@@ -0,0 +1,42 @@
+{
+  description = "Development environment for the opf Ruby gem";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
+  };
+
+  outputs =
+    { self, nixpkgs }:
+    let
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
+      forAllSystems = nixpkgs.lib.genAttrs systems;
+    in
+    {
+      devShells = forAllSystems (
+        system:
+        let
+          pkgs = nixpkgs.legacyPackages.${system};
+        in
+        {
+          default = pkgs.mkShell {
+            packages = [
+              pkgs.ruby_4_0
+            ];
+
+            # The nix-provided Ruby is read-only; install gems into a
+            # project-local directory so bundler works out of the box.
+            shellHook = ''
+              export GEM_HOME="$PWD/.nix-gems"
+              export GEM_PATH="$GEM_HOME"
+              export PATH="$GEM_HOME/bin:$PATH"
+            '';
+          };
+        }
+      );
+    };
+}

data/lib/opf/fetcher.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module Opf
+  # Fetches an HTML document over HTTP(S), following redirects.
+  #
+  # Only `text/html` documents are accepted. All failure modes raise
+  # Opf::InvalidURLError or Opf::FetchError.
+  class Fetcher
+    MAX_REDIRECTS = 5
+    OPEN_TIMEOUT = 5
+    READ_TIMEOUT = 5
+    USER_AGENT = "Opf/#{Opf::VERSION}".freeze
+    HTML_MIME_TYPES = %w[text/html application/xhtml+xml].freeze
+
+    NETWORK_ERRORS = [
+      SocketError, # DNS failures
+      SystemCallError, # Errno::ECONNREFUSED and friends
+      Timeout::Error, # Net::OpenTimeout / Net::ReadTimeout
+      OpenSSL::SSL::SSLError, # TLS negotiation failures
+      EOFError, # connection dropped mid response
+      Net::ProtocolError # malformed HTTP responses
+    ].freeze
+
+    # The result of a successful fetch: the final URL (after redirects) and
+    # the raw HTML body.
+    Response = Data.define(:url, :body)
+
+    def self.call(url)
+      new.call(url)
+    end
+
+    def call(url)
+      uri = parse_uri(url)
+      redirects = 0
+
+      loop do
+        response = request(uri)
+        return success_response(uri, response) if response.is_a?(Net::HTTPSuccess)
+
+        uri = follow_redirect(uri, response, redirects += 1)
+      end
+    end
+
+    private
+
+    def parse_uri(url)
+      uri = URI.parse(url.to_s)
+      return uri if http_uri?(uri)
+
+      raise InvalidURLError, "only http(s) URLs are supported: #{url.inspect}"
+    rescue URI::InvalidURIError => e
+      raise InvalidURLError, "invalid URL #{url.inspect}: #{e.message}"
+    end
+
+    def http_uri?(uri)
+      uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+    end
+
+    def request(uri)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                          open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT) do |http|
+        http.request_get(uri.request_uri, "User-Agent" => USER_AGENT, "Accept" => HTML_MIME_TYPES.join(", "))
+      end
+    rescue *NETWORK_ERRORS => e
+      raise FetchError, "request to #{uri} failed: #{e.message}"
+    end
+
+    def follow_redirect(uri, response, count)
+      raise FetchError, "giving up after #{MAX_REDIRECTS} redirects" if count > MAX_REDIRECTS
+
+      unless response.is_a?(Net::HTTPRedirection)
+        raise FetchError, "request to #{uri} failed with status #{response.code}"
+      end
+
+      redirect_uri(uri, response)
+    end
+
+    def redirect_uri(uri, response)
+      location = response["location"].to_s
+      raise FetchError, "redirect from #{uri} lacked a Location header" if location.empty?
+
+      redirected = URI.join(uri, location)
+      return redirected if http_uri?(redirected)
+
+      raise FetchError, "redirect from #{uri} points to an invalid URL: #{location.inspect}"
+    rescue URI::InvalidURIError => e
+      raise FetchError, "redirect from #{uri} points to an invalid URL: #{e.message}"
+    end
+
+    def success_response(uri, response)
+      mime_type = response["content-type"].to_s.split(";").first.to_s.strip
+      return Response.new(url: uri.to_s, body: response.body.to_s) if HTML_MIME_TYPES.include?(mime_type)
+
+      raise FetchError,
+            "expected an HTML document from #{uri}, got: #{mime_type.empty? ? "no Content-Type" : mime_type}"
+    end
+  end
+end

data/lib/opf/page.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Opf
+  # Immutable value object with everything we managed to learn about a page:
+  # its final URL, title, description, every declared OpenGraph image and the
+  # favicon URL.
+  Page = Data.define(:url, :title, :description, :images, :favicon) do
+    # The primary image: the first og:image declared by the page.
+    def image
+      images&.first
+    end
+  end
+end

data/lib/opf/parser.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "uri"
+
+module Opf
+  # Extracts metadata from a fetched HTML document: OpenGraph tags with plain
+  # HTML fallbacks, plus the site's favicon.
+  class Parser
+    IMAGE_PROPERTIES = %w[og:image og:image:secure_url og:image:url].freeze
+
+    def self.call(url:, body:)
+      new(url: url, body: body).call
+    end
+
+    def initialize(url:, body:)
+      @url = url
+      @body = body
+    end
+
+    def call
+      Page.new(
+        url: @url,
+        title: open_graph("og:title") || html_title,
+        description: open_graph("og:description") || html_description,
+        images: images,
+        favicon: favicon
+      )
+    end
+
+    private
+
+    def doc
+      @doc ||= Nokogiri::HTML(@body)
+    end
+
+    # Some sites wrongly use a `name` attribute for OpenGraph tags, so both
+    # spellings are accepted.
+    def open_graph(property)
+      tag = doc.at_css(%(meta[property="#{property}"]), %(meta[name="#{property}"]))
+      content = tag&.[]("content").to_s.strip
+      content.empty? ? nil : content
+    end
+
+    def html_title
+      title = doc.at_css("title")&.text.to_s.strip
+      title.empty? ? nil : title
+    end
+
+    def html_description
+      tag = doc.at_css('meta[name="description"]')
+      content = tag&.[]("content").to_s.strip
+      content.empty? ? nil : content
+    end
+
+    def images
+      doc.css(image_selector).filter_map { |tag| tag["content"] }.map(&:strip).reject(&:empty?).uniq
+    end
+
+    def image_selector
+      IMAGE_PROPERTIES
+        .flat_map { |property| [%(meta[property="#{property}"]), %(meta[name="#{property}"])] }.join(", ")
+    end
+
+    # The site's favicon: a declared <link rel="icon">, then the legacy
+    # "shortcut icon" spelling, and finally the conventional /favicon.ico,
+    # which is returned unverified.
+    def favicon
+      resolve(declared_favicon || "/favicon.ico")
+    end
+
+    def declared_favicon
+      links = doc.css("link[href]")
+      link = links.find { rel_tokens(_1) == ["icon"] } ||
+             links.find { rel_tokens(_1) == %w[icon shortcut] }
+      href = link&.[]("href").to_s.strip
+      href.empty? || href.start_with?("data:") ? nil : href
+    end
+
+    def rel_tokens(link)
+      link["rel"].to_s.downcase.split.sort
+    end
+
+    # Relative hrefs are common for favicons; they resolve against the final
+    # (post-redirect) page URL.
+    def resolve(href)
+      URI.join(@url, href).to_s
+    rescue URI::InvalidURIError
+      nil
+    end
+  end
+end

data/lib/opf/version.rb

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

data/lib/opf.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "opf/version"
+require_relative "opf/page"
+require_relative "opf/fetcher"
+require_relative "opf/parser"
+
+# Fetches OpenGraph metadata (title, description, images) and the favicon
+# from user-provided URLs.
+module Opf
+  class Error < StandardError; end
+
+  # Raised when the provided URL cannot be used (missing host, non
+  # http/https scheme, malformed URI, ...).
+  class InvalidURLError < Error; end
+
+  # Raised when the URL could not be fetched: network failure, too many
+  # redirects, unsuccessful status code or a non HTML response.
+  class FetchError < Error; end
+
+  # Fetches OpenGraph information for the given URL and returns an Opf::Page.
+  #
+  #   page = Opf.fetch("https://example.com")
+  #   page.title    #=> "Example Domain"
+  #   page.image    #=> "https://example.com/og.png"
+  #
+  # Raises Opf::InvalidURLError or Opf::FetchError on failure.
+  def self.fetch(url)
+    response = Fetcher.call(url)
+    Parser.call(url: response.url, body: response.body)
+  end
+end

data/sig/opf.rbs

@@ -0,0 +1,4 @@
+module Opf
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: opf
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- iagus
+bindir: exe
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.19'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.19'
+description: Opf fetches OpenGraph metadata (title, description, images) and the favicon
+  URL from user-provided URLs, raising typed errors for invalid URLs or failed fetches.
+email:
+- iagus.widget524@passinbox.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".envrc"
+- ".gitignore"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- flake.lock
+- flake.nix
+- lib/opf.rb
+- lib/opf/fetcher.rb
+- lib/opf/page.rb
+- lib/opf/parser.rb
+- lib/opf/version.rb
+- sig/opf.rbs
+homepage: https://github.com/iagus/opf
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/iagus/opf
+  source_code_uri: https://rubygems.org
+  changelog_uri: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Fetch OpenGraph metadata (title, description, images) and favicons from URLs.
+test_files: []