perf: optimize url blocking on navigation (upstream #14945)

Throw immediately in Frame.GoToAsync when the destination URL is
blocked by blocklist/allowlist rules, instead of waiting for the
browser to fail the request. Saves a network round-trip and aligns
with upstream Puppeteer behavior.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: kblok

lib/PuppeteerSharp.Tests/NetworkRestrictionTests/NetworkRestrictionsTests.cs

@@ -34,7 +34,7 @@ await page.GoToAsync(blockedUrl).ContinueWith(t =>
         });
 
         Assert.That(error, Is.Not.Null);
-        Assert.That(error.Message, Does.Contain("net::ERR_INTERNET_DISCONNECTED"));
+        Assert.That(error.Message, Does.Contain("is blocked by blocklist/allowlist rules"));
     }
 
     [Test, PuppeteerTest("network_restrictions.spec", "Network Restrictions", "should block window.location.href navigation to URLs in the blocklist")]
@@ -156,20 +156,29 @@ public async Task ShouldDetachFromTargetsViolatingBlocklistWhenConnectingToRunni
         }
     }
 
-    [Test, PuppeteerTest("network_restrictions.spec", "Network Restrictions", "should not block chrome://version/ even if it matches blocklist")]
-    public async Task ShouldNotBlockChromeVersionEvenIfItMatchesBlocklist()
+    [Test, PuppeteerTest("network_restrictions.spec", "Network Restrictions", "should block chrome://version/ when it matches blocklist")]
+    public async Task ShouldBlockChromeVersionWhenItMatchesBlocklist()
     {
-        const string chromeUrl = "chrome://version/";
+        const string blockedUrl = "chrome://version/";
         var options = TestConstants.DefaultBrowserOptions();
-        options.BlockList = [chromeUrl];
+        options.BlockList = [blockedUrl];
 
         await using var browser = await Puppeteer.LaunchAsync(options, TestConstants.LoggerFactory);
         await using var page = await browser.NewPageAsync();
 
-        await page.GoToAsync(chromeUrl);
+        Exception error = null;
+        await page.GoToAsync(blockedUrl).ContinueWith(t =>
+        {
+            if (t.IsFaulted)
+            {
+                error = t.Exception?.InnerException ?? t.Exception;
+            }
 
-        // Navigation should succeed as chrome:// URLs usually bypass the network
-        Assert.That(page.Url, Is.EqualTo(chromeUrl));
+            return t;
+        });
+
+        Assert.That(error, Is.Not.Null);
+        Assert.That(error.Message, Does.Contain("is blocked by blocklist/allowlist rules"));
     }
 
     [Test, PuppeteerTest("network_restrictions.spec", "Network Restrictions", "should only allow navigation to URLs in the allowlist")]
@@ -199,7 +208,7 @@ await page.GoToAsync(blockedUrl).ContinueWith(t =>
 
         Assert.That(page.Url, Is.Not.EqualTo(blockedUrl));
         Assert.That(error, Is.Not.Null);
-        Assert.That(error.Message, Does.Contain("net::ERR_INTERNET_DISCONNECTED"));
+        Assert.That(error.Message, Does.Contain("is blocked by blocklist/allowlist rules"));
     }
 
     [Test, PuppeteerTest("network_restrictions.spec", "Network Restrictions", "should block window.location.href navigation to URLs not in the allowlist")]
@@ -382,4 +391,33 @@ public async Task ShouldThrowAnErrorForAnInvalidPattern()
 
         Assert.That(error, Is.Not.Null);
     }
+
+    [Test, PuppeteerTest("network_restrictions.spec", "Network Restrictions", "should block frame.goto when the destination is in the blocklist")]
+    public async Task ShouldBlockFrameGotoWhenDestinationIsInBlocklist()
+    {
+        var options = TestConstants.DefaultBrowserOptions();
+        options.BlockList = ["*://*:*/empty.html"];
+
+        await using var browser = await Puppeteer.LaunchAsync(options, TestConstants.LoggerFactory);
+        await using var page = await browser.NewPageAsync();
+
+        await page.GoToAsync(TestConstants.ServerUrl + "/frames/one-frame.html");
+        var frame = Array.Find(page.Frames, f => f != page.MainFrame);
+        Assert.That(frame, Is.Not.Null);
+
+        var blockedUrl = TestConstants.ServerUrl + "/empty.html";
+        Exception error = null;
+        await frame.GoToAsync(blockedUrl).ContinueWith(t =>
+        {
+            if (t.IsFaulted)
+            {
+                error = t.Exception?.InnerException ?? t.Exception;
+            }
+
+            return t;
+        });
+
+        Assert.That(error, Is.Not.Null);
+        Assert.That(error.Message, Does.Contain("is blocked by blocklist/allowlist rules"));
+    }
 }

lib/PuppeteerSharp/Cdp/CdpFrame.cs

@@ -88,6 +88,13 @@ public override async Task<IResponse> GoToAsync(string url, NavigationOptions op
             throw new ArgumentNullException(nameof(options));
         }
 
