Nav

HTTP Caching Policy

This policy provides a way to store HTTP responses from an API implementation or an API proxy for later reuse. This policy avoids performing multiple calls to the backend when the response of a service does not change often and to optimize against computationally expensive processing. This policy uses the concept of a cache which stores data so future requests for that data can be served faster.

Note: Values persisted in Object Store v2 appear as binary, not in plain text.

What this Policy Stores

This policy stores a whole HTTP response from the backend as received by the policy including the status codes, headers, payload, and session variables. If there are policies that edit the response before it is received by this policy, those changes are also present in the response received and therefore stored. If there are policies that make modifications to the response after it passes through the caching policy, those changes won’t be stored, but are replicated each time the value is retrieved from the cache.

Each entry has a size limit of 1 MB. In case of HTTP Responses that do not provide content length information, the policy tries to read up to that limit and stores it when it is not reached or continues without storing it, when that limit is exceeded.

How this Policy Works

When the policy receives a request, it calculates a key under which to store the response. When a second request with the same key arrives, the policy searches the cache for the previously stored response and returns it. If a matching response is found in the cache, the request does not reach either the policies that are defined after the cached one or the API implementation or proxy.

Where Entries are Stored

The underlying store used as cache is Mule’s ObjectStore. Depending on the policy’s configuration and where it is deployed, the policy uses an in-memory, persistent, file-based object store or the Runtime Manager ObjectStore v2. In case of the latter, a separate store is created just for the policy with the configured TTL. For more information on accessing the object store, see Caching in a Custom Policy for Mule 4.

Policy Configuration Parameters

Policy configuration topics:

HTTP Caching Key

The cache works as a dictionary where each response stored in the cache is associated to a string called key. The policy must have a way to compute this key, so this field must contain a DataWeave expression that returns a String value.

For example: #[attributes.headers['key']]

For information on DataWeave variables, see DataWeave Variables for Mule Runtime and Mule Message Structure.

If the evaluation of the expression results in an error due to missing parameters or any other cause, this policy is not applied and passes the request to the next receptor in the policy chain.

Note: This parameter is mandatory and it’s default value is #[attributes.requestPath], which means that the key for the caching is the request’s path. If you call the endpoint as http://myAppUrl.com/my/policy the key is /my/policy.

Maximum Cache Entries

This is the maximum number of responses that can be present in the cache at the same time. The criteria for removing the responses from the cache when this maximum is surpassed is FIFO. This configuration is ignored in Runtime Manager.

This field is also mandatory and has a default value of 10000 entries.

Note: When using the Runtime Manager ObjectStore v2, this is not enforced.

Entry Time To Live

The Time to live (TTL) value is measured in seconds.

This parameter represents how many seconds a response is stored in the cache, and once this time elapses, that the request is removed from the cache. When a new request arrives, the response is not present in the cache, and a new response must be computed. When using the policy with Object Store v2 in Runtime Manager, the edition of this value won’t be correctly reflected, in this case it’s recommended to remove the policy and object store and apply a new one.

Note: This is a mandatory parameter and its default value is ten minutes (600 seconds).

Distributed

When running a cluster or several workers in Runtime Manager, the values stored in the cache can be shared between the different nodes. To accomplish this, this option must be checked, otherwise each node has its own cache. In the case of Runtime Manager, the object store v2 must be enabled for this option to work.

By default this option is unchecked and there maybe a small penalty when distributing the cache, but negligible.

Persist Cache

If this box is checked the values stored in the cache persist after a runtime restart. If this option is used in Runtime Manager, enable the object store V2 on the application’s configuration in Runtime Manager.

By default this option is unchecked.

Follow HTTP Caching Directives

To obtain more control over the cache, this policy implemented some of the HTTP directives from the RFC-7234. If this box is checked, the policy takes into consideration the following headers to decide which responses to store, when to use the cache, and when the entry expires.

By default this box is checked.

To accomplish this, use the following headers:

Cache-Control

This header can be present in the request or the response. The values can be combined separated by commas. The values are:

In the request:

  • no-cache: The response isn’t searched for in the cache, but is stored in the cache.

  • no-store: The response isn’t stored in the cache, but if it is already present in the cache the policy returns the response.

In the response:

  • no-store, no-cache, private - All these values share the same behavior, the response isn’t stored in the cache.

  • max-age=<integer>, s-maxage=<integer> - The <integer> value should be replaced with an integer. Indicates how many seconds the response should live in the cache (if both are defined s-maxage takes precedence over max-age). This value overrides the global TTL configured in the policy.

