Speed up a website with the cache

Coritan's network can keep copies of the files on your website that look the same to every visitor, such as pictures and fonts. A visitor who asks for one gets the copy from Coritan's network without a trip to your origin, so the page loads faster and your origin has less to send. A website's Caching tab shows what the cache keeps, and lets you turn it off, choose how long it keeps copies, let signed-in visitors skip it and clear it after you change a file.

• The hostname is on Coritan's network: a DNS record with Proxied on (Proxied records), or a web proxy (Manage a website's origin). Until the domain has one, the tab offers Proxy a DNS record and Set up a web proxy in place of its settings.
• Once account plans open on your account, changing the cache and clearing it come with the Pro, Business and Enterprise plans (How account plans work). On the Free plan the tab shows the settings without letting you change them, with Cache settings come with the Pro plan. The cache keeps working as its settings say.

The cache keeps:

• Pictures, fonts, sound and video files. Coritan's network goes by the Content-Type your origin sends (image/, font/, audio/ or video/). An answer with no type, or with application/octet-stream, counts when its path ends in an extension such as .png, .jpg, .svg, .woff2, .mp3 or .mp4.
• Scripts, stylesheets and JSON files under /assets/v/ or /_next/static/ that your origin marks immutable in its Cache-Control header. Their address changes whenever they do, as a Next.js build names its files.
• Answers under /api/v1/orgs/ that your origin marks public with an s-maxage time, for 15 seconds at most, whatever Keep copies for says. A request there that sends an API key, or a cookie other than the one that remembers the answer to our math question, always reaches your origin.

The cache never keeps:

• Pages, and any other file not listed above.
• An answer that sets a cookie, or whose Cache-Control header says private or no-store.
• An answer whose Vary header names a request header other than Accept-Encoding.
• A request with an Authorization header, or with the cookie you set under Cookie name (Let signed-in visitors skip the cache).
• Any request but GET and HEAD, and any answer but 200.
• A file over 10 MB, or one your origin sends without a Content-Length.
• Anything under /api/, /ws/, /admin, /docs, /openapi or /health, apart from /api/v1/orgs/ as above and files under /docs/assets/.

A copy stays for the time in your origin's Cache-Control header: s-maxage, else max-age, or 1 hour when it gives neither. A time of 0 keeps nothing. Coritan's network can drop a copy sooner to make room for others.

A picture, font, sound or video file has one copy whatever its query string, so /images/logo.png?v=2 gets the same copy as /images/logo.png.

An answer from a copy carries the response header X-Cache: HIT. An answer from your origin carries X-Cache: MISS, even for a page the cache never keeps. Neither header comes when the cache is off, on a request but GET and HEAD, on a request with an Authorization header, or under the paths in the last item above.

1. In the dashboard, go to Websites and open the domain.
2. Select the Caching tab.
3. If the domain has more than one hostname on Coritan's network, choose one under Settings for. Each hostname has a cache and settings of its own. The tab opens on the hostname you chose last, or on the domain itself.

On the Cache card, turn Cache on our network on or off. The change saves at once and shows Cache turned off for www.example.com. or Cache turned on for www.example.com.. While the cache is off, every request goes to your origin.

On the Cache card, choose a time under Keep copies for: As long as your origin says, 5 minutes, 1 hour, 4 hours, 1 day, 1 week or 30 days. The change saves at once and shows Cache time for www.example.com saved..

A time here replaces the one in your origin's Cache-Control header, for the files the cache keeps anyway. It does not make a page or any other file cacheable. An answer marked private or no-store, or with a time of 0, is still not kept. Keep copies for waits while the cache is off.

The people who edit your site want to see a new picture as soon as they upload it. Name the cookie your site gives to signed-in visitors, and Coritan's network sends every request that carries it to your origin.

1. On the Skip the cache for signed-in visitors card, enter the cookie's name, or the start of it, under Cookie name. Any cookie whose name starts with that text counts, so wordpress_logged_in also matches wordpress_logged_in_8f3a.
2. Select Save cookie. The card shows Saved wordpress_logged_in for www.example.com. Visitors with that cookie now skip the cache.

For a WordPress site, select Use the WordPress cookie, which saves wordpress_logged_in at once. WordPress sets it for everyone who signs in, WooCommerce customers too, and for no one else.

A cookie name has 1 to 128 characters: letters, digits and the symbols !#$%&'*+-.^_`|~, with no spaces. The card checks the name before it saves it. To let every visitor use the cache again, select Clear, or empty the field and select Save cookie.

Clear the cache after you change a file at the same address, so visitors get the new version at once. Each file then comes from your origin on its next request, and the cache keeps it again from there. You can clear the cache of each hostname 30 times in any hour. Clearing everything and clearing some files count the same, and a clear that Coritan refuses does not count.

1. On the Clear the cache card, select Clear some files….
2. Under Addresses, enter up to 30 addresses, one on each line. Each is a path, such as /images/logo.png or /pricing?plan=pro, or a full http or https address on the hostname, such as https://www.example.com/css/site.css.
3. Select Clear files.

