aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/net.py
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--webmentions_ssg/net.py47
1 files changed, 41 insertions, 6 deletions
diff --git a/webmentions_ssg/net.py b/webmentions_ssg/net.py
index c9c2bec..262434a 100644
--- a/webmentions_ssg/net.py
+++ b/webmentions_ssg/net.py
@@ -179,7 +179,13 @@ class PublicHTTPTransport(httpx.HTTPTransport):
def build_client(user_agent: str, *, accept: str | None = None) -> httpx.Client:
- """Return the hardened HTTP client shared by receiver and sender."""
+ """Return the hardened HTTP client shared by receiver and sender.
+
+ :param user_agent: User-Agent header sent with each request.
+ :param accept: Optional Accept header for the client.
+ :returns: HTTP client configured with public-only transport, deadlines, and bounded
+ redirects.
+ """
headers = {"User-Agent": user_agent}
if accept is not None:
headers["Accept"] = accept
@@ -199,6 +205,9 @@ def is_public_address(address: ipaddress.IPv4Address | ipaddress.IPv6Address) ->
``is_global`` alone does not reliably exclude IPv6 transition addresses
across Python versions or networks with NAT64/6to4 routing.
+
+ :param address: IPv4 or IPv6 address to classify.
+ :returns: ``True`` if the address is globally routable and safe to connect to.
"""
if isinstance(address, ipaddress.IPv6Address):
# The well-known NAT64 prefix can translate an otherwise global IPv6
@@ -237,6 +246,12 @@ def public_addresses(
entirety. IP literals are handled without DNS, including IPv6 literals.
The returned strings must be used for the actual TCP connection; checking
them and then connecting to ``hostname`` reintroduces DNS rebinding.
+
+ :param hostname: Hostname or IP literal to validate.
+ :param lifetime: Optional maximum time allotted for DNS resolution, in seconds.
+ :returns: Checked numeric IP addresses to use for the TCP connection.
+ :raises AddressResolutionError: If DNS resolution fails or returns no addresses.
+ :raises UnsafeAddressError: If any resolved address is not publicly routable.
"""
try:
addresses = (ipaddress.ip_address(hostname),)
@@ -253,7 +268,11 @@ def public_addresses(
def hostname_of(url: str) -> str | None:
- """Return a normalized URL hostname, or None for malformed URLs."""
+ """Return a normalized URL hostname, or None for malformed URLs.
+
+ :param url: URL from which to extract a hostname.
+ :returns: Normalized hostname, or ``None`` when the URL is invalid or has no host.
+ """
try:
hostname = urlsplit(url).hostname
except TypeError, ValueError:
@@ -262,7 +281,11 @@ def hostname_of(url: str) -> str | None:
def content_type_of(headers: Mapping[str, str]) -> str:
- """Return a normalized media type without Content-Type parameters."""
+ """Return a normalized media type without Content-Type parameters.
+
+ :param headers: HTTP response headers to inspect.
+ :returns: Lowercase media type without parameters, or an empty string if absent.
+ """
return headers.get("Content-Type", "").partition(";")[0].strip().lower()
@@ -270,7 +293,7 @@ def is_http_url(url: str) -> bool:
"""Check whether a URL is an absolute HTTP or HTTPS URL.
:param url: URL to validate.
- :return: Whether the URL uses HTTP or HTTPS and contains a hostname.
+ :returns: Whether the URL uses HTTP or HTTPS and contains a hostname.
"""
try:
parsed = urlsplit(url)
@@ -281,7 +304,15 @@ def is_http_url(url: str) -> bool:
def read_limited_body(response: httpx.Response, max_bytes: int, *, label: str) -> bytes:
- """Read a streaming response, rejecting oversized declared or actual bodies."""
+ """Read a streaming response, rejecting oversized declared or actual bodies.
+
+ :param response: Streaming HTTP response to consume.
+ :param max_bytes: Maximum permitted response body size in bytes.
+ :param label: Description of the response for size-limit errors.
+ :returns: Response body if it fits within the configured byte limit.
+ :raises ResponseTooLargeError: If declared or streamed content exceeds the byte
+ limit.
+ """
if (content_length := response.headers.get("Content-Length")) is not None:
try:
declared_length = int(content_length)
@@ -300,7 +331,11 @@ def read_limited_body(response: httpx.Response, max_bytes: int, *, label: str) -
def is_temporary_status(status: int) -> bool:
- """Return whether an HTTP status is normally retryable."""
+ """Return whether an HTTP status is normally retryable.
+
+ :param status: HTTP response status code to classify.
+ :returns: ``True`` if the HTTP status indicates a retryable failure.
+ """
return (
status
in {