HTTP Caching Policy
Policy Name |
HTTP caching |
Summary |
Caches HTTP responses from an API implementation |
Category |
Quality of Service |
First Mule version available |
v4.1.0 |
Returned Status Codes |
No return codes exist for this policy |
Summary
The HTTP Caching policy enables you to cache HTTP responses for reuse. Caching these responses speeds up the response time for user requests and reduces the load on the backend. For example, if your backend exposes an endpoint for which the responses to requests are not likely to change, you can reuse the HTTP responses and bypass the backend request processing by using the HTTP Caching policy.
Configuring Policy Parameters
Mule Gateway
When you apply the HTTP Caching policy to your API from the UI, you can configure the following parameters:
| Parameter | Description | Required? |
|---|---|---|
HTTP Caching Key |
A DataWeave expression.
Default value: |
Yes |
Maximum Cache Entries |
Specifies the maximum number of entries that can be stored in the cache at any given time.
Default value: |
Yes |
Entry Time To Live |
Specifies the amount of time (in seconds) after which a single entry expires from the cache.
Default value: |
Yes |
Distributed |
Configures the cache to be distributed among different nodes in a cluster.
If you are using CloudHub, ensure that you enable Object Store v2 when deploying an application.
Default value: |
Yes |
Persistent Cache |
Configures the cache to persist between different restarts of the Mule/Flex instance.
If you are using CloudHub, ensure that you enable Object Store v2 when deploying an application.
Default value: |
Yes |
Follow HTTP Caching directives |
Enables the use of Cache-Control header directives.
Default value: |
Yes |
Invalidation Header |
Name of the header used to invalidate a single entry or the entire cache. |
No |
Conditional Request Caching Expression |
The DataWeave expression that is used to decide which requests are to be cached (caches the response only if the condition is true).
Default value: |
No |
Conditional Response Caching Expression |
The DataWeave expression that is used to decide which responses are to be cached (caches the response only if the condition is true).
Default value: |
No |
How This Policy Works
When an HTTP request reaches an endpoint, what happens next depends on whether that request does not already exist in cache (a cache miss) or whether it does (a cache hit).
Cache Miss
In a cache miss scenario, the HTTP Caching policy checks whether a response to the submitted request is already cached. The request reaches the backend and the process is initiated only when it’s a cache miss. The diagram illustrates the flow of events that occur in this scenario:
-
The client (user) sends a request to the API.
-
The request proceeds through other policies in the policy chain before reaching the HTTP Caching policy.
-
The HTTP Caching policy checks if the request is already in the object store and, if not, the cache miss process is initiated.
-
The request continues throughout the chain of other remaining policies.
-
The request reaches the backend and completes all required processing.
-
The backend responds and the response travels back through the policy chain.
-
The response reaches the HTTP Caching policy.
-
Caching hits the object store again and attempts to save the key of the request for later reuse.
-
The response continues through the remaining policies in the policy chain.
-
The response is returned to the client.
Cache Hit
In a cache hit scenario, the HTTP Caching policy searches for the key in the object store and finds that the response to a request is already cached as a stored entry. The request does not proceed any further in the policy chain toward the backend, and the cached response is reused.
Subsequently, all the policies that must be executed in the policy chain after caching are not executed, in case of a cache hit:
-
The client (user) sends a request to the API.
-
The request crosses other policies before reaching the HTTP Caching policy.
-
The HTTP Caching policy verifies that the request is already in the cache.
-
The key is found in the object store and the stored response is returned.
-
The response continues through the rest of the policy chain until it reaches the last one.
-
The cached response is returned to the client.
Stored Entries
Stored entries are the cached HTTP responses. The cache can store any serializable data or input streams of up to 1 MB. If that value is surpassed, then the reading stops and the value is not stored in such a case.
HTTP Caching Key
The cache works as a dictionary, where each response stored in the cache is associated with a string called key. For example, the expression #[attributes.headers['key']] uses the header called key as the entry key.
Cache Size and Entry Expiration
The cache can hold a specified number of entries at any given time. You can configure this number using the Maximum Cache Entries property. Each stored entry is held in the cache memory for a specific period of time, after which the entry expires and must be processed again. This expiration time is called time to live (TTL).
Another condition that can trigger the expiration of an entry is when the cache reaches the maximum number of items that it can store. When this scenario occurs, the entry is removed by using the FIFO (First-In First-Out) criteria. This means that the earliest entry to reach the cache is removed, even though it hasn’t reached the TTL value yet.
Distributed Cache
Each entry in the cache can be shared between different nodes in a cluster or between several workers in Runtime Manager using the Distributed option (see table). If this option is not enabled, then each node is assigned its own cache memory.
Persistent Cache
A persistent cache enables the stored entries in the cache to persist if Mule runtime engine (Mule) or Flex replica is restarted.
When you upgrade a version of the instance that has the HTTP Caching policy configured to use the persistent store, the policy tries to maintain the entries stored by the previous version. However in a worst-case scenario, the entries in the cache are invalidated and the cache is re-populated when new requests arrive. This manipulation of the entries in the cache occurs automatically and is invisible to the user.
HTTP Caching Directives
To obtain more control over the cache, the HTTP Caching policy interprets some of the HTTP directives from the RFC-7234 protocol by taking the following headers into account:
-
Cache-Control -
Expires -
Date -
Age
Cache-Control
The Cache-Control header can exist either in the request or in the response. Possible values for the header, which can be combined separated by commas, include:
-
In requests:
-
no-cache
-
The response is not searched for, but is directly stored in the cache.
-
no-store
The response is not stored in the cache. However, if the response is already present in the cache, the policy returns the response.
-
In responses:
-
no-store,no-cache,private
-
For each value, the response is not stored in the cache.
-
max-age=<integer>,s-maxage=<integer>
The <integer> placeholder must be replaced with a valid integer that indicates the time (in seconds) for which the response can remain in the cache. If both parameters are defined, s-maxage takes precedence over max-age.
If a global time-to-live (TTL) value is also defined for the policy, these header values override the global TTL configured in the policy if the time specified in the headers is less than the global TTL.
Expires
If present, this header specifies the date by which the entry in the cache expires. If you specify the max-age directive or s-maxage directive, this header is ignored. You must define the header value as stated in RFC-1123.
Date
The date header, as defined per RFC-1123, specifies the date and time when the response is created. If not defined, the date header is added with the time when the request was received. This header is used in conjunction with the values defined in the max-age and s-maxage directives of the Cache-Control header.
Age
The age header indicates the time (in seconds) elapsed since the origin of the cached response specified in the date header. This header is calculated by the policy and added to each response that is retrieved from the cache.
The expiration time is calculated using the cache-control, date, and expires headers. However, if the resulting expiration time exceeds the one imposed by the TTL value of the entry, the cache entry expires anyway.
Invalidate
The invalidate header, if configured in the HTTP Caching policy, invalidates the entries in the cache, thereby causing the request to be processed again. You specify the name of the header in the Invalidation Header configuration to turn on the option. The value of the header can take only one of the following options:
invalidate
This option invalidates the entry whose key matches the current request.
invalidate-all
This option invalidates all the entries from the cache.
For example, imagine that the following values are configured in the policy for the request:
-
HTTP Caching Key: "#[attributes.requestPath]" -
Invalidation header: "myInvalidationHeader"
The following command invalidates the entry with key “/my/policy" from the cache:
curl http://<MyAppURL>/my/policy -H “myInvalidationHeader:invalidate”
The following request invalidates all entries from the cache:
curl http://<MyAppURL>/my/policy -H “myInvalidationHeader:invalidate-all”
Conditional Caching
Conditional caching enables you to configure a set of conditions that must be met before entries are stored in the cache. If none of the conditional caching parameters are configured, the cache stores the responses for every incoming request. If configured, parameters are evaluated for each request to determine whether the response of the current request must be stored.
For conditional request expressions, only the responses for incoming requests with HTTP methods GET or HEAD are cached by default. For conditional response expressions, only status codes specified by RFC-7231 are cached by default.
For more information about the default values, see Configuring Policy Parameters.
FAQ
What happens when the evaluation of the key results in any error?
If the evaluation of the expression for a particular request results in an error, the policy does not take effect and the request continues to the next receptor in the policy chain.
Can I store only part of the response with this policy?
No, but you can apply a policy before this one and transform the response to something else.
What happens if one parameter is configured to search for the response in the cache and the other parameter is configured for the opposite action?
This is the same as configuring the response to be stored in the cache when there is a no-store directive in the Cache-Control header.
In this situation, the response isn’t stored. You must configure both the Cache-Control header and the cache to be able to store and search for the response in the cache.
How does running the HTTP Caching policy in CloudHub differ compared with running it in Mule runtime engine?
-
If the Distributed option is selected, the cache is always persistent.
-
The maximum cache configuration is ignored in Runtime Manager.
-
The edition of the TTL of the policy is not correctly reflected while using Object Store v2. To change this value, remove the HTTP Caching policy and apply a new one.
What happens if I do not define some of the optional parameters?
If you have not configured the invalidation header, you cannot invalidate the cache in a request.
Additionally, if you have not configured the request expression or response expression, the cache is used for all requests and all the responses are stored in the cache (expression #[true]).
Can I modify the Invalidation header values?
No, you can modify only the header name.
If I deploy my application in an on-premise server, will it use Object Store v2?
No, Object Store v2 is not available for on-premises servers. You must use the Mule object store. For more information, see Object Store v2 FAQs.