sxg_checker 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36798f6fd5461309de602122e726814a47c484bcf798260796f2b74726d158d4
-  data.tar.gz: 6ececedef77191f20b4b15d9b32faf84837af6e8f3c03ab87f87cfde1a6d2229
+  metadata.gz: a0e170be7a494ed2f4c5d03ce592d49360d51cdaa4bcf487bf2fed7c7e3c47cd
+  data.tar.gz: 948f14c9a90571044f5c873b5686cf3eac582529830a6274e6d49391fc00129b
 SHA512:
-  metadata.gz: f33f3769f4f2a2671d10434800e0b6d247d7088f98535ab8bda5175f78ab3f1a411f3669f32a95a490254fffb835b791d49691311d3769b51cca607e2fe97e10
-  data.tar.gz: 7ace8929013bf4681de47150ec6ea9f5e92b535eca33da5aac72293339ddbb64fbcaca477a798ba6af14e344c25193c494182348e1d9f2255dd617cd4d4e8668
+  metadata.gz: f2d88e2fb7c90d1cb5397bc51a1561f458d5370a1ebb6e3147d2ea1a9a0d8beeb10801e70be87822ba63c2170da8d0ff84d0e66499ea586a908d8e3defa3fee2
+  data.tar.gz: a4d2bcb7468d44d929882662e8f1e773f260908ffbc626bb9b1e05e30e593f7fb5e7b4bc5f837f3bf66a7d976d69499194e0a4c3539eaeec481020bcbf53ef0d

data/README.md