Example of header present in the request: Cache-Control: no-cache,no-store

This results in the request not being searched with the value from the cache and not storing the result.

Example of header present in the response: Cache-Control: max-age=2, s-maxage=10

This results in the response are cached for 10 seconds.

Expires

This header value should be defined as stated in RFC-1123.

If present, this date is the date of expiration. If the max-age directive or s-maxage directive are specified, this header is ignored.

Date

If this header is defined as stated in RFC-1123, it is considered as the time creation of the response. If not defined, the date header is added with the time of reception of the response. This header is used in conjunction with the values defined in the max-age and s-maxage directives of the Cache-Control header.

Age

This header is calculated by the policy and added to each response returned that is retrieved from the cache, it indicates the seconds since the origin of the cached response specified in the date header.

The expiration time is calculated using the Cache-Control, Date, and Expiration headers. However, if the resulting expiration time surpasses the one imposed by the Entry Time To Live, it expires due to this one.

Invalidation Header

This parameter, if defined, indicates the name of the header that will be used for invalidating values in the cache. If not defined, it won’t be possible to invalidate the entries from the cache. The header can take two values:

  • invalidate: This option invalidates from the cache the entry with the key that the current request has.

  • invalidate-all: This option invalidates from the cache all the entries from the cache.

If the header is present in a request, due to the invalidation of at least the key present in the request, the cache won’t be inquired for a previously existing result.

This parameter is optional and by default it is not defined.

Example:

Considering the following values for the policy, #[attributes.requestPath] for the HTTP Caching Key and myInvalidationHeader for the invalidation header, the request:

curl http://myAppUrl.com/my/policy -H“myInvalidationHeader:invalidate”

This command invalidates the entry with key “/my/policy" from the cache. On the other hand the request:

curl http://myAppUrl.com/my/policy -H“myInvalidationHeader:invalidate-all”

This command invalidates all entries from the cache.

Conditional Request Caching Expression

This field holds a DataWeave expression that evaluates the response and returns a boolean.
If the request matches the expression, the expression returns True and the policy stores the request in the cache. If the request takes any other value, the expression returns False and the cache won’t store the request.

For information on DataWeave variables, see DataWeave Variables for Mule Runtime and Mule Message Structure.

This parameter is optional and its default value is:

#[attributes.method == 'GET' or attributes.method == 'HEAD']

This means that only the responses for incoming requests with HTTP methods GET or HEAD are cached by default.

Conditional Response Caching Expression

This field holds a DataWeave expression that evaluates the response and returns a boolean.
If the response matches the expression, the expression returns True and the policy stores the response in the cache.
If the response takes any other value, the expression returns False and the cache won’t store the response.

For information on DataWeave variables, see DataWeave Variables for Mule Runtime and Mule Message Structure.

This parameter is optional and its default value is:

#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]

This means that only status codes specified by RFC-7231 are cached by default.

FAQ

What happens if one parameter says that the response should be searched in the cache and the other says the opposite?

This is the same as What happens if the response expression says that the result should be stored but it has a no-store directive in the Cache-Control header?

The response isn’t stored. For it to be stored or searched in the cache, all conditions must be positive, if at least one condition says the cache shouldn’t intervene, it won’t.

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 behaviors are different in Runtime Manager?

  • If the distributed checkbox is checked, it’s always persistent.

  • The maximum cache entry doesn’t apply in Runtime Manager.

  • Edition of the TTL of the policy won’t be correctly reflected while using object store V2; to change this value remove the policy and apply a new one.

Do I need to configure something to use the policy in Runtime Manager?

Yes, if you want for the cache to be distributed or persistent, you have to set the Object Store as v2 in the Runtime Manager.

Which data types are supported to store in the cache?

Java serializables and input streams can be cached. In the case of input streams, they are read up to the maximum size of 1 MB that a cache entry can have. If that value is surpassed, then reading stops and the store is avoided.

What happens if I don’t define some of the optional parameters?

  • If invalidation header is not set, it won’t be possible to invalidate the cache in a request.

  • If the request expression or response expression are not set, the cache is used for all requests, and stores all the responses in the cache respectively, as if the expression #[true] was set.

Can I change the Invalidation Header values?

No, only the header name.

We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used and to tailor advertising. You can read more and make your cookie choices here. By continuing to use this site you are giving us your consent to do this.

+