Skip to content

Caching

PixivFE has separate upstream-response and downstream HTTP caches. Do not treat their policies as interchangeable.

Guide for caching

The optional upstream cache isolates responses by URL, effective upstream cookies and configured request language. Its configured TTL is an upper bound: upstream freshness, response age and revalidation directives can shorten or prevent storage. Keep mutation-driven invalidation in place even for session-specific entries. The authoritative policy and endpoint exclusions are in core/requests/caching.go.

Only Vary: Cookie and Vary: Accept-Language can be cached, since both effective outbound headers are represented in the cache identity. Responses varying on any other field, including User-Agent and Accept-Encoding, are not cached. This deliberately favors correct representations over cache hit rate. Invalidation also prevents in-flight pre-mutation GET responses from repopulating the cache after a write.

Instance-pooled requests require a healthy selected token before checking the cache. Cached responses must not bypass the token manager's cooldown: once the token recovers, its matching cached response can be reused. The cache never searches other accounts' cached entries as a fallback.

Rendered output can depend on visitor cookies, negotiated language and partial request headers. Preserve Cache-Control and Vary through any reverse proxy; never force public caching over private or no-store responses. Rendered error and authorization responses must not be stored, since they can contain per-client challenge links. See server/middleware/set_response_headers.go and the affected route for downstream policy.

Respect upstream cache headers for proxied media rather than caching all status codes forever. Conditional requests, HEAD and ranges must preserve their HTTP semantics. For the protocol rules, see HTTP caching (RFC 9111).

Predictive caching proposal

The following is an unimplemented design idea, not current cache behavior.

Preload header is already implemented for /artwork/ and /artwork-multi/ for the main images.

However, we can do better.

When we send an HTML page to the client, we can start fetching all the images in the page. We need a lot of correct synchronization to get it right, but it will make the browsing experience faster.

  • pixivfe predictively fetch images to store in its cache.
  • every proxied request goes through the cache as well.

every cache item has three possible states:

  • not in cache
  • pending
  • cached