Add a daily cron to sweep expired preview artifacts

Refs self-expire from the indexes (skipped on read, pruned on the next write),
but their per-version R2 objects (meta/<name>/<version>.json and the tarball)
were never auto-deleted, only on explicit purge, so R2 storage grew with every
ref ever published.

Add cleanupExpiredArtifacts: it lists the meta/ and tarball/ prefixes and
bulk-deletes objects whose uploaded age exceeds REF_TTL_MS. Each object is
re-uploaded on republish, so uploaded age tracks the ref's age and the cutoff
maps exactly to the ref TTL, an active ref is never touched, and the live indexes
(refs/, meta-index/) are under different prefixes and left alone. A Void cron
(crons/cleanup-expired.ts, daily) runs it; the generated Worker already dispatches
scheduled events, so this composes with the routes/ app entry.

Author: fengmk2

README.md

@@ -220,7 +220,7 @@ are uploaded with `void secret put`:
 
 Bindings/secrets:
 
-- `STORAGE` (R2) - generated tarballs, rewritten metadata (incl. integrity), and the runtime-registered refs index. Auto-provisioned by Void on deploy (no manual bucket creation); the binding is declared in `void.json` (`inference.bindings.storage`). The runtime refs index self-expires after 90 days (in-code TTL).
+- `STORAGE` (R2) - generated tarballs, rewritten metadata (incl. integrity), and the runtime-registered refs index. Auto-provisioned by Void on deploy (no manual bucket creation); the binding is declared in `void.json` (`inference.bindings.storage`). The runtime refs index self-expires after 90 days (in-code TTL), and a daily Void cron (`crons/cleanup-expired.ts`) sweeps the per-version meta/tarball objects once their ref TTL lapses, so R2 storage stays bounded to the active-ref window.
 - `ADMIN_TOKEN` (secret) - guards the admin endpoints. Set with `void secret put ADMIN_TOKEN`.
 
 ## Develop

crons/cleanup-expired.ts

@@ -0,0 +1,13 @@
+import { defineScheduled } from 'void'
+import { cleanupExpiredArtifacts } from '../src/preview/cleanupExpired'
+
+// Daily maintenance. Refs self-expire from the indexes (skipped on read, pruned
+// on the next write), but their per-version R2 objects (meta + tarball) would
+// otherwise orphan forever. This deletes the ones past the ref TTL so storage
+// stays bounded to the active-ref window, "in advance" of any manual purge.
+export const cron = '37 3 * * *' // 03:37 UTC daily (off the hour)
+
+export default defineScheduled(async (_controller, env) => {
+  const { deleted } = await cleanupExpiredArtifacts(env)
+  console.log(`cleanup-expired: deleted ${deleted} expired preview artifact(s)`)
+})

src/preview/cleanupExpired.ts

@@ -0,0 +1,43 @@
+import type { Env } from '../config'
+import { REF_TTL_MS } from './getConfiguredRefs'
+
+// R2 key prefixes for the per-version preview artifacts. Must match `metaKey` /
+// `tarballKey` in ../cache/r2Cache. NOT `meta-index/` or `refs/`: those are the
+// live indexes (self-pruned on write), not per-version orphans.
+const ARTIFACT_PREFIXES = ['meta/', 'tarball/']
+
+/**
+ * Delete per-version preview artifacts (meta + tarball) whose ref TTL has lapsed,
+ * so R2 storage stays bounded to the active-ref window rather than growing with
+ * every ref ever published.
+ *
+ * A ref's objects are (re-)uploaded on each publish, so an object's `uploaded`
+ * age equals its ref's age, and the ref TTL maps exactly to
+ * `uploaded < now - REF_TTL_MS`. An active ref (published within the window) is
+ * therefore never touched; an expired ref's objects, which are no longer served
+ * (the packument skips expired refs), are the orphans this removes. `now` is
+ * injectable for tests.
+ */
+export async function cleanupExpiredArtifacts(
+  env: Pick<Env, 'STORAGE'>,
+  now: number = Date.now(),
+): Promise<{ deleted: number }> {
+  const cutoff = now - REF_TTL_MS
+  let deleted = 0
+  for (const prefix of ARTIFACT_PREFIXES) {
+    let cursor: string | undefined
+    do {
+      const listing = await env.STORAGE.list({ prefix, cursor })
+      const expired = listing.objects
+        .filter((o) => o.uploaded.getTime() < cutoff)
+        .map((o) => o.key)
+      if (expired.length > 0) {
+        // R2 bulk delete takes up to 1000 keys; a list page is <= 1000.
+        await env.STORAGE.delete(expired)
+        deleted += expired.length
+      }
+      cursor = listing.truncated ? listing.cursor : undefined
+    } while (cursor)
+  }
+  return { deleted }
+}

test/worker.test.ts

@@ -1,5 +1,7 @@
 import { SELF, env } from 'cloudflare:test'
 import { metaIndexKey, metaKey } from '../src/cache/r2Cache'
+import { cleanupExpiredArtifacts } from '../src/preview/cleanupExpired'
+import { REF_TTL_MS } from '../src/preview/getConfiguredRefs'
 import {
   afterAll,
   beforeAll,
@@ -1094,3 +1096,35 @@ describe('health', () => {
     expect(await res.json()).toEqual({ status: 'ok' })
   })
 })
+
+describe('cleanup of expired artifacts (scheduled)', () => {
+  it('deletes per-version meta + tarball past the ref TTL', async () => {
+    await env.STORAGE.put('meta/vite-plus/0.0.0-commit.old00001.json', '{}')
+    await env.STORAGE.put('tarball/vite-plus/0.0.0-commit.old00001.tgz', 'x')
+    // A future "now" makes every object older than the TTL, so all are expired.
+    const { deleted } = await cleanupExpiredArtifacts(
+      env,
+      Date.now() + 2 * REF_TTL_MS,
+    )
+    expect(deleted).toBeGreaterThanOrEqual(2)
+    expect(
+      await env.STORAGE.get('meta/vite-plus/0.0.0-commit.old00001.json'),
+    ).toBeNull()
+    expect(
+      await env.STORAGE.get('tarball/vite-plus/0.0.0-commit.old00001.tgz'),
+    ).toBeNull()
+  })
+
+  it('keeps artifacts within the TTL and never touches the indexes', async () => {
+    await env.STORAGE.put('meta/vite-plus/0.0.0-commit.fresh001.json', '{}')
+    // beforeEach published commit.a832a55, so the refs + meta indexes exist.
+    const { deleted } = await cleanupExpiredArtifacts(env) // now = Date.now()
+    expect(deleted).toBe(0)
+    expect(
+      await env.STORAGE.get('meta/vite-plus/0.0.0-commit.fresh001.json'),
+    ).not.toBeNull()
+    // The live indexes live under different prefixes and must be untouched.
+    expect(await env.STORAGE.get('refs/index.json')).not.toBeNull()
+    expect(await env.STORAGE.get(metaIndexKey('vite-plus'))).not.toBeNull()
+  })
+})

tsconfig.json

@@ -21,6 +21,7 @@
   "include": [
     "src",
     "routes",
+    "crons",
     "env.ts",
     "test",
     "vite.config.ts",