feat: add request timeout to load_web_page

Merge #4887

## Link to Issue or Description of Change

Closes #4886

## Update — 2026-04-30

After merging the latest `upstream/main`, the SSRF rewrite already covers URL-scheme validation and routes every fetch failure through a unified `Failed to fetch url` message. The unique contribution of this PR is now the request **timeout**; the body and tests below have been updated to reflect the post-merge scope. No code added by this PR duplicates what upstream already provides.

## Problem

`load_web_page()` calls `requests.get()` without a `timeout`. If the target server is unresponsive, the agent hangs indefinitely.

## Solution

Add `timeout=_DEFAULT_TIMEOUT_SECONDS` (30 seconds) to both HTTP entry points in the module:
- `requests.get` in `_fetch_response` (proxy path).
- `session.get` in `_fetch_direct_response` (pinned-IP path).

Extend the `except` in `load_web_page` to also catch `requests.RequestException`, so timeout and connection errors return the standard `Failed to fetch url: {url}` message instead of propagating.

**Design note:** the timeout is a module-level constant rather than a function parameter to keep it out of the LLM function-calling schema. It can be overridden via `load_web_page._DEFAULT_TIMEOUT_SECONDS = 30` if needed.

## Testing Plan

### Unit Tests
- [x] Added/updated unit tests.
- [x] All unit tests pass locally (`pytest tests/unittests/tools/test_load_web_page.py` → 10 passed).

New/updated tests in `tests/unittests/tools/test_load_web_page.py`:
- `test_load_web_page_uses_proxy_for_unresolved_public_hostnames` — updated to verify `timeout=10` is forwarded on the proxy path.
- `test_load_web_page_passes_timeout_to_pinned_session` — verifies the timeout reaches the pinned-IP session.
- `test_load_web_page_passes_timeout_to_proxied_get` — verifies the timeout is forwarded when a proxy is configured.
- `test_load_web_page_returns_failure_on_timeout` — verifies `requests.exceptions.Timeout` is converted into `Failed to fetch url`.

### Manual E2E
N/A — internal hardening; function signature unchanged.

## Checklist

- [x] I have read the CONTRIBUTING.md document.
- [x] I have performed a self-review of my own code.
- [x] I have added tests that prove my fix is effective.
- [x] New and existing unit tests pass locally with my changes.

## Additional Context

This complements the existing SSRF protection (`allow_redirects=False`, hostname/IP validation, pinned-IP adapter) already present in the module after upstream/main was merged.

Co-authored-by: Bo Yang <ybo@google.com>
COPYBARA_INTEGRATE_REVIEW=#4887 from cchinchilla-dev:feat/load-web-page-timeout-and-url-validation 4bd4799
PiperOrigin-RevId: 930335977

Author: 2 people

src/google/adk/tools/load_web_page.py

@@ -30,6 +30,8 @@
 
 _ALLOWED_URL_SCHEMES = frozenset({'http', 'https'})
 _DEFAULT_PORT_BY_SCHEME = {'http': 80, 'https': 443}
+# Default timeout in seconds for HTTP requests.
+_DEFAULT_TIMEOUT_SECONDS = 30
 _ResolvedAddress = ipaddress.IPv4Address | ipaddress.IPv6Address
 
 
@@ -230,6 +232,7 @@ def _fetch_direct_response(
           url,
           allow_redirects=False,
           proxies={'http': None, 'https': None},
+          timeout=_DEFAULT_TIMEOUT_SECONDS,
       )
     except requests.RequestException as exc:
       last_error = exc
@@ -253,7 +256,9 @@ def _fetch_response(url: str) -> requests.Response:
     # localhost-style names can be rejected locally without breaking proxy use.
     if parsed_ip_literal is not None and _is_blocked_address(parsed_ip_literal):
       raise ValueError(f'Blocked host: {target.hostname}')
-    return requests.get(url, allow_redirects=False)
+    return requests.get(
+        url, allow_redirects=False, timeout=_DEFAULT_TIMEOUT_SECONDS
+    )
 
   if parsed_ip_literal is not None:
     if _is_blocked_address(parsed_ip_literal):
@@ -285,7 +290,7 @@ def load_web_page(url: str) -> str:
 
   try:
     response = _fetch_response(url)
-  except ValueError:
+  except (ValueError, requests.RequestException):
     return _failed_to_fetch_message(url)
 
   # Set allow_redirects=False to prevent SSRF attacks via redirection.

tests/unittests/tools/test_load_web_page.py

