@opennextjs/cloudflare 0.5.11 → 0.6.0

package/dist/api/overrides/tag-cache/do-sharded-tag-cache.js

@@ -0,0 +1,247 @@
+import { debug, error } from "@opennextjs/aws/adapters/logger.js";
+import { generateShardId } from "@opennextjs/aws/core/routing/queue.js";
+import { IgnorableError } from "@opennextjs/aws/utils/error.js";
+import { getCloudflareContext } from "../../cloudflare-context";
+const SOFT_TAG_PREFIX = "_N_T_/";
+export const DEFAULT_SOFT_REPLICAS = 4;
+export const DEFAULT_HARD_REPLICAS = 2;
+export const DEFAULT_WRITE_RETRIES = 3;
+export const DEFAULT_NUM_SHARDS = 4;
+export class TagCacheDOId {
+    options;
+    shardId;
+    replicaId;
+    constructor(options) {
+        this.options = options;
+        const { baseShardId, shardType, numberOfReplicas, replicaId } = options;
+        this.shardId = `tag-${shardType};${baseShardId}`;
+        this.replicaId = replicaId ?? this.generateRandomNumberBetween(1, numberOfReplicas);
+    }
+    generateRandomNumberBetween(min, max) {
+        return Math.floor(Math.random() * (max - min + 1) + min);
+    }
+    get key() {
+        return `${this.shardId};replica-${this.replicaId}`;
+    }
+}
+class ShardedDOTagCache {
+    opts;
+    mode = "nextMode";
+    name = "do-sharded-tag-cache";
+    numSoftReplicas;
+    numHardReplicas;
+    maxWriteRetries;
+    localCache;
+    constructor(opts = { baseShardSize: DEFAULT_NUM_SHARDS }) {
+        this.opts = opts;
+        this.numSoftReplicas = opts.shardReplicationOptions?.numberOfSoftReplicas ?? DEFAULT_SOFT_REPLICAS;
+        this.numHardReplicas = opts.shardReplicationOptions?.numberOfHardReplicas ?? DEFAULT_HARD_REPLICAS;
+        this.maxWriteRetries = opts.maxWriteRetries ?? DEFAULT_WRITE_RETRIES;
+    }
+    getDurableObjectStub(doId) {
+        const durableObject = getCloudflareContext().env.NEXT_TAG_CACHE_DO_SHARDED;
+        if (!durableObject)
+            throw new IgnorableError("No durable object binding for cache revalidation");
+        const id = durableObject.idFromName(doId.key);
+        return durableObject.get(id);
+    }
+    /**
+     * Generates a list of DO ids for the shards and replicas
+     * @param tags The tags to generate shards for
+     * @param shardType Whether to generate shards for soft or hard tags
+     * @param generateAllShards Whether to generate all shards or only one
+     * @returns An array of TagCacheDOId and tag
+     */
+    generateDOIdArray({ tags, shardType, generateAllReplicas = false, }) {
+        let replicaIndexes = [1];
+        const isSoft = shardType === "soft";
+        let numReplicas = 1;
+        if (this.opts.enableShardReplication) {
+            numReplicas = isSoft ? this.numSoftReplicas : this.numHardReplicas;
+            replicaIndexes = generateAllReplicas
+                ? Array.from({ length: numReplicas }, (_, i) => i + 1)
+                : [undefined];
+        }
+        return replicaIndexes.flatMap((replicaId) => {
+            return tags
+                .filter((tag) => (isSoft ? tag.startsWith(SOFT_TAG_PREFIX) : !tag.startsWith(SOFT_TAG_PREFIX)))
+                .map((tag) => {
+                return {
+                    doId: new TagCacheDOId({
+                        baseShardId: generateShardId(tag, this.opts.baseShardSize, "shard"),
+                        numberOfReplicas: numReplicas,
+                        shardType,
+                        replicaId,
+                    }),
+                    tag,
+                };
+            });
+        });
+    }
+    /**
+     * Same tags are guaranteed to be in the same shard
+     * @param tags
+     * @returns An array of DO ids and tags
+     */
+    groupTagsByDO({ tags, generateAllReplicas = false }) {
+        // Here we'll start by splitting soft tags from hard tags
+        // This will greatly increase the cache hit rate for the soft tag (which are the most likely to cause issue because of load)
+        const softTags = this.generateDOIdArray({ tags, shardType: "soft", generateAllReplicas });
+        const hardTags = this.generateDOIdArray({ tags, shardType: "hard", generateAllReplicas });
+        const tagIdCollection = [...softTags, ...hardTags];
+        // We then group the tags by DO id
+        const tagsByDOId = new Map();
+        for (const { doId, tag } of tagIdCollection) {
+            const doIdString = doId.key;
+            const tagsArray = tagsByDOId.get(doIdString)?.tags ?? [];
+            tagsArray.push(tag);
+            tagsByDOId.set(doIdString, {
+                // We override the doId here, but it should be the same for all tags
+                doId,
+                tags: tagsArray,
+            });
+        }
+        const result = Array.from(tagsByDOId.values());
+        return result;
+    }
+    async getConfig() {
+        const cfEnv = getCloudflareContext().env;
+        const db = cfEnv.NEXT_TAG_CACHE_DO_SHARDED;
+        if (!db)
+            debug("No Durable object found");
+        const isDisabled = !!globalThis.openNextConfig
+            .dangerous?.disableTagCache;
+        return !db || isDisabled
+            ? { isDisabled: true }
+            : {
+                isDisabled: false,
+                db,
+            };
+    }
+    /**
+     * This function checks if the tags have been revalidated
+     * It is never supposed to throw and in case of error, it will return false
+     * @param tags
+     * @param lastModified default to `Date.now()`
+     * @returns
+     */
+    async hasBeenRevalidated(tags, lastModified) {
+        const { isDisabled } = await this.getConfig();
+        if (isDisabled)
+            return false;
+        try {
+            const shardedTagGroups = this.groupTagsByDO({ tags });
+            const shardedTagRevalidationOutcomes = await Promise.all(shardedTagGroups.map(async ({ doId, tags }) => {
+                const cachedValue = await this.getFromRegionalCache(doId, tags);
+                if (cachedValue) {
+                    return (await cachedValue.text()) === "true";
+                }
+                const stub = this.getDurableObjectStub(doId);
+                const _hasBeenRevalidated = await stub.hasBeenRevalidated(tags, lastModified);
+                //TODO: Do we want to cache the result if it has been revalidated ?
+                // If we do so, we risk causing cache MISS even though it has been revalidated elsewhere
+                // On the other hand revalidating a tag that is used in a lot of places will cause a lot of requests
+                if (!_hasBeenRevalidated) {
+                    getCloudflareContext().ctx.waitUntil(this.putToRegionalCache(doId, tags, _hasBeenRevalidated));
+                }
+                return _hasBeenRevalidated;
+            }));
+            return shardedTagRevalidationOutcomes.some((result) => result);
+        }
+        catch (e) {
+            error("Error while checking revalidation", e);
+            return false;
+        }
+    }
+    /**
+     * This function writes the tags to the cache
+     * Due to the way shards and regional cache are implemented, the regional cache may not be properly invalidated
+     * @param tags
+     * @returns
+     */
+    async writeTags(tags) {
+        const { isDisabled } = await this.getConfig();
+        if (isDisabled)
+            return;
+        const shardedTagGroups = this.groupTagsByDO({ tags, generateAllReplicas: true });
+        // We want to use the same revalidation time for all tags
+        const currentTime = Date.now();
+        await Promise.all(shardedTagGroups.map(async ({ doId, tags }) => {
+            await this.performWriteTagsWithRetry(doId, tags, currentTime);
+        }));
+    }
+    async performWriteTagsWithRetry(doId, tags, lastModified, retryNumber = 0) {
+        try {
+            const stub = this.getDurableObjectStub(doId);
+            await stub.writeTags(tags, lastModified);
+            // Depending on the shards and the tags, deleting from the regional cache will not work for every tag
+            await this.deleteRegionalCache(doId, tags);
+        }
+        catch (e) {
+            error("Error while writing tags", e);
+            if (retryNumber >= this.maxWriteRetries) {
+                error("Error while writing tags, too many retries");
+                // Do we want to throw an error here ?
+                await getCloudflareContext().env.NEXT_TAG_CACHE_DO_SHARDED_DLQ?.send({
+                    failingShardId: doId.key,
+                    failingTags: tags,
+                    lastModified,
+                });
+                return;
+            }
+            await this.performWriteTagsWithRetry(doId, tags, lastModified, retryNumber + 1);
+        }
+    }
+    // Cache API
+    async getCacheInstance() {
+        if (!this.localCache && this.opts.regionalCache) {
+            this.localCache = await caches.open("sharded-do-tag-cache");
+        }
+        return this.localCache;
+    }
+    async getCacheKey(doId, tags) {
+        return new Request(new URL(`shard/${doId.shardId}?tags=${encodeURIComponent(tags.join(";"))}`, "http://local.cache"));
+    }
+    async getFromRegionalCache(doId, tags) {
+        try {
+            if (!this.opts.regionalCache)
+                return;
+            const cache = await this.getCacheInstance();
+            if (!cache)
+                return;
+            const key = await this.getCacheKey(doId, tags);
+            return cache.match(key);
+        }
+        catch (e) {
+            error("Error while fetching from regional cache", e);
+            return;
+        }
+    }
+    async putToRegionalCache(doId, tags, hasBeenRevalidated) {
+        if (!this.opts.regionalCache)
+            return;
+        const cache = await this.getCacheInstance();
+        if (!cache)
+            return;
+        const key = await this.getCacheKey(doId, tags);
+        await cache.put(key, new Response(`${hasBeenRevalidated}`, {
+            headers: { "cache-control": `max-age=${this.opts.regionalCacheTtlSec ?? 5}` },
+        }));
+    }
+    async deleteRegionalCache(doId, tags) {
+        // We never want to crash because of the cache
+        try {
+            if (!this.opts.regionalCache)
+                return;
+            const cache = await this.getCacheInstance();
+            if (!cache)
+                return;
+            const key = await this.getCacheKey(doId, tags);
+            await cache.delete(key);
+        }
+        catch (e) {
+            debug("Error while deleting from regional cache", e);
+        }
+    }
+}
+export default (opts) => new ShardedDOTagCache(opts);

