Add server-side URL validation for absolute URLs to reduce flicker

Broken Gravatar links (absolute URLs) now render fallback SVG immediately
instead of showing a brief broken image before client-side JS swaps it.

Author: akabiru

app/components/primer/open_project/avatar_with_fallback.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "net/http"
+require "uri"
+
 module Primer
   module OpenProject
     # OpenProject-specific Avatar component that extends Primer::Beta::Avatar
@@ -16,6 +19,9 @@ module OpenProject
     class AvatarWithFallback < Primer::Beta::Avatar
       status :open_project
 
+      # Set to false to disable server-side URL validation (useful for tests)
+      mattr_accessor :validate_urls, default: true
+
       # @see
       #   - https://primer.style/foundations/typography/
       #   - https://github.com/primer/css/blob/main/src/support/variables/typography.scss
@@ -33,7 +39,7 @@ def initialize(src: nil, alt: nil, size: DEFAULT_SIZE, shape: DEFAULT_SHAPE, hre
 
         @unique_id = unique_id
         @fallback_svg = generate_fallback_svg(alt, size)
-        final_src = src.blank? ? @fallback_svg : src
+        final_src = resolve_src(src)
 
         super(src: final_src, alt: alt, size: size, shape: shape, href: href, **system_arguments)
       end
@@ -59,6 +65,33 @@ def require_src_or_alt_arguments(src, alt)
         raise ArgumentError, "`src` or `alt` is required"
       end
 
+      def resolve_src(src)
+        return @fallback_svg if src.blank?
+
+        if validate_urls
+          return @fallback_svg if absolute_url?(src) && !url_accessible?(src)
+        end
+
+        src
+      end
+
+      def absolute_url?(url)
+        url.to_s.match?(%r{\Ahttps?://}i)
+      end
+
+      def url_accessible?(url)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 2
+        http.read_timeout = 2
+
+        response = http.head(uri.request_uri)
+        response.is_a?(Net::HTTPSuccess)
+      rescue StandardError
+        false
+      end
+
       def generate_fallback_svg(alt, size)
         svg_content = content_tag(
           :svg,

previews/primer/open_project/avatar_with_fallback_preview.rb

@@ -69,19 +69,37 @@ def fallback_as_link
 
       # @!group Error Handling (404 Fallback)
       #
-      # @label Broken image (404)
+      # @label Broken absolute URL (server-side fallback)
       # @snapshot
-      def broken_image_404
-        # Uses a non-existent URL - will trigger error handler and show fallback SVG
+      def broken_absolute_url
+        # Absolute URLs are validated server-side via HEAD request
+        # If inaccessible, fallback SVG is rendered immediately (no flicker)
         render(Primer::OpenProject::AvatarWithFallback.new(
-          src: "/non-existent-avatar.png",
+          src: "https://example.com/non-existent-avatar.png",
           alt: "User With Missing Avatar",
           unique_id: 42
         ))
       end
 
-      # @label Multiple broken images
-      def multiple_broken_images
+      # @label Multiple broken absolute URLs (server-side)
+      def multiple_broken_absolute_urls
+        render_with_template(locals: {})
+      end
+
+      # @label Broken relative URL (client-side fallback)
+      # @snapshot
+      def broken_relative_url
+        # Relative URLs cannot be validated server-side (no host context)
+        # Client-side JS handles the error and swaps to fallback SVG
+        render(Primer::OpenProject::AvatarWithFallback.new(
+          src: "/non-existent-avatar.png",
+          alt: "User With Missing Avatar",
+          unique_id: 43
+        ))
+      end
+
+      # @label Multiple broken relative URLs (client-side)
+      def multiple_broken_relative_urls
         render_with_template(locals: {})
       end
       #

previews/primer/open_project/avatar_with_fallback_preview/multiple_broken_absolute_urls.html.erb

@@ -0,0 +1,8 @@
+<div class="d-flex gap-3 flex-items-center">
+  <p class="color-fg-muted">Absolute URLs are validated server-side. Broken URLs render fallback immediately (no flicker):</p>
+</div>
+<div class="d-flex gap-3 flex-items-center mt-2">
+  <%= render(Primer::OpenProject::AvatarWithFallback.new(src: "https://example.com/missing/alice.png", alt: "Alice Johnson", unique_id: 10)) %>
+  <%= render(Primer::OpenProject::AvatarWithFallback.new(src: "https://example.com/missing/bob.png", alt: "Bob Smith", unique_id: 20)) %>
+  <%= render(Primer::OpenProject::AvatarWithFallback.new(src: "https://invalid-domain-12345.com/avatar.png", alt: "Charlie Brown", unique_id: 30)) %>
+</div>

previews/primer/open_project/avatar_with_fallback_preview/multiple_broken_images.html.erb

@@ -0,0 +1,8 @@
+<div class="d-flex gap-3 flex-items-center">
+  <p class="color-fg-muted">Relative URLs are handled client-side. JS swaps to fallback on error (may show brief flicker):</p>
+</div>
+<div class="d-flex gap-3 flex-items-center mt-2">
+  <%= render(Primer::OpenProject::AvatarWithFallback.new(src: "/missing/alice.png", alt: "Alice Johnson", unique_id: 10)) %>
+  <%= render(Primer::OpenProject::AvatarWithFallback.new(src: "/missing/bob.png", alt: "Bob Smith", unique_id: 20)) %>
+  <%= render(Primer::OpenProject::AvatarWithFallback.new(src: "/avatars/charlie.png", alt: "Charlie Brown", unique_id: 30)) %>
+</div>

previews/primer/open_project/avatar_with_fallback_preview/multiple_broken_relative_urls.html.erb

@@ -5,6 +5,15 @@
 class PrimerOpenProjectAvatarStackTest < Minitest::Test
   include Primer::ComponentTestHelpers
 
+  def setup
+    @original_validate_urls = Primer::OpenProject::AvatarWithFallback.validate_urls
+    Primer::OpenProject::AvatarWithFallback.validate_urls = false
+  end
+
+  def teardown
+    Primer::OpenProject::AvatarWithFallback.validate_urls = @original_validate_urls
+  end
+
   def test_renders_with_image_avatars
     render_inline(Primer::OpenProject::AvatarStack.new) do |component|
       component.with_avatar_with_fallback(src: "https://github.com/github.png", alt: "@github")

test/components/open_project/avatar_stack_test.rb

@@ -5,6 +5,16 @@
 class PrimerOpenProjectAvatarWithFallbackTest < Minitest::Test
   include Primer::ComponentTestHelpers
 
+  def setup
+    # Disable URL validation by default in tests to avoid HTTP requests
+    @original_validate_urls = Primer::OpenProject::AvatarWithFallback.validate_urls
+    Primer::OpenProject::AvatarWithFallback.validate_urls = false
+  end
+
+  def teardown
+    Primer::OpenProject::AvatarWithFallback.validate_urls = @original_validate_urls
+  end
+
   def test_renders_image_avatar_with_src
     render_inline(Primer::OpenProject::AvatarWithFallback.new(src: "https://github.com/github.png", alt: "github"))
 
@@ -31,6 +41,18 @@ def test_image_avatar_error_handling_setup
     assert_includes svg_content, ">AJ<", "Fallback SVG should contain initials 'AJ'"
   end
 
+  def test_falls_back_when_absolute_url_is_inaccessible
+    Primer::OpenProject::AvatarWithFallback.validate_urls = true
+    Primer::OpenProject::AvatarWithFallback.any_instance.stubs(:url_accessible?).returns(false)
+
+    render_inline(Primer::OpenProject::AvatarWithFallback.new(src: "https://broken.example.com/avatar.png", alt: "Test User", unique_id: 42))
+
+    # Should render fallback SVG when URL is inaccessible
+    assert_selector("avatar-fallback[data-unique-id='42']") do
+      assert_selector("img.avatar[src^='data:image/svg+xml;base64,']")
+    end
+  end
+
   def test_renders_fallback_when_src_is_nil
     render_inline(Primer::OpenProject::AvatarWithFallback.new(src: nil, alt: "OpenProject Admin"))