proxy-cache

Caches upstream responses on disk or in memory.

Category TrafficAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin proxy-cachePriority 1085

What it does

proxy-cache keeps a copy of the answers a route's backend gives and serves the next matching request from that copy, without asking the backend. Its Cache strategy chooses where the copies live, on disk or in memory, and Cache key decides which requests share one.

The first request for a key reaches the backend, and its answer carries the cache status MISS. The same request again is answered from the cache with HIT, for as long as the copy lives.

When to use it

• A list of products that every client reads and that changes rarely, served from memory for a minute instead of from the backend on every request.
• A slow report that may be a few minutes old, computed once and then served from the cache.
• A burst of identical reads, for example after a mobile app release, that the backend should not answer one by one.
• Answers that differ by caller, kept apart per consumer with Consumer isolation.

Guides

Pages that walk through a job with proxy-cache, step by step.

• Serve answers from a cacheKeep a route's answers in the gateway's memory for a minute and serve repeated requests without asking the backend.

Set it up

Keep successful responses in memory for one minute

Under Basics set Cache strategy to memory, set Cache TTL to 60 seconds, set Cache zone to memory_cache and fill Cache key as in the JSON below. Under Behavior fill Cached response statuses as in the JSON below.

The console's Add plugin panel, filled with this example.

proxy-cache · as the console saves it

{
  "cache_strategy": "memory",
  "cache_zone": "memory_cache",
  "cache_ttl": 60,
  "cache_key": [
    "$host",
    "$request_uri"
  ],
  "cache_http_status": [
    200
  ]
}

What you will see

• The first request is answered 200 by the backend, and the answer's cache status header reads MISS; the gateway keeps the answer.
• The second request within the minute is answered 200 by the gateway from its memory, and the cache status header reads HIT; the backend is not called.

Things to know

• Cache key — With the key $host and $request_uri, a second request to the same path is answered from memory. The first answer carries MISS, the second HIT.
• Cache key — Each part is a $variable or text of two characters or more. $request_method is refused, and a variable the request lacks adds nothing to the key.
• Cache strategy — Under Disk the lifetime of a stored response is set by the gateway's own cache configuration and not by this object, which is why the lifetime field is drawn under Memory alone.
• Cache zone — Any other name, or a zone of the other strategy, is refused on save.
• Cache zone — Under Cache strategy disk, the zone memory_cache is refused when you save.
• Cache control — On, a response is cached only as long as its own Cache-Control or Expires allows, and one carrying neither is never stored. The lifetime box above is not read. A request that asks for no-store goes to the upstream.
• Cached request methods — A method other than GET, HEAD and POST, for example PUT, is refused when you save.
• Cache bypass — Each part is a $variable or text of two characters or more, so a lone 0 or 1 is refused.
• No cache — Each part is a $variable or text of two characters or more, so a lone 0 or 1 is refused.
• Consumer isolation — On, each consumer gets its own entries; off, an entry cached for one consumer is served to the others. Not read when the cache key carries $consumer_name, $consumer_group_id, $remote_user or $http_authorization: a name empty for all leaves them one cache.
• AdviceCache only answers that every caller of the route may see. For an answer that depends on who asks, keep Consumer isolation on or put the caller in the key.

Settings

The fields as the console shows them, section by section. A field under “When … is …” is there only while that value is set.

Basics

Cache strategycache_strategystringdefault disk

one of disk, memory

When Cache strategy is memory

Cache TTLcache_ttlintegerdefault 300

at least 1 · in seconds

Cache controlcache_controlbooleandefault false

Cache set cookiecache_set_cookiebooleandefault false

Off, a response that carries a Set-Cookie header is never stored, wherever that header came from.

Response body limitmax_resp_body_sizeintegerdefault 67108864

Responses of this many bytes or more are passed through and not stored.

at least 1

Cache zonecache_zonestringdefault disk_cache_one

A zone the gateway declares for this strategy: disk_cache_one for Disk and memory_cache for Memory, as shipped.

1 to 100 characters

Cache keycache_keyarray of stringsdefault ["$host","$request_uri"]

at least 1 item

Behavior

Cached request methodscache_methodarray of stringsdefault ["GET","HEAD"]

at least 1 item · one of GET, HEAD, POST

Cached response statusescache_http_statusarray of integersdefault [200,301,404]

at least 1 item; each 200 to 599

Cache bypasscache_bypassarray of strings

Skip the cache when these parts join into anything but empty or 0, such as $arg_nocache.

at least 1 item

No cacheno_cachearray of strings

Do not store the response when these parts join into anything but empty or 0, such as $arg_nostore.

at least 1 item

Hide cache headershide_cache_headersbooleandefault false

On, the response reaches the client without the Cache-Control and Expires headers it was stored with.

Consumer isolationconsumer_isolationbooleandefault true

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.