package/dist/api/overrides/tag-cache/do-sharded-tag-cache.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api/overrides/tag-cache/do-sharded-tag-cache.spec.js

@@ -0,0 +1,322 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import doShardedTagCache, { DEFAULT_HARD_REPLICAS, DEFAULT_SOFT_REPLICAS, TagCacheDOId, } from "./do-sharded-tag-cache";
+const hasBeenRevalidatedMock = vi.fn();
+const writeTagsMock = vi.fn();
+const idFromNameMock = vi.fn();
+const getMock = vi
+    .fn()
+    .mockReturnValue({ hasBeenRevalidated: hasBeenRevalidatedMock, writeTags: writeTagsMock });
+const waitUntilMock = vi.fn().mockImplementation(async (fn) => fn());
+const sendDLQMock = vi.fn();
+vi.mock("../../cloudflare-context", () => ({
+    getCloudflareContext: () => ({
+        env: {
+            NEXT_TAG_CACHE_DO_SHARDED: { idFromName: idFromNameMock, get: getMock },
+            NEXT_TAG_CACHE_DO_SHARDED_DLQ: {
+                send: sendDLQMock,
+            },
+        },
+        ctx: { waitUntil: waitUntilMock },
+    }),
+}));
+describe("DOShardedTagCache", () => {
+    afterEach(() => vi.clearAllMocks());
+    describe("generateShardId", () => {
+        it("should generate a shardId", () => {
+            const cache = doShardedTagCache();
+            const expectedResult = [
+                { doId: expect.objectContaining({ shardId: "tag-hard;shard-1" }), tags: ["tag1"] },
+                { doId: expect.objectContaining({ shardId: "tag-hard;shard-2" }), tags: ["tag2"] },
+            ];
+            const result = cache.groupTagsByDO({ tags: ["tag1", "tag2"] });
+            expect(result).toEqual(expectedResult);
+            expect(result[0]?.doId.key).toBe("tag-hard;shard-1;replica-1");
+            expect(result[1]?.doId.key).toBe("tag-hard;shard-2;replica-1");
+        });
+        it("should group tags by shard", () => {
+            const cache = doShardedTagCache();
+            const expectedResult = [
+                { doId: expect.objectContaining({ shardId: "tag-hard;shard-1" }), tags: ["tag1", "tag6"] },
+            ];
+            const result = cache.groupTagsByDO({ tags: ["tag1", "tag6"] });
+            expect(result).toEqual(expectedResult);
+            expect(result[0]?.doId.key).toBe("tag-hard;shard-1;replica-1");
+        });
+        it("should generate the same shardId for the same tag", () => {
+            const cache = doShardedTagCache();
+            const firstResult = cache.groupTagsByDO({ tags: ["tag1"] });
+            const secondResult = cache.groupTagsByDO({ tags: ["tag1", "tag3", "tag4"] });
+            expect(firstResult[0]).toEqual(secondResult[0]);
+        });
+        it("should split hard and soft tags", () => {
+            const cache = doShardedTagCache();
+            const expectedResult = [
+                { doId: expect.objectContaining({ shardId: "tag-soft;shard-3" }), tags: ["_N_T_/tag1"] },
+                { doId: expect.objectContaining({ shardId: "tag-hard;shard-1", replicaId: 1 }), tags: ["tag1"] },
+            ];
+            const result = cache.groupTagsByDO({ tags: ["tag1", "_N_T_/tag1"] });
+            expect(result).toEqual(expectedResult);
+            expect(result[1]?.doId.key).toBe("tag-hard;shard-1;replica-1");
+            expect(result[0]?.doId.key).toBe("tag-soft;shard-3;replica-1");
+        });
+        describe("with shard replication", () => {
+            it("should generate all doIds if generateAllReplicas is true", () => {
+                const cache = doShardedTagCache({ baseShardSize: 4, enableShardReplication: true });
+                const expectedResult = [
+                    { doId: expect.objectContaining({ shardId: "tag-soft;shard-3" }), tags: ["_N_T_/tag1"] },
+                    { doId: expect.objectContaining({ shardId: "tag-soft;shard-3" }), tags: ["_N_T_/tag1"] },
+                    { doId: expect.objectContaining({ shardId: "tag-soft;shard-3" }), tags: ["_N_T_/tag1"] },
+                    { doId: expect.objectContaining({ shardId: "tag-soft;shard-3" }), tags: ["_N_T_/tag1"] },
+                    { doId: expect.objectContaining({ shardId: "tag-hard;shard-1" }), tags: ["tag1"] },
+                    { doId: expect.objectContaining({ shardId: "tag-hard;shard-1" }), tags: ["tag1"] },
+                ];
+                const result = cache.groupTagsByDO({ tags: ["tag1", "_N_T_/tag1"], generateAllReplicas: true });
+                expect(result).toEqual(expectedResult);
+            });
+            it("should generate only one doIds by tag type if generateAllReplicas is false", () => {
+                const cache = doShardedTagCache({ baseShardSize: 4, enableShardReplication: true });
+                const shardedTagCollection = cache.groupTagsByDO({
+                    tags: ["tag1", "_N_T_/tag1"],
+                    generateAllReplicas: false,
+                });
+                expect(shardedTagCollection.length).toBe(2);
+                const firstDOId = shardedTagCollection[0]?.doId;
+                const secondDOId = shardedTagCollection[1]?.doId;
+                expect(firstDOId?.shardId).toBe("tag-soft;shard-3");
+                expect(secondDOId?.shardId).toBe("tag-hard;shard-1");
+                // We still need to check if the last part is between the correct boundaries
+                expect(firstDOId?.replicaId).toBeGreaterThanOrEqual(1);
+                expect(firstDOId?.replicaId).toBeLessThanOrEqual(DEFAULT_SOFT_REPLICAS);
+                expect(secondDOId?.replicaId).toBeGreaterThanOrEqual(1);
+                expect(secondDOId?.replicaId).toBeLessThanOrEqual(DEFAULT_HARD_REPLICAS);
+            });
+        });
+    });
+    describe("hasBeenRevalidated", () => {
+        beforeEach(() => {
+            globalThis.openNextConfig = {
+                dangerous: { disableTagCache: false },
+            };
+        });
+        it("should return false if the cache is disabled", async () => {
+            globalThis.openNextConfig = {
+                dangerous: { disableTagCache: true },
+            };
+            const cache = doShardedTagCache();
+            const result = await cache.hasBeenRevalidated(["tag1"]);
+            expect(result).toBe(false);
+            expect(idFromNameMock).not.toHaveBeenCalled();
+        });
+        it("should return false if stub return false", async () => {
+            const cache = doShardedTagCache();
+            cache.getFromRegionalCache = vi.fn();
+            hasBeenRevalidatedMock.mockImplementationOnce(() => false);
+            const result = await cache.hasBeenRevalidated(["tag1"], 123456);
+            expect(cache.getFromRegionalCache).toHaveBeenCalled();
+            expect(idFromNameMock).toHaveBeenCalled();
+            expect(hasBeenRevalidatedMock).toHaveBeenCalled();
+            expect(result).toBe(false);
+        });
+        it("should return true if stub return true", async () => {
+            const cache = doShardedTagCache();
+            cache.getFromRegionalCache = vi.fn();
+            hasBeenRevalidatedMock.mockImplementationOnce(() => true);
+            const result = await cache.hasBeenRevalidated(["tag1"], 123456);
+            expect(cache.getFromRegionalCache).toHaveBeenCalled();
+            expect(idFromNameMock).toHaveBeenCalled();
+            expect(hasBeenRevalidatedMock).toHaveBeenCalledWith(["tag1"], 123456);
+            expect(result).toBe(true);
+        });
+        it("should return false if it throws", async () => {
+            const cache = doShardedTagCache();
+            cache.getFromRegionalCache = vi.fn();
+            hasBeenRevalidatedMock.mockImplementationOnce(() => {
+                throw new Error("error");
+            });
+            const result = await cache.hasBeenRevalidated(["tag1"], 123456);
+            expect(cache.getFromRegionalCache).toHaveBeenCalled();
+            expect(idFromNameMock).toHaveBeenCalled();
+            expect(hasBeenRevalidatedMock).toHaveBeenCalled();
+            expect(result).toBe(false);
+        });
+        it("Should return from the cache if it was found there", async () => {
+            const cache = doShardedTagCache();
+            cache.getFromRegionalCache = vi.fn().mockReturnValueOnce(new Response("true"));
+            const result = await cache.hasBeenRevalidated(["tag1"], 123456);
+            expect(result).toBe(true);
+            expect(idFromNameMock).not.toHaveBeenCalled();
+            expect(hasBeenRevalidatedMock).not.toHaveBeenCalled();
+        });
+        it("should try to put the result in the cache if it was not revalidated", async () => {
+            const cache = doShardedTagCache();
+            cache.getFromRegionalCache = vi.fn();
+            cache.putToRegionalCache = vi.fn();
+            hasBeenRevalidatedMock.mockImplementationOnce(() => false);
+            const result = await cache.hasBeenRevalidated(["tag1"], 123456);
+            expect(result).toBe(false);
+            expect(waitUntilMock).toHaveBeenCalled();
+            expect(cache.putToRegionalCache).toHaveBeenCalled();
+        });
+        it("should call all the durable object instance", async () => {
+            const cache = doShardedTagCache();
+            cache.getFromRegionalCache = vi.fn();
+            const result = await cache.hasBeenRevalidated(["tag1", "tag2"], 123456);
+            expect(result).toBe(false);
+            expect(idFromNameMock).toHaveBeenCalledTimes(2);
+            expect(hasBeenRevalidatedMock).toHaveBeenCalledTimes(2);
+        });
+    });
+    describe("writeTags", () => {
+        beforeEach(() => {
+            globalThis.openNextConfig = {
+                dangerous: { disableTagCache: false },
+            };
+            vi.useFakeTimers();
+            vi.setSystemTime(1000);
+        });
+        afterEach(() => {
+            vi.useRealTimers();
+        });
+        it("should return early if the cache is disabled", async () => {
+            globalThis.openNextConfig = {
+                dangerous: { disableTagCache: true },
+            };
+            const cache = doShardedTagCache();
+            await cache.writeTags(["tag1"]);
+            expect(idFromNameMock).not.toHaveBeenCalled();
+            expect(writeTagsMock).not.toHaveBeenCalled();
+        });
+        it("should write the tags to the cache", async () => {
+            const cache = doShardedTagCache();
+            await cache.writeTags(["tag1"]);
+            expect(idFromNameMock).toHaveBeenCalled();
+            expect(writeTagsMock).toHaveBeenCalled();
+            expect(writeTagsMock).toHaveBeenCalledWith(["tag1"], 1000);
+        });
+        it("should write the tags to the cache for multiple shards", async () => {
+            const cache = doShardedTagCache();
+            await cache.writeTags(["tag1", "tag2"]);
+            expect(idFromNameMock).toHaveBeenCalledTimes(2);
+            expect(writeTagsMock).toHaveBeenCalledTimes(2);
+            expect(writeTagsMock).toHaveBeenCalledWith(["tag1"], 1000);
+            expect(writeTagsMock).toHaveBeenCalledWith(["tag2"], 1000);
+        });
+        it('should write to all the replicated shards if "generateAllReplicas" is true', async () => {
+            const cache = doShardedTagCache({ baseShardSize: 4, enableShardReplication: true });
+            await cache.writeTags(["tag1", "_N_T_/tag1"]);
+            expect(idFromNameMock).toHaveBeenCalledTimes(6);
+            expect(writeTagsMock).toHaveBeenCalledTimes(6);
+            expect(writeTagsMock).toHaveBeenCalledWith(["tag1"], 1000);
+            expect(writeTagsMock).toHaveBeenCalledWith(["_N_T_/tag1"], 1000);
+        });
+        it("should call deleteRegionalCache", async () => {
+            const cache = doShardedTagCache();
+            cache.deleteRegionalCache = vi.fn();
+            await cache.writeTags(["tag1"]);
+            expect(cache.deleteRegionalCache).toHaveBeenCalled();
+            expect(cache.deleteRegionalCache).toHaveBeenCalledWith(expect.objectContaining({ key: "tag-hard;shard-1;replica-1" }), ["tag1"]);
+            // expect(cache.deleteRegionalCache).toHaveBeenCalledWith("tag-hard;shard-1;replica-1", ["tag1"]);
+        });
+    });
+    describe("getCacheInstance", () => {
+        it("should return undefined by default", async () => {
+            const cache = doShardedTagCache();
+            expect(await cache.getCacheInstance()).toBeUndefined();
+        });
+        it("should try to return the cache instance if regional cache is enabled", async () => {
+            // @ts-expect-error - Defined on cloudfare context
+            globalThis.caches = {
+                open: vi.fn().mockResolvedValue("cache"),
+            };
+            const cache = doShardedTagCache({ baseShardSize: 4, regionalCache: true });
+            expect(cache.localCache).toBeUndefined();
+            expect(await cache.getCacheInstance()).toBe("cache");
+            expect(cache.localCache).toBe("cache");
+            // @ts-expect-error - Defined on cloudfare context
+            globalThis.caches = undefined;
+        });
+    });
+    describe("getFromRegionalCache", () => {
+        it("should return undefined if regional cache is disabled", async () => {
+            const cache = doShardedTagCache();
+            const doId = new TagCacheDOId({
+                baseShardId: "shard-1",
+                numberOfReplicas: 1,
+                shardType: "hard",
+            });
+            expect(await cache.getFromRegionalCache(doId, ["tag1"])).toBeUndefined();
+        });
+        it("should call .match on the cache", async () => {
+            // @ts-expect-error - Defined on cloudfare context
+            globalThis.caches = {
+                open: vi.fn().mockResolvedValue({
+                    match: vi.fn().mockResolvedValue("response"),
+                }),
+            };
+            const cache = doShardedTagCache({ baseShardSize: 4, regionalCache: true });
+            const doId = new TagCacheDOId({
+                baseShardId: "shard-1",
+                numberOfReplicas: 1,
+                shardType: "hard",
+            });
+            expect(await cache.getFromRegionalCache(doId, ["tag1"])).toBe("response");
+            // @ts-expect-error - Defined on cloudfare context
+            globalThis.caches = undefined;
+        });
+    });
+    describe("getCacheKey", () => {
+        it("should return the cache key without the random part", async () => {
+            const cache = doShardedTagCache();
+            const doId1 = new TagCacheDOId({ baseShardId: "shard-0", numberOfReplicas: 1, shardType: "hard" });
+            const reqKey = await cache.getCacheKey(doId1, ["_N_T_/tag1"]);
+            expect(reqKey.url).toBe("http://local.cache/shard/tag-hard;shard-0?tags=_N_T_%2Ftag1");
+            const doId2 = new TagCacheDOId({
+                baseShardId: "shard-1",
+                numberOfReplicas: 1,
+                shardType: "hard",
+            });
+            const reqKey2 = await cache.getCacheKey(doId2, ["tag1"]);
+            expect(reqKey2.url).toBe("http://local.cache/shard/tag-hard;shard-1?tags=tag1");
+        });
+    });
+    describe("performWriteTagsWithRetry", () => {
+        it("should retry if it fails", async () => {
+            vi.useFakeTimers();
+            vi.setSystemTime(1000);
+            const cache = doShardedTagCache();
+            writeTagsMock.mockImplementationOnce(() => {
+                throw new Error("error");
+            });
+            const spiedFn = vi.spyOn(cache, "performWriteTagsWithRetry");
+            const doId = new TagCacheDOId({
+                baseShardId: "shard-1",
+                numberOfReplicas: 1,
+                shardType: "hard",
+            });
+            await cache.performWriteTagsWithRetry(doId, ["tag1"], Date.now());
+            expect(writeTagsMock).toHaveBeenCalledTimes(2);
+            expect(spiedFn).toHaveBeenCalledTimes(2);
+            expect(spiedFn).toHaveBeenCalledWith(doId, ["tag1"], 1000, 1);
+            expect(sendDLQMock).not.toHaveBeenCalled();
+            vi.useRealTimers();
+        });
+        it("should stop retrying after 3 times", async () => {
+            vi.useFakeTimers();
+            vi.setSystemTime(1000);
+            const cache = doShardedTagCache();
+            writeTagsMock.mockImplementationOnce(() => {
+                throw new Error("error");
+            });
+            const spiedFn = vi.spyOn(cache, "performWriteTagsWithRetry");
+            await cache.performWriteTagsWithRetry(new TagCacheDOId({ baseShardId: "shard-1", numberOfReplicas: 1, shardType: "hard" }), ["tag1"], Date.now(), 3);
+            expect(writeTagsMock).toHaveBeenCalledTimes(1);
+            expect(spiedFn).toHaveBeenCalledTimes(1);
+            expect(sendDLQMock).toHaveBeenCalledWith({
+                failingShardId: "tag-hard;shard-1;replica-1",
+                failingTags: ["tag1"],
+                lastModified: 1000,
+            });
+            vi.useRealTimers();
+        });
+    });
+});

