Content Invalidation Jobs, or simply "jobs" as they are sometimes known, are ways of forcing cache servers to treat content as no longer valid, bypassing their normal caching policies.
In general, this should be unnecessary, because a well-behaved Origin should be setting its HTTP caching headers properly, so that content is only considered valid for some appropriate time intervals. Occasionally, however, an Origin will be too optimistic with its caching instructions, and when content needs to be updated, cache servers need to be informed that they must check back with the Origin. Content Invalidation Jobs allow this to be done for specific patterns of assets, so that cache servers will check back in with the Origin and verify that the content they have cached is still valid.
The model for Content Invalidation Job as API objects is given in jobs-model.
/** This is the form used to create a new Content Invalidation Job */
interface ContentInvalidationJobCreationRequest {
deliveryService: string;
invalidationType: "REFRESH" | "REFETCH";
regex: `/${string}` | `\\/${string}`; // must also be a valid RegExp
startTime: Date; // RFC3339 string
ttlHours: number;
}
/**
* This is the form used to return representations of Content Invalidation
* Requests to clients.
*/
interface ContentInvalidationJob {
assetUrl: string;
createdBy: string;
deliveryService: string;
id: number;
invalidationType: "REFRESH" | "REFETCH";
startTime: Date; // RFC3339 string
ttlHours: number;
}This property only appears in responses from the to-api (and in the bodies of PUT requests to to-api-jobs, where the scheme and host/authority sections of the URL is held immutable). The Asset URL is constructed from the Regular Expression used in the creation of a Content Invalidation Job and the ds-origin-url of the Delivery Service for which it was created. It is a URL that has a valid regular expression as its path (and may not be "percent-encoded" where a normal URL typically would be). Requests from CDN clients for content that matches this pattern will trigger Content Invalidation behavior.
The username of the user who created the Content Invalidation Job is stored as the Created By property of the Content Invalidation Job.
A Content Invalidation Job can only act on content for a single Delivery Service - invalidating content for multiple Delivery Services requires multiple Content Invalidation Jobs. The Delivery Service property of a Content Invalidation Job holds the ds-xmlid of the Delivery Service on which it operates.
4.0 In earlier API versions, this property was allowed to be either the integral, unique identifier of the target Delivery Service, or its ds-xmlid - this is no longer the case, but it should always be safe to use the ds-xmlid in any case.
The integral, unique identifier for the Content Invalidation Job, assigned to it upon its creation.
Invalidation Type defines how a cache server should go about ensuring that its cache is valid.
The normal operating mode for a Content Invalidation Job is to force the cache server to send a request to the Origin to verify that its cache is valid. If that is the case, no extra work is done and business as usual resumes. However, some Origins are misconfigured and do not respond as required by HTTP specification. In this case, it is strongly advised to fix the Origin so that it properly implements HTTP. However, if an Origin is sending cache-able responses to requests, and cannot be trusted to verify the validity of cached content based on cache-controlling HTTP headers (e.g. If-Modified-Since) instead returning responses like 304 Not Modified even when the content has in fact been modified, and if correcting this behavior is not an option, then the cache server may be forced to pretend that the content it has was actually invalidated by the Origin and must be completely re-fetched.
The two values allowed for a Content Invalidation Job's Invalidation Type are:
- REFRESH
A
REFRESHContent Invalidation Job instructscache serversto behave normally - when matching content is requested, send an upstream request to (eventually) theOriginwith cache-controlling HTTP headers, and trust theOrigin's response. The vast majority of all Content Invalidation Jobs should most likely use this Invalidation Type.- REFETCH
Rather than treating the cached content as "stale", the
cache serversprocessing aREFETCHContent Invalidation Job should fetch the cached content again, regardless of what theOriginhas to say about the validity of their caches. These types of Content Invalidation Jobs cannot be created without a proper "semi-global"refetch_enabled Parameter <parameter-name-refetch_enabled>.
Caution
A "REFETCH" Content Invalidation Job should be used only when the Origin is not properly configured to support HTTP caching, and will return invalid or incorrect responses to conditional requests as described in section 4.3.2 of 7234. In any other case, this will cause undo load on both the Origin and the requesting cache servers, and "REFRESH" should be used instead.
The Regular Expression of a Content Invalidation Job defines the content on which it acts. It is used to match URL paths (including the query string - but not including document fragments, which are not sent in HTTP requests) of content to be invalidated, and is combined with the ds-origin-url of the Delivery Service for which the Content Invalidation Job was created to obtain a final pattern that is made available as the Asset URL.
Note
While the to-api and tp-overview both require the Regular Expression to begin with / (so that it matches URL paths), the to-api allows optionally escaping this leading character with a "backslash" \\, while tp-overview does not. As / is not syntactically important to regular expressions, the use of a leading \\ should be avoided where possible, and is only allowed for legacy compatibility reasons.
| Name | Use(s) | Type |
|---|---|---|
| Path Regex | In Traffic Portal forms | unchanged (String, str, etc.) |
| regex | In raw to-api requests and responses, internally in multiple components |
unchanged (String, str, etc.) |
Content Invalidation Jobs are planned in advance, by setting their Start Time to some point in the future (the to-api will refuse to create Content Invalidation Jobs with a Start Time in the past). Content Invalidation Jobs will have no effect until their Start Time.
The TTL of a Content Invalidation Job defines how long a Content Invalidation Job should remain in effect. This is generally expressed as an integer number of hours.
| Name | Use(s) | Type |
|---|---|---|
| parameters | In legacy to-api versions |
A string, containing the TTL in the format TTL:{Actual TTL}h |
| ttlHours | In to-api requests and responses |
Unchanged (unsigned integer number of hours) |