NetworkError
extends AxiamException
in package
Transport-level failure: connection refused, timeout, TLS error, DNS failure, or a server-side 5xx (CONTRACT.md §2).
Redact-before-wrap (D-10/D-11, CR-04 carry-forward): self::fromResponse() is
the ONLY construction path that accepts a live PSR-7 ResponseInterface, and it
strips the Set-Cookie/Authorization/Cookie header VALUES into a sanitized
summary string BEFORE the constructor ever runs. There is no public constructor and
no path that stores the raw $response object (or any wrapped exception that might
itself carry one) as this exception's message, cause, or any other property — this
structurally prevents the token-leak-via-error class of bug first found in the
TypeScript sibling SDK (Phase 17 CR-04, its src/core/errorMapper.ts
sanitizeAxiosError) and mirrored by every later sibling SDK's NetworkError.
Not final, so CONTRACT.md §27.4 rule 7 can classify 400/422 as
ValidationError inside this type — §2's own 400 row
already lands here, and the sub-type keeps that mapping. The redact-before-wrap
invariant above is untouched by that: the constructor a subclass can reach takes a
string and a \Throwable, never a ResponseInterface, so a subclass has no
more access to a live response than any other caller — self::fromResponse()
remains the only path from a response into this type.
Table of Contents
Properties
- $retryAfterMs : float|null
- A server-supplied `Retry-After` hint in milliseconds (CONTRACT.md §16.1), `null` when the response carried none.
Methods
- fromException() : self
- Builds a NetworkError from a caught transport exception (socket/TLS/DNS/timeout failure). The caught exception's own message is defensively regex-sanitized in case a lower-level exception echoed a sensitive header verbatim; the exception itself is never stored as a cause (see class doc).
- fromMessage() : self
- Builds a `NetworkError` from a plain message with no live response or exception to redact — e.g. a malformed/short response BODY already decoded into a plain array by the caller, with no `ResponseInterface`/headers left to sanitize.
- fromResponse() : self
- Builds a NetworkError from a live PSR-7 response. Header NAMES are preserved for debuggability; VALUES of `Set-Cookie`/`Authorization`/`Cookie` are replaced with `[SENSITIVE]` before the summary string is built. The `$response` argument itself is never stored — only the resulting sanitized string survives past this method.
Properties
$retryAfterMs
A server-supplied `Retry-After` hint in milliseconds (CONTRACT.md §16.1), `null` when the response carried none.
public
float|null
$retryAfterMs
= null
A parsed duration, never the raw header text, so the sanitization discipline this class exists to enforce is untouched: a float cannot carry a token, a URL, or anything else a header might. §16 honors it as a floor on the backoff — the server is stating when it will be ready, so retrying sooner is not permitted.
Methods
fromException()
Builds a NetworkError from a caught transport exception (socket/TLS/DNS/timeout failure). The caught exception's own message is defensively regex-sanitized in case a lower-level exception echoed a sensitive header verbatim; the exception itself is never stored as a cause (see class doc).
public
static fromException(Throwable $exception[, string $context = 'Transport error' ]) : self
Parameters
- $exception : Throwable
- $context : string = 'Transport error'
Return values
selffromMessage()
Builds a `NetworkError` from a plain message with no live response or exception to redact — e.g. a malformed/short response BODY already decoded into a plain array by the caller, with no `ResponseInterface`/headers left to sanitize.
public
static fromMessage(string $message) : self
$message still passes through self::sanitizeMessage() as defense in
depth, matching self::fromException()'s own discipline.
Parameters
- $message : string
Return values
selffromResponse()
Builds a NetworkError from a live PSR-7 response. Header NAMES are preserved for debuggability; VALUES of `Set-Cookie`/`Authorization`/`Cookie` are replaced with `[SENSITIVE]` before the summary string is built. The `$response` argument itself is never stored — only the resulting sanitized string survives past this method.
public
static fromResponse(ResponseInterface $response[, string $context = 'HTTP error' ]) : self
Parameters
- $response : ResponseInterface
- $context : string = 'HTTP error'