spanlight 0.2.0__tar.gz → 0.3.0__tar.gz

{spanlight-0.2.0 → spanlight-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spanlight
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python SDK for Spanlight, open-source observability for LLM applications.
 Author: Dheeraj
 License-Expression: MIT
@@ -167,9 +167,11 @@ event, `client_disconnected` when your code closed it early, and
   annotations, which are not a count of searches. No count is recorded and the
   span gets `usage.fee_unknown = "openai_chat_web_search"`, so the search fee
   shows as unknown rather than zero.
-- Requests that set `inference_geo` (other than `global`) or `speed: "fast"`
-  are priced at the standard rate and tagged with
-  `usage.pricing_modifier_unknown`, because those modifiers are not modelled.
+- Anthropic data residency and fast mode are priced from the answer's
+  `usage.inference_geo` and `usage.speed` (1.1 times and 2 times the standard
+  rate). When the answer lacks them, the requested option is tagged
+  `usage.pricing_modifier_unknown` and priced at the standard rate, as is an
+  OpenAI call through a regional host (`regional_endpoint`).
 
 ### Batch output
 
@@ -447,6 +449,13 @@ options. Use `tracer.observe`, `tracer.span` and
 | `shutdown_timeout` |                         | `5.0`                   | Time budget for the flush at interpreter exit                            |
 | `prompt_cache_ttl` |                         | `60.0`                  | Seconds a fetched prompt is served before it is revalidated              |
 
+`host` must use `https://`. Plain `http://` works only for local and private-network hosts:
+`localhost` and names ending in `.localhost`, `.local` or `.internal`, single-label names such
+as a Compose service (`http://api:8000`), and loopback, private and link-local IP addresses.
+With any other plain-http host the SDK logs a warning and stays disabled rather than send the
+key in clear text. A service name with an underscore (`my_api`) is not a valid host name and is
+refused too: rename it with a hyphen or use `https://`.
+
 ### `@observe(name=None, kind="chain", capture_input=True, capture_output=True)`
 
 Traces each call of a function. It supports plain functions, `async def`,
@@ -505,8 +514,63 @@ Trace ids are 32 lowercase hex characters and span ids are 16, both
 W3C Trace Context compatible. `spanlight.get_current_trace_id()` returns the
 current trace id so you can put it in your logs.
 
+### `inject(carrier=None) -> dict` and `continue_trace(carrier)`
+
+These carry a trace from one process to another as a W3C `traceparent`, so an MCP server, an
+agent you call over HTTP or a queue worker records its spans as children of the caller's span.
+
+`inject` returns a copy of `carrier` with `traceparent` set to the current span. A
+`traceparent` already in the carrier is kept, and outside a span the copy is returned
+unchanged. `continue_trace` is a `with` and `async with` block: spans opened inside it become
+children of the span the `traceparent` names. A missing or invalid `traceparent` is ignored and
+the next span starts a new trace. The W3C sampled flag is not honoured (every span is recorded),
+and `tracestate` and `baggage` are not used.
+
+MCP carries trace context in `params._meta` under the key `traceparent`
+([SEP-414](https://modelcontextprotocol.io/seps/414-request-meta)):
+
+```python
+# Client: before sending a request
+params["_meta"] = spanlight.inject(params.get("_meta"))
+
+# Server: while handling it
+with spanlight.continue_trace(request.params.meta):
+    result = run_tool(request.params.arguments)
+```
+
+HTTP headers work the same way:
+
+```python
+# Client
+with spanlight.span("ask-billing-agent"):
+    response = httpx.post(url, json=body, headers=spanlight.inject())
+
+# Server (any headers object with .get, such as Starlette's or Flask's)
+with spanlight.continue_trace(request.headers), spanlight.span("answer"):
+    ...
+```
+
+Spans the server records carry no trace name, environment or release, so they never overwrite the
+caller's. The remote parent is a placeholder that is never sent: inside the block
+`get_current_span()` returns it, and setters called on it are lost, so open a span of your own
+first.
+
+Only continue traces from callers you trust. The caller chooses the trace id, so it can attach
+your spans to another trace of the same project. Your spans still land in the project of your
+own API key.
+
 ## Delivery guarantees
 
+Delivery is confirmed only by a JSON acknowledgment whose nonnegative integer `accepted`
+count plus its `rejected` entries equals the batch size. Rejection indexes must be unique
+integers within the batch. Empty, malformed or inconsistent success responses are ambiguous:
+the SDK retries the same IDs within its configured retry budget, then counts unconfirmed
+entries as failed. A write may already have committed; server idempotence prevents duplicate
+stored records when those IDs are retried. A valid `Retry-After` is a minimum delay, even above
+the client exponential backoff cap. Integer delays beyond exact numeric representation remain
+pending until shutdown rather than retrying early. Shutdown interrupts pending retry waits.
+
+
 Spans are sent by a background daemon thread. A batch goes out when it reaches
 `batch_size` spans or after `flush_interval` seconds. Failed requests are
 retried with jittered exponential backoff on network errors, `429` and `5xx`,

{spanlight-0.2.0 → spanlight-0.3.0}/README.md

@@ -140,9 +140,11 @@ event, `client_disconnected` when your code closed it early, and
   annotations, which are not a count of searches. No count is recorded and the
   span gets `usage.fee_unknown = "openai_chat_web_search"`, so the search fee
   shows as unknown rather than zero.
-- Requests that set `inference_geo` (other than `global`) or `speed: "fast"`
-  are priced at the standard rate and tagged with
-  `usage.pricing_modifier_unknown`, because those modifiers are not modelled.
+- Anthropic data residency and fast mode are priced from the answer's
+  `usage.inference_geo` and `usage.speed` (1.1 times and 2 times the standard
+  rate). When the answer lacks them, the requested option is tagged
+  `usage.pricing_modifier_unknown` and priced at the standard rate, as is an
+  OpenAI call through a regional host (`regional_endpoint`).
 
 ### Batch output
 
@@ -420,6 +422,13 @@ options. Use `tracer.observe`, `tracer.span` and
 | `shutdown_timeout` |                         | `5.0`                   | Time budget for the flush at interpreter exit                            |
 | `prompt_cache_ttl` |                         | `60.0`                  | Seconds a fetched prompt is served before it is revalidated              |
 
+`host` must use `https://`. Plain `http://` works only for local and private-network hosts:
+`localhost` and names ending in `.localhost`, `.local` or `.internal`, single-label names such
+as a Compose service (`http://api:8000`), and loopback, private and link-local IP addresses.
+With any other plain-http host the SDK logs a warning and stays disabled rather than send the
+key in clear text. A service name with an underscore (`my_api`) is not a valid host name and is
+refused too: rename it with a hyphen or use `https://`.
+
 ### `@observe(name=None, kind="chain", capture_input=True, capture_output=True)`
 
 Traces each call of a function. It supports plain functions, `async def`,
@@ -478,8 +487,63 @@ Trace ids are 32 lowercase hex characters and span ids are 16, both
 W3C Trace Context compatible. `spanlight.get_current_trace_id()` returns the
 current trace id so you can put it in your logs.
 
+### `inject(carrier=None) -> dict` and `continue_trace(carrier)`
+
+These carry a trace from one process to another as a W3C `traceparent`, so an MCP server, an
+agent you call over HTTP or a queue worker records its spans as children of the caller's span.
+
+`inject` returns a copy of `carrier` with `traceparent` set to the current span. A
+`traceparent` already in the carrier is kept, and outside a span the copy is returned
+unchanged. `continue_trace` is a `with` and `async with` block: spans opened inside it become
+children of the span the `traceparent` names. A missing or invalid `traceparent` is ignored and
+the next span starts a new trace. The W3C sampled flag is not honoured (every span is recorded),
+and `tracestate` and `baggage` are not used.
+
+MCP carries trace context in `params._meta` under the key `traceparent`
+([SEP-414](https://modelcontextprotocol.io/seps/414-request-meta)):
+
+```python
+# Client: before sending a request
+params["_meta"] = spanlight.inject(params.get("_meta"))
+
+# Server: while handling it
+with spanlight.continue_trace(request.params.meta):
+    result = run_tool(request.params.arguments)
+```
+
+HTTP headers work the same way:
+
+```python
+# Client
+with spanlight.span("ask-billing-agent"):
+    response = httpx.post(url, json=body, headers=spanlight.inject())
+
+# Server (any headers object with .get, such as Starlette's or Flask's)
+with spanlight.continue_trace(request.headers), spanlight.span("answer"):
+    ...
+```
+
+Spans the server records carry no trace name, environment or release, so they never overwrite the
+caller's. The remote parent is a placeholder that is never sent: inside the block
+`get_current_span()` returns it, and setters called on it are lost, so open a span of your own
+first.
+
+Only continue traces from callers you trust. The caller chooses the trace id, so it can attach
+your spans to another trace of the same project. Your spans still land in the project of your
+own API key.
+
 ## Delivery guarantees
 
+Delivery is confirmed only by a JSON acknowledgment whose nonnegative integer `accepted`
+count plus its `rejected` entries equals the batch size. Rejection indexes must be unique
+integers within the batch. Empty, malformed or inconsistent success responses are ambiguous:
+the SDK retries the same IDs within its configured retry budget, then counts unconfirmed
+entries as failed. A write may already have committed; server idempotence prevents duplicate
+stored records when those IDs are retried. A valid `Retry-After` is a minimum delay, even above
+the client exponential backoff cap. Integer delays beyond exact numeric representation remain
+pending until shutdown rather than retrying early. Shutdown interrupts pending retry waits.
+
+
 Spans are sent by a background daemon thread. A batch goes out when it reaches
 `batch_size` spans or after `flush_interval` seconds. Failed requests are
 retried with jittered exponential backoff on network errors, `429` and `5xx`,

{spanlight-0.2.0 → spanlight-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spanlight"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python SDK for Spanlight, open-source observability for LLM applications."
 readme = "README.md"
 license = "MIT"

{spanlight-0.2.0 → spanlight-0.3.0}/src/spanlight/__init__.py

@@ -22,6 +22,7 @@ from ._context import get_current_span, get_current_trace_id
 from ._globals import flush, get_client, init, observe, prompts, score, shutdown, span
 from ._prompt_client import PromptClient
 from ._prompts import CompiledPrompt, Prompt, PromptUnavailableError, no_prompt
+from ._propagation import continue_trace, inject
 from ._span import Span, SpanKind, SpanStatus
 from ._templates import InvalidTemplateError, MissingVariablesError, TemplateTooLargeError
 from ._version import __version__
@@ -43,11 +44,13 @@ __all__ = [
     "Spanlight",
     "TemplateTooLargeError",
     "__version__",
+    "continue_trace",
     "flush",
     "get_client",
     "get_current_span",
     "get_current_trace_id",
     "init",
+    "inject",
     "no_prompt",
     "observe",
     "prompts",

{spanlight-0.2.0 → spanlight-0.3.0}/src/spanlight/_client.py

@@ -19,6 +19,7 @@ from ._context import (
     set_current_span,
 )
 from ._exporter import BatchExporter
+from ._hosts import is_safe_host
 from ._prompt_client import PromptClient
 from ._scores import ScoreValue, build_score
 from ._span import Span, SpanKind, normalize_kind
@@ -104,9 +105,11 @@ class Spanlight:
             prompt_cache_ttl=prompt_cache_ttl,
         )
         self._exporter: BatchExporter | None = None
+        # The key is a bearer credential: never send it in clear text to another machine.
+        safe_host = is_safe_host(self.config.host)
         self.prompts: PromptClient = PromptClient(
             base_url=self.config.prompts_url,
-            api_key=self.config.api_key,
+            api_key=self.config.api_key if safe_host else None,
             timeout=self.config.timeout,
             cache_ttl=self.config.prompt_cache_ttl,
             transport=transport,
@@ -118,6 +121,12 @@ class Spanlight:
                 "Spanlight: no API key configured (set SPANLIGHT_API_KEY or pass "
                 "api_key=...); tracing is disabled."
             )
+        elif self.config.enabled and not safe_host:
+            logger.warning(
+                "Spanlight: the host must be an https:// URL (plain http:// is allowed only for "
+                "local and private-network hosts); the API key is not sent, so tracing and "
+                "prompt fetching are disabled."
+            )
         elif self.config.enabled and self.config.api_key:
             self._exporter = BatchExporter(
                 url=self.config.ingest_url,

{spanlight-0.2.0 → spanlight-0.3.0}/src/spanlight/_config.py

@@ -8,7 +8,7 @@ a ``SPANLIGHT_*`` environment variable and then to a default.
 from __future__ import annotations
 
 import os
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 DEFAULT_HOST = "http://localhost:8000"
 INGEST_PATH = "/v1/traces"
@@ -39,7 +39,7 @@ class SpanlightConfig:
         prompt_cache_ttl: Seconds a fetched prompt is served before it is revalidated.
     """
 
-    api_key: str | None
+    api_key: str | None = field(repr=False)
     host: str
     environment: str | None
     release: str | None

{spanlight-0.2.0 → spanlight-0.3.0}/src/spanlight/_decorator.py

@@ -16,6 +16,7 @@ SDK itself are swallowed so they cannot break the decorated function.
 
 from __future__ import annotations
 
+import asyncio
 import functools
 import inspect
 import logging
@@ -252,6 +253,10 @@ async def _traced_async_generator(
     """Async counterpart of :func:`_traced_generator`."""
     collected = _OutputCollector(enabled=options.capture_output)
     step: Callable[[], Any] = functools.partial(generator.asend, None)
+    # A cancellation thrown in at a `yield` means the consumer abandoned the generator: asyncio
+    # closes one left behind by `async for ... break` that way at loop shutdown. Like a `break`
+    # over a sync generator, that ends the span as ok, not failed.
+    abandoned: BaseException | None = None
     while True:
         previous = get_current_span()
         token = set_current_span(span)
@@ -266,7 +271,15 @@ async def _traced_async_generator(
             )
             return
         except BaseException as exc:
-            _finish(span, error=exc)
+            if exc is abandoned:
+                _finish(
+                    span,
+                    output=collected.result(None),
+                    capture_output=options.capture_output,
+                    output_cut=collected.truncated,
+                )
+            else:
+                _finish(span, error=exc)
             raise
         finally:
             restore_current_span(token, previous)
@@ -286,6 +299,7 @@ async def _traced_async_generator(
                 )
             raise
         except BaseException as exc:
+            abandoned = exc if isinstance(exc, asyncio.CancelledError) else None
             step = functools.partial(generator.athrow, exc)
         else:
             step = functools.partial(generator.asend, sent)

{spanlight-0.2.0 → spanlight-0.3.0}/src/spanlight/_experiments_api.py

@@ -10,18 +10,18 @@ from __future__ import annotations
 from collections.abc import Iterator
 from dataclasses import dataclass
 from typing import Any
-from urllib.parse import quote, urlsplit
+from urllib.parse import quote
 
 import httpx
 
 from ._experiments_parse import PromptRef
+from ._hosts import is_safe_host
 from ._version import __version__
 
 _PAGE_SIZE = 200
 # A guard against a server that keeps returning cursors: 50 pages of 200 is 10 000 rows.
 _MAX_PAGES = 50
 _ESCAPE = "~"
-_LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
 
 
 class ExperimentError(Exception):
@@ -39,15 +39,12 @@ class ResolvedPrompt:
 
 def _require_safe_host(host: str) -> None:
     """Refuse to send the access token over plain http, except to the local machine."""
-    parts = urlsplit(host)
-    if parts.scheme == "https" and parts.hostname:
-        return
-    if parts.scheme == "http" and parts.hostname in _LOCAL_HOSTS:
-        return
-    raise ExperimentError(
-        "the host must be an https:// URL (http:// is allowed only for localhost); "
-        "the access token is never sent in clear text"
-    )
+    if not is_safe_host(host):
+        raise ExperimentError(
+            "the host must be an https:// URL (http:// is allowed only for local and "
+            "private-network hosts); "
+            "the access token is never sent in clear text"
+        )
 
 
 def wire_name(name: str) -> str:

{spanlight-0.2.0 → spanlight-0.3.0}/src/spanlight/_exporter.py

@@ -63,7 +63,8 @@ class BatchExporter:
         jitter: Function returning a float in ``[0, 1)`` used to randomize
             backoff delays.
         base_backoff: Backoff before the first retry, in seconds.
-        max_backoff: Upper bound for any single wait, in seconds.
+        max_backoff: Upper bound for client exponential backoff, in seconds.
+            A valid server ``Retry-After`` minimum may exceed this bound.
     """
 
     def __init__(
@@ -189,6 +190,8 @@ class BatchExporter:
             ``True`` if the queue drained in time, ``False`` otherwise.
         """
         try:
+            # A forked child must not wait on the parent's in-flight batch.
+            self._check_fork()
             self._ensure_worker()
             deadline = None if timeout is None else time.monotonic() + timeout
             with self._condition:

{spanlight-0.2.0 → spanlight-0.3.0}/src/spanlight/_exporter_delivery.py

@@ -135,35 +135,41 @@ class Delivery:
     def _send_batch(
         self, target: _Target, batch: list[SpanPayload], client: Mapping[str, Any] | None
     ) -> None:
+        batch, encoded = self._encode_each(target, batch)
         if not batch:
             return
-        envelope: dict[str, Any] = {target.body_key: batch}
+        fields = [f'"{target.body_key}":[{",".join(encoded)}]']
         if client is not None and target.body_key == SPANS:
-            envelope["client"] = dict(client)
-        body = json.dumps(envelope, separators=(",", ":"), default=str).encode()
+            fields.append('"client":' + json.dumps(dict(client), separators=(",", ":")))
+        body = ("{" + ",".join(fields) + "}").encode()
         if self._gzip:
             body = gzip.compress(body)
 
         for attempt in range(self._max_retries + 1):
+            if self._abort_retries.is_set():
+                self.failed += len(batch)
+                return
             retry_after: float | None = None
             try:
                 response = self._http_client().post(target.url, content=body, headers=self._headers)
             except httpx.HTTPError as exc:
-                failure = f"{type(exc).__name__}: {exc}"
+                failure = type(exc).__name__
             else:
                 status = response.status_code
                 if 200 <= status < 300:
-                    self._handle_success(target, response, batch)
-                    return
-                if status == 413 and len(batch) > 1:
+                    if self._handle_success(target, response, batch):
+                        return
+                    failure = "ambiguous acknowledgment"
+                elif status == 413 and len(batch) > 1:
                     self._split_and_send(target, batch, client)
                     return
-                if not _is_retryable(status):
+                elif not _is_retryable(status):
                     self.failed += len(batch)
                     self._log_rejected_batch(target, response, len(batch))
                     return
-                failure = f"HTTP {status}"
-                retry_after = parse_retry_after(response.headers.get("Retry-After"))
+                else:
+                    failure = f"HTTP {status}"
+                    retry_after = parse_retry_after(response.headers.get("Retry-After"))
 
             if attempt >= self._max_retries or self._abort_retries.is_set():
                 self.failed += len(batch)
@@ -179,6 +185,27 @@ class Delivery:
             logger.debug("Export failed (%s); retrying in %.2fs", failure, delay)
             self._sleep(delay)
 
+    def _encode_each(
+        self, target: _Target, batch: list[SpanPayload]
+    ) -> tuple[list[SpanPayload], list[str]]:
+        """JSON-encode each item on its own, so one that cannot be encoded loses only itself."""
+        kept: list[SpanPayload] = []
+        encoded: list[str] = []
+        for item in batch:
+            try:
+                encoded.append(json.dumps(item, separators=(",", ":"), default=str))
+            except Exception as exc:
+                self.failed += 1
+                logger.warning(
+                    "Dropping %s %s: it cannot be encoded as JSON (%s)",
+                    target.body_key[:-1],
+                    item.get(target.id_field),
+                    type(exc).__name__,
+                )
+            else:
+                kept.append(item)
+        return kept, encoded
+
     def _split_and_send(
         self, target: _Target, batch: list[SpanPayload], client: Mapping[str, Any] | None
     ) -> None:
@@ -206,20 +233,35 @@ class Delivery:
 
     def _handle_success(
         self, target: _Target, response: httpx.Response, batch: list[SpanPayload]
-    ) -> None:
+    ) -> bool:
         batch_size = len(batch)
         try:
             result: Any = response.json()
         except ValueError:
-            self.sent += batch_size
-            return
-        rejected = result.get("rejected") if isinstance(result, dict) else None
-        if not isinstance(rejected, list) or not rejected:
-            self.sent += batch_size
-            return
-
-        self.sent += batch_size - len(rejected)
+            return False
+        if not isinstance(result, dict):
+            return False
+        accepted, rejected = result.get("accepted"), result.get("rejected")
+        if (
+            type(accepted) is not int
+            or accepted < 0
+            or not isinstance(rejected, list)
+            or accepted + len(rejected) != batch_size
+        ):
+            return False
+        indexes: set[int] = set()
+        for item in rejected:
+            if not isinstance(item, dict):
+                return False
+            index = item.get("index")
+            if type(index) is not int or not 0 <= index < batch_size or index in indexes:
+                return False
+            indexes.add(index)
+
+        self.sent += accepted
         self.failed += len(rejected)
+        if not rejected:
+            return True
         logger.warning(
             "Spanlight rejected %d of %d %s",
             len(rejected),
@@ -238,21 +280,26 @@ class Delivery:
                     item.get("reason"),
                 )
 
+        return True
+
     def retry_delay(self, attempt: int, retry_after: float | None) -> float:
         """Return seconds to wait before retry number ``attempt + 1``.
 
-        ``Retry-After`` wins when present. Otherwise use "equal jitter"
+        ``Retry-After`` sets a minimum when present. Use "equal jitter"
         exponential backoff: half of the exponential step is fixed and the
         other half random, which spreads retries out without ever retrying
         immediately.
         """
-        if retry_after is not None:
-            return min(max(retry_after, 0.0), self._max_backoff)
-        step = min(self._max_backoff, self._base_backoff * (2.0**attempt))
-        return step / 2 + self._jitter() * step / 2
+        step = min(self._max_backoff, self._base_backoff * (2.0 ** min(attempt, 1023)))
+        return max(retry_after or 0.0, step / 2 + self._jitter() * step / 2)
 
     def _interruptible_sleep(self, seconds: float) -> None:
-        self._abort_retries.wait(seconds)
+        # Event.wait overflows on very large valid server delays; wait in bounded chunks.
+        while seconds > 0 and not self._abort_retries.is_set():
+            started = time.monotonic()
+            if self._abort_retries.wait(min(seconds, threading.TIMEOUT_MAX)):
+                return
+            seconds -= time.monotonic() - started
 
 
 def _is_retryable(status: int) -> bool:
@@ -264,6 +311,10 @@ def parse_retry_after(value: str | None) -> float | None:
     if value is None:
         return None
     value = value.strip()
+    if value.isascii() and value.isdecimal():
+        seconds = float(value)
+        # Beyond exact integer representation, keep the minimum indefinite until shutdown.
+        return seconds if seconds <= 2**53 else math.inf
     try:
         seconds = float(value)
     except ValueError:
@@ -275,7 +326,11 @@ def parse_retry_after(value: str | None) -> float | None:
         moment = email.utils.parsedate_to_datetime(value)
     except (TypeError, ValueError):
         return None
-    return max(moment.timestamp() - time.time(), 0.0)
+    try:
+        seconds = moment.timestamp() - time.time()
+    except (OverflowError, OSError, ValueError):
+        return None
+    return max(seconds, 0.0) if math.isfinite(seconds) else None
 
 
 def _short_body(response: httpx.Response) -> str:

spanlight-0.3.0/src/spanlight/_hosts.py

@@ -0,0 +1,61 @@
+"""Which hosts the SDK may send a credential to.
+
+Any https:// host is fine. Plain http:// is allowed only for a host that cannot be on the public
+internet: loopback, private and link-local addresses, and local-only names. The TypeScript SDK
+applies the same rule (``sdks/typescript/src/client.ts``).
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import socket
+from urllib.parse import urlsplit
+
+# Explicit lists rather than ``is_private``, which is broader and would make the SDKs disagree.
+_LOCAL_NETWORKS = tuple(
+    ipaddress.ip_network(network)
+    for network in (
+        "127.0.0.0/8",
+        "10.0.0.0/8",
+        "172.16.0.0/12",
+        "192.168.0.0/16",
+        "169.254.0.0/16",
+        "::1/128",
+        "fc00::/7",
+        "fe80::/10",
+    )
+)
+_LOCAL_SUFFIXES = (".localhost", ".local", ".internal")
+_SINGLE_LABEL = re.compile(r"[a-z0-9-]+")
+
+
+def is_safe_host(host: str) -> bool:
+    """True for an https:// URL, or plain http:// to a local or private-network host."""
+    try:
+        parts = urlsplit(host)
+        hostname = parts.hostname
+    except ValueError:  # e.g. an unclosed "[::1"; fail closed instead of raising into the app
+        return False
+    if not hostname:
+        return False
+    if parts.scheme == "https":
+        return True
+    return parts.scheme == "http" and _is_local(hostname)
+
+
+def _is_local(hostname: str) -> bool:
+    name = hostname.removesuffix(".")
+    if name == "localhost" or name.endswith(_LOCAL_SUFFIXES):
+        return True
+    try:
+        address: ipaddress.IPv4Address | ipaddress.IPv6Address = ipaddress.ip_address(name)
+    except ValueError:
+        if "." in name or not _SINGLE_LABEL.fullmatch(name):
+            return False
+        try:
+            # The resolver reads a dotless number ("134744072", "0x8080808") as an IPv4 address.
+            address = ipaddress.IPv4Address(socket.inet_aton(name))
+        except OSError:
+            return True  # a single-label name such as a Compose service ("api")
+    return any(address in network for network in _LOCAL_NETWORKS)