@@ -2,11 +2,15 @@
 
 [![Gem Version](https://badge.fury.io/rb/sxg_checker.svg)](https://badge.fury.io/rb/sxg_checker)
 
-A library and command-line tool for checking the Google SXG cache for the presence of a document and its subresources.
+A library and command-line tool for checking the Google Signed Exchanges (SXG) cache for the presence of a document and its subresources.
 
-It verifies if your web page and its resources are properly available in Google's Signed Exchanges (SXG) cache,
+It verifies if your web page and its resources are properly available in Google's SXG cache,
 helping you troubleshoot SXG implementation issues with detailed status reporting for each resource.
 
+SXG enables websites to optimize Largest Contentful Paint (LCP) by allowing prefetching directly from the Google search results page.
+For a step-by-step guide, see my [SXG tutorial](https://www.pawelpokrywka.com/p/how-i-took-lcp-down-under-350ms).
+This tool is also referenced in the section on [monitoring and measuring SXG](https://www.pawelpokrywka.com/p/measuring-signed-exchanges-impact).
+
 ## Status indicators
 
 | Symbol | Status | Description |
@@ -51,14 +55,13 @@ gem contents sxg_checker | grep sxg-checker
 To check a URL in Google's SXG cache:
 
 ```shell
-sxg-checker https://www.yourwebsite.com/your-page
+sxg-checker validate https://www.yourwebsite.com/your-page
 ```
 
-If you installed the `dump-signedexchange` binary somewhere other than `~/go/bin/dump-signedexchange`, specify the
-path in the `DSXG_PATH` environment variable:
+To get full usage instructions, run:
 
 ```shell
-DSXG_PATH=/usr/local/bin/dump-signedexchange sxg-checker https://www.yourwebsite.com/your-page
+sxg-checker --help
 ```
 
 ### In Ruby applications
@@ -69,16 +72,23 @@ You can also use SXG Checker as a library in your Ruby applications:
 require 'sxg_checker'
 
 checker = SxgChecker::Checker.new(tool: '/usr/local/bin/dump-signedexchange') # The `tool` parameter is optional
-result = checker.call(url)
+document = checker.validate(url)
 
 # Access the results
-puts result.url    # The URL of the cached document
-puts result.status # The status symbol (:ok, :missing, etc.)
+puts document.url    # The URL of the cached document
+puts document.status # The status symbol (:ok, :missing, etc.)
 
 # Iterate through subresources
-result.subresources.each do |subresource|
+document.subresources.each do |subresource|
   puts "#{subresource.url}: #{subresource.status}"
 end
+
+# If you want to skip validating subresources
+result = checker.validate(url, subresources: false)
+
+# If you want to only warm the SXG cache for a given URL
+checker.warm_cache(url)
+
 ```
 
 ## Development

data/exe/sxg-checker

@@ -4,4 +4,5 @@ require "sxg_checker"
 
 exe_name = File.basename($0)
 cli = SxgChecker::Cli.new(exe_name)
-cli.call(ARGV[0])
+code = cli.call(ARGV)
+exit code

data/lib/basic_loader.rb

@@ -5,5 +5,5 @@
 require "sxg_checker/checker"
 require "sxg_checker/cli"
 require "sxg_checker/document"
-require "sxg_checker/formatter"
+require "sxg_checker/printer"
 require "sxg_checker/subresource"

data/lib/sxg_checker/checker.rb

@@ -4,9 +4,13 @@ require "parallel"
 
 module SxgChecker
   class Checker
-    def call(document_url)
-      raise ToolNotFound.new("executable not found: #{tool}") unless File.executable?(tool)
+    def warm_cache(document_url)
+      url = cacheify_document_url(document_url)
+      fetch_sxg(url)
+      nil
+    end
 
+    def validate(document_url, subresources: true)
       url = cacheify_document_url(document_url)
       response = fetch_sxg(url)
       return Document.new(url, :missing) unless response
@@ -20,6 +24,8 @@ module SxgChecker
       fresh_integrity = extract_integrity(sxg.fetch("ResponseHeaders").fetch("Link", [""]))
       return Document.new(url, :links_mismatch) if fresh_cached.keys.sort != fresh_integrity.keys.sort
 
+      return Document.new(url, :ok) unless subresources
+
       cached_integrity = fresh_integrity.map do |fresh, integrity|
         cached = fresh_cached.fetch(fresh)
         [cached, integrity]
@@ -89,27 +95,30 @@ module SxgChecker
     end
 
     def parse_sxg_file(path)
+      raise ToolNotFound.new("executable not found: #{tool}") unless tool_available?
+
       command = "#{tool} -json -verify -i #{path}"
       result = `#{command} 2> /dev/null`
       return nil if result.empty?
       JSON.parse(result)
     end
 
+    def tool_available?
+      @tool_available ||= File.executable?(tool)
+    end
+
     def cacheify_document_url(url)
       uri = URI.parse(url)
-      raise InvalidUrl.new("invalid URL") unless uri.scheme == "https" && uri.host && uri.fragment.nil?
+      raise InvalidUrl.new("invalid URL: #{url}") unless uri.scheme == "https" && uri.host && uri.fragment.nil?
 
-      host = uri.host.to_s.tr(".", "-")
-      "https://#{host}.webpkgcache.com/doc/-/s/#{url.sub("https://", "")}"
+      "https://#{uri.host.tr(".", "-")}.webpkgcache.com/doc/-/s/#{uri.host}#{uri.request_uri}"
     rescue URI::InvalidURIError
       raise InvalidUrl.new("can't parse URL")
     end
 
     attr_reader :tool, :mapper
 
-    def initialize(mapper: Parallel.method(:map),
-      default_tool: "#{ENV["HOME"]}/go/bin/dump-signedexchange",
-      tool: ENV["DSXG_PATH"] || default_tool)
+    def initialize(mapper: Parallel.method(:map), tool: DUMP_BINARY)
       @mapper = mapper
       @default_tool = default_tool
       @tool = tool

data/lib/sxg_checker/cli.rb

@@ -1,49 +1,136 @@
+require "optparse"
+
 module SxgChecker
   class Cli
-    def call(url)
-      return show_usage if url.nil? || url == "-h" || url == "--help"
+    def call(argv)
+      argv = argv.dup # argv will be changed
+      options = {
+        subresources: true,
+        errors_only: false,
+        dump_binary: DUMP_BINARY
+      }
+
+      parser = OptionParser.new do |opts|
+        opts.on("-h", "--help") do
+          show_usage
+          return 0
+        end
+
+        opts.on("-v", "--version") do
+          puts VERSION
+          return 0
+        end
+
+        opts.on("-n", "--no-subresources") do
+          options[:subresources] = false
+        end
+
+        opts.on("-e", "--errors-only") do
+          options[:errors_only] = true
+        end
 
-      document = checker.call(url)
-      resources = [document] + document.subresources.sort
-      resources.each do |resource|
-        puts formatter.resource(resource)
+        opts.on("-d", "--dump-binary=PATH", String) do |path|
+          options[:dump_binary] = path
+        end
+      end
+
+      if argv.empty?
+        print_error "command required, use -h for help"
+        return 1
+      end
+
+      begin
+        # Parse options, leaving the command and URLs in argv
+        parser.parse!(argv)
+      rescue OptionParser::InvalidOption => e
+        print_error e.message
+        return 1
+      end
+
+      command = argv.shift
+      urls = argv
+
+      checker = SxgChecker::Checker.new(tool: options[:dump_binary])
+
+      case command
+      when "warm"
+        if urls.empty?
+          print_error "no URLs provided for warming"
+          return 1
+        end
+
+        urls.each do |url|
+          checker.warm_cache(url)
+        end
+        0
+      when "validate"
+        if urls.empty?
+          print_error "no URLs provided for validation"
+          return 1
+        end
+
+        urls.each do |url|
+          document = checker.validate(url, subresources: options[:subresources])
+          printer.call(document) unless document.ok? && options[:errors_only]
+        end
+        0
+      else
+        print_error "unknown command '#{command}'"
+        1
       end
     rescue Error => e
-      puts "#{exe_name}: error: #{e.message}"
-      exit 1
+      print_error e.message
+      1
     end
 
     private
 
+    def print_error(message)
+      puts "#{exe_name}: error: #{message}"
+    end
+
     def show_usage
-      puts "SXG Checker v#{VERSION}"
-      puts "  Checks the Google SXG cache for the presence of a document and its subresources."
+      puts "SXG Checker #{VERSION}"
+      puts "  Queries the Google SXG cache for the presence of documents and their subresources."
       puts
       puts "Usage:"
-      puts "  #{exe_name} <URL>"
+      puts "  #{exe_name} [global options]"
+      puts "  #{exe_name} warm <URLs>"
+      puts "  #{exe_name} validate [validate options] <URLs>"
       puts
-      puts "Example:"
-      puts "  #{exe_name} https://www.yourwebsite.com/your-page"
+      puts "Global options:"
+      puts "  -h, --help             Show this help message and exit"
+      puts "  -v, --version          Show version information and exit"
       puts
-      puts "Environment variables:"
-      puts "  DSXG_PATH - path to dump-signedexchange binary (default: #{checker.default_tool})"
+      puts "Commands:"
+      puts "  warm                   Warm the cache for specified URLs"
+      puts "  validate               Validate SXG documents and their subresources"
+      puts
+      puts "Validate options:"
+      puts "  -n, --no-subresources  Skip validating subresources (validate documents only)"
+      puts "  -e, --errors-only      Display only errors (skip successfully validated URLs)"
+      puts "  -d, --dump-binary=PATH Path to dump-signedexchange binary"
+      puts "                         Default: #{DUMP_BINARY}"
       puts
       show_statuses
+      puts
+      puts "Examples:"
+      puts "  #{exe_name} warm https://example.com/page1"
+      puts "  #{exe_name} validate -n -e https://example.com/page1 https://another.com"
     end
 
     def show_statuses
-      puts "Possible statuses:"
-      formatter.icons.map do |status, icon|
-        puts "  #{icon} #{status.to_s.tr("_", " ")}"
+      puts "Validation status indicators:"
+      printer.icons.map do |status, icon|
+        puts "  #{icon} #{status.to_s.tr("_", " ").capitalize}"
       end
     end
 
-    attr_reader :exe_name, :formatter, :checker
+    attr_reader :exe_name, :printer, :default_dump_binary
 
     def initialize(exe_name)
       @exe_name = exe_name
-      @formatter = SxgChecker::Formatter.new
-      @checker = SxgChecker::Checker.new
+      @printer = SxgChecker::Printer.new
     end
   end
 end

data/lib/sxg_checker/document.rb

@@ -2,6 +2,10 @@ module SxgChecker
   class Document
     attr_reader :url, :status, :subresources
 
+    def ok?
+      status == :ok && subresources.all?(&:ok?)
+    end
+
     private
 
     def initialize(url, status, subresources = [])

data/lib/sxg_checker/{formatter.rb → printer.rb}

@@ -1,14 +1,20 @@
 module SxgChecker
-  class Formatter
-    def resource(resource)
-      icon = icons.fetch(resource.status)
-      "#{icon} #{resource.url}"
+  class Printer
+    def call(document)
+      puts "#{icon(document)} #{document.url}"
+      document.subresources.sort.each do |subresource|
+        puts "#{icon(subresource)}   #{subresource.url}"
+      end
     end
 
     attr_reader :icons
 
     private
 
+    def icon(resource)
+      icons.fetch(resource.status)
+    end
+
     def initialize(icons = {
       ok: "✓",
       missing: "?",

data/lib/sxg_checker/subresource.rb

@@ -12,6 +12,10 @@ module SxgChecker
       fresh_url <=> other.fresh_url
     end
 
+    def ok?
+      status == :ok
+    end
+
     private
 
     def initialize(url, status)

data/lib/sxg_checker/version.rb

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

data/lib/sxg_checker.rb

@@ -16,4 +16,6 @@ module SxgChecker
   Error = Class.new(StandardError)
   InvalidUrl = Class.new(Error)
   ToolNotFound = Class.new(Error)
+
+  DUMP_BINARY = "#{ENV["HOME"]}/go/bin/dump-signedexchange"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sxg_checker
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Paweł Pokrywka
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-05-08 00:00:00.000000000 Z
+date: 2025-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -59,7 +59,7 @@ files:
 - lib/sxg_checker/checker.rb
 - lib/sxg_checker/cli.rb
 - lib/sxg_checker/document.rb
-- lib/sxg_checker/formatter.rb
+- lib/sxg_checker/printer.rb
 - lib/sxg_checker/subresource.rb
 - lib/sxg_checker/version.rb
 homepage: https://github.com/pepawel/sxg_checker