langgraph-api 0.7.102__tar.gz → 0.8.0__tar.gz

{langgraph_api-0.7.102 → langgraph_api-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-api
-Version: 0.7.102
+Version: 0.8.0
 Author-email: Will Fu-Hinthorn <will@langchain.dev>, Josh Rogers <josh@langchain.dev>, Parker Rule <parker@langchain.dev>
 License: Elastic-2.0
 License-File: LICENSE

{langgraph_api-0.7.102 → langgraph_api-0.8.0}/benchmark/capacity_runner.mjs

@@ -30,11 +30,11 @@ const clusterNameToSettings = {
   },
   'py-7-node': {
     url: 'https://cap-bench-py-7-node-5f471cdb8a725e0bbb076cc9fb32b76d.staging.langgraph.app',
-    rampEndMultiplier: 1.8,
+    rampEndMultiplier: 5,
   },
   'py-20-node': {
     url: 'https://cap-bench-py-20-node-0970dd3e458059e488db99d48c69ca69.staging.langgraph.app',
-    rampEndMultiplier: 2.4,
+    rampEndMultiplier: 10,
   },
   // Distributed runtime multi-node scaling benchmarks
   'dr-1-node': {
@@ -47,11 +47,11 @@ const clusterNameToSettings = {
   },
   'dr-7-node': {
     url: 'https://cap-bench-dr-7-node-fbf64b46fc9b57239764478187abe534.staging.langgraph.app',
-    rampEndMultiplier: 1.8,
+    rampEndMultiplier: 5,
   },
   'dr-20-node': {
     url: 'https://cap-bench-dr-20-node-7cea036a01a25a9caec0be0b873f9b0a.staging.langgraph.app',
-    rampEndMultiplier: 2.4,
+    rampEndMultiplier: 10,
   },
 };
 

langgraph_api-0.8.0/langgraph_api/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.8.0"

{langgraph_api-0.7.102 → langgraph_api-0.8.0}/langgraph_api/cli.py

@@ -108,6 +108,47 @@ def _find_open_port(host: str) -> int:
         return s.getsockname()[1]
 
 
+def _resolve_server_url(
+    host: str, port: int, *, mount_prefix: str | None, tunnel: bool
+) -> str:
+    """Return the public-facing base URL for the server.
+
+    When *tunnel* is True a Cloudflare tunnel is started and the tunnel
+    URL is returned; otherwise the local ``http://host:port`` URL is used.
+    *mount_prefix* (if any) is appended to the result.
+    """
+    from langgraph_api.utils.network import format_hostport  # noqa: PLC0415
+
+    upstream_url = f"http://{format_hostport(host, port)}"
+    if mount_prefix:
+        upstream_url += mount_prefix
+
+    if not tunnel:
+        return upstream_url
+
+    logger.info("Starting Cloudflare Tunnel...")
+    from langgraph_api.tunneling.cloudflare import start_tunnel  # noqa: PLC0415
+
+    tunnel_obj = start_tunnel(port)
+    try:
+        public_url = tunnel_obj.url.result(timeout=30)
+    except FutureTimeoutError:
+        logger.warning(
+            "Timed out waiting for Cloudflare Tunnel URL; using local URL %s",
+            upstream_url,
+        )
+        public_url = upstream_url
+    except Exception as e:
+        tunnel_obj.process.kill()
+        raise RuntimeError("Failed to start Cloudflare Tunnel") from e
+
+    # Only append the prefix if we got a real tunnel URL; on timeout
+    # fallback, public_url is already upstream_url which has the prefix.
+    if mount_prefix and public_url != upstream_url:
+        public_url += mount_prefix
+    return public_url
+
+
 def _resolve_port(host: str, port: int | None) -> int:
     """Resolve the port to use for the server."""
     if port is not None:
@@ -209,38 +250,11 @@ def run_server(
             debugpy.wait_for_client()
             logger.info("Debugger attached. Starting server...")
 
-    # Determine local or tunneled URL
-    with patch_environment(
-        MIGRATIONS_PATH=__migrations_path__,
-        DATABASE_URI=__database_uri__,
-        REDIS_URI=__redis_uri__,
-    ):
-        from langgraph_api.utils.network import format_hostport  # noqa: PLC0415
-
-        upstream_url = f"http://{format_hostport(host, port)}"
-    if mount_prefix:
-        upstream_url += mount_prefix
-    if tunnel:
-        logger.info("Starting Cloudflare Tunnel...")
-        from langgraph_api.tunneling.cloudflare import start_tunnel  # noqa: PLC0415
-
-        tunnel_obj = start_tunnel(port)
-        try:
-            public_url = tunnel_obj.url.result(timeout=30)
-        except FutureTimeoutError:
-            logger.warning(
-                "Timed out waiting for Cloudflare Tunnel URL; using local URL %s",
-                upstream_url,
-            )
-            public_url = upstream_url
-        except Exception as e:
-            tunnel_obj.process.kill()
-            raise RuntimeError("Failed to start Cloudflare Tunnel") from e
-        local_url = public_url
-        if mount_prefix:
-            local_url += mount_prefix
-    else:
-        local_url = upstream_url
+    # Build all env patches up front so that langgraph_api.config (which
+    # is read at import time) sees every config value.  LANGGRAPH_API_URL
+    # is resolved inside the block (it depends on tunnel/mount_prefix) and
+    # overwritten then; the empty placeholder ensures patch_environment
+    # tracks and restores the original value on exit.
     to_patch = dict(
         MIGRATIONS_PATH=__migrations_path__,
         DATABASE_URI=__database_uri__,
@@ -258,7 +272,7 @@ def run_server(
         LANGGRAPH_UI_CONFIG=json.dumps(ui_config) if ui_config else None,
         LANGGRAPH_CHECKPOINTER=json.dumps(checkpointer) if checkpointer else None,
         LANGGRAPH_UI_BUNDLER="true",
-        LANGGRAPH_API_URL=local_url,
+        LANGGRAPH_API_URL="",  # resolved below, inside the patched block
         LANGGRAPH_DISABLE_FILE_PERSISTENCE=str(disable_persistence).lower(),
         LANGGRAPH_RUNTIME_EDITION=runtime_edition,
         # If true, we will not raise on blocking IO calls (via blockbuster)
@@ -273,9 +287,13 @@ def run_server(
                 logger.debug(f"Skipping loaded env var {k}={v}")
                 continue
             to_patch[k] = v
-    with patch_environment(
-        **to_patch,
-    ):
+
+    with patch_environment(**to_patch):
+        local_url = _resolve_server_url(
+            host, port, mount_prefix=mount_prefix, tunnel=tunnel
+        )
+        os.environ["LANGGRAPH_API_URL"] = local_url
+
         studio_origin = studio_url or _get_ls_origin() or "https://smith.langchain.com"
         full_studio_url = f"{studio_origin}/studio/?baseUrl={local_url}"
 

{langgraph_api-0.7.102 → langgraph_api-0.8.0}/langgraph_api/config/__init__.py

@@ -351,7 +351,8 @@ FF_CRONS_ENABLED = env("FF_CRONS_ENABLED", cast=bool, default=True)
 FF_LOG_DROPPED_EVENTS = env("FF_LOG_DROPPED_EVENTS", cast=bool, default=False)
 FF_LOG_QUERY_AND_PARAMS = env("FF_LOG_QUERY_AND_PARAMS", cast=bool, default=False)
 # Not in public docs: internal feature flag
-FF_USE_REDIS_QUEUE = env("FF_USE_REDIS_QUEUE", cast=bool, default=False)
+FF_USE_REDIS_QUEUE = env("FF_USE_REDIS_QUEUE", cast=bool, default=True)
+
 
 # Internal flag intended for testing only
 CRON_SCHEDULER_SLEEP_TIME = env("CRON_SCHEDULER_SLEEP_TIME", cast=int, default=5)

{langgraph_api-0.7.102 → langgraph_api-0.8.0}/langgraph_api/config/schemas.py

@@ -386,7 +386,13 @@ class WebhookUrlPolicy(TypedDict, total=False):
     max_url_length: int
     """Maximum permitted URL length in characters; longer inputs are rejected early."""
     disable_loopback: bool
-    """Disallow relative URLs (internal loopback calls) when true."""
+    """Disallow relative URLs (internal loopback calls) and localhost hostnames when true."""
+    disable_private_ips: bool
+    """Block RFC 1918 / CGN private IP ranges as webhook targets when true.
+
+    Defaults to false (private IPs allowed). Set to true to block private
+    IP ranges for stricter SSRF protection.
+    """
 
 
 # Matches things like "${{ env.LG_WEBHOOK_FOO_BAR }}"
@@ -421,6 +427,8 @@ def _validate_url_policy(
         policy["max_url_length"] = 2048
     if "disable_loopback" not in policy:
         policy["disable_loopback"] = False
+    if "disable_private_ips" not in policy:
+        policy["disable_private_ips"] = False
     return policy
 
 

{langgraph_api-0.7.102 → langgraph_api-0.8.0}/langgraph_api/http.py

@@ -123,6 +123,37 @@ def get_loopback_client() -> JsonHttpClient:
     return _loopback_client
 
 
+_webhook_http_client: JsonHttpClient | None = None
+
+
+async def ensure_webhook_http_client() -> JsonHttpClient:
+    """Return (or create) an SSRF-safe HTTP client for webhook dispatch."""
+    global _webhook_http_client
+    if _webhook_http_client is not None:
+        return _webhook_http_client
+
+    from langgraph_api.lc_security import ssrf_safe_async_client  # noqa: PLC0415
+    from langgraph_api.webhook import _get_webhook_config  # noqa: PLC0415
+
+    inner = ssrf_safe_async_client(
+        policy=_get_webhook_config().base_ssrf_policy,
+        retries=2,
+        limits=httpx.Limits(max_keepalive_connections=10, keepalive_expiry=60.0),
+        follow_redirects=True,
+        max_redirects=5,
+    )
+    _webhook_http_client = JsonHttpClient(client=inner)
+    return _webhook_http_client
+
+
+async def stop_webhook_http_client() -> None:
+    global _webhook_http_client
+    if _webhook_http_client is None:
+        return
+    await _webhook_http_client.client.aclose()
+    _webhook_http_client = None
+
+
 def is_retriable_error(exception: BaseException) -> bool:
     # httpx error hierarchy: https://www.python-httpx.org/exceptions/
     # Retry all timeout related errors

{langgraph_api-0.7.102 → langgraph_api-0.8.0}/langgraph_api/js/package.json

@@ -19,7 +19,7 @@
     "dedent": "^1.7.2",
     "esbuild": "^0.27.4",
     "exit-hook": "^5.1.0",
-    "hono": "^4.12.12",
+    "hono": "^4.12.14",
     "p-queue": "^9.0.1",
     "p-retry": "^7.1.1",
     "tsx": "^4.21.0",

{langgraph_api-0.7.102 → langgraph_api-0.8.0}/langgraph_api/js/yarn.lock

@@ -1316,10 +1316,10 @@ graceful-fs@^4.2.4:
   resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-4.2.11.tgz#4183e4e8bf08bb6e05bbb2f7d2e0c8f712ca40e3"
   integrity sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==
 
-hono@^4.12.12, hono@^4.5.4:
-  version "4.12.12"
-  resolved "https://registry.yarnpkg.com/hono/-/hono-4.12.12.tgz#1f14b0ffb47c386ff50d457d66e706d9c9a7f09c"
-  integrity sha512-p1JfQMKaceuCbpJKAPKVqyqviZdS0eUxH9v82oWo1kb9xjQ5wA6iP3FNVAPDFlz5/p7d45lO+BpSk1tuSZMF4Q==
+hono@^4.12.14, hono@^4.5.4:
+  version "4.12.14"
+  resolved "https://registry.yarnpkg.com/hono/-/hono-4.12.14.tgz#4777c9512b7c84138e4f09e61e3d2fa305eb1414"
+  integrity sha512-am5zfg3yu6sqn5yjKBNqhnTX7Cv+m00ox+7jbaKkrLMRJ4rAdldd1xPd/JzbBWspqaQv6RSTrgFN95EsfhC+7w==
 
 icss-utils@^5.0.0, icss-utils@^5.1.0:
   version "5.1.0"
@@ -1393,9 +1393,9 @@ kuler@^2.0.0:
   integrity sha512-Xq9nH7KlWZmXAtodXDDRE7vs6DU1gTU8zYDHDiWLSip45Egwq3plLHzPn27NgvzL2r1LMPC1vdqh98sQxtqj4A==
 
 "langsmith@>=0.3.33 <1.0.0", langsmith@>=0.4.6, "langsmith@>=0.5.0 <1.0.0":
-  version "0.5.18"
-  resolved "https://registry.yarnpkg.com/langsmith/-/langsmith-0.5.18.tgz#c691ad23614f0b46eaf07d982e0ac988e1f43880"
-  integrity sha512-3zuZUWffTHQ+73EAwnodADtf534VNEZUpXr9jC12qyG8/IQuJET7PRsCpTb9wX2lmBspakwLUpqpj3tNm/0bVA==
+  version "0.5.20"
+  resolved "https://registry.yarnpkg.com/langsmith/-/langsmith-0.5.20.tgz#4021847d2ccd5a86c5eb96060f9bb5f19f80eca5"
+  integrity sha512-ULhLM8RswvQDXufLtNtvclHrWCBx8Cb5UPI6lAZC+8Dq59iHsVPz/3Ac9khWNm1VIvChRsuykixD/WrmzuuA3Q==
   dependencies:
     p-queue "6.6.2"
     uuid "10.0.0"

langgraph_api-0.8.0/langgraph_api/lc_security/__init__.py

@@ -0,0 +1,29 @@
+"""lc_security — SSRF protection and security utilities.
+
+Vendored from langchainplus/lc_security. When lc-security is published
+to PyPI, delete this package and add the pip dependency instead.
+"""
+
+from langgraph_api.lc_security.exceptions import SSRFBlockedError
+from langgraph_api.lc_security.policy import (
+    SSRFPolicy,
+    validate_hostname,
+    validate_resolved_ip,
+    validate_url,
+    validate_url_sync,
+)
+from langgraph_api.lc_security.transport import (
+    SSRFSafeTransport,
+    ssrf_safe_async_client,
+)
+
+__all__ = [
+    "SSRFBlockedError",
+    "SSRFPolicy",
+    "SSRFSafeTransport",
+    "ssrf_safe_async_client",
+    "validate_hostname",
+    "validate_resolved_ip",
+    "validate_url",
+    "validate_url_sync",
+]

langgraph_api-0.8.0/langgraph_api/lc_security/exceptions.py

@@ -0,0 +1,9 @@
+"""SSRF protection exceptions."""
+
+
+class SSRFBlockedError(Exception):
+    """Raised when a request is blocked by SSRF protection policy."""
+
+    def __init__(self, reason: str) -> None:
+        self.reason = reason
+        super().__init__(f"SSRF blocked: {reason}")

langgraph_api-0.8.0/langgraph_api/lc_security/policy.py

@@ -0,0 +1,349 @@
+"""SSRF protection policy with IP validation and DNS-aware URL checking."""
+
+import asyncio
+import dataclasses
+import ipaddress
+import socket
+import urllib.parse
+
+import structlog
+
+from langgraph_api.lc_security.exceptions import SSRFBlockedError
+
+logger = structlog.get_logger(__name__)
+
+# ---------------------------------------------------------------------------
+# Blocklist constants
+# ---------------------------------------------------------------------------
+
+# Ranges that are NEVER valid webhook targets (always blocked regardless of
+# deployment mode).
+_ALWAYS_BLOCKED_IPV4_NETWORKS: tuple[ipaddress.IPv4Network, ...] = tuple(
+    ipaddress.IPv4Network(n)
+    for n in (
+        "169.254.0.0/16",  # RFC 3927 - link-local
+        "0.0.0.0/8",  # RFC 1122 - "this network"
+        "192.0.0.0/24",  # RFC 6890 - IETF protocol assignments
+        "192.0.2.0/24",  # RFC 5737 - TEST-NET-1 (documentation)
+        "198.18.0.0/15",  # RFC 2544 - benchmarking
+        "198.51.100.0/24",  # RFC 5737 - TEST-NET-2 (documentation)
+        "203.0.113.0/24",  # RFC 5737 - TEST-NET-3 (documentation)
+        "224.0.0.0/4",  # RFC 5771 - multicast
+        "240.0.0.0/4",  # RFC 1112 - reserved for future use
+        "255.255.255.255/32",  # RFC 919  - limited broadcast
+    )
+)
+
+# Loopback ranges — blocked when block_localhost is set, allowed by default.
+_LOOPBACK_IPV4_NETWORKS: tuple[ipaddress.IPv4Network, ...] = tuple(
+    ipaddress.IPv4Network(n)
+    for n in ("127.0.0.0/8",)  # RFC 1122 - loopback
+)
+
+# Private/internal ranges — blocked in SAAS, allowed in self-hosted/BYOC
+# where internal webhook targets are legitimate.
+_PRIVATE_IPV4_NETWORKS: tuple[ipaddress.IPv4Network, ...] = tuple(
+    ipaddress.IPv4Network(n)
+    for n in (
+        "10.0.0.0/8",  # RFC 1918 - private class A
+        "172.16.0.0/12",  # RFC 1918 - private class B
+        "192.168.0.0/16",  # RFC 1918 - private class C
+        "100.64.0.0/10",  # RFC 6598 - shared/CGN address space
+    )
+)
+
+_ALWAYS_BLOCKED_IPV6_NETWORKS: tuple[ipaddress.IPv6Network, ...] = tuple(
+    ipaddress.IPv6Network(n)
+    for n in (
+        "fe80::/10",  # RFC 4291 - link-local
+        "ff00::/8",  # RFC 4291 - multicast
+        "::ffff:0:0/96",  # RFC 4291 - IPv4-mapped IPv6 addresses
+        "::0.0.0.0/96",  # RFC 4291 - IPv4-compatible IPv6 (deprecated)
+        "64:ff9b::/96",  # RFC 6052 - NAT64 well-known prefix
+        "64:ff9b:1::/48",  # RFC 8215 - NAT64 discovery prefix
+    )
+)
+
+_LOOPBACK_IPV6_NETWORKS: tuple[ipaddress.IPv6Network, ...] = tuple(
+    ipaddress.IPv6Network(n)
+    for n in ("::1/128",)  # RFC 4291 - loopback
+)
+
+# Private/internal IPv6 — blocked in SAAS, allowed in self-hosted/BYOC.
+_PRIVATE_IPV6_NETWORKS: tuple[ipaddress.IPv6Network, ...] = tuple(
+    ipaddress.IPv6Network(n)
+    for n in (
+        "fc00::/7",  # RFC 4193 - unique local addresses (ULA)
+    )
+)
+
+_CLOUD_METADATA_IPS: frozenset[str] = frozenset(
+    {
+        "169.254.169.254",
+        "169.254.170.2",
+        "100.100.100.200",
+        "fd00:ec2::254",
+    }
+)
+
+_CLOUD_METADATA_HOSTNAMES: frozenset[str] = frozenset(
+    {
+        "metadata.google.internal",
+        "metadata.amazonaws.com",
+        "metadata",
+        "instance-data",
+    }
+)
+
+_LOCALHOST_NAMES: frozenset[str] = frozenset(
+    {
+        "localhost",
+        "localhost.localdomain",
+        "host.docker.internal",
+    }
+)
+
+_K8S_SUFFIX = ".svc.cluster.local"
+
+# NAT64 well-known prefixes
+_NAT64_PREFIX = ipaddress.IPv6Network("64:ff9b::/96")
+
+# ---------------------------------------------------------------------------
+# SSRFPolicy
+# ---------------------------------------------------------------------------
+
+
+@dataclasses.dataclass(frozen=True)
+class SSRFPolicy:
+    """Immutable policy controlling which URLs/IPs are considered safe."""
+
+    allowed_schemes: frozenset[str] = frozenset({"http", "https"})
+    block_private_ips: bool = False
+    block_localhost: bool = False
+    block_cloud_metadata: bool = True
+    block_k8s_internal: bool = True
+    allowed_hosts: frozenset[str] = frozenset()
+    additional_blocked_cidrs: tuple[
+        ipaddress.IPv4Network | ipaddress.IPv6Network, ...
+    ] = ()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _extract_embedded_ipv4(
+    addr: ipaddress.IPv6Address,
+) -> ipaddress.IPv4Address | None:
+    """Extract an embedded IPv4 from IPv4-mapped or NAT64 IPv6 addresses."""
+    # Check ipv4_mapped first (covers ::ffff:x.x.x.x)
+    if addr.ipv4_mapped is not None:
+        return addr.ipv4_mapped
+
+    # Check NAT64 well-known prefix (/96) - embedded IPv4 is in the last 4 bytes.
+    # NOTE: We intentionally only extract for the /96 prefix where the
+    # last-4-bytes extraction is correct per RFC 6052 §2.2. The /48 discovery
+    # prefix (64:ff9b:1::/48, RFC 8215) embeds IPv4 at a different offset
+    # and is already blocked outright via _BLOCKED_IPV6_NETWORKS.
+    if addr in _NAT64_PREFIX:
+        raw = addr.packed
+        return ipaddress.IPv4Address(raw[-4:])
+
+    return None
+
+
+def _ip_in_blocked_networks(
+    addr: ipaddress.IPv4Address | ipaddress.IPv6Address,
+    policy: SSRFPolicy,
+) -> str | None:
+    """Return a reason string if *addr* falls in a blocked range, else None."""
+    if isinstance(addr, ipaddress.IPv4Address):
+        # Always-blocked ranges (link-local, reserved, etc.)
+        for net in _ALWAYS_BLOCKED_IPV4_NETWORKS:
+            if addr in net:
+                return "blocked IP range"
+        # Loopback — only when block_localhost is set.
+        if policy.block_localhost:
+            for net in _LOOPBACK_IPV4_NETWORKS:
+                if addr in net:
+                    return "loopback IP range"
+        # Private ranges (RFC 1918, CGN) — only when policy says so.
+        if policy.block_private_ips:
+            for net in _PRIVATE_IPV4_NETWORKS:
+                if addr in net:
+                    return "private IP range"
+        for net in policy.additional_blocked_cidrs:
+            if isinstance(net, ipaddress.IPv4Network) and addr in net:
+                return "blocked CIDR"
+    else:
+        for net in _ALWAYS_BLOCKED_IPV6_NETWORKS:
+            if addr in net:
+                return "blocked IP range"
+        # Loopback — only when block_localhost is set.
+        if policy.block_localhost:
+            for net in _LOOPBACK_IPV6_NETWORKS:
+                if addr in net:
+                    return "loopback IP range"
+        if policy.block_private_ips:
+            for net in _PRIVATE_IPV6_NETWORKS:
+                if addr in net:
+                    return "private IP range"
+        for net in policy.additional_blocked_cidrs:
+            if isinstance(net, ipaddress.IPv6Network) and addr in net:
+                return "blocked CIDR"
+
+    # Cloud metadata IP check
+    if policy.block_cloud_metadata and str(addr) in _CLOUD_METADATA_IPS:
+        return "cloud metadata endpoint"
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Public validation functions
+# ---------------------------------------------------------------------------
+
+
+def validate_resolved_ip(ip_str: str, policy: SSRFPolicy) -> None:
+    """Validate a resolved IP address against the SSRF policy.
+
+    Raises SSRFBlockedError if the IP is blocked.
+    """
+    try:
+        addr = ipaddress.ip_address(ip_str)
+    except ValueError as exc:
+        raise SSRFBlockedError("invalid IP address") from exc
+
+    if isinstance(addr, ipaddress.IPv6Address):
+        # Check the original IPv6 address first — this catches addresses
+        # in blocked IPv6 networks (e.g. NAT64 discovery prefix 64:ff9b:1::/48)
+        # before we attempt IPv4 extraction.
+        reason = _ip_in_blocked_networks(addr, policy)
+        if reason is not None:
+            raise SSRFBlockedError(reason)
+        inner = _extract_embedded_ipv4(addr)
+        if inner is not None:
+            addr = inner
+
+    reason = _ip_in_blocked_networks(addr, policy)
+    if reason is not None:
+        raise SSRFBlockedError(reason)
+
+
+def validate_hostname(hostname: str, policy: SSRFPolicy) -> None:
+    """Validate a hostname against the SSRF policy.
+
+    Raises SSRFBlockedError if the hostname is blocked.
+    """
+    lower = hostname.lower()
+
+    if policy.block_localhost and lower in _LOCALHOST_NAMES:
+        raise SSRFBlockedError("localhost address")
+
+    if policy.block_cloud_metadata and lower in _CLOUD_METADATA_HOSTNAMES:
+        raise SSRFBlockedError("cloud metadata endpoint")
+
+    if policy.block_k8s_internal and lower.endswith(_K8S_SUFFIX):
+        raise SSRFBlockedError("Kubernetes internal DNS")
+
+
+def _effective_allowed_hosts(policy: SSRFPolicy) -> frozenset[str]:
+    """Return the policy's allowed_hosts set."""
+    return policy.allowed_hosts
+
+
+async def validate_url(url: str, policy: SSRFPolicy = SSRFPolicy()) -> None:
+    """Validate a URL against the SSRF policy, including DNS resolution.
+
+    This is the primary entry-point for async code paths. It delegates
+    scheme/hostname/allowed-hosts checks to ``validate_url_sync``, then
+    resolves DNS and validates every resolved IP.
+
+    Raises SSRFBlockedError on any violation.
+    """
+    parsed = urllib.parse.urlparse(url)
+    hostname = parsed.hostname or ""
+
+    # Reuse synchronous checks (scheme, hostname, allowed-hosts bypass).
+    try:
+        validate_url_sync(url, policy)
+    except SSRFBlockedError as exc:
+        logger.warning(
+            "ssrf_blocked",
+            hostname=hostname,
+            reason=str(exc),
+            validation_type="write_time",
+        )
+        raise
+
+    # If the host is in the allowed list, validate_url_sync returned
+    # successfully and no DNS/IP checks are needed.
+    allowed = {h.lower() for h in _effective_allowed_hosts(policy)}
+    if hostname.lower() in allowed:
+        return
+
+    # If localhost is allowed and hostname is a localhost name, skip DNS/IP
+    # checks — the resolved IP (e.g. link-local in Docker) is irrelevant
+    # since we've explicitly permitted localhost access.
+    if not policy.block_localhost and hostname.lower() in _LOCALHOST_NAMES:
+        return
+
+    # DNS resolution
+    scheme = (parsed.scheme or "").lower()
+    port = parsed.port or (443 if scheme == "https" else 80)
+    try:
+        addrinfo = await asyncio.to_thread(
+            socket.getaddrinfo, hostname, port, type=socket.SOCK_STREAM
+        )
+    except socket.gaierror as exc:
+        logger.warning(
+            "ssrf_blocked",
+            hostname=hostname,
+            reason="DNS resolution failed",
+            validation_type="write_time",
+        )
+        raise SSRFBlockedError("DNS resolution failed") from exc
+
+    # Validate every resolved IP
+    for _family, _type, _proto, _canonname, sockaddr in addrinfo:
+        ip_str = sockaddr[0]
+        try:
+            validate_resolved_ip(ip_str, policy)
+        except SSRFBlockedError as exc:
+            logger.warning(
+                "ssrf_blocked",
+                hostname=hostname,
+                reason=str(exc),
+                validation_type="write_time",
+            )
+            raise
+
+
+def validate_url_sync(url: str, policy: SSRFPolicy = SSRFPolicy()) -> None:
+    """Synchronous URL validation (no DNS resolution).
+
+    Suitable for Pydantic validators and other sync contexts. Checks scheme
+    and hostname patterns only — use validate_url for full DNS-aware checking.
+
+    Raises SSRFBlockedError on any violation.
+    """
+    parsed = urllib.parse.urlparse(url)
+
+    # Scheme check
+    scheme = (parsed.scheme or "").lower()
+    if scheme not in policy.allowed_schemes:
+        raise SSRFBlockedError(f"scheme '{scheme}' not allowed")
+
+    # Hostname check
+    hostname = parsed.hostname
+    if not hostname:
+        raise SSRFBlockedError("missing hostname")
+
+    # Allowed-hosts bypass
+    allowed = _effective_allowed_hosts(policy)
+    if hostname.lower() in {h.lower() for h in allowed}:
+        return
+
+    # Hostname pattern checks
+    validate_hostname(hostname, policy)