package/dist/cli/args.d.ts

@@ -1,6 +1,17 @@
-export declare function getArgs(): {
+import type { WranglerTarget } from "./utils/run-wrangler.js";
+export type Arguments = ({
+    command: "build";
     skipNextBuild: boolean;
     skipWranglerConfigCheck: boolean;
-    outputDir?: string;
     minify: boolean;
+} | {
+    command: "preview" | "deploy";
+    passthroughArgs: string[];
+} | {
+    command: "populateCache";
+    target: WranglerTarget;
+    environment?: string;
+}) & {
+    outputDir?: string;
 };
+export declare function getArgs(): Arguments;

package/dist/cli/args.js

@@ -1,40 +1,55 @@
 import { mkdirSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
+import { getWranglerEnvironmentFlag, isWranglerTarget } from "./utils/run-wrangler.js";
 export function getArgs() {
-    const { skipBuild, skipWranglerConfigCheck, output, noMinify } = parseArgs({
+    const { positionals, values } = parseArgs({
         options: {
-            skipBuild: {
-                type: "boolean",
-                short: "s",
-                default: false,
-            },
-            output: {
-                type: "string",
-                short: "o",
-            },
-            noMinify: {
-                type: "boolean",
-                default: false,
-            },
-            skipWranglerConfigCheck: {
-                type: "boolean",
-                default: false,
-            },
+            skipBuild: { type: "boolean", short: "s", default: false },
+            output: { type: "string", short: "o" },
+            noMinify: { type: "boolean", default: false },
+            skipWranglerConfigCheck: { type: "boolean", default: false },
         },
-        allowPositionals: false,
-    }).values;
-    const outputDir = output ? resolve(output) : undefined;
-    if (outputDir) {
+        allowPositionals: true,
+    });
+    const outputDir = values.output ? resolve(values.output) : undefined;
+    if (outputDir)
         assertDirArg(outputDir, "output", true);
+    const passthroughArgs = getPassthroughArgs();
+    switch (positionals[0]) {
+        case "build":
+            return {
+                command: "build",
+                outputDir,
+                skipNextBuild: values.skipBuild || ["1", "true", "yes"].includes(String(process.env.SKIP_NEXT_APP_BUILD)),
+                skipWranglerConfigCheck: values.skipWranglerConfigCheck ||
+                    ["1", "true", "yes"].includes(String(process.env.SKIP_WRANGLER_CONFIG_CHECK)),
+                minify: !values.noMinify,
+            };
+        case "preview":
+        case "deploy":
+            return {
+                command: positionals[0],
+                outputDir,
+                passthroughArgs,
+            };
+        case "populateCache":
+            if (!isWranglerTarget(positionals[1])) {
+                throw new Error(`Error: invalid target for populating the cache, expected 'local' | 'remote'`);
+            }
+            return {
+                command: "populateCache",
+                outputDir,
+                target: positionals[1],
+                environment: getWranglerEnvironmentFlag(passthroughArgs),
+            };
+        default:
+            throw new Error("Error: invalid command, expected 'build' | 'preview' | 'deploy' | 'populateCache'");
     }
-    return {
-        outputDir,
-        skipNextBuild: skipBuild || ["1", "true", "yes"].includes(String(process.env.SKIP_NEXT_APP_BUILD)),
-        skipWranglerConfigCheck: skipWranglerConfigCheck ||
-            ["1", "true", "yes"].includes(String(process.env.SKIP_WRANGLER_CONFIG_CHECK)),
-        minify: !noMinify,
-    };
+}
+function getPassthroughArgs() {
+    const passthroughPos = process.argv.indexOf("--");
+    return passthroughPos === -1 ? [] : process.argv.slice(passthroughPos + 1);
 }
 function assertDirArg(path, argName, make) {
     let dirStats;