Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / APIs and data / Data cachingRead Markdown
    On this page

    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
    "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.

    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:

    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:

    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:

    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 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
    export const brixServer = defineBrixServer(brix, {
      env,
      cachePolicies: ["publicPage", "sharedChrome"] as const,
    });
    
    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 for page query policy and the manifest, and translations for locale partitioning.