diff options
Diffstat (limited to '')
| -rw-r--r-- | webmentions_ssg/net.py | 47 |
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 { |