The dialog checks the list before it sends it and names the line it cannot take: an address on another hostname, a line that is neither a path nor an address, or more than 30 lines. A path and a full address for the same file count once. When it worked, the dialog closes and shows Cleared 3 files from the cache of www.example.com..

1. On the Clear the cache card, select Clear everything….
2. Select Clear everything to confirm.

Coritan's network drops every copy it holds of the hostname's files and shows Cleared every file from the cache of www.example.com.. Pages load those files from your origin until the copies build up again.

On some other networks, a development mode turns the cache off while you work on a site. On Coritan, development mode shows your origin's address and the exact connection failure on Coritan's error pages. Visitors still get files from the cache, so clear the files you changed to see them at once.

The switch and the time save as soon as you change them, and the cookie saves when you select Save cookie. Each change shows a confirmation that names the hostname. To check one file, open your browser's developer tools and read the file's response headers: X-Cache: HIT means it came from a copy.

A visitor still sees the old version of a file

The cache serves its copy until its time runs out: the one under Keep copies for, or your origin's. Clear the file with Clear some files…. A new query string such as ?v=2 on a picture, font, sound or video file does not get it a new copy, so clear it or give it a new file name. Browsers keep their own copies too, for the time your origin gives, so reload with Ctrl+Shift+R, or Cmd+Shift+R on a Mac.

A file always answers with X-Cache: MISS

Compare its response headers with What Coritan's network keeps. The usual causes are a Set-Cookie header, private, no-store or a time of 0 in Cache-Control, a Vary header other than Accept-Encoding, a size over 10 MB or no Content-Length. A page is never kept. A visitor who has the cookie under Cookie name always gets MISS.

A file answers with no X-Cache header

The cache is off for the hostname, the request is not a GET or HEAD, it carries an Authorization header, or its path is under one of those in the last item of What Coritan's network keeps.

You cleared the cache of www.example.com 30 times in the last hour, which is the limit.

Each clear stops counting an hour after you made it, so try again later. The API answers 429 with Retry-After: 3600.

play.example.com is another website. Each address must be on www.example.com.

Each address must be on the hostname chosen under Settings for. Choose the other hostname, then clear its files there.

images/logo.png is not a path or a web address. Start it with / or https://.

Start each line with /, or with http:// or https:// and the hostname.

Cache settings come with the Pro plan

Your account is on the Free plan, so the tab shows the settings without letting you change them. Choose a plan that includes them (Choose or change your account plan). The API answers 402 with entitlement_exceeded.

• How web proxies work
• Protect a website
• View web proxy traffic

The cache settings are fields of the hostname's web proxy, and each hostname is one route. GET /api/v1/proxy/routes lists your routes with their id and domain. Change the settings with PATCH /api/v1/proxy/routes/{route_id}:

curl -X PATCH https://api.coritan.com/api/v1/proxy/routes/31 \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cache_enabled": true, "cache_max_age": 86400, "cache_bypass_cookie": "wordpress_logged_in"}'

{"message": "Route updated"}

cache_enabled

true keeps copies, false sends every request to your origin.

cache_max_age

Seconds, from 0 to 31536000. 0 or null follows your origin's Cache-Control header.

cache_bypass_cookie

A cookie name, or the start of one, of 1 to 128 characters. null or "" removes it.

A value that is not a cookie name answers 422 with "wp logged in" is not a cookie name. Use letters, digits and the symbols !#$%&'*+-.^_`|~, with no spaces., and one longer than 128 characters with A cookie name can be up to 128 characters..

Clear every file of the hostname with no body:

curl -X POST https://api.coritan.com/api/v1/proxy/routes/31/cache/purge \
  -H "Authorization: Bearer $CORITAN_TOKEN"

{"success": true, "domain": "www.example.com", "cleared": "everything"}

Clear some files with urls, 1 to 30 paths or full addresses on the hostname:

curl -X POST https://api.coritan.com/api/v1/proxy/routes/31/cache/purge \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["/images/logo.png", "https://www.example.com/images/logo.png", "/css/site.css?v=2"]}'

{"success": true, "domain": "www.example.com", "cleared": "urls", "urls": ["/images/logo.png", "/css/site.css?v=2"]}

urls in the answer lists each file once, as a path. An address on another hostname answers 422 with play.example.com is another website. Each address must be on www.example.com., and more than 30 addresses answer 422 too.

The 31st clear of a hostname in an hour answers 429 with a Retry-After header in seconds:

{
  "detail": {
    "error": "rate_limited",
    "message": "Too many requests for this action. Try again later.",
    "action": "proxy.cache_purge",
    "retry_after_seconds": 3600
  }
}

Once account plans open on your account, a plan without cache settings answers 402 with entitlement_exceeded to a clear, and to a PATCH only when cache_enabled, cache_max_age or cache_bypass_cookie would change:

{
  "detail": {
    "code": "entitlement_exceeded",
    "entitlement": "cache_controls",
    "limit": false,
    "used": 0,
    "upgrade": {"plan": "plan-pro", "addon": null},
    "message": "Your Free plan does not include cache settings. To use it, upgrade to Pro."
  }
}

A refusal for the plan or for an address does not count towards the 30 clears.