tai42_kit.net.url_guard) resolves and validates each target
host, and fetch_url is the httpx download built on it: while the guard is
enabled (the default) that download is DNS-rebinding-safe, redirect-safe, and
size-capped. guarded_request is the single guarded GET/POST/DELETE beside it
(no redirects followed, a size cap, one total deadline). The guard is reusable on its
own by any caller that fetches a caller-supplied URL server-side over its own HTTP client.
fetch_url, fetch_media and guarded_request are re-exported LAZILY (PEP 562): they pull in
httpx/httpcore, and a consumer of a lighter net utility (e.g.
tai42_kit.net.request_body) must not drag that backend into its import graph merely
by importing a sibling module. This is the same reason tai42_kit.net.jwt (which
needs joserfc) stays out of this re-export.
GuardedRequestError
tai42_kit.net.guarded_request.GuardedRequestError
GuardedRequestTimeoutError
tai42_kit.net.guarded_request.GuardedRequestTimeoutError
GuardedResponse
tai42_kit.net.guarded_request.GuardedResponse
MediaFetchError
tai42_kit.net.fetch_media.MediaFetchError
status_code is the HTTP
status when the fault was an error response (or an unfollowed redirect), else
None (a transport fault — timeout, connection error, a torn read — a
malformed response header, or a URL that cannot be parsed). transient tells the caller whether a redelivery
could plausibly succeed; it is derived from the status — a 5xx, a 408 (Request
Timeout) or a 429 (Too Many Requests, a vendor throttle) is transient, and so is a
transport fault (status None); every other 4xx/3xx is permanent — unless an
explicit value is given for a fault the status cannot classify (a malformed response
header or a URL that cannot be parsed is permanent).
Attributes
MediaStream
tai42_kit.net.fetch_media.MediaStream
content_type is the final response’s Content-Type media type with parameters
stripped and lower-cased (None when the header is absent or empty).
content_length is the parsed Content-Length (None when absent). host is
the final response’s host, for error/log text only — never the URL. chunks yields
the body as it arrives; a fault while iterating raises MediaFetchError
(transient=True, URL-free).
Attributes
UrlGuardError
tai42_kit.net.url_guard.UrlGuardError
max_redirects.
UrlGuardSettings
tai42_kit.net.url_guard.UrlGuardSettings
enforce_size
tai42_kit.net.url_guard.enforce_size
UrlGuardError when nbytes exceeds the configured cap.
A no-op when the guard is disabled. Never truncates — an over-cap response is
refused loudly.
Parameters
fetch_media
tai42_kit.net.fetch_media.fetch_media
max_bytes, SSRF-pinned while the guard is enabled.
Shares the streaming primitive _stream_media with open_media_stream and collects
its body, raising RequestBodyTooLargeError (never
truncating) the instant the running total crosses max_bytes. Redirect handling, the
cross-origin credential drop, and the URL-free faults are exactly those of
open_media_stream. Returns (bytes, media type) where the media type is the response
Content-Type with parameters stripped and lower-cased (None when absent).
Parameters
fetch_url
tai42_kit.net.fetch_url.fetch_url
(bytes, mime).
mime is the response Content-Type header (None when absent). When
the guard is enabled the request runs over PinningTransport, which
validates and pins every connection (initial request and each redirect hop
that opens a new connection), the body is size-capped while streaming, and at
most the guard’s max_redirects hops are followed. Raises rather than
truncating an over-cap body or reaching a non-public host. When the guard is
disabled the transport caps nothing and pins nothing, and the redirect bound is
httpx’s own (httpx.TooManyRedirects past it).
Redirects are followed one hop at a time on the shared client rather than by
httpx, which reads each intermediate body into memory in full before chasing
Location. A hop carrying a body large enough to exhaust memory would slip
past the cap that way, so each redirect response is closed unread — forgoing
connection reuse for that hop — and only the terminal body is streamed and
counted. The cookies a hop sets ride this fetch’s later hops only.
Parameters
guard_enabled
tai42_kit.net.url_guard.guard_enabled
TAI_URL_GUARD_ENABLED).
guarded_request
tai42_kit.net.guarded_request.guarded_request
UrlGuardError when the URL is refused (not https on
a non-loopback host, or a host the guard blocks), GuardedRequestTimeoutError when the
whole call outlasts timeout seconds, and GuardedRequestError on a transport failure
or a body over max_bytes. form is sent form-encoded, json_body as JSON; at most one.
Parameters
is_loopback_host
tai42_kit.net.url_guard.is_loopback_host
host names this machine: localhost or a loopback IP literal (127.0.0.0/8, ::1).
Parameters
media_url_host
tai42_kit.net.fetch_media.media_url_host
url contacts first, for error and log text only.
Parses url as fetch_media and open_media_stream do, so a URL this
returns a host for is never refused by them as unparsable; one that cannot be parsed raises
the same permanent, URL-free MediaFetchError.
Parameters
open_media_stream
tai42_kit.net.fetch_media.open_media_stream
guard_enabled is set the request runs over the
PinningTransport; when it is unset a plain transport
that pins nothing is used instead — the same one operator switch fetch_url honours.
When follow_redirects is set, redirects are followed hop-by-hop up to the guard’s
max_redirects (follow_redirects is never handed to httpx, so the pin re-runs per
hop while enabled); when it is not, an unfollowed redirect is a fault. headers/auth
carry the vendor credential on the call only — never returned, never logged; auth is a
Basic-auth (username, password) pair only. On a cross-origin hop, and every hop after
it, the request carries no caller-supplied header and no auth (only httpx’s defaults); a
same-origin hop keeps them.
Yields a MediaStream for the final response; the response is closed when the
context exits, including on an exception raised while iterating chunks. Faults never
carry the request URL: an SSRF rejection surfaces as
UrlGuardError (host only); an HTTP-status, transport,
or malformed-header fault as MediaFetchError (vendor host + status/class only) —
at open, or from the chunks iterator on a mid-body fault; a url that cannot be
parsed as a permanent MediaFetchError naming no host.
Parameters
resolve_and_validate
tai42_kit.net.url_guard.resolve_and_validate
host, reject non-public addresses, and return the first validated address.
The returned address is the one to connect to (the “pin”).
Resolving once and connecting to the returned address closes DNS-rebinding:
the same lookup that is validated is the one the connection uses, so an
attacker cannot answer public during the check and internal at connect time.
Raises UrlGuardError if resolution fails or any address is blocked.
Parameters
url_guard_settings
tai42_kit.net.url_guard.url_guard_settings
UrlGuardSettings, cached after first load.
