> [Agent navigation index](/llms.txt)

# Cache stores and edge hints

Choose provider-native shared stores for replicas and keep native data caching separate from route-level edge policy hints.

## Use provider-native stores for replicas

The default memory store is process-local. When replicas must share cached data, pass a
provider-native store with a stable namespace:

`src/brix.server.ts`

```ts
"use server";

import { createDynamoDataCacheStore } from "brix/cache/dynamodb";
import { defineBrixServer } from "brix/server";
import { brix } from "./brix.ts";
import { env } from "./env.server.ts";

export const brixServer = defineBrixServer(brix, {
  env,
  dataCache: {
    namespace: "storefront-production",
    store: createDynamoDataCacheStore({
      tableName: "storefront-data-cache",
      region: "eu-west-1",
    }),
  },
});
export const { dataCache } = brixServer;

```

Each adapter is server-only and supported on one platform: DynamoDB on `platform: "lambda"` and
Fastly KV on `platform: "fastly"`. Brix rejects importing an adapter when building for another
platform; the DynamoDB adapter is also rejected in development on other platforms. Only the Brix
adapter is restricted: other platforms can import the AWS SDK directly, for example to supply a
[custom store](#write-a-custom-store).

### Use DynamoDB

Provision one string partition key named `pk`, no sort key or indexes, and TTL on `expiresAt`. Grant least-privilege GetItem and PutItem access. The adapter does not provision infrastructure. `tableName` must be a valid DynamoDB table name. `region` and `endpoint` configure the SDK client and otherwise follow the normal AWS configuration chain; a supplied `client` replaces both. `strong` defaults to `false`; when true, every native GetItem uses `ConsistentRead`, which costs twice the read capacity of an eventually consistent read. The adapter does not use transactions.

Entries expire logically at `staleUntil`; provider TTL performs cleanup. Per-tag invalidation tokens live for 30 days plus 60 seconds. There are no global revisions, but every entry depends on at least three marker items: one for the whole namespace (used by `invalidateAll()`), one per API contract, and one per cache key, plus one per custom tag. A cache read fetches the entry and then each marker it depends on, and a write reads the same markers before storing.

The namespace and contract markers are single items shared by every read in the namespace, and DynamoDB serves one item at roughly 3,000 read capacity units per second. To keep hot markers under that ceiling, each process reuses a token it has read for `tagTokenCacheMs` milliseconds (default `1000`, maximum `60000`). A steady cache hit then costs one entry GetItem, and each process reads each marker at most once per window. Invalidation through the same process takes effect immediately; other processes observe it once their reused token expires, in addition to DynamoDB's own replication delay. With `strong: true`, `tagTokenCacheMs` defaults to `0` and every operation reads every marker, so only use it when shared-marker read rates stay well below the per-item ceiling. Set `tagTokenCacheMs` explicitly to trade invalidation latency for capacity in either mode. Without S3 overflow, writes above the conservative 380 KiB estimated item limit fail open: the origin response still succeeds, but is not cached.

### Store oversized values in S3

Enable overflow with a separately provisioned bucket:

```ts
const store = createDynamoDataCacheStore({
  tableName: "storefront-data-cache",
  region: "eu-west-1",
  overflow: { bucketName: "storefront-cache-overflow" },
});

```

Small values stay inline in DynamoDB. Oversized values upload to unique S3 objects before DynamoDB stores their references, expiry, and invalidation metadata. Reads check expiry and invalidation before downloading the object, then recheck expiry afterward. When `staleIfError` serves an overflow value after a transient origin failure, Brix confirms that the entry's metadata, tag tokens, and S3 reference are unchanged rather than downloading the object again. Storage failures fail open through the data-cache coordinator; S3 does not replace DynamoDB during a DynamoDB outage.

Grant `s3:GetObject` and `s3:PutObject` on the cache prefix, and configure bucket encryption and access controls. The default prefix is `brix-data-cache/`; set `overflow.keyPrefix` to choose another prefix (at most 512 UTF-8 bytes). S3 inherits the top-level `region` and uses the normal AWS credential chain. Optional `overflow.region`, `overflow.endpoint`, and `overflow.client` support custom configuration; the DynamoDB endpoint is never inherited.

Configure bucket lifecycle expiration after **at least 31 days**, covering the maximum 30-day cache retention plus margin. DynamoDB TTL does not delete S3 objects. Lifecycle cleanup removes superseded objects and uploads left behind by failed publication; versioned buckets also need noncurrent-version expiration. HTTP `Expires` metadata is not a cleanup rule.

Keep the bucket and prefix stable across replicas and configure readers before enabling overflow writes. Changing either makes existing references unreadable. The default cache-operation deadline remains one second for the entire DynamoDB/S3 operation. Measure latency and adjust `createDataCache({ operationTimeoutMs })` when needed.

When a request has Brix timings, each actual DynamoDB or overflow S3 operation is reported as `cache.dynamodb`, including overflow body reads. Cache hits, misses, and failed writes are timed without wrapping the origin load. Process-local memory operations are not reported as external dependencies.

### Use Fastly KV

On Fastly, provision a KV store, link it to the Compute service under the name you pass as
`storeName`, and use the native adapter:

```ts
import { createFastlyKvDataCacheStore } from "brix/cache/fastly";

const store = createFastlyKvDataCacheStore({ storeName: "storefront-data-cache" });

```

Native KV handles are request-scoped, so the adapter opens one per store operation; create the store
once and use it only while handling requests. Fastly KV has no strong-read option. It limits writes to the same key to about one per second. Each invalidation writes one marker per tag, so invalidating the same tag, including `invalidateAll()`, more often than that can be rejected; the awaited invalidation rejects, so retry it with backoff and coalesce webhook bursts. Concurrent misses for one hot key can also lose entry writes, which fail open to the origin result. Native KV operations do not accept an abort signal: Brix checks cancellation before submitting work and bounds how long callers wait, but an already-submitted write may finish after cancellation.

With `platform: "fastly"`, `brix dev` runs native KV in the real Viceroy runtime using the root `fastly.toml` `local_server` fixtures. Entry and marker TTL rules match DynamoDB. Neither adapter purges CDN or browser caches. Treat Fastly KV as provider-visible storage and avoid sensitive data unless its controls and your threat model explicitly permit it.

Each native KV get (including its body read) or put is reported as `cache.fastly` when request timings are available. This includes misses, provider errors, writes, and invalidation puts.

Both stores use separate entry and per-tag-token operations, so invalidation is eventual. They suit non-authoritative cached data where bounded staleness is acceptable, not correctness-critical state.

## Write a custom store

`createDataCache({ store })` and server `dataCache.store` accept any `DataCacheStore` from
`brix/cache`. It has three methods, each receiving `{ signal, timings? }` as its final argument:

```ts
import type { DataCacheStore } from "brix/cache";

export const store: DataCacheStore = {
  async read(namespace, key, { signal }) {
    signal.throwIfAborted();
    // Resolve the current DataCacheEntry, or undefined when absent, expired, or invalidated.
    return undefined;
  },
  async write(namespace, key, entry, { signal }) {
    signal.throwIfAborted();
    // Replace any existing entry for this namespace and key, including its tags.
  },
  async invalidate(namespace, tags, { signal }) {
    signal.throwIfAborted();
    // Make every entry in this namespace carrying any of these tags unreadable.
  },
};

```

An entry is `{ value, freshUntil, staleUntil, tags }`. `value` is a JSON string: return it
unchanged. `freshUntil` and `staleUntil` are epoch milliseconds, with `freshUntil <= staleUntil`.
`tags` are opaque dependency tokens; the coordinator also uses tags to implement contract and
`invalidateAll()` invalidation, so a store needs no other invalidation mechanism. A conforming
store:

- keeps returning an entry after `freshUntil` until `staleUntil`, then returns `undefined`;
- never returns an entry written before an invalidation of one of its tags. The bundled distributed stores record a token for each tag at write time and compare tokens on read, so invalidation is eventual rather than transactional;
- isolates namespaces and lets a later write replace an earlier entry, including its tags;
- returns copies rather than objects that callers can mutate later;
- may rely on entries living at most 30 days and carrying at most 64 tags, which the coordinator never exceeds; the bundled distributed stores reject larger entries;
- keeps invalidation state for at least 30 days plus a clock margin, the longest an entry can live;
- checks `signal` before I/O and rejects with its reason once aborted.

Throw on provider failures. The coordinator fails reads and writes open to the origin and makes `invalidate` reject. A stored entry that fails to parse or validate is reported as a `corrupt` read event and treated as a miss. Report provider I/O to `timings` when it is present so request logs attribute store latency. Verify an adapter with [`testDataCacheStore`](/docs/testing.md#test-a-data-cache-store) from `brix/test`.

## Route edge hints are different

Route `cache` options are a separate system. Declare policy names on the server, then reference one
from a page or fragment route:

`src/brix.server.ts`

```ts
export const brixServer = defineBrixServer(brix, {
  env,
  cachePolicies: ["publicPage", "sharedChrome"] as const,
});

```

```ts
import { createPageRoute } from "#brix/server";
import { productPageContract } from "./contract.ts";
import { ProductPage } from "./Page.tsx";

export const productPageRoute = createPageRoute(productPageContract, {
  cache: "publicPage",
  component: ProductPage,
});

```

Policy names are manifest hints, not an in-process response cache. Brix never stores route
responses, chooses TTLs, or purges entries. Your edge maps names to provider policy and uses the
`decidePageCache` and `decideFragmentCache` helpers from `brix/edge` to decide admission. Omitted
`cache` and `cache: false` are uncached.

Routes with `auth` cannot declare a shared cache policy: this is a type error and fails route
creation. Authenticated responses default to `Cache-Control: private`, and the edge decision
helpers bypass authenticated routes and any request carrying `Authorization`. Keep other
user-specific pages uncached too. Translation locale and HTML/Markdown representation must be in
edge identity; opaque locale selection fails closed. See
[edge composition](/docs/fragments-composition.md#cache-and-compose-at-the-edge) for page query policy
and the manifest, and [translations](/docs/translations.md) for locale partitioning.
