Estimated Reading time: 3 minutes | Last modified: 2024-03-25, 11:49:25 pm

Caching

This document describes how to cache static resources or content with fewer changes by enabling caching options within page rules. Utilizing caching can significantly improve the access speed of resources and optimize the end-user experience.

Parameter Description

Parameter NameData TypeRequiredDescription
cache_keyarrayYesThe key values used to identify cached resources
enforce_cacheboolNoWhether to ignore cache directives like Cache-Control or Expires in the server’s response header and use the default caching strategy defined by the default_ttls parameter
default_ttlsarrayNoThe default cache expiration time strategy
browser_ttlarrayNoSets the cache validity period on the browser side
browser_ttl_unitarrayNoThe unit of the browser cache validity period, with selectable values s (seconds), min (minutes), hour (hours), day (days)
disable_convert_headboolNoWhether to convert HEAD requests to GET requests, with the default value being true

The parameter cache_key is an array used to generate the key that identifies the cache.

Common choices for cache keys without parameters include:

  • uri: The request’s URI, for example, /hello.html.
  • sorted-query-string: Sorted query parameters.
  • query-string: Query parameters.
  • user-agent: User-agent.
  • scheme: Protocol type, could be http or https.
  • client-continent: The continent where the client is located, which is identified by default through the client’s IP address, but can also be determined by the first address in the X-Forwarded-For request header.
  • req-method: HTTP request method, such as CONNECT, DELETE, GET, HEAD, POST, PUT, TRACE, OPTIONS, PATCH, etc.
  • first-x-forwarded-addr: The first IP address in the X-Forwarded-For request header, for example, 1.1.1.1 in 1.1.1.1,2.2.2.2.
  • last-x-forwarded-addr: The last IP address in the X-Forwarded-For request header, for example, 2.2.2.2 in 1.1.1.1,2.2.2.2.
  • http-version: HTTP version number could be 2.0, 1.1, 1.0, 0.9.

Common choices for cache keys with parameters include:

  • uri-arg: Parameters in the URI, for example, username in “hello.html?username=openresty”.
  • req-header: Request header information, for example, Host in “Host: openresty.com”.
  • req-cookie: Cookies in the request, for example, token in “Cookie: token=tokenvalue”.

The parameters browser_ttl and browser_ttl_unit define the browser-side caching settings. During the set caching period, the browser reads resources from the local cache.

The default_ttls parameter is an array format, allowing multiple caching strategies to be set up. The specific parameters within the strategy include:

Parameter NameData TypeRequiredDescription
ttlnumberYesDefines the lifetime of the cache
ttl_unitstringYesThe unit of the cache lifetime, supporting s (seconds), min (minutes), hour (hours), day (days)
statusnumberYesSpecifies the caching strategy under certain response status codes

Configuration Example

- enable_rule: true
  conditions:
  - op: prefix
    var: uri
    val: /static/

  cache:
    cache_key:
      - name: uri
      - name: query-string
      - name: req-header
        args: Host
      - name: uri-arg
        args: argname
      - name: req-cookie
        args: cookiename
      - name: client-continent  # means args: client-addr
      - name: client-continent
        args: first-x-forwarded-addr
    enforce_cache: true
    default_ttls:
      - ttl_unit: min
        status: 200
        ttl: 300
    browser_ttl: 300
    browser_ttl_unit: min
    disable_convert_head: false

This example checks if the request’s URI starts with the prefix /static/. If so, the caching mechanism is initiated. The cache key consists of the URI and request parameters, and the cache duration is set to 300 minutes.