+        if (CdpPage != null && !CdpPage.IsUrlAllowed(url))
+        {
+            throw new NavigationException(
+                $"Navigation to {url} is blocked by blocklist/allowlist rules",
+                url);
+        }
+
         var referrer = string.IsNullOrEmpty(options.Referer)
             ? FrameManager.NetworkManager.ExtraHTTPHeaders?.GetValue(RefererHeaderName)
             : options.Referer;

lib/PuppeteerSharp/Cdp/CdpPage.cs

@@ -901,6 +901,8 @@ internal static decimal ConvertPrintParameterToInches(object parameter)
         return pixels / 96;
     }
 
+    internal bool IsUrlAllowed(string url) => _targetManager.IsUrlAllowed(url);
+
     /// <inheritdoc />
     protected override async Task ExposeFunctionAsync(string name, Delegate puppeteerFunction)
     {

lib/PuppeteerSharp/Cdp/ChromeTargetManager.cs

@@ -112,6 +112,49 @@ await _connection.SendAsync(
 
         public IEnumerable<ITarget> GetChildTargets(ITarget target) => target.ChildTargets;
 
+        public bool IsUrlAllowed(string url)
+        {
+            var hasBlockList = _blockList != null && _blockList.Length > 0;
+            var hasAllowList = _allowList != null && _allowList.Length > 0;
+
+            if (!hasBlockList && !hasAllowList)
+            {
+                return true;
+            }
+
+            // Always allow internal or setup pages
+            if (string.IsNullOrEmpty(url) || url == "about:blank")
+            {
+                return true;
+            }
+
+            if (hasBlockList)
+            {
+                foreach (var pattern in _blockList)
+                {
+                    if (MatchesUrlPattern(url, pattern))
+                    {
+                        return false;
+                    }
+                }
+            }
+
+            if (hasAllowList)
+            {
+                foreach (var pattern in _allowList)
+                {
+                    if (MatchesUrlPattern(url, pattern))
+                    {
+                        return true;
+                    }
+                }
+
+                return false;
+            }
+
+            return true;
+        }
+
         private static void ValidateUrlPatterns(string[] patterns)
         {
             if (patterns == null)
@@ -459,49 +502,6 @@ private void OnDetachedFromTarget(object sender, TargetDetachedFromTargetRespons
             TargetGone?.Invoke(this, new TargetChangedArgs { Target = target });
         }
 
-        private bool IsUrlAllowed(string url)
-        {
-            var hasBlockList = _blockList != null && _blockList.Length > 0;
-            var hasAllowList = _allowList != null && _allowList.Length > 0;
-
-            if (!hasBlockList && !hasAllowList)
-            {
-                return true;
-            }
-
-            // Always allow internal or setup pages
-            if (string.IsNullOrEmpty(url) || url == "about:blank")
-            {
-                return true;
-            }
-
-            if (hasBlockList)
-            {
-                foreach (var pattern in _blockList)
-                {
-                    if (MatchesUrlPattern(url, pattern))
-                    {
-                        return false;
-                    }
-                }
-            }
-
-            if (hasAllowList)
-            {
-                foreach (var pattern in _allowList)
-                {
-                    if (MatchesUrlPattern(url, pattern))
-                    {
-                        return true;
-                    }
-                }
-
-                return false;
-            }
-
-            return true;
-        }
-
         private async Task MaybeSetupNetworkBlockListAsync(CDPSession session)
         {
             var hasBlockList = _blockList != null && _blockList.Length > 0;

lib/PuppeteerSharp/Cdp/FirefoxTargetManager.cs

@@ -62,6 +62,8 @@ public async Task InitializeAsync()
 
         public IEnumerable<ITarget> GetChildTargets(ITarget target) => [];
 
+        public bool IsUrlAllowed(string url) => true;
+
         private void OnMessageReceived(object sender, MessageEventArgs e)
         {
             try

lib/PuppeteerSharp/Cdp/ITargetManager.cs

@@ -49,5 +49,12 @@ internal interface ITargetManager
         /// <param name="target">Target to evaluate.</param>
         /// <returns>A list of targets.</returns>
         IEnumerable<ITarget> GetChildTargets(ITarget target);
+
+        /// <summary>
+        /// Validates a URL against the configured blocklist/allowlist patterns.
+        /// </summary>
+        /// <param name="url">URL to validate.</param>
+        /// <returns><c>true</c> if the URL is allowed, otherwise <c>false</c>.</returns>
+        bool IsUrlAllowed(string url);
     }
 }

lib/PuppeteerSharp/IFrame.cs

@@ -243,6 +243,7 @@ public interface IFrame
         /// - the `timeout` is exceeded during navigation.
         /// - the remote server does not respond or is unreachable.
         /// - the main resource failed to load.
+        /// - the URL is blocked by blocklist/allowlist rules.
         ///
         /// <see cref="GoToAsync(string, int?, WaitUntilNavigation[])"/> will not throw an error when any valid HTTP status code is returned by the remote server,
         /// including 404 "Not Found" and 500 "Internal Server Error".  The status code for such responses can be retrieved by calling <see cref="IResponse.Status"/>