Cache options and troubleshooting

Cache options are a trailing sequence on the proxy password. Username options such as pool, country, city, and session stay unchanged. The suffix is the complete opt-in: Litport does not silently enable caching for a token, and a request without it remains an ordinary proxy request.

PASSWORD_cache-<types>[_cacheduration-<minutes>][_cacheignoreheader-1]

Examples:

username:password_cache-images,fonts
username_country-us_sid-crawl-42:password_cache-all_cacheduration-30
username:password_cache-scripts_cacheduration-60_cacheignoreheader-1

Litport first tries the complete password literally. This preserves an existing password that happens to end with cache-like text. Only when that exact credential does not exist does Litport parse a valid trailing cache sequence and authenticate the base password.

Options#

Extensions are png,jpg,jpeg,gif,svg,ico,webp, js,css,wasm,map, and woff,woff2,ttf,eot,otf. An empty list or unsupported value leaves the request uncached without breaking proxy authentication.

Request outcome#

• Hit: response-body bytes delivered from the hub entry are free. A client abort or cache read error remains visible as delivery status and is never moved into billable traffic.
• Miss: Litport opens the normal upstream path. Request and response bytes are billed normally. A valid complete response may be stored for another request.
• Bypass: Litport sends the request upstream without using or storing a cache entry. Traffic is billed normally.

There is no proprietary or authoritative Litport cache-hit response header. Age can appear or increase on a cached response, but origins and CDNs can set it too; use Traffic statistics or the Account API for hits, misses, bypasses, free bytes, and pay-per-GB savings. Manual purge is not available.

Eligibility and absolute exclusions#

Litport stores only HTTPS GET responses with status 200 and a path ending in a selected extension. The exact URL, including query order and encoding, identifies the object. In standard mode, s-maxage overrides max-age; the shorter valid origin freshness and requested duration wins. The requested duration is a hard maximum: when a standard-mode origin response already has a corrected Age at or above it, Litport does not store that response. With _cacheignoreheader-1, the requested TTL starts when Litport receives and stores the complete response, without subtracting origin Date or Age.

These requests always bypass, even with _cacheignoreheader-1:

• Authorization, Cookie, Range, or conditional request headers
• request Cache-Control: no-cache, no-store, or max-age=0, or Pragma: no-cache
• Set-Cookie, unsupported Vary, partial content, oversized responses, or incomplete bodies
• service workers, extensionless URLs, APIs, documents, video, audio, and archives
• plain http:// targets, SOCKS5 ingress, UDP, and HTTP/3/QUIC

_cacheignoreheader-1 may override missing or blocking response cache directives, but not the list above. Because a stored entry is shared on one hub, use this option only for public unauthenticated assets that are identical for every requester.

Protocol behavior#

HTTP/1.1 and HTTP/2 clients are supported for cache-mode HTTPS requests. Litport can also negotiate HTTP/2 on the verified origin leg. HTTP/3 uses QUIC over UDP, while the explicit Litport HTTP proxy path is TCP CONNECT; the QUIC request therefore does not enter this cache path. Applications often fall back to HTTP/2, but Litport does not claim HTTP/3 caching.

The Litport proxy endpoint may be written as http://HUB:PORT. Eligibility is based on the target URL, which must be https://....

Troubleshooting#

For transport-sensitive targets, read TLS and HTTP fingerprints.