Concepts

By default, the nuu:bit Edge Proxy caches objects that simultaneously match all the conditions below:

• The origin marks them as cacheable by returning either an Expires or a Cache-Control header with an s-max-age or max-age parameter larger than 0. If both are present, the Cache-Control header takes precedence. If both s-max-age and max-age are present, the former takes precedence. By default the object is cached for the duration specified by the origin:

• If Expires is present, but Cache-Control isn’t, the cache lifetime (referred to as time-to-live (TTL)) is the difference between the time specified by the header and the current time on the edge proxy.
• If Cache-Control is present and its [s-]max-age is larger than zero, then TTL is the value, in seconds, specified by the [s-]max-age parameter.

• The object is requested through a GET or HEAD HTTP method. All other methods, such as POST, PUT and DELETE are not cached.

• The browser doesn’t send any cookies with the request and the origin doesn’t set any cookies in the response. This behavior can be changed, as we will see later.

• The object is public - that is, it doesn’t require authentication as signalled by the presence of an Authorization header in the request.

These restrictions make many, if not all objects uncacheable, mostly because the browser sends the domain cookies as part of every request for a resource in that domain, regardless of type. For example, it sends them both for HTML pages and images.

The workaround for this issue requires actual knowledge about the website structure. The cache needs to be told:

• Which objects are cacheable and for how long, even if the origin doesn’t mark them as such.

• Which objects are dynamically generated and, among these, which ones require cookies in order to generate the resource.

The nuu:bit Customer Portal allows the configuration of caching parameters for a domain. Currently, the interface allows a user to configure a list of caching rules in JSON format, as described in the section nuu:bit Caching Rules. 

Let us now look at how the cache actually works:

1. A request for a resource is received from the browser.
2. Check that all the conditions for cacheability of this resource, defined above, are met for the request:

• If at least one of them isn’t met:

a. Download the object from the origin.
b. Override the browser TTL if necessary (see nuu:bit Caching Rules).
c. Return it to the browser without caching it.

3. If the object is deemed cacheable:

a. Compute a hash value, composed of:

• The domain name.
• The full URL, containing the query string, if present. (The query string behavior can be controlled, as described below.)
• The user agent capabilities. These capabilities are taken from the “User-Agent” request HTTP header, although the full “User-Agent” header is not used.
• The set of request cookies that are relevant for the object, as defined through caching rules (see nuu:bit Caching Rules).

b. Check if the cache already contains an unexpired object associated with this hash value. The “stale” object TTL default is 10 seconds.

• If it does:

i. Override the browser TTL if necessary (see nuu:bit Caching Rules).
ii. Return the cached object.

c. If the object is not in the cache or it is expired, download the object from the origin.
d. Check that all the conditions for cacheability of this resource, defined above, are met for the response:

• If at least one of them isn’t met:

i. Override the browser TTL if necessary (see nuu:bit Caching Rules).
ii. Return the object to the browser without caching it.

e. The object is cacheable.

i. Compute the TTL of the object.
ii. Insert it into the cache and associate it with the previously computed hash value.

f. Override the browser TTL if necessary (see nuu:bit Caching Rules).
g. Return the object to the browser.

Note that given the manner in which the hash value is computed, there can be more than one instance of the same object in the cache at any time:

• One instance for each user agent with different capabilities (mobile/desktop, supported HTML features, WebP support etc.).
• One instance for each combination of query parameters and their values, if present.
• One instance for each combination of cookies and their values, if cookies are allowed (see nuu:bit Caching Rules).