* ci: whitelist the document-server-backend integration trunk * feat(storage): DocumentStore HTTP contract + client + reference-server routes (1B PR1) (#975) Mirrors the runtime line's server-backed delivery for the document store: a documented /documents HTTP contract (validation/not-found/FUTURE_VERSION taxonomy; authorization stays a deployment concern via injected hooks with an any-authenticated default), an HttpDocumentStore that runs the same validators and migrate-on-read semantics as the browser backend before and after the wire, and document routes on the shared reference server — one server, both stores. The backend-agnostic document contract suite now runs against HTTP → reference server → browser store. Co-authored-by: Codex <codex@openai.com> * ci: whitelist the trunk in the storage PG contract workflow too * feat(storage): PgDocumentStore — Postgres document backend (1B PR2) (#976) Implements the full DocumentStore contract over document_stages / document_scenes / document_outlines, reusing the pure adapter split so every backend shares one aggregate semantics: saveDocument replaces the aggregate in one transaction under the stage row's FOR UPDATE lock (vanished scenes deleted, outline row added/removed — omission means deletion), incremental putStage/putScene/deleteScene take the same current-version gate as the browser backend, loads read FOR SHARE and migrate without writing back, listings never touch content, and deletes cascade by FK. The document contract suite is PG-gated the same way the runtime one is; local coverage comes from stubbed-queryable unit tests. Co-authored-by: Codex <codex@openai.com> * feat(document-store): sealed bootstrap injection seam for the document backend (1B PR3) (#977) configureDocumentStorage mirrors the runtime seam: module-level bootstrap injection sealed after first resolution, a factory that receives the app validators so a server-backed store cannot silently skip them, and reset-for-tests wiring. A deployment swaps the browser document backend for HttpDocumentStore without touching app code. Storage README roadmap updated — the document HTTP/PG backend items are done. Co-authored-by: Codex <codex@openai.com> * fix(storage): 1B final-review hardening — error classification, JSON-safety, body limits, parity coverage (#978) Unversioned legacy incremental writes classify as 400 instead of leaking a 500; document/scene reads assert JSON safety before serialization so a structured-clone value fails loud (500 NOT_JSON_SAFE naming the path) instead of silently converting; a shared streaming body reader bounds request bodies (default 32 MiB, 413 PAYLOAD_TOO_LARGE, option exposed through every handler factory); the putStage stale/future guards and corrupt-stamp listing tolerance move into the shared contract suite so all four backends prove them; both HTTP store errors retain structured details. Co-authored-by: Codex <codex@openai.com> * refactor(storage): typed document version/not-found errors replace prose classification (#980) DocumentVersionError (future | not-current, storedVersion) and DocumentNotFoundError now carry the classification the server previously regex-derived from message prose — instanceof matching mirrors the runtime sibling's RuntimeAppendConflictError pattern, so a wording change can no longer silently break status mapping. The prose fallback remains, after the typed checks, solely for third-party DocumentStore implementations. The HTTP client rematerializes 409s as DocumentVersionError for symmetry, and http.ts's private validator fields are renamed to match the public option names all three backends already share. Co-authored-by: Codex <codex@openai.com> --------- Co-authored-by: Codex <codex@openai.com>
414 lines
16 KiB
TypeScript
414 lines
16 KiB
TypeScript
// Implementation-agnostic contract for `DocumentStore`. Every backend (browser
|
|
// today, HTTP later) is proven equivalent by running this same suite against it,
|
|
// so a new backend cannot silently diverge from the store's semantics.
|
|
//
|
|
// The harness exposes a narrow raw-version seeding seam so version-guard and
|
|
// corrupt-stamp behavior is proven identically by every backend.
|
|
import { describe, expect, test } from 'vitest';
|
|
import { DSL_VERSION } from '@openmaic/dsl';
|
|
import type { Scene } from '@openmaic/dsl';
|
|
import { DocumentVersionError, type DocumentStore, type MaicDocument } from '../src/index.js';
|
|
|
|
// --- fixtures ---------------------------------------------------------------
|
|
|
|
// Fixtures are cast through `unknown`: `validateScene` only requires `content.canvas`
|
|
// to be an object, so these minimal shapes are valid at the boundary without
|
|
// spelling out a full `Slide` (viewportSize / theme / …) the store never inspects.
|
|
|
|
/** A valid slide scene (passes `validateScene`: id/stageId/title/order + slide content). */
|
|
export function slideScene(stageId: string, id: string, order: number, title = id): Scene {
|
|
return {
|
|
id,
|
|
stageId,
|
|
title,
|
|
order,
|
|
type: 'slide',
|
|
content: { type: 'slide', canvas: { id: `canvas-${id}`, elements: [] } },
|
|
} as unknown as Scene;
|
|
}
|
|
|
|
/** A valid quiz scene. */
|
|
export function quizScene(stageId: string, id: string, order: number, title = id): Scene {
|
|
return {
|
|
id,
|
|
stageId,
|
|
title,
|
|
order,
|
|
type: 'quiz',
|
|
content: {
|
|
type: 'quiz',
|
|
questions: [{ id: `q-${id}`, type: 'single', question: 'Q?' }],
|
|
},
|
|
} as unknown as Scene;
|
|
}
|
|
|
|
/** A valid document: stage metadata + two scenes + an outline snapshot. */
|
|
export function makeDocument(stageId = 'stage-1'): MaicDocument {
|
|
return {
|
|
stage: { id: stageId, name: 'Intro Course', createdAt: 1000, updatedAt: 2000 },
|
|
scenes: [slideScene(stageId, 'scene-a', 0), quizScene(stageId, 'scene-b', 1)],
|
|
outline: { entries: [{ id: 'o1', title: 'Intro' }], generationComplete: true },
|
|
};
|
|
}
|
|
|
|
// --- contract ---------------------------------------------------------------
|
|
|
|
export interface DocumentStoreContractHarness {
|
|
store: DocumentStore;
|
|
seedStoredVersion(stageId: string, version: string | undefined): Promise<void>;
|
|
}
|
|
|
|
export function runDocumentStoreContract(
|
|
name: string,
|
|
makeContractHarness: () => DocumentStoreContractHarness,
|
|
): void {
|
|
describe(`DocumentStore contract: ${name}`, () => {
|
|
const makeStore = (): DocumentStore => makeContractHarness().store;
|
|
test('round-trips a full document (stage + scenes + outline)', async () => {
|
|
const store = makeStore();
|
|
const doc = makeDocument();
|
|
await store.saveDocument(doc);
|
|
|
|
const loaded = await store.loadDocument('stage-1');
|
|
expect(loaded).not.toBeNull();
|
|
expect(loaded!.stage).toMatchObject(doc.stage);
|
|
expect(loaded!.scenes.map((s) => s.id)).toEqual(['scene-a', 'scene-b']);
|
|
expect(loaded!.outline).toEqual(doc.outline);
|
|
});
|
|
|
|
test('loadDocument returns null for an unknown stage', async () => {
|
|
const store = makeStore();
|
|
expect(await store.loadDocument('nope')).toBeNull();
|
|
});
|
|
|
|
test('scenes come back sorted by order regardless of input order', async () => {
|
|
const store = makeStore();
|
|
const doc = makeDocument('stage-x');
|
|
doc.scenes = [
|
|
slideScene('stage-x', 'third', 2),
|
|
slideScene('stage-x', 'first', 0),
|
|
slideScene('stage-x', 'second', 1),
|
|
];
|
|
await store.saveDocument(doc);
|
|
|
|
const loaded = await store.loadDocument('stage-x');
|
|
expect(loaded!.scenes.map((s) => s.id)).toEqual(['first', 'second', 'third']);
|
|
});
|
|
|
|
test('stamps the current DSL version on load', async () => {
|
|
const store = makeStore();
|
|
await store.saveDocument(makeDocument());
|
|
const loaded = await store.loadDocument('stage-1');
|
|
expect(loaded!.dslVersion).toBe(DSL_VERSION);
|
|
});
|
|
|
|
test('listDocuments returns one summary per stage with a scene count', async () => {
|
|
const store = makeStore();
|
|
await store.saveDocument(makeDocument('stage-1'));
|
|
await store.saveDocument(makeDocument('stage-2'));
|
|
|
|
const list = await store.listDocuments();
|
|
expect(list.map((d) => d.id).sort()).toEqual(['stage-1', 'stage-2']);
|
|
const one = list.find((d) => d.id === 'stage-1')!;
|
|
expect(one).toMatchObject({ name: 'Intro Course', createdAt: 1000, sceneCount: 2 });
|
|
});
|
|
|
|
test('deleteDocument removes the stage, its scenes, and its outline', async () => {
|
|
const store = makeStore();
|
|
await store.saveDocument(makeDocument());
|
|
await store.deleteDocument('stage-1');
|
|
|
|
expect(await store.loadDocument('stage-1')).toBeNull();
|
|
expect(await store.getScene('stage-1', 'scene-a')).toBeNull();
|
|
expect(await store.listDocuments()).toEqual([]);
|
|
});
|
|
|
|
test('deleteDocument is idempotent', async () => {
|
|
const store = makeStore();
|
|
await store.deleteDocument('never-existed');
|
|
await store.saveDocument(makeDocument());
|
|
await store.deleteDocument('stage-1');
|
|
await expect(store.deleteDocument('stage-1')).resolves.toBeUndefined();
|
|
});
|
|
|
|
test('putStage updates only the stage row of an existing document', async () => {
|
|
const store = makeStore();
|
|
const doc = makeDocument();
|
|
await store.saveDocument(doc);
|
|
|
|
await store.putStage('stage-1', { ...doc.stage, name: 'Renamed', updatedAt: 3000 });
|
|
|
|
const loaded = await store.loadDocument('stage-1');
|
|
expect(loaded!.stage).toMatchObject({ name: 'Renamed', updatedAt: 3000 });
|
|
expect(loaded!.scenes).toEqual(doc.scenes);
|
|
expect(loaded!.outline).toEqual(doc.outline);
|
|
});
|
|
|
|
test('putStage rejects when the document is absent', async () => {
|
|
const store = makeStore();
|
|
await expect(
|
|
store.putStage('ghost-stage', {
|
|
id: 'ghost-stage',
|
|
name: 'Missing',
|
|
createdAt: 1,
|
|
updatedAt: 2,
|
|
}),
|
|
).rejects.toThrow(/missing document/);
|
|
});
|
|
|
|
test('putStage rejects a stale stored document', async () => {
|
|
const { store, seedStoredVersion } = makeContractHarness();
|
|
const doc = makeDocument();
|
|
await store.saveDocument(doc);
|
|
await seedStoredVersion('stage-1', undefined);
|
|
|
|
await expect(
|
|
store.putStage('stage-1', { ...doc.stage, name: 'Stale Rename' }),
|
|
).rejects.toThrow();
|
|
expect((await store.loadDocument('stage-1'))!.stage.name).toBe('Intro Course');
|
|
});
|
|
|
|
test('putStage rejects a future-versioned stored document', async () => {
|
|
const { store, seedStoredVersion } = makeContractHarness();
|
|
const doc = makeDocument();
|
|
await store.saveDocument(doc);
|
|
await seedStoredVersion('stage-1', '99.0.0');
|
|
|
|
await expect(
|
|
store.putStage('stage-1', { ...doc.stage, name: 'Future Rename' }),
|
|
).rejects.toThrow();
|
|
expect((await store.loadDocument('stage-1'))!.stage.name).toBe('Intro Course');
|
|
});
|
|
|
|
test('listDocuments tolerates a corrupt stored version stamp', async () => {
|
|
const { store, seedStoredVersion } = makeContractHarness();
|
|
await store.saveDocument(makeDocument());
|
|
await seedStoredVersion('stage-1', 'not-a-version');
|
|
|
|
await expect(store.listDocuments()).resolves.toEqual([
|
|
expect.objectContaining({ id: 'stage-1', name: 'Intro Course', sceneCount: 2 }),
|
|
]);
|
|
await expect(store.loadDocument('stage-1')).rejects.toThrow();
|
|
});
|
|
|
|
// --- validation gate ---
|
|
|
|
test('rejects a document whose stage is missing required fields', async () => {
|
|
const store = makeStore();
|
|
const doc = makeDocument();
|
|
// drop the required `name`
|
|
delete (doc.stage as { name?: string }).name;
|
|
await expect(store.saveDocument(doc)).rejects.toThrow();
|
|
});
|
|
|
|
test('rejects a document with an invalid scene', async () => {
|
|
const store = makeStore();
|
|
const doc = makeDocument();
|
|
// a slide scene whose content type disagrees with the scene type
|
|
(doc.scenes[0] as { content: unknown }).content = { type: 'quiz', questions: [] };
|
|
await expect(store.saveDocument(doc)).rejects.toThrow();
|
|
});
|
|
|
|
test('a rejected save leaves the store untouched (atomic)', async () => {
|
|
const store = makeStore();
|
|
await store.saveDocument(makeDocument());
|
|
|
|
const bad = makeDocument();
|
|
bad.stage.name = 'Renamed';
|
|
bad.scenes.push({ id: 'broken', stageId: 'stage-1' } as unknown as Scene); // invalid scene
|
|
await expect(store.saveDocument(bad)).rejects.toThrow();
|
|
|
|
// original persists; nothing from the bad save landed
|
|
const loaded = await store.loadDocument('stage-1');
|
|
expect(loaded!.stage.name).toBe('Intro Course');
|
|
expect(loaded!.scenes.map((s) => s.id)).toEqual(['scene-a', 'scene-b']);
|
|
expect(await store.getScene('stage-1', 'broken')).toBeNull();
|
|
});
|
|
|
|
test('rejects a scene whose stageId does not match the document', async () => {
|
|
const store = makeStore();
|
|
const doc = makeDocument('stage-1');
|
|
// a scene mis-assigned to a different stage would otherwise be written to a
|
|
// phantom partition no read path can see — fail loud instead of losing it.
|
|
doc.scenes = [slideScene('stage-1', 'ok', 0), slideScene('other-stage', 'stray', 1)];
|
|
await expect(store.saveDocument(doc)).rejects.toThrow();
|
|
// nothing landed: the whole save is rejected before any write
|
|
expect(await store.loadDocument('stage-1')).toBeNull();
|
|
expect(await store.getScene('other-stage', 'stray')).toBeNull();
|
|
});
|
|
|
|
test('rejects a scene with a non-finite order', async () => {
|
|
const store = makeStore();
|
|
const doc = makeDocument();
|
|
// NaN/Infinity are `typeof number` but break the read-time `order` sort.
|
|
(doc.scenes[0] as { order: number }).order = NaN;
|
|
await expect(store.saveDocument(doc)).rejects.toThrow();
|
|
expect(await store.loadDocument('stage-1')).toBeNull();
|
|
});
|
|
|
|
test('rejects duplicate scene ids within a document', async () => {
|
|
const store = makeStore();
|
|
const doc = makeDocument('stage-1');
|
|
doc.scenes = [slideScene('stage-1', 'dup', 0), slideScene('stage-1', 'dup', 1)];
|
|
await expect(store.saveDocument(doc)).rejects.toThrow();
|
|
// rejected before any write — nothing landed
|
|
expect(await store.loadDocument('stage-1')).toBeNull();
|
|
});
|
|
|
|
test('rejects saving a document stamped at an unknown/unreachable DSL version', async () => {
|
|
const store = makeStore();
|
|
const doc = makeDocument();
|
|
// A stale stamp with no path up the DSL migration ladder is corrupt input —
|
|
// fail loud rather than persist it mislabeled as current.
|
|
doc.dslVersion = '0.0.1';
|
|
await expect(store.saveDocument(doc)).rejects.toThrow();
|
|
expect(await store.loadDocument('stage-1')).toBeNull();
|
|
});
|
|
|
|
test('normalizes a legacy-stamped document to the current version on save', async () => {
|
|
const store = makeStore();
|
|
const doc = makeDocument();
|
|
// A pre-versioning stamp is lifted forward by the ladder, then persisted at
|
|
// the current version (never mislabeled without running migrate()).
|
|
doc.dslVersion = '0.0.0';
|
|
await store.saveDocument(doc);
|
|
const loaded = await store.loadDocument('stage-1');
|
|
expect(loaded!.dslVersion).toBe(DSL_VERSION);
|
|
// the opaque outline survives migration verbatim (it is not DSL-shaped, so
|
|
// migrations never see it)
|
|
expect(loaded!.outline).toEqual(doc.outline);
|
|
});
|
|
|
|
test('rejects saving a document written by a newer client', async () => {
|
|
const store = makeStore();
|
|
await store.saveDocument(makeDocument()); // current
|
|
|
|
const future = makeDocument();
|
|
future.dslVersion = '99.0.0';
|
|
future.stage.name = 'Should Not Persist';
|
|
// an old client must not overwrite (and downgrade) a newer-versioned document
|
|
const failure = store.saveDocument(future);
|
|
await expect(failure).rejects.toBeInstanceOf(DocumentVersionError);
|
|
await expect(failure).rejects.toMatchObject({
|
|
stageId: 'stage-1',
|
|
kind: 'future',
|
|
storedVersion: '99.0.0',
|
|
});
|
|
|
|
const loaded = await store.loadDocument('stage-1');
|
|
expect(loaded!.stage.name).toBe('Intro Course');
|
|
});
|
|
|
|
// --- incremental scene ops ---
|
|
|
|
test('putScene inserts a new scene into an existing document', async () => {
|
|
const store = makeStore();
|
|
await store.saveDocument(makeDocument());
|
|
await store.putScene('stage-1', slideScene('stage-1', 'scene-c', 2));
|
|
|
|
const loaded = await store.loadDocument('stage-1');
|
|
expect(loaded!.scenes.map((s) => s.id)).toEqual(['scene-a', 'scene-b', 'scene-c']);
|
|
});
|
|
|
|
test('putScene overwrites an existing scene', async () => {
|
|
const store = makeStore();
|
|
await store.saveDocument(makeDocument());
|
|
await store.putScene('stage-1', slideScene('stage-1', 'scene-a', 0, 'Renamed Title'));
|
|
|
|
const scene = await store.getScene('stage-1', 'scene-a');
|
|
expect(scene!.title).toBe('Renamed Title');
|
|
});
|
|
|
|
test('putScene rejects a scene whose stageId does not match the argument', async () => {
|
|
const store = makeStore();
|
|
await store.saveDocument(makeDocument('stage-1'));
|
|
await expect(
|
|
store.putScene('stage-1', slideScene('other-stage', 'stray', 2)),
|
|
).rejects.toThrow();
|
|
// the mismatched scene is not reachable under either stage
|
|
expect(await store.getScene('stage-1', 'stray')).toBeNull();
|
|
expect(await store.getScene('other-stage', 'stray')).toBeNull();
|
|
});
|
|
|
|
test('putScene rejects when the parent document is absent', async () => {
|
|
const store = makeStore();
|
|
await expect(
|
|
store.putScene('ghost-stage', slideScene('ghost-stage', 's', 0)),
|
|
).rejects.toThrow();
|
|
});
|
|
|
|
test('putScene validates the scene', async () => {
|
|
const store = makeStore();
|
|
await store.saveDocument(makeDocument());
|
|
await expect(
|
|
store.putScene('stage-1', { id: 'x', stageId: 'stage-1' } as unknown as Scene),
|
|
).rejects.toThrow();
|
|
});
|
|
|
|
test('getScene returns null for a missing scene', async () => {
|
|
const store = makeStore();
|
|
await store.saveDocument(makeDocument());
|
|
expect(await store.getScene('stage-1', 'no-such-scene')).toBeNull();
|
|
});
|
|
|
|
test('deleteScene removes one scene and leaves the others', async () => {
|
|
const store = makeStore();
|
|
await store.saveDocument(makeDocument());
|
|
await store.deleteScene('stage-1', 'scene-a');
|
|
|
|
const loaded = await store.loadDocument('stage-1');
|
|
expect(loaded!.scenes.map((s) => s.id)).toEqual(['scene-b']);
|
|
await expect(store.deleteScene('stage-1', 'scene-a')).resolves.toBeUndefined();
|
|
});
|
|
|
|
test('deleteScene on an absent document is a no-op', async () => {
|
|
const store = makeStore();
|
|
await expect(store.deleteScene('ghost-stage', 'x')).resolves.toBeUndefined();
|
|
});
|
|
|
|
// --- diff-on-write (observable behaviour) ---
|
|
|
|
test('re-saving reconciles added / edited / removed scenes', async () => {
|
|
const store = makeStore();
|
|
await store.saveDocument(makeDocument()); // scene-a, scene-b
|
|
|
|
const next = makeDocument();
|
|
next.scenes = [
|
|
slideScene('stage-1', 'scene-a', 0, 'Edited A'), // edited
|
|
slideScene('stage-1', 'scene-c', 1), // added; scene-b removed
|
|
];
|
|
await store.saveDocument(next);
|
|
|
|
const loaded = await store.loadDocument('stage-1');
|
|
expect(loaded!.scenes.map((s) => s.id)).toEqual(['scene-a', 'scene-c']);
|
|
expect(loaded!.scenes.find((s) => s.id === 'scene-a')!.title).toBe('Edited A');
|
|
expect(await store.getScene('stage-1', 'scene-b')).toBeNull();
|
|
});
|
|
|
|
// --- outline snapshot ---
|
|
|
|
test('persists the outline verbatim and can clear it', async () => {
|
|
const store = makeStore();
|
|
const doc = makeDocument();
|
|
await store.saveDocument(doc);
|
|
expect((await store.loadDocument('stage-1'))!.outline).toEqual(doc.outline);
|
|
|
|
const withoutOutline = makeDocument();
|
|
delete withoutOutline.outline;
|
|
await store.saveDocument(withoutOutline);
|
|
expect((await store.loadDocument('stage-1'))!.outline).toBeUndefined();
|
|
});
|
|
|
|
test('documents are isolated from one another', async () => {
|
|
const store = makeStore();
|
|
await store.saveDocument(makeDocument('stage-1'));
|
|
await store.saveDocument(makeDocument('stage-2'));
|
|
await store.deleteScene('stage-1', 'scene-a');
|
|
|
|
// stage-2 untouched by a stage-1 scene delete
|
|
const two = await store.loadDocument('stage-2');
|
|
expect(two!.scenes.map((s) => s.id)).toEqual(['scene-a', 'scene-b']);
|
|
});
|
|
});
|
|
}
|