feat(share-backend): OG image + scheduled deletion worker

[graydawnc]

What

Two distinct concerns that share the same R2 surface, paired in one PR because they only make sense end-to-end:

1. OG preview image for every published share
   • On publish, ctx.waitUntil() renders a 1200×630 PNG via @vercel/og (Satori-backed) and stores it at r2://OG/<slug>.png
   • GET /api/og/<slug>.png serves the PNG with the same 30s edge-cache + must-revalidate disposition as /api/snapshots/<slug>, so the social-preview image stops at the same moment the share content does on revoke
2. Scheduled deletion worker (functions/_scheduled/deletion-worker.ts)
   • Iterates deletion_queue rows whose scheduled_at <= now and cancelled = 0
   • Stamps a tombstone in META for every share the user owned, deletes the R2 snapshot + OG bodies, removes the rows
   • Drops user_identities (so the provider sub can be re-linked by a future sign-up), releases the handles row, finally soft-deletes users
   • Plus an orphan-asset sweep that mops up R2 objects whose D1 row was lost in a partial publish

Why

OG and deletion both touch the same buckets (SNAPSHOTS, OG) and the same shape of cleanup (revoke a slug, drop the assets). Implementing one in isolation makes you encode half the policy in two places. Bundling means there's one truth for "what does a tombstoned share look like" and one truth for "how do we sweep R2".

The OG render is waitUntil-only on the publish path. A renderer failure is logged but does not fail the publish — the share is usable the moment the D1 row commits; the preview catches up best-effort. If the render really never lands (e.g. Satori throws on a pathological prompt), the orphan sweep picks it up on its next cron tick.

The deletion worker re-checks deletion_queue inside the per-user loop. The outer SELECT can race with a user POSTing DELETE /api/me/delete to cancel; without the re-check, an in-flight cancel between the outer SELECT and the per-user write would be ignored. With it, the race window shrinks from "the whole sweep" to "one user's processing time" — small enough that a v0.5 retry on next tick is acceptable.

Deletion lifecycle (end to end)

stateDiagram-v2
    [*] --> Active
    Active --> Pending: POST /api/me/delete
    Pending --> Active: DELETE /api/me/delete<br/>(cancelled=1)
    Pending --> Executing: cron tick, scheduled_at ≤ now
    Executing --> Active: re-check finds cancelled=1<br/>(in-loop race guard)
    Executing --> Tombstoned: shares → META revoked,<br/>R2 snapshots + OG deleted
    Tombstoned --> Cleaned: user_identities dropped,<br/>handle released,<br/>users.deleted_at set
    Cleaned --> [*]

Loading

Sweep + OG flow

flowchart TD
    subgraph publish["POST /api/publish (existing)"]
        P[D1 INSERT/UPDATE] --> M[KV META]
        M --> S[R2 SNAPSHOT]
        S -.waitUntil.-> OG[renderOgPng]
        OG -.-> ROG[R2 OG]
    end

    subgraph reader
        R[GET /api/og/:id.png] --> M2[KV META check]
        M2 -->|live| ROG
        M2 -->|revoked/expired| G[GONE]
    end

    subgraph cron["scheduled (cron 6h)"]
        T[runDeletionSweep] --> SD[sweepDeletedUsers]
        T --> SO[sweepOrphanShareAssets]
        SD -->|due rows| Q[(deletion_queue)]
        SD -->|tombstone owned shares| M3[KV META]
        SD -->|delete bulk| S3[R2 SNAPSHOT]
        SD -->|delete preview| ROG2[R2 OG]
        SD -->|drop identity| UI[(user_identities)]
        SD -->|release handle| H[(handles)]
        SD -->|soft-delete| U[(users)]
        SO -->|orphan window 7d, cap 500| S3
        SO --> ROG2
    end

Loading

Correctness + safety notes

• In-loop race re-check. Cancels that land between the outer SELECT and the user's processing don't get steamrolled.
• Identity drop = re-sign-up is fresh. Removing user_identities for the deleted user means a future sign-up with the same Google sub doesn't reincarnate the old users.id. They get a brand-new account, which matches the user-facing promise of deletion.
• Handle release returns to pool. The released handle is claimable by anyone, including the same person on a new account. Per design.
• Orphan sweep is bounded. 7-day window, 500-row cap per tick. With a 6h cron that's a 2k-object/day drain ceiling — far above any realistic v0.5 backlog.
• OG cache aligned with snapshot cache. Both 30s with must-revalidate. A panic revoke is fully effective on both within the same window — without alignment the PNG could linger at the edge 5× longer.
• OG render is fire-and-forget. A render failure logs and yields nothing; the publish path doesn't care. The orphan sweep is the safety net.
• Satori 'flex everywhere' quirk. og.ts declares display: flex on every nested div and collapses HTML whitespace (Satori treats whitespace as text nodes and refuses non-flex layout otherwise). Without these the renderer throws at runtime with an opaque message — see the three fix(share-backend) commits in this PR's history.

Verification

• pnpm --filter @spool-lab/share-backend test — deletion-worker.test.ts (16 cases: due/not-due, in-loop cancel race, identity drop, handle release, orphan sweep) + og.test.ts (renders happy, regenerates on revoke, 410 on tombstone, 404 on missing)
• Manual: trigger the worker locally via wrangler dev --test-scheduled; sweep visible in logs

Risk

Deletion worker is wired up as a separate Worker project (Pages doesn't host crons). Until the companion Worker is deployed, the queue accumulates but nothing executes — no functional regression, just a delayed cleanup.

OG endpoint is additive — no existing path serves PNGs.

Submitted by @graydawnc.