Package org.microproxy.cache

Class HttpCache

java.lang.Object
org.microproxy.cache.HttpCache
All Implemented Interfaces:
HttpFiltersSource
public final class HttpCache extends Object implements HttpFiltersSource
A shared HTTP cache (RFC 9111) that can also keep a site usable offline. 

 HttpCache cache = HttpCache.builder()
         .store(new DiskCacheStore(Path.of("cache"), 1L << 30))
         .build();
 MicroProxy.bootstrap().withHttpCache(cache).start();

What it does:

  • Storing: complete responses to GET, up to HttpCache.Builder.maxEntrySize, that are storable for a shared cache: not no-store or private, not to requests with Authorization (unless public, s-maxage or must-revalidate), not Vary: *, and not setting cookies unless public.
  • Freshness: from s-maxage, max-age, Expires, or 10% of the time since Last-Modified (at most a day); ages follow the RFC's calculation, including Age and response delay. Request directives max-age, min-fresh, max-stale, no-cache, no-store and only-if-cached are honoured.
  • Validation: stale entries with an ETag or Last-Modified are revalidated with a conditional request; a 304 refreshes the entry and the client gets the stored response.
  • Variants: Vary is matched on normalized request field values; each URL may have several stored variants. HEAD is answered from a stored GET.
  • Invalidation: a successful unsafe request (POST, PUT, ...) removes the stored responses for its URL and for same-origin Location / Content-Location.
  • Unreachable servers: when the server cannot be reached (the proxy would answer 502 or 504) a stale entry is served instead, unless it says must-revalidate, proxy-revalidate, no-cache or s-maxage. A server error (5xx) is replaced by a stale entry only within its stale-if-error window. Intercepted HTTPS keeps working: a CONNECT to an unreachable server is still intercepted so cached pages can be served inside it.
  • Offline mode (HttpCache.Builder.offline): requests are answered only from the cache, whatever their age and directives; anything not stored gets 504.

Responses carry a Cache-Status field (RFC 9211), e.g. MicroProxy; hit or MicroProxy; fwd=miss; stored. Not implemented: stale-while-revalidate, partial content (Range requests bypass the cache), and caching of POST responses.

Install it with HttpProxyServerBootstrap.withHttpCache(org.microproxy.cache.HttpCache), which runs it after all other filters: they see requests before the cache answers them, and the cache stores responses as they leave the other filters.

  • Method Details

    • builder

      public static HttpCache.Builder builder()
      Starts a builder with the default settings.
      Returns:
      a new builder with default settings

    • stats

      public HttpCache.Stats stats()
      Returns a snapshot of the cache counters.
      Returns:
      a snapshot of the cache counters

    • store

      public CacheStore store()
      Returns the backing response store.
      Returns:
      the backing cache store

    • isOffline

      public boolean isOffline()
      Reports whether the cache operates without contacting servers.
      Returns:
      whether upstream requests are disabled

    • filterRequest

      public HttpFilters filterRequest(HttpRequest originalRequest, FlowContext flowContext)
      Description copied from interface: HttpFiltersSource
      Returns the filters for a request, or null to proxy it unfiltered.
      Specified by:
      filterRequest in interface HttpFiltersSource
      Parameters:
      originalRequest - a copy of the request as received from the client
      flowContext - the client connection the request arrived on
      Returns:
      the per-request filters, or null to leave the request unfiltered