Caching

After this page you know what MDRN caches for your app on its own, how to have MDRN cache your app’s responses at the edge, how your code keeps responses in a cache of its own, how long each lasts, and what is never cached. Static files and requests your app makes need no setup; your app’s own responses are cached only when it asks.

What MDRN caches for you

Cache your app’s responses

MDRN keeps a response your app marks as cacheable at our network’s edge and gives it to the next visitor who asks the same address, without running your code. Mark it with one header:

export default {
  async fetch(request) {
    return new Response("<h1>Prices</h1>", {
      headers: {
        "Content-Type": "text/html",
        "MDRN-Cache-Control": "max-age=60, stale-while-revalidate=300",
      },
    });
  },
};

Each location of our network keeps its own copy, so the first visitor in each location runs your code. A new release, a rollback or a change to variables starts with nothing cached. You cannot clear the cache by hand yet: deploy, or keep the time short.

Never cached

MDRN never serves a cached response to a request that could get someone’s own answer, and never keeps a response that could be someone’s own. Whatever your headers say, these are never cached:

• a request that is not GET or HEAD, asks for part of a file (Range), or opens a WebSocket;
• a request that carries any cookie or an Authorization header, and every request of a signed-in visitor;
• a request that carries any header a browser does not send by itself, such as an API key, Origin, X-Forwarded-Host or X-HTTP-Method-Override;
• MDRN’s own sign-in paths, your sign-in and account pages, and every page that needs a signed-in visitor;
• a deployment only its owner can open (while you build);
• a response that sets a cookie (Set-Cookie), or says private in Cache-Control, even beside MDRN-Cache-Control;
• a response whose Vary names anything but Accept-Encoding and Next.js’s own router headers;
• a response with a status not listed above, a body your app compressed itself, an empty 200 without Content-Length: 0, or a body that does not match its Content-Length.

A HEAD request is answered from a kept GET, but never fills the cache. A cached response is the same for every visitor: never mark a page that depends on who asks, such as their country, their address or their language, unless the address says it (/de/, ?lang=de). MDRN cannot tell that a page differs by country, and would give one visitor’s page to the next.

Identical requests that arrive together, for an address whose last response was kept, wait for one run of your code and all get its response, when that response may be kept. If it may not (it sets a cookie, say), each runs your code itself.

See what happened

Every response MDRN considered caching says what it did:

A response your app did not mark, with auto cache off, gets no x-mdrn-cache header and works exactly as before.

Examples

A Hono route:

app.get("/blog/:slug", async (c) => {
  const post = await loadPost(c.req.param("slug"));
  c.header("MDRN-Cache-Control", "max-age=300, stale-while-revalidate=3600");
  return c.html(render(post));
});

With the SDK, cache and noCache write the header for you (SDK):

import { cache } from "@mdrnio/sdk";

return cache(Response.json(prices), { maxAge: 60, staleWhileRevalidate: 300 });

Next.js needs nothing: a page with revalidate, or one built ahead of time, already answers Cache-Control: s-maxage=<seconds>, usually with stale-while-revalidate, which MDRN follows (Frameworks). A route handler sets its own:

export async function GET() {
  return Response.json(await prices(), {
    headers: { "Cache-Control": "s-maxage=60, stale-while-revalidate=300" },
  });
}

To have pages that set no caching header cached for 10 seconds, turn on auto cache for the deployment, in its Configuration tab or from the CLI. Your own headers still win, no-store and private included.

mdrn deployments set <deployment_id> --auto-cache on

What a cached response costs

A response given out from the cache is one request on your Requests, with no CPU time: your code did not run (Billing). A refresh in the background runs your code, and counts as a request with its CPU time like any other.

Cache in your code

Your app has a cache of its own through the standard Cache API. Put a response under a GET request’s URL and match it on a later request:

export default {
  async fetch(request, env, ctx) {
    const cache = caches.default;
    const hit = await cache.match(request);
    if (hit) return hit;
    const upstream = await fetch("https://<api-you-call>/<path>");
    const response = new Response(upstream.body, upstream);
    response.headers.set("Cache-Control", "public, max-age=300");
    ctx.waitUntil(cache.put(request, response.clone()));
    return response;
  },
};

caches.default and caches.open("<name>") both work, and code written for either runs unchanged:

• caches.default is your app’s cache named default, the same one caches.open("default") gives.
• caches.open("<name>") gives another cache of your app’s own; two names are two caches.
• A response is kept for as long as its Cache-Control says, and may be dropped sooner when the location needs the room. Treat a miss as normal.
• Only a GET request can be a key. A response marked no-store, or one that sets a cookie, is not kept.
• In a Python app, use caches.open("<name>"): there caches.default refuses every call.

How long your app’s cache lasts

What does not work

Request and time limits your code runs within are on Limits; every error code is on Errors.