Default cache rules

Default cache policy

Cache configurations apply only to requests routed to the ESA cache component. ESA uses the following steps to determine whether a request enters the cache:

1. Check whether the request is of the GET or HEAD type.

2. Check whether the request meets the conditions specified in a cache rule. If the request meets the conditions, the cache rule, instead of the global cache settings, applies to the request. For more information, see Cache rules for successful responses and redirections.

3. Check if the file extension is listed under extensions of default cached files. If it is, the global cache settings apply to the request.

Cache rules for successful responses and redirections

Applicable status codes: 200, 203, 206, 300, 301, and 410.

The edge cache TTL has four options:

• Honor Origin TTL or Use Default Cache Rule: If the response returned from the origin server contains the Cache-Control, Expires, Last-Modified, and ETag headers for setting a cache policy, ESA uses the cache policy of the origin server. If the response returned from the origin server does not contain any of the Cache-Control, Expires, Last-Modified, and ETag headers, ESA caches resources based on the default cache policy of ESA.

  Cache policy details

  

  Cache-Control in the response

  The Cache-Control header in the origin response specifies one of the following policies:

  1. If the Cache-Control header has one of the following directives, the resource is not cached:

     • no-cache

     • no-store

     • max-age=0

  2. If the Cache-Control header contains the max-age or s-maxage directive with a value greater than 0, such as 3600, the TTL specified by the directive is used. If both the max-age and s-maxage directives exist, the value of the s-maxage directive prevails.

  No Cache-Control in the response

  If the origin response does not contain the Cache-Control header, the default cache policy of ESA is used. Header priority (highest first): Expires > Last-Modified > ETag.

  1. If the origin response contains the Expires header, such as Expires:Tue, 25 Nov 2031 17:25:43 GMT, ESA uses the TTL set in the Expires header.

  2. If the origin response does not contain the Expires header but contains the Last-Modified header, the TTL is calculated based on the following rules:

     • TTL = (Current time - Value of Last-Modified) × 0.1. If the resulting value ranges from 10 seconds to 3,600 seconds, the actual value is used. If the resulting value is less than 10 seconds, the TTL is 10 seconds. If the resulting value is greater than 3,600 seconds, the TTL is 3,600 seconds.

  3. If the origin response contains only the ETag header, the TTL is 10 seconds.

  4. If the origin response does not contain the Cache-Control, Expires, ETag, or Last-Modified header, the resource is not cached.

• Honor Origin TTL or Do Not Cache: If the response returned from the origin server contains the Cache-Control header for setting a cache policy, ESA uses the cache policy of the origin sever. If the response returned from the origin server does not contain the Cache-Control header, ESA does not cache resources.

  Cache policy details

  

  Determine the cache policy of the origin server

  Check whether the origin response contains the Cache-Control header. If absent, resources are not cached. If present, one of the following policies applies:

  1. If the Cache-Control header contains the no-cache, no-store, or max-age=0 directive, resources are not cached.

  2. If the Cache-Control header contains the max-age or s-maxage directive with a value greater than 0, such as 3600, the TTL specified by the directive is used. If both the max-age and s-maxage directives exist, the value of the s-maxage directive prevails.

• Do Not Cache: All resources retrieved from the origin server are not cached on ESA POPs.

• Use Custom TTL: ESA ignores the Cache-Control, Expires, Last-Modified, and ETag headers of the cache policy in the origin response and uses the TTL set on ESA.

Cache rules for responses with error status codes

• For status codes 204, 305, 404, 405, 414, 424, 429, 500, 501, 502, 503, and 504, the cache rules are as follows:

  

  1. If the origin server returns a set-cookie response header, the response is not cached.

  2. If the origin server does not return a set-cookie response header, the system checks whether a TTL for the status code is configured in the console:

     1. If a TTL is configured, the response is cached based on the settings in the console. If multiple rules are set, the rule with smallest ordinal number takes effect.

     2. If no TTL is configured, the response is cached based on the Pragma, Cache-Control, or Expires response headers from the origin server.

  3. If the origin server does not return Pragma, Cache-Control, or Expires response headers, the response is cached for 1 second by default.

• For status codes 302, 307, and 403, the cache rules are as follows:

  

  1. If the origin server returns a set-cookie response header, the response is not cached.

  2. If the origin server does not return a set-cookie response header, the system checks whether a TTL for the status code is configured in the console:

     1. If a TTL is configured, the response is cached based on the settings in the console. If multiple rules are set, the rule with smallest ordinal number takes effect.

     2. If no TTL is configured, the response is cached based on the Pragma, Cache-Control, or Expires response headers from the origin server.

  3. If the origin server does not return Pragma, Cache-Control, or Expires response headers, the response is not cached.