@@ -147,7 +147,9 @@ def test_load_web_page_uses_proxy_for_unresolved_public_hostnames(monkeypatch):
 
   assert result == 'This page has enough words to keep.'
   mock_get.assert_called_once_with(
-      'https://does-not-resolve.invalid', allow_redirects=False
+      'https://does-not-resolve.invalid',
+      allow_redirects=False,
+      timeout=load_web_page_module._DEFAULT_TIMEOUT_SECONDS,
   )
   mock_send.assert_not_called()
 
@@ -272,3 +274,124 @@ def _send(
       'https://93.184.216.35',
   ]
   mock_get.assert_not_called()
+
+
+def test_load_web_page_passes_timeout_to_pinned_session(monkeypatch):
+  """Verify that the default timeout is passed to the pinned IP session."""
+  _clear_proxy_env(monkeypatch)
+  monkeypatch.setattr(
+      load_web_page_module.socket,
+      'getaddrinfo',
+      mock.Mock(
+          return_value=[(
+              socket.AF_INET,
+              socket.SOCK_STREAM,
+              socket.IPPROTO_TCP,
+              '',
+              ('93.184.216.34', 0),
+          )]
+      ),
+  )
+  monkeypatch.setattr(
+      'bs4.BeautifulSoup',
+      mock.Mock(
+          return_value=mock.Mock(
+              get_text=mock.Mock(
+                  return_value='This page has enough words to keep.'
+              )
+          )
+      ),
+  )
+  captured_timeouts: list[object] = []
+
+  def _send(
+      self,
+      request,
+      stream=False,
+      timeout=None,
+      verify=True,
+      cert=None,
+      proxies=None,
+  ):
+    del self, request, stream, verify, cert, proxies
+    captured_timeouts.append(timeout)
+    return _create_response(
+        '<html><body><p>This page has enough words to keep.</p></body></html>'
+    )
+
+  monkeypatch.setattr(load_web_page_module.HTTPAdapter, 'send', _send)
+
+  load_web_page('https://example.com')
+
+  assert captured_timeouts == [load_web_page_module._DEFAULT_TIMEOUT_SECONDS]
+
+
+def test_load_web_page_passes_timeout_to_proxied_get(monkeypatch):
+  """Verify that the default timeout is passed to requests.get when proxy is used."""
+  monkeypatch.setenv('HTTPS_PROXY', 'http://proxy.example.test:8080')
+  monkeypatch.setenv('NO_PROXY', '')
+  monkeypatch.setattr(
+      load_web_page_module.socket,
+      'getaddrinfo',
+      mock.Mock(side_effect=AssertionError('unexpected local DNS lookup')),
+  )
+  monkeypatch.setattr(
+      'bs4.BeautifulSoup',
+      mock.Mock(
+          return_value=mock.Mock(
+              get_text=mock.Mock(
+                  return_value='This page has enough words to keep.'
+              )
+          )
+      ),
+  )
+  mock_get = mock.Mock(
+      return_value=_create_response(
+          '<html><body><p>This page has enough words to keep.</p></body></html>'
+      )
+  )
+  monkeypatch.setattr(load_web_page_module.requests, 'get', mock_get)
+
+  load_web_page('https://does-not-resolve.invalid')
+
+  mock_get.assert_called_once_with(
+      'https://does-not-resolve.invalid',
+      allow_redirects=False,
+      timeout=load_web_page_module._DEFAULT_TIMEOUT_SECONDS,
+  )
+
+
+def test_load_web_page_returns_failure_on_timeout(monkeypatch):
+  """Verify that a timeout exception is converted to a failed to fetch message."""
+  _clear_proxy_env(monkeypatch)
+  monkeypatch.setattr(
+      load_web_page_module.socket,
+      'getaddrinfo',
+      mock.Mock(
+          return_value=[(
+              socket.AF_INET,
+              socket.SOCK_STREAM,
+              socket.IPPROTO_TCP,
+              '',
+              ('93.184.216.34', 0),
+          )]
+      ),
+  )
+
+  def _send(
+      self,
+      request,
+      stream=False,
+      timeout=None,
+      verify=True,
+      cert=None,
+      proxies=None,
+  ):
+    del self, request, stream, timeout, verify, cert, proxies
+    raise requests.exceptions.Timeout('boom')
+
+  monkeypatch.setattr(load_web_page_module.HTTPAdapter, 'send', _send)
+
+  result = load_web_page('https://example.com')
+
+  assert result == 'Failed to fetch url: https://example.com'