public interface NetworkGuard

Called on the network thread immediately before the connection is opened, and again on each retry or redirect so a stale token is never reused.

May block – it is off the EDT and outside the network queue’s lock. Add headers here. Throwing fails the request through the normal error path.

Whether this URL’s certificate chain needs to be inspected, i.e. whether the host has pins.

Must be fast and purely local. On iOS this is consulted from the TLS delegate thread while the handshake is held open.

Returning true has a cost beyond the check itself: the framework asks the platform for the richer certificate details, including public-key digests, which it does not otherwise collect. Return false for hosts with no pins.

Vets the certificate chain, after the handshake and before any request body is written.

Throwing an IOException aborts the request and surfaces through the request’s normal error handling, rather than completing it with an empty response.

Must be local and non-blocking, for the same delegate-thread reason as isCertificateCheckRequired(String). In particular it must not try to fetch a fresh pin set: use the last known one and let a mismatch stand.

Response header names this guard wants captured, or null for none.

Asked once per response, while the connection is still open. The framework does not retain arbitrary response headers, and by the time afterResponse runs the connection has been closed – so anything a guard needs to see has to be named here first.

Called once the response code is known, including for failed requests.

This is how a token layer learns its token was refused – a 401 or 403 from a protected host usually means the cached token should be discarded before the next attempt. Must not throw; exceptions here are logged and swallowed so a telemetry problem cannot fail a request that otherwise succeeded.