• For other error status codes, such as 400, the cache rules are as follows:

  1. If the origin server returns a set-cookie response header, the response is not cached.

  2. If the origin server does not return a set-cookie response header, the system checks whether a TTL for the status code is configured in the console. If multiple rules are set, the rule with smallest ordinal number takes effect.

  3. In all other cases, the response is not cached.

• For requests that use range origin fetch, if a POP receives a response with a status code other than 206 from the origin server, the POP deletes the cached file shards. An origin fetch timeout does not cause the cache files to be deleted.

  When using range origin fetch, the origin server splits a large file into multiple smaller file shards and sends them to the POP. For example, a file is split into 10 shards and the POP has cached 5 of these shards. When the POP requests the 6th shard and the origin server returns a 5xx status code, the POP deletes all 5 cached shards.

Cache response information

ESA POPs return cache-related response headers with the following information:

• Ali-Swift-Global-Savetime: The time when the resource first entered the ESA POP (determined by the website's cache architecture, which may be an L2 POP or a POP at another cache tier).

  • Its value is a UNIX timestamp. For example: 1745053111 indicates 16:58:31 on April 19, 2025.

• Date: The date when the origin server returns the resource to the ESA POP.

  • The date is updated when the ESA POP initiates an origin request that contains the If-Modified-Since or If-None-Match header to revalidate the resource and the origin server returns HTTP status code 304.

  • The time is in GMT format. Example: Sat, 19 Apr 2025 08:58:31 GMT.

• X-Site-Cache-Status: The cache status of the requested resource on the ESA POP. The following list describes the resource states:

  • HIT: The resource is found in the ESA POP cache.

  • MISS: The resource is not found in the ESA POP cache. The POP retrieves the resource from the origin server and then returns the resource to the client.

  • NONE/UNKNOWN: The resource is not eligible for caching for the following reasons:

    • An edge function generates a response but does not send any subrequests. In this case, the response is not from the cache, and the cache status is recorded as none/unknown.

    • When an edge function's main request initiates a subrequest (fetch), the cache status is recorded for the subrequest, while the main request's cache status is recorded as none/unknown. This occurs because the edge function module runs before the cache module, preventing the main request from passing through the cache.

    • A client request hits a custom WAF rule and is blocked by WAF. Because WAF runs before the cache module, the request does not pass through the cache, and the cache status is recorded as none/unknown.

    • A client request hits a Redirect rules or an HTTPS rules. The POP then sends a redirection response to another URL. Because these rules run before the cache module, the cache status is recorded as none/unknown.

  • EXPIRED: The resource is found in the ESA POP cache but has expired. The POP retrieves the resource from the origin server and then returns the resource to the client. The status code returned by the origin server is 200 or 206.

  • STALE:

    The resource is served from the ESA POP cache but has expired. This occurs in the following cases:

    • The cache setting is Honor Origin TTL and the origin response contains Cache-Control:stale-while-revalidate=<seconds>. Within the specified time, the ESA initiates a request to the origin server to revalidate the resource and serves the expired cache to the client.

    • The cache setting is Honor Origin TTL and the origin response contains Cache-Control:stale-if-error=<seconds>. Within the specified time, ESA serves the expired cache to the client when ESA cannot connect to the origin server to retrieve the updated resource.

    • The Configure response cache expiration feature is enabled. This feature allows the ESA POP to serve the expired cache to the client when the origin response times out or when the origin server is unreachable.

  • BYPASS

    The request to the resource bypasses the ESA cache. This occurs in the following cases:

    • The cache setting is not Honor Origin TTL and ESA sets a custom cache TTL to 0 seconds.

    • The cache setting is Honor Origin TTL but the value of the Cache-Control header returned by the origin server is no-store.

  • REVALIDATED

    The resource is served by the ESA cache, but it has expired. ESA initiates an origin request that contains the If-Modified-Since or lf-None-Match header to the origin server to revalidate the resource. The origin server returns HTTP status code 304.

  • DYNAMIC

    ESA detects that the resource is dynamic content and no defined cache rules apply to such a request. In this case, ESA retrieves the resource from the origin server and then returns it to the client.

• X-Swift-Cachetime: Specifies the TTL of the resource on the POP in seconds. The X-Swift-Cachetime value is not the same as the TTL set in ESA. It is calculated using the following formula: X-Swift-Cachetime = Ali-Swift-Global-Savetime + the TTL set in ESA - X-Swift-SaveTime. The following scenarios may occur:

  • The X-Swift-Cachetime value is equal to the TTL set in ESA, for example, 3600 seconds.

  • The X-Swift-Cachetime value is slightly less than the TTL set in ESA. For example, if the TTL set in ESA is 300 seconds, the X-Swift-Cachetime value may be 295 seconds. This discrepancy can occur for the following reasons:

    • High latency occurs when an L1 node fetches content from an L2 node.

    • The clocks on the L1 and L2 nodes are not in sync.

  • The X-Swift-Cachetime value is negative. This can occur if you change the TTL setting in ESA after a resource is cached. This happens when a client request arrives after the L1 node cache has expired, but while the L2 node cache is still valid. For example, the TTL was originally set to 3600 seconds in ESA and was later changed to 300 seconds. If a client sends a request 600 seconds after the resource was cached, the response includes X-Swift-Cachetime:-300. To resolve this issue, you can refresh the cache.

• X-Swift-Cachetime:

  The cache TTL of the resource on the ESA POP. Unit: seconds.

• X-Swift-SaveTime:

  • The time when the resource first entered the current POP (L1 POP) that receives the client request.

  • The time is in GMT format. Example: Sat, 19 Apr 2025 08:58:31 GMT.

Do Not Cache policy

The ESA POP does not cache files and passes through all file requests in the following conditions:

• Edge Cache TTL on the ESA Settings page is set to Honor Origin TTL or Do Not Cache and the origin response is Cache-Control: no-store.

• [CONREF:app_site_cache_configuration_node_expiration_title] on the ESA Settings page is set to Do Not Cache.

• [CONREF:app_site_cache_configuration_node_expiration_title] on the ESA Settings page is set to Use Custom TTL and the cache TTL is set to 0 seconds.

Cache revalidation

After a cached file on the ESA POP expires, the ESA POP sends a validation request to the origin server on the next client request. If the file has not changed, the origin server returns 304 not-modified, and the ESA POP serves the cached file without re-downloading it. This reduces origin traffic and improves response speed.

• Special policy configuration: A file is cached for 0 seconds, and the ESA POP redirects each request to the origin server for validation.

  • Edge Cache TTL on the ESA Settings page is set to Honor Origin TTL or Use Default Cache Rule, and the origin response meets the following conditions:

    • Cache-Control: no-cache

    • Cache-Control: max-age=0

• Regular policy configuration: The origin server responds to the policy related to cache validation, and the ESA POP executes the actual policy.

  • Edge Cache TTL on the ESA Settings page is set to Honor Origin TTL or Use Default Cache Rule, and the origin response meets one of the following cache validation policies:

    • must-revalidate

    • proxy-revalidate

    • stale-while-revalidate=seconds

    • stale-if-error=seconds

• Cache validation policy

  Cache validation policies:

  • must-revalidate

    • Description: Once expired, any cache (proxy or browser) must revalidate the resource with the origin server before serving it. The cache cannot serve expired content even if the network is unavailable, unless the resource has been validated to be unchanged.

    • Example: Cache-Control: max-age=3600, must-revalidate indicates that a resource must be returned to the origin server to validate its freshness after the resource expires.

  • proxy-revalidate

    • Description: Similar to must-revalidate, but applies only to shared caches (CDN, proxy servers). Private caches such as browsers are not subject to this constraint.

    • Example: Cache-Control: max-age=3600, proxy-revalidate indicates that a resource must be returned to the origin server to validate its freshness after the resource expires.

  • stale-while-revalidate=seconds

    • Description: After expiry, the cache serves stale content for the specified duration while asynchronously revalidating with the origin in the background. Use this when reduced latency outweighs serving briefly stale content.

    • Example: Cache-Control: max-age=3600, stale-while-revalidate=60 indicates that a resource is considered fresh for 3,600 seconds (1 hour) after it is first published. Once expired, the resource can still be provided for users for the next 60 seconds. At the same time, the POP attempts to obtain updates from the origin server.

  • stale-if-error=seconds

    • Description: When the origin is unreachable (server breakdown, network error), the POP serves expired cached content for the specified duration. This improves fault tolerance and maintains availability during origin outages.

    • Example: Cache-Control: max-age=86400, stale-if-error=604800 indicates that a resource is considered fresh for 86,400 seconds (24 hours) after it is first published. If revalidation after the 86,400 seconds fails, the last successfully cached resource can still be provided for the next 604,800 seconds (one week).