feat(share-backend): publish, snapshot read, revoke, republish

[graydawnc]

What

Adds the three endpoints that put / get / withdraw a share:

• POST /api/publish — first-publish or republish (uses optional override_slug); content-hash idempotent; rate-limited per-user (30/h, 100/d)
• GET /api/snapshots/<id> — public read; serves the snapshot body from R2 or a 410 tombstone if revoked / expired
• POST /api/revoke/<id> — owner-only tombstone of a live share

Plus supporting code:

• src/publish/validators.ts — Zod schema for the publish body (snapshot envelope, visibility, expires_at, optional override_slug for republish)
• src/publish/slug.ts — nanoidSlug() (21 chars) + isValidSlug() (regex ^[\w-]{21}$)

Why

These three handlers are the entire lifecycle of a share, and they all share state machines (idempotency key, version bump, tombstone semantics). Splitting them into separate PRs would mean each one carries half the helper code, half the test fixture, and the contracts would drift between landings.

The crucial invariants — D1 write first, KV tombstone second, R2 third; idempotency keyed on a client-derived sha256; override_slug is the only way to address an existing slug — only stay coherent when read as one diff.

Write order

Every state-changing path uses the same discipline: D1 (source of truth) → KV META (read-path tombstone gate) → R2 (bulk body). Partial failure leaves the row in a consistent state from the owner's point of view; the reader sees a single coherent answer; a retry can complete the missing tail without orphan rows.

flowchart TD
    P([POST /api/publish]) -->|insert / update| D1[(D1 published_shares)]
    D1 -->|on commit| MET[(KV META)]
    MET --> R2[(R2 SNAPSHOTS)]
    R2 -.OG fire-and-forget.-> OG[(R2 OG)]

    R([POST /api/revoke/:id]) -->|UPDATE revoked_at| D1
    D1 -.->|stamp revoked_at| MET
    MET -.waitUntil.-> DEL[Delete R2 SNAPSHOT + OG]

    G([GET /api/snapshots/:id]) -->|read meta first| MET
    MET -->|live| R2
    MET -->|revoked / expired| T[410 tombstone JSON]

Loading

Publish state machine

stateDiagram-v2
    [*] --> Validating
    Validating --> RateLimited: 30/h or 100/d trip
    Validating --> Sized: body ≤ 2MB
    Sized --> ContentHashed: snapshot hash = idempotency_key
    ContentHashed --> Idempotent_hit: token matches live row
    Idempotent_hit --> [*]: 200 with original slug
    ContentHashed --> Republish: override_slug set
    Republish --> ConcurrentRetry: meta.changes==0 → 409
    Republish --> Bumped: UPDATE OK, version++
    ContentHashed --> First: no override_slug
    First --> SlugMint: nanoid(21)
    SlugMint --> Inserted
    First --> ConcurrentInsertRetry: UNIQUE(user, token) → re-read row, 200
    Bumped --> Persisted
    Inserted --> Persisted
    Persisted --> KV_META: meta/<slug>
    KV_META --> R2_Body: <slug>.json
    R2_Body --> OG_FireAndForget
    OG_FireAndForget --> [*]

Loading

Revoke + read

sequenceDiagram
    autonumber
    participant O as Owner
    participant Rv as POST /api/revoke/:id
    participant D as D1
    participant K as KV META
    participant R2 as R2 SNAPSHOTS
    participant Rd as Reader (GET /api/snapshots/:id)

    O->>Rv: revoke slug
    Rv->>Rv: requireUser, rate-limit (60/h), owner-scope check
    Rv->>D: UPDATE revoked_at=now WHERE id=?
    Rv->>K: meta.revoked_at = now
    Rv-->>Rv: waitUntil(delete R2 snapshot + OG)
    Rv-->>O: 200 { ok: true }
    Rd->>K: GET meta/<id>
    K-->>Rd: { revoked_at: <ts> }
    Rd-->>Rd: 410 Gone + tombstone JSON (no-store)

Loading

Correctness notes

• Idempotency lookup excludes revoked rows. (user_id, client_request_id) WHERE revoked_at IS NULL lets a publish-then-revoke-then-republish recycle the same content hash onto a fresh slug instead of resurrecting the tombstoned one.
• Republish requires override_slug. No "I think you meant to update slug X" inference — the renderer either targets a specific slug or asks for a new one. Eliminates a class of "wrong share got mutated" bugs.
• Optimistic concurrency on republish. UPDATE … WHERE version=? against the version we just SELECTed. Two concurrent republishers can't silently overwrite each other — the second sees changes=0 and gets 409 CONFLICT.
• draft_id healing. Pre-PR rows have draft_id IS NULL. A republish carrying a draft_id writes it through; once written it's immutable (any mismatch is 400 bad request). This keeps "which draft owns which slug" stable for the slug's lifetime without forcing a schema backfill.
• Body cap. 2 MiB. ~10× a typical session export and far short of anything that would exhaust a Worker memory budget.
• expires_at bounds. ≥5 min (clock-skew guard, blocks instant-tombstoned publishes) and ≤1 year (matches retention policy).
• Tombstone JSON. 410 Gone with { revoked: true, at } or { expired: true, at }. Reader pages render this as a friendly "this share was withdrawn" page instead of a generic browser 404.
• No owner_user_id in the public JSON. Anyone with a slug already knows the share exists; exposing the internal user id would hand them a pivot into a user-enumeration vector via /api/profiles/*.
• OG render is waitUntil. A broken render logs but doesn't fail the publish. A user's session is published the moment the D1 row lands; the OG image catches up best-effort.

Verification

• pnpm --filter @spool-lab/share-backend test — publish.test.ts covers: happy publish, republish bumps version, idempotency short-circuit, revoke-then-republish mints new slug, concurrent republish lands one 200 + one 409, body too large, expires_at bounds, profile-listed without handle 4xx, slug regex, tombstone 410 (revoked + expired), R2 missing → 404
• Manual: wrangler dev, sign in, publish a snapshot, curl the public read, revoke, public read returns 410

Risk

Schema is the same as PR #356. Endpoints are additive. Renderer code that calls these endpoints comes in later stack PRs and is gated by featureFlags.ts share: DEV || envFlag('SHARE') — prod doesn't set the env, so this PR is dormant on main until the gate flips.

Submitted by @graydawnc.