Skip to main content
SSRF-guarded server-side URL fetching. The SSRF guard (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
A guarded request that reached no usable answer: a transport failure or a body over the cap.

GuardedRequestTimeoutError

tai42_kit.net.guarded_request.GuardedRequestTimeoutError
A guarded request that did not complete within its total deadline.

GuardedResponse

tai42_kit.net.guarded_request.GuardedResponse
The complete answer to a guarded request: status, headers and the whole (capped) body. Attributes

MediaFetchError

tai42_kit.net.fetch_media.MediaFetchError
A vendor media fetch failed at the HTTP or transport layer. The message carries the vendor HOST plus the HTTP status code or the transport-exception class ONLY — never the request URL — so a credential riding the URL path or query never reaches an error string. 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
A vendor media response opened for streaming — the final hop’s metadata plus its body. 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
Raised when a target host is unresolvable, non-public, over the size cap, or over-redirected. Covers a host that cannot be resolved or is rejected as non-public, a response that exceeds the guard’s size cap, and a redirect chain that exceeds max_redirects.

UrlGuardSettings

tai42_kit.net.url_guard.UrlGuardSettings
Policy for the SSRF guard on server-side URL fetches. Attributes

enforce_size

tai42_kit.net.url_guard.enforce_size
Raise 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
Fetch a vendor media object bounded by 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
Fetch the URL’s body and return (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
Return whether the SSRF guard is enabled (TAI_URL_GUARD_ENABLED).

guarded_request

tai42_kit.net.guarded_request.guarded_request
Send one guarded request and return its complete answer, whatever its status. Raises 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
Whether 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
The host a media fetch of 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
Open a vendor media object for streaming, SSRF-pinned while the guard is enabled. While 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
Resolve 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
Return the process-wide UrlGuardSettings, cached after first load.