fix: add grace period to blob deletion scheduling

Author: jakejarvis

lib/blob.ts

@@ -15,7 +15,7 @@ export async function putBlob(options: {
     access: "public",
     contentType: options.contentType,
     cacheControlMaxAge: options.cacheControlMaxAge,
-    allowOverwrite: true,
+    allowOverwrite: true, // TODO: temporary fix until KV/blob storage self-heals
   });
 
   return {

lib/cache.test.ts

@@ -110,4 +110,81 @@ describe("cached assets", () => {
 
     expect(result).toEqual({ url: null });
   });
+
+  it("schedules blob deletion with grace period beyond Redis TTL", async () => {
+    const indexKey = ns("test", "grace-test");
+    const lockKey = ns("lock", "grace-test");
+    const purgeQueue = "test-queue";
+    const ttl = 60; // 1 minute
+    const gracePeriod = 300; // 5 minutes
+
+    const beforeMs = Date.now();
+
+    await getOrCreateCachedAsset({
+      indexKey,
+      lockKey,
+      ttlSeconds: ttl,
+      purgeQueue,
+      blobGracePeriodSeconds: gracePeriod,
+      produceAndUpload: async () => ({
+        url: "https://cdn/grace.webp",
+        key: "grace-key",
+      }),
+    });
+
+    const afterMs = Date.now();
+
+    const { redis } = await import("@/lib/redis");
+    const purgeKey = ns("purge", purgeQueue);
+    const members = (await redis.zrange(purgeKey, 0, -1)) as string[];
+
+    expect(members).toHaveLength(1);
+    expect(members[0]).toBe("https://cdn/grace.webp");
+
+    const scheduledDeleteMs = await redis.zscore(purgeKey, members[0]);
+    expect(scheduledDeleteMs).not.toBeNull();
+
+    const expectedMinMs = beforeMs + (ttl + gracePeriod) * 1000;
+    const expectedMaxMs = afterMs + (ttl + gracePeriod) * 1000;
+
+    expect(scheduledDeleteMs).toBeGreaterThanOrEqual(expectedMinMs);
+    expect(scheduledDeleteMs).toBeLessThanOrEqual(expectedMaxMs);
+  });
+
+  it("uses 24-hour default grace period when not specified", async () => {
+    const indexKey = ns("test", "default-grace");
+    const lockKey = ns("lock", "default-grace");
+    const purgeQueue = "default-queue";
+    const ttl = 3600; // 1 hour
+
+    const beforeMs = Date.now();
+
+    await getOrCreateCachedAsset({
+      indexKey,
+      lockKey,
+      ttlSeconds: ttl,
+      purgeQueue,
+      // No blobGracePeriodSeconds specified - should default to 86400 (24 hours)
+      produceAndUpload: async () => ({
+        url: "https://cdn/default.webp",
+      }),
+    });
+
+    const afterMs = Date.now();
+
+    const { redis } = await import("@/lib/redis");
+    const purgeKey = ns("purge", purgeQueue);
+    const members = (await redis.zrange(purgeKey, 0, -1)) as string[];
+
+    expect(members).toHaveLength(1);
+    const scheduledDeleteMs = await redis.zscore(purgeKey, members[0]);
+    expect(scheduledDeleteMs).not.toBeNull();
+
+    const defaultGracePeriod = 86400; // 24 hours
+    const expectedMinMs = beforeMs + (ttl + defaultGracePeriod) * 1000;
+    const expectedMaxMs = afterMs + (ttl + defaultGracePeriod) * 1000;
+
+    expect(scheduledDeleteMs).toBeGreaterThanOrEqual(expectedMinMs);
+    expect(scheduledDeleteMs).toBeLessThanOrEqual(expectedMaxMs);
+  });
 });

lib/cache.ts

@@ -118,9 +118,25 @@ export async function acquireLockOrWaitForResult<T = unknown>(options: {
 }
 
 type CachedAssetOptions<TProduceMeta extends Record<string, unknown>> = {
+  /**
+   * Index key for the Redis cache
+   */
   indexKey: string;
+  /**
+   * Lock key for the Redis cache
+   */
   lockKey: string;
-  ttlSeconds: number;
+  /**
+   * TTL in seconds for the Redis cache
+   * @default 604800 (7 days)
+   */
+  ttlSeconds?: number;
+  /**
+   * Grace period in seconds to add to blob deletion schedule beyond Redis TTL
+   * This prevents race conditions where Redis expires but blob hasn't been pruned yet
+   * @default 86400 (24 hours)
+   */
+  blobGracePeriodSeconds?: number;
   /**
    * Produce and upload the asset, returning { url, key } and any metrics to attach
    */
@@ -139,8 +155,14 @@ type CachedAssetOptions<TProduceMeta extends Record<string, unknown>> = {
 export async function getOrCreateCachedAsset<T extends Record<string, unknown>>(
   options: CachedAssetOptions<T>,
 ): Promise<{ url: string | null }> {
-  const { indexKey, lockKey, ttlSeconds, produceAndUpload, purgeQueue } =
-    options;
+  const {
+    indexKey,
+    lockKey,
+    ttlSeconds = 604800, // 7 days default
+    blobGracePeriodSeconds = 86400, // 24 hours default
+    produceAndUpload,
+    purgeQueue,
+  } = options;
 
   // 1) Check index
   try {
@@ -209,6 +231,8 @@ export async function getOrCreateCachedAsset<T extends Record<string, unknown>>(
   try {
     const produced = await produceAndUpload();
     const expiresAtMs = Date.now() + ttlSeconds * 1000;
+    // Schedule blob deletion AFTER Redis TTL + grace period to prevent race conditions
+    const blobDeleteAtMs = expiresAtMs + blobGracePeriodSeconds * 1000;
 
     try {
       // Use pipeline to batch cache writes and lock release
@@ -220,7 +244,7 @@ export async function getOrCreateCachedAsset<T extends Record<string, unknown>>(
       );
       if (purgeQueue && produced.url) {
         pipeline.zadd(ns("purge", purgeQueue), {
-          score: expiresAtMs,
+          score: blobDeleteAtMs, // Use extended deadline for blob deletion
           member: produced.url,
         });
       }