test: add DO storage + integration coverage via wrangler unstable_dev

Pure-function unit tests for chunk-storage (BLOB-grow, orphan-row read,
multi-chunk grouping) and cooldown-store (TTL math, INSERT cursor drain,
GC sampling, release/refund) cover the bugs Phase 1 fixed.

Integration suite boots a local Worker + real DO via wrangler
unstable_dev and asserts cookie issuance, cooldown isolation across
identities, Content-Length 411/413 guards, WS upgrade semantics, WS
broadcast frame shape with monotonic seq, ping/pong, per-identity WS
cap, and Origin allowlist. WS uses the ws package directly since
unstable_dev's fetch strips CF's webSocket Response field.

156 tests pass in ~3.3s; verified stable across 3 consecutive runs.

test/durable-objects/canvas-room.integration.test.js

@@ -0,0 +1,227 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import {
+  setupDO,
+  placePixel,
+  fetchCanvas,
+  openWs,
+  nextMessage,
+  randomCookie,
+} from '../helpers/do-harness.js';
+import {
+  CANVAS_WIDTH,
+  TOTAL_PIXELS,
+  MAX_BATCH_SIZE,
+  MAX_WS_PER_IDENTITY,
+} from '../../src/lib/constants.js';
+
+let harness;
+
+beforeAll(async () => {
+  harness = await setupDO();
+}, 30_000);
+
+afterAll(async () => {
+  await harness?.close();
+});
+
+describe('GET /api/canvas', () => {
+  it('returns a TOTAL_PIXELS-sized body on first call', async () => {
+    const { status, bytes } = await fetchCanvas(harness);
+    expect(status).toBe(200);
+    expect(bytes.length).toBe(TOTAL_PIXELS);
+  });
+
+  it('issues Set-Cookie when no cookie is present', async () => {
+    const { setCookie } = await fetchCanvas(harness);
+    expect(setCookie).toMatch(/^rplace_id=[0-9a-f-]{36}/);
+    expect(setCookie).toMatch(/HttpOnly/);
+    expect(setCookie).toMatch(/Secure/);
+    expect(setCookie).toMatch(/SameSite=Lax/);
+  });
+
+  it('does not re-issue Set-Cookie when a valid cookie is present', async () => {
+    const cookie = randomCookie();
+    const { setCookie } = await fetchCanvas(harness, { cookie });
+    expect(setCookie).toBeNull();
+  });
+});
+
+describe('POST /api/place — happy path', () => {
+  it('places a single pixel and is visible on /api/canvas', async () => {
+    const cookie = randomCookie();
+    const x = 100, y = 200, color = 42;
+    const res = await placePixel(harness, { x, y, color, cookie });
+    expect(res.status).toBe(200);
+    expect(res.json?.ok).toBe(true);
+
+    const canvas = await fetchCanvas(harness, { cookie });
+    const offset = y * CANVAS_WIDTH + x;
+    expect(canvas.bytes[offset]).toBe(color);
+  });
+});
+
+describe('POST /api/place — cooldown', () => {
+  it('429s the same cookie within 1 second', async () => {
+    const cookie = randomCookie();
+    const a = await placePixel(harness, { x: 0, y: 0, color: 1, cookie });
+    expect(a.status).toBe(200);
+    const b = await placePixel(harness, { x: 1, y: 0, color: 2, cookie });
+    expect(b.status).toBe(429);
+    expect(b.json?.error).toBe('rate_limited');
+  });
+
+  it('does not interfere across distinct cookies', async () => {
+    const c1 = randomCookie();
+    const c2 = randomCookie();
+    const r1 = await placePixel(harness, { x: 10, y: 0, color: 5, cookie: c1 });
+    const r2 = await placePixel(harness, { x: 11, y: 0, color: 6, cookie: c2 });
+    expect(r1.status).toBe(200);
+    expect(r2.status).toBe(200);
+  });
+});
+
+describe('POST /api/place — Content-Length guard', () => {
+  it('rejects POST with missing Content-Length (411)', async () => {
+    const res = await harness.fetch('/api/place', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{"pixels":[]}',
+    });
+    expect(res.status).toBe(411);
+  });
+
+  it('rejects POST with zero Content-Length (411)', async () => {
+    const res = await harness.fetch('/api/place', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': '0' },
+      body: '',
+    });
+    expect(res.status).toBe(411);
+  });
+
+  it('rejects POST above the body cap (413)', async () => {
+    // Send a body that actually matches the declared Content-Length so the
+    // HTTP transport accepts it; the edge validation should still reject on
+    // size alone, before parsing.
+    const oversized = '{"pad":"' + 'x'.repeat(MAX_BATCH_SIZE * 64 + 10) + '"}';
+    const res = await harness.fetch('/api/place', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': String(new TextEncoder().encode(oversized).byteLength),
+      },
+      body: oversized,
+    });
+    expect(res.status).toBe(413);
+  });
+});
+
+describe('WS upgrade', () => {
+  it('rejects requests missing the Upgrade header', async () => {
+    const res = await harness.fetch('/api/ws');
+    expect(res.status).toBe(426);
+  });
+
+  it('accepts an upgrade with a valid cookie', async () => {
+    const { status, ws } = await openWs(harness, { cookie: randomCookie() });
+    expect(status).toBe(101);
+    ws.close();
+  });
+});
+
+describe('WS broadcast', () => {
+  it('delivers a pixels frame with monotonic seq to every connected socket', async () => {
+    const subCookie = randomCookie();
+    const placerCookie = randomCookie();
+    const { ws } = await openWs(harness, { cookie: subCookie });
+
+    // Pre-arm the listener BEFORE triggering the broadcast: the WS message
+    // can arrive faster than the HTTP response, so registering after the
+    // placePixel await would miss it.
+    const msgPromise = nextMessage(ws);
+    const res = await placePixel(harness, { x: 50, y: 50, color: 9, cookie: placerCookie });
+    expect(res.status).toBe(200);
+
+    const data = JSON.parse(await msgPromise);
+    expect(data.type).toBe('pixels');
+    expect(typeof data.seq).toBe('number');
+    expect(data.seq).toBeGreaterThan(0);
+    expect(Array.isArray(data.pixels)).toBe(true);
+    expect(data.pixels[0]).toMatchObject({ x: 50, y: 50, color: 9 });
+
+    ws.close();
+  });
+
+  it('seq increments across placements', async () => {
+    const subCookie = randomCookie();
+    const p1 = randomCookie();
+    const p2 = randomCookie();
+    const { ws } = await openWs(harness, { cookie: subCookie });
+
+    const m1Promise = nextMessage(ws);
+    await placePixel(harness, { x: 60, y: 0, color: 1, cookie: p1 });
+    const m1 = JSON.parse(await m1Promise);
+
+    const m2Promise = nextMessage(ws);
+    await placePixel(harness, { x: 61, y: 0, color: 2, cookie: p2 });
+    const m2 = JSON.parse(await m2Promise);
+
+    expect(m2.seq).toBeGreaterThan(m1.seq);
+    ws.close();
+  });
+});
+
+describe('WS ping/pong', () => {
+  it('responds to "ping" with {type:"pong"}', async () => {
+    const { ws } = await openWs(harness, { cookie: randomCookie() });
+    ws.send('ping');
+    const msg = await nextMessage(ws);
+    const data = JSON.parse(msg);
+    expect(data.type).toBe('pong');
+    ws.close();
+  });
+});
+
+describe('WS per-identity cap', () => {
+  it('accepts up to MAX_WS_PER_IDENTITY sockets, rejects the next', async () => {
+    const cookie = randomCookie();
+    const sockets = [];
+    for (let i = 0; i < MAX_WS_PER_IDENTITY; i++) {
+      const r = await openWs(harness, { cookie });
+      expect(r.status).toBe(101);
+      sockets.push(r.ws);
+    }
+    const over = await openWs(harness, { cookie });
+    expect(over.status).toBe(429);
+    for (const ws of sockets) ws.close();
+  });
+});
+
+describe('WS Origin allowlist (env override)', () => {
+  let restricted;
+  beforeAll(async () => {
+    restricted = await setupDO({
+      vars: { ALLOWED_ORIGINS: 'https://allowed.example', ENVIRONMENT: 'development' },
+    });
+  }, 30_000);
+  afterAll(async () => {
+    await restricted?.close();
+  });
+
+  it('rejects WS upgrade from a disallowed Origin (403)', async () => {
+    const r = await openWs(restricted, {
+      cookie: randomCookie(),
+      origin: 'https://evil.example',
+    });
+    expect(r.status).toBe(403);
+  });
+
+  it('accepts WS upgrade from an allowed Origin', async () => {
+    const r = await openWs(restricted, {
+      cookie: randomCookie(),
+      origin: 'https://allowed.example',
+    });
+    expect(r.status).toBe(101);
+    r.ws?.close();
+  });
+});

test/durable-objects/chunk-storage.test.js

@@ -0,0 +1,181 @@
+import { describe, it, expect } from 'vitest';
+import { readChunk, readAllChunks, writePixels } from '../../src/durable-objects/lib/chunk-storage.js';
+import {
+  CANVAS_WIDTH,
+  CHUNK_BYTES,
+  CHUNK_COUNT,
+  TOTAL_PIXELS,
+} from '../../src/lib/constants.js';
+import { createFakeSql } from '../helpers/fake-sql.js';
+
+describe('readChunk', () => {
+  it('returns a zero-filled buffer for missing rows (lazy init)', () => {
+    const sql = createFakeSql();
+    const buf = readChunk(sql, 0);
+    expect(buf).toBeInstanceOf(Uint8Array);
+    expect(buf.length).toBe(CHUNK_BYTES);
+    expect(buf.every((b) => b === 0)).toBe(true);
+  });
+
+  it('returns the persisted blob when row exists', () => {
+    const sql = createFakeSql();
+    const seed = new Uint8Array(CHUNK_BYTES);
+    seed[42] = 99;
+    sql._seedChunk(0, seed);
+    const buf = readChunk(sql, 0);
+    expect(buf[42]).toBe(99);
+  });
+});
+
+describe('writePixels — single chunk', () => {
+  it('persists pixels and reads them back identically', () => {
+    const sql = createFakeSql();
+    writePixels(sql, [
+      { x: 0, y: 0, color: 5 },
+      { x: 1, y: 0, color: 17 },
+      { x: 5, y: 0, color: 250 },
+    ]);
+    const chunk0 = readChunk(sql, 0);
+    expect(chunk0[0]).toBe(5);
+    expect(chunk0[1]).toBe(17);
+    expect(chunk0[5]).toBe(250);
+  });
+
+  it('overwrites previous color at same coordinate', () => {
+    const sql = createFakeSql();
+    writePixels(sql, [{ x: 10, y: 0, color: 1 }]);
+    writePixels(sql, [{ x: 10, y: 0, color: 42 }]);
+    const chunk0 = readChunk(sql, 0);
+    expect(chunk0[10]).toBe(42);
+  });
+
+  it('is a no-op on empty input', () => {
+    const sql = createFakeSql();
+    writePixels(sql, []);
+    expect(sql._chunks.size).toBe(0);
+  });
+});
+
+describe('writePixels — multi-chunk', () => {
+  it('groups writes across chunks correctly', () => {
+    const sql = createFakeSql();
+    // (x=0,y=0) → offset 0 → chunk 0
+    // (x=CHUNK_BYTES,y=0) → offset CHUNK_BYTES → chunk 1, byteOffset 0
+    writePixels(sql, [
+      { x: 0, y: 0, color: 11 },
+      { x: CHUNK_BYTES, y: 0, color: 22 },
+    ]);
+    expect(sql._chunks.size).toBe(2);
+    expect(readChunk(sql, 0)[0]).toBe(11);
+    expect(readChunk(sql, 1)[0]).toBe(22);
+  });
+
+  it('issues exactly one INSERT per touched chunk regardless of pixel count', () => {
+    const sql = createFakeSql();
+    let writes = 0;
+    const origExec = sql.exec;
+    sql.exec = (q, ...p) => {
+      if (q.startsWith('INSERT INTO canvas_chunks')) writes++;
+      return origExec(q, ...p);
+    };
+    writePixels(sql, [
+      { x: 0, y: 0, color: 1 },
+      { x: 1, y: 0, color: 2 },
+      { x: 2, y: 0, color: 3 },
+      { x: 3, y: 0, color: 4 },
+    ]);
+    expect(writes).toBe(1);
+  });
+});
+
+describe('writePixels — BLOB-grow safety', () => {
+  it('writes against chunkSize, not the persisted blob length', () => {
+    const sql = createFakeSql();
+    // Pre-seed chunk 0 with a short blob (e.g. legacy 8 KB).
+    const shortBlob = new Uint8Array(8192);
+    shortBlob[100] = 7;
+    sql._seedChunk(0, shortBlob);
+
+    // Write a pixel at byteOffset 30000 — well beyond the seeded 8 KB.
+    // y=0, x=30000 → offset=30000 → chunk 0, byteOffset 30000.
+    writePixels(sql, [{ x: 30000, y: 0, color: 123 }]);
+
+    const buf = readChunk(sql, 0);
+    expect(buf.length).toBe(CHUNK_BYTES);
+    expect(buf[100]).toBe(7);       // preserved
+    expect(buf[30000]).toBe(123);   // newly written, would have been dropped
+  });
+});
+
+describe('readAllChunks', () => {
+  it('returns a TOTAL_PIXELS Uint8Array even when chunks are empty', () => {
+    const sql = createFakeSql();
+    const out = readAllChunks(sql);
+    expect(out).toBeInstanceOf(Uint8Array);
+    expect(out.length).toBe(TOTAL_PIXELS);
+    expect(out[0]).toBe(0);
+    expect(out[TOTAL_PIXELS - 1]).toBe(0);
+  });
+
+  it('concatenates seeded chunks at correct offsets', () => {
+    const sql = createFakeSql();
+    const c0 = new Uint8Array(CHUNK_BYTES);
+    c0[0] = 1;
+    c0[CHUNK_BYTES - 1] = 2;
+    const c1 = new Uint8Array(CHUNK_BYTES);
+    c1[0] = 3;
+    sql._seedChunk(0, c0);
+    sql._seedChunk(1, c1);
+
+    const out = readAllChunks(sql);
+    expect(out[0]).toBe(1);
+    expect(out[CHUNK_BYTES - 1]).toBe(2);
+    expect(out[CHUNK_BYTES]).toBe(3);
+  });
+
+  it('skips orphan rows with chunk_id >= CHUNK_COUNT (canvas-shrink residue)', () => {
+    const sql = createFakeSql();
+    // Seed a valid chunk and an orphan past the boundary.
+    const c0 = new Uint8Array(CHUNK_BYTES);
+    c0[0] = 9;
+    sql._seedChunk(0, c0);
+    const orphan = new Uint8Array(CHUNK_BYTES);
+    orphan[0] = 99;
+    sql._seedChunk(CHUNK_COUNT + 5, orphan);
+
+    const out = readAllChunks(sql);
+    expect(out.length).toBe(TOTAL_PIXELS);
+    expect(out[0]).toBe(9);
+    // Orphan would have caused a RangeError on out.set() if not bounded.
+  });
+
+  it('trims oversized blobs at the last chunk to expected size', () => {
+    const sql = createFakeSql();
+    // Last chunk's "expected" size equals CHUNK_BYTES when TOTAL_PIXELS is a
+    // multiple of CHUNK_BYTES (our current case). Seed an oversized blob and
+    // verify no overflow into adjacent memory.
+    const lastId = CHUNK_COUNT - 1;
+    const oversized = new Uint8Array(CHUNK_BYTES + 100);
+    oversized[0] = 4;
+    oversized[CHUNK_BYTES + 99] = 7; // beyond expected — must be trimmed
+    sql._seedChunk(lastId, oversized);
+
+    // Should not throw.
+    const out = readAllChunks(sql);
+    expect(out.length).toBe(TOTAL_PIXELS);
+    const lastChunkStart = lastId * CHUNK_BYTES;
+    expect(out[lastChunkStart]).toBe(4);
+  });
+});
+
+describe('pixel-to-chunk math (coverage via writePixels)', () => {
+  it('maps (x,y) coordinates to the expected chunk index', () => {
+    const sql = createFakeSql();
+    // Pick a y that crosses chunk boundaries: y=16 with CANVAS_WIDTH=4096
+    // gives offset = 65536 → chunk 1, byteOffset 0.
+    writePixels(sql, [{ x: 0, y: CHUNK_BYTES / CANVAS_WIDTH, color: 200 }]);
+    expect(sql._chunks.size).toBe(1);
+    expect(sql._chunks.has(1)).toBe(true);
+    expect(readChunk(sql, 1)[0]).toBe(200);
+  });
+});

test/durable-objects/cooldown-store.test.js

@@ -0,0 +1,144 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { tryAcquire, release, gc } from '../../src/durable-objects/lib/cooldown-store.js';
+import { REQUEST_COOLDOWN_SEC } from '../../src/lib/constants.js';
+import { createFakeSql } from '../helpers/fake-sql.js';
+
+const TTL_MS = REQUEST_COOLDOWN_SEC * 1000;
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('tryAcquire — first call', () => {
+  it('inserts a fresh row and returns allowed', () => {
+    const sql = createFakeSql();
+    const now = 1_000_000;
+    const r = tryAcquire(sql, 'cookie:abc', now);
+    expect(r).toEqual({ allowed: true, retryAfter: 0 });
+    expect(sql._cooldowns.get('cookie:abc')).toBe(now + TTL_MS);
+  });
+});
+
+describe('tryAcquire — within window', () => {
+  it('rejects a second call inside TTL', () => {
+    const sql = createFakeSql();
+    const now = 1_000_000;
+    tryAcquire(sql, 'cookie:abc', now);
+    const r = tryAcquire(sql, 'cookie:abc', now + 500);
+    expect(r.allowed).toBe(false);
+    expect(r.retryAfter).toBe(REQUEST_COOLDOWN_SEC);
+    // The active row should remain untouched.
+    expect(sql._cooldowns.get('cookie:abc')).toBe(now + TTL_MS);
+  });
+});
+
+describe('tryAcquire — after window expires', () => {
+  it('accepts a second call after expires_at', () => {
+    const sql = createFakeSql();
+    const now = 1_000_000;
+    tryAcquire(sql, 'cookie:abc', now);
+    const later = now + TTL_MS + 1;
+    const r = tryAcquire(sql, 'cookie:abc', later);
+    expect(r.allowed).toBe(true);
+    expect(sql._cooldowns.get('cookie:abc')).toBe(later + TTL_MS);
+  });
+
+  it('accepts exactly at expires_at boundary (<=)', () => {
+    const sql = createFakeSql();
+    const now = 1_000_000;
+    tryAcquire(sql, 'cookie:abc', now);
+    const r = tryAcquire(sql, 'cookie:abc', now + TTL_MS);
+    expect(r.allowed).toBe(true);
+  });
+});
+
+describe('tryAcquire — independent users', () => {
+  it('does not interfere across user IDs', () => {
+    const sql = createFakeSql();
+    const now = 1_000_000;
+    expect(tryAcquire(sql, 'cookie:a', now).allowed).toBe(true);
+    expect(tryAcquire(sql, 'cookie:b', now).allowed).toBe(true);
+    expect(tryAcquire(sql, 'cookie:a', now).allowed).toBe(false);
+    expect(tryAcquire(sql, 'cookie:b', now).allowed).toBe(false);
+  });
+});
+
+describe('tryAcquire — INSERT branch executes (cursor drain)', () => {
+  it('persists the INSERT even when no UPDATE preceded it', () => {
+    const sql = createFakeSql();
+    let inserts = 0;
+    const origExec = sql.exec;
+    sql.exec = (q, ...p) => {
+      if (q.startsWith('INSERT INTO cooldowns')) inserts++;
+      return origExec(q, ...p);
+    };
+    tryAcquire(sql, 'cookie:fresh', 1_000_000);
+    expect(inserts).toBe(1);
+    expect(sql._cooldowns.has('cookie:fresh')).toBe(true);
+  });
+});
+
+describe('tryAcquire — GC sweep sampling', () => {
+  it('deletes expired rows when the sample fires', () => {
+    const sql = createFakeSql();
+    // Seed expired rows.
+    sql._seedCooldown('cookie:dead1', 100);
+    sql._seedCooldown('cookie:dead2', 200);
+    // Force the sample to fire.
+    vi.spyOn(Math, 'random').mockReturnValue(0);
+    tryAcquire(sql, 'cookie:fresh', 1_000_000);
+    expect(sql._cooldowns.has('cookie:dead1')).toBe(false);
+    expect(sql._cooldowns.has('cookie:dead2')).toBe(false);
+    expect(sql._cooldowns.has('cookie:fresh')).toBe(true);
+  });
+
+  it('does not run GC when sample misses', () => {
+    const sql = createFakeSql();
+    sql._seedCooldown('cookie:dead', 100);
+    vi.spyOn(Math, 'random').mockReturnValue(0.99);
+    tryAcquire(sql, 'cookie:fresh', 1_000_000);
+    expect(sql._cooldowns.has('cookie:dead')).toBe(true);
+  });
+
+  it('continues if GC throws (best-effort)', () => {
+    const sql = createFakeSql();
+    vi.spyOn(Math, 'random').mockReturnValue(0);
+    const origExec = sql.exec;
+    sql.exec = (q, ...p) => {
+      if (q.startsWith('DELETE FROM cooldowns WHERE expires_at')) {
+        throw new Error('boom');
+      }
+      return origExec(q, ...p);
+    };
+    const r = tryAcquire(sql, 'cookie:fresh', 1_000_000);
+    expect(r.allowed).toBe(true);
+  });
+});
+
+describe('release', () => {
+  it('removes the cooldown row so the next acquire succeeds immediately', () => {
+    const sql = createFakeSql();
+    tryAcquire(sql, 'cookie:abc', 1_000_000);
+    expect(sql._cooldowns.has('cookie:abc')).toBe(true);
+    release(sql, 'cookie:abc');
+    expect(sql._cooldowns.has('cookie:abc')).toBe(false);
+    // Second acquire at the same instant should succeed now.
+    expect(tryAcquire(sql, 'cookie:abc', 1_000_000).allowed).toBe(true);
+  });
+
+  it('is a no-op when the row does not exist', () => {
+    const sql = createFakeSql();
+    expect(() => release(sql, 'cookie:missing')).not.toThrow();
+  });
+});
+
+describe('gc', () => {
+  it('deletes only expired rows', () => {
+    const sql = createFakeSql();
+    sql._seedCooldown('cookie:dead', 100);
+    sql._seedCooldown('cookie:alive', 1_000_000_000);
+    gc(sql, 5_000_000);
+    expect(sql._cooldowns.has('cookie:dead')).toBe(false);
+    expect(sql._cooldowns.has('cookie:alive')).toBe(true);
+  });
+});