Cookies, proxy and certificates

This page shows how HTTP requests reach the network and how responses come back. The rules apply to HTTP requests. gRPC and WebSocket reuse parts of the TLS policy and say so on their own pages.

Cookies

Postguy keeps one cookie jar per workspace. It follows RFC 6265.

Turning the jar off

• Globally: Settings › General › Disable cookies ("Do not send or store cookies for any request").
• Per request: the request's Settings tab, Disable cookie jar.

Either switch stops sending and storing for that request. Your own Cookie header is then sent untouched.

The Cookies manager

Open it from the bottom bar or with the command Open cookies. It has:

• A list of every jar cookie with domain, name, value, path and flags (S Secure, H HttpOnly, T has an expiry).
• Search, a delete button on each row, and Clear all.
• A Script domain allowlist (an Allow field and a list with remove buttons). The allowlist is stored in the jar file.

Known limits

• There is no public-suffix list. A Domain attribute is refused when it equals the host itself, or when it has no dot and differs from the host.
• SameSite is stored and shown. It is not enforced beyond the RFC 6265bis defaults.
• The __Host- and __Secure- prefixes are not enforced.

Headless

• cookies_list
• cookies_set (a raw Set-Cookie value for a URL)
• cookies_delete (domain, path, name)
• cookies_clear

Redirects

Postguy follows redirects with its own loop. It records every hop (url, status, location).

Rules that apply on every hop:

• Cross-host hop (scheme, host or port changed):
  • Authorization is dropped unless Follow Authorization header on cross-host redirects is on.
  • The manual Cookie header is always dropped.
  • The body headers are always dropped: Content-Length, Content-Type, Content-Encoding, Content-Language, Transfer-Encoding.
  • The jar adds back the cookies that match the new host.
• Remove referer header on redirect removes a Referer you set.
• More than Maximum redirects hops fails with stopped after N redirects (maximum N).
• Seeing the same method and URL twice fails with redirect loop at <url> (N hops).
• The hop list is kept for the Console.
• With Automatically follow redirects off, the 3xx response is returned as is.

Per-request settings (Settings tab):

The global Automatically follow redirects in Settings is combined with the request's. Redirects are followed only if both are on.

Proxy

Settings › Proxy has two modes.

Environment proxy URLs can be http://host:port, socks5://…, socks5h://… or a bare host:port (treated as HTTP). The default port is 8080 for HTTP proxies and 1080 for SOCKS. Credentials in the URL (user:pass@host) are used for proxy Basic auth.

Custom proxy fields:

How routing works:

• HTTP proxy. Plain http:// requests use absolute-form requests. https:// requests use a CONNECT tunnel.
• HTTP/2 limit. A plain-HTTP request through an HTTP proxy cannot use HTTP/2. Forcing HTTP/2 fails with HTTP/2 cannot go through an HTTP proxy in absolute-form; choose HTTP/1.x or a SOCKS5 proxy.
• SOCKS5 resolves the target host on your machine. SOCKS5h resolves it at the proxy.
• Bypass list (and NO_PROXY): * disables proxying. An entry matches a host, host:port, .suffix, *.suffix or a glob with *.
• Only http and https URLs are proxied.
• The Console logs the effective proxy for each request.

TLS and certificates

HTTPS checks server certificates against the operating system's trust store. Settings › Certificates adds to that:

Set the certificate chain and the private key together. Setting only one fails with client certificate and key paths must both be set.

Not supported: PFX/PKCS#12 files, encrypted private keys, per-host certificates and stored passphrases. The settings screen says Encrypted keys and PFX files are not supported yet.

Turning verification off

Two switches control it:

• Settings › General › SSL certificate verification (global).
• The request's own Enable SSL certificate verification.

For HTTP, verification is off if either switch is off. When the global switch is off, its row shows the warning Verification is off: responses are encrypted but unauthenticated.

The connection is still encrypted, but the server is not authenticated. Anyone on the path can impersonate it. Add the server's CA to the custom CA bundle instead.

Other protocols

• WebSocket: uses the request's own verifySsl, the custom CA bundle and the client certificate. It does not use the global switch.
• gRPC: uses the request's TLS checkbox, the custom CA bundle and the client certificate. There is no verification-off mode.

HTTP version (global and per request: Auto, HTTP/1.x, HTTP/2) sets the protocols offered during TLS negotiation. Auto offers HTTP/2 and falls back to HTTP/1.1.

Compression

Postguy decodes responses automatically.

• Encodings: gzip, deflate (zlib, with a raw-deflate fallback), br (Brotli) and zstd.
• Chains such as Content-Encoding: br, gzip are decoded in reverse order.
• Postguy sends Accept-Encoding: gzip, deflate, br unless you set the header yourself.

Two caps protect memory:

• Decoded size: 50 MiB by default (the Max response size setting; 0 means unlimited).
• Ratio: decoded size may not exceed 200 times the encoded size plus 64 KiB of headroom.

A response that breaks a cap, such as a compression bomb, fails with an error that names the cap. A body larger than Max response size fails with response body exceeds the N-byte cap. The response viewer shows the size breakdown (headers, encoded body and decoded body).

Timeouts and cancel

• Request timeout has a global value (Settings › General) and a per-request value (Request timeout (ms, 0 = none)). 0 means no timeout. The request's value wins when it is not 0.
• Connecting has its own limit of 30 seconds for each stage (TCP connect, proxy handshake, TLS handshake).
• A timeout or a cancel names the phase it stopped in. Any partial bytes are discarded.
• Cancel a running request with Esc (command Cancel request).
• Timings shown with a response: connect (DNS, TCP and TLS combined), wait (time to first byte), download and total.

Headless

request_send sends a saved request with the workspace settings. request_cancel cancels it. cookies_* manage the jar. See Automation tools.