Cache

cache makes the app fast without leaking one customer's data to another: keys carry the tenant and region, and credentialed responses are never shared-cacheable.

cache.wrap memoises a call under a key that always carries the current tenant and region, runs it once per key under load, and serves a slightly stale value while it refreshes. Every response to a signed-in person or an API key goes out private, no-store unless you choose a private policy, and shared CDN caching is a declaration on a read action. Small values you set and read yourself belong in kv.

cache:
  driver: kv
  timeout: 50ms
  max-value: 256KB
  memory: { max-entries: 1000, max-ttl: 30s }

import { cache } from "mainsdk/cache";

const top = await cache.wrap("top-products", () => loadTopProducts(), { ttl: "5m", tags: ["products"] });
await cache.delete({ tag: "products" });   // every instance drops it

cache:
  driver: kv

Quick start

cache:
  driver: kv          # uses the kv store, with an in-process tier in front
  timeout: 50ms       # a slower store read is skipped; your function runs instead

import { cache } from "mainsdk/cache";

declare function loadTopProducts(): Promise<{ id: string }[]>;   // your slow query

export function topProducts() {
  return cache.wrap("top-products", () => loadTopProducts(), { ttl: "5m", swr: "1h", tags: ["products"] });
}

export function productsChanged() {
  return cache.delete({ tag: "products" });   // every instance drops it, in this tenant only
}

You should see loadTopProducts run once per tenant however many requests arrive, and run again after productsChanged.

Configuration

cache:
  driver: kv          # kv (default when the app has a kv store) | local
  timeout: 50ms
  max-value: 256KB
  memory: { max-entries: 1000, max-ttl: 30s }

What you get

scope is "tenant" by default: the stored key is t:<tenant>:r:<region>:<key>, from the current context. scope: "app" stores app:<key> for every tenant and must hold no personal data: a value with an email, phone number, card number or secret in it is not stored (MAIN-CACHE-0004), and mainsdk check refuses an app-scoped cache around a db read (MAIN-CACHE-0012).

Share a read action with a CDN

Shared caching is a declaration on a read action, never a header you write by hand.

import { action, s } from "mainsdk";
import { serveRead } from "mainsdk/cache";

declare function loadProducts(): Promise<{ id: string }[]>;   // your catalogue query

export const listProducts = action({
  name: "products.list", intent: "List the public catalogue", risk: "read",
  input: s.object({}),
  http: { method: "GET", path: "/products", cache: { scope: "public", maxAge: "60s", swr: "5m" } },
  run: () => loadProducts(),
});

// in the route handler:  return serveRead(listProducts, request, { log });

The response carries Cache-Control: public, max-age=60, stale-while-revalidate=300 and a weak ETag; a request with a matching If-None-Match gets 304 after the access check, so a caller without access still gets their 403. If run reads the session, an API key or the tenant, the response goes out private, no-store and the error MAIN-CACHE-0002 is logged. A public action with no permission is open to everyone. scope: "private" with maxAge gives private, max-age=<s> on any read action.

What it always does

• Keys carry the tenant and region; no call can read another tenant's entry (ADR-0073).
• A response to a request with a session cookie, an Authorization header, an API key or a new cookie goes out private, no-store, and a public, s-maxage or bare max-age directive set by a handler is replaced, its CDN-Cache-Control removed, and the route logged once (MAIN-CACHE-0001). Every adapter applies this after your handler.
• A slow or failed cache store never fails or blocks a request (MAIN-CACHE-0005).
• Read actions answer with an ETag and a 304 after the access check.
• Deleting a key or tag reaches every instance through events.broadcast; if the broadcast fails, in-process entries expire within cache.memory.max-ttl.
• Erasing a tenant deletes every entry under its prefix.

Errors and checks

Each code's cause and fix is in check codes.

Swapping drivers

Change driver in main.yaml. kv shares entries across instances through the kv store, so a delete reaches all of them. local keeps entries in each process and needs no store. cache.wrap, cache.get, cache.set and cache.delete do not change.

Testing

Build the app with createTestApp() and the local driver, and the cache runs in process with no store. new Cache(opts) takes a store and a clock for the slow-store and expiry cases. See Test your app.

Helpers for wiring and tests

Next

• Key-value store
• Typed API and OpenAPI document
• Tenants
• Cache safely