completefrontend

Write the codeHard

Write a "use cache: remote" cache handler that three self-hosted servers share, tags included

Leaf and Kettle self-hosts on three containers behind a load balancer. Its tea pages read prices through "use cache: remote", and next.config.ts points cacheHandlers.remote at this handler, cache-handlers/remote.ts (compiled, since Next.js imports a handler with Node, outside the bundler). Today it keeps everything in its own process: each container computes every price itself, and a revalidateTag that reaches one container is news to the other two. Rewrite it on the shop's shared key-value store, @/lib/kv.

Export createRemoteHandler(store), which returns a handler with Next.js's five methods for that store; the default export is createRemoteHandler(kv). The tests make one handler per container, all on one store. Store entries in the store, which keeps copies, so it can't hold the entry's ReadableStream: read the stream into bytes in set(), and give each get() a new stream over them. Store each entry with its expire as the store's ttlSeconds, so the store drops what can never be used again. A value whose stream fails part-way is never stored, and neither get() nor set() ever throws: a failed read is a miss, undefined.

updateTags(tags, durations) records when each tag was revalidated, in this container and in the store's cache-tags hash, one field per tag. Without durations, from updateTag or revalidatePath, the tag is expired from now. With them, from revalidateTag(tag, profile), it's stale from now and expired durations.expire seconds later. refreshTags(), which Next.js calls before a request first reads this cache, copies the store's tag times into this container. get() checks the entry's tags against this container's copy: an entry made before a tag's expiry is a miss once that time has come, and one made before a tag went stale comes back with revalidate: -1, so Next.js serves it and refreshes it in the background. getExpiration(tags) is the latest expiry among the tags, or 0. Read the time with Date.now(): an entry's timestamp is in the same milliseconds.

// What Next.js hands set() (as a promise) and expects back from get():
type CacheEntry = {
  value: ReadableStream<Uint8Array>; // the cached result, readable once
  tags: string[];
  stale: number; // seconds the browser may reuse it
  timestamp: number; // when it was made, in milliseconds since 1970
  expire: number; // seconds until it may no longer be served
  revalidate: number; // seconds until it should be refreshed in the background
};
Write this: cache-handlers/remote.ts
import type { CacheEntry, CacheHandler } from "next/cache";
import { kv, type Kv } from "@/lib/kv";
 
type Stored = Omit<CacheEntry, "value"> & { value: Uint8Array };
 
export function createRemoteHandler(store: Kv): CacheHandler {
  // Everything lives in this process: the other containers never see it.
  const entries = new Map<string, Stored>();
 
  return {
    async get(cacheKey) {
      const stored = entries.get(cacheKey);
      if (!stored) return undefined;
      const bytes = stored.value;
      return {
        ...stored,
        value: new ReadableStream({
          start(controller) {
            controller.enqueue(bytes);
            controller.close();
          },
        }),
      };
    },
    async set(cacheKey, pendingEntry) {
      const entry = await pendingEntry;
      const value = new Uint8Array(await new Response(entry.value).arrayBuffer());
      entries.set(cacheKey, { ...entry, value });
    },
    async refreshTags() {},
    async getExpiration() {
      return 0;
    },
    async updateTags() {},
  };
}
 
export default createRemoteHandler(kv);
lib/kv.ts (read-only)
/**
 * A stand-in for the shop's Redis: one store that every container talks to. Like a network store,
 * it keeps copies of what it's given (made with structuredClone), so it can't hold a stream, and a
 * key stored with `ttlSeconds` disappears once they have passed.
 */
export function createKv() {
  const rows = new Map<string, { value: unknown; until: number }>();
  const hashes = new Map<string, Map<string, unknown>>();
  /** Every set() call, for tests: the key and the ttlSeconds it was given. */
  const log: { key: string; ttlSeconds?: number }[] = [];
 
  return {
    log,
    /** A copy of the value stored under `key`, or undefined. */
    async get<T>(key: string): Promise<T | undefined> {
      const row = rows.get(key);
      if (!row || Date.now() >= row.until) return undefined;
      return structuredClone(row.value) as T;
    },
    /** Stores a copy of `value` under `key`, for `ttlSeconds` seconds when given. */
    async set(key: string, value: unknown, options: { ttlSeconds?: number } = {}): Promise<void> {
      const copy = structuredClone(value);
      const until = options.ttlSeconds === undefined ? Infinity : Date.now() + options.ttlSeconds * 1000;
      rows.set(key, { value: copy, until });
      log.push({ key, ttlSeconds: options.ttlSeconds });
    },
    /** Sets one field of the hash at `key`: writers of different fields never overwrite each other. */
    async hset(key: string, field: string, value: unknown): Promise<void> {
      const hash = hashes.get(key) ?? new Map<string, unknown>();
      hash.set(field, structuredClone(value));
      hashes.set(key, hash);
    },
    /** A copy of every field of the hash at `key`, as an object, or {} when there's none. */
    async hgetall<T>(key: string): Promise<Record<string, T>> {
      return structuredClone(Object.fromEntries(hashes.get(key) ?? new Map())) as Record<string, T>;
    },
  };
}
 
export type Kv = ReturnType<typeof createKv>;
 
/** The store all three containers use. */
export const kv = createKv();
The tests your code must pass
  • set stores an entry, and get serves it as a new stream every time
  • what one container stores, the others serve
  • updateTag on one container is a miss there at once, and on the others after refreshTags
  • revalidateTag with a profile is served stale, revalidate -1, until its expire, then a miss
  • getExpiration is 0 for tags never expired, and the latest expiry otherwise, on every container
  • entries are stored with their expire as the store's TTL
  • a value that fails part-way is never stored, and failures are misses, not errors

The answer

Write it yourself first. Then compare it with a reference solution and the checks it passes.

Checking your sign-in…