wyuc e39c64cd9e
feat(persistence): one-command server-backed stack (compose profile + embedded API + docs) (#982)
* feat(persistence): one-command server-backed stack — embedded API + compose postgres profile

docker compose --profile server-persistence up --build runs exactly two
containers: the app (persistence HTTP server embedded at /api/persistence,
enabled only when DATABASE_URL is set — unset keeps today's browser-only
behavior byte-for-byte) and PostgreSQL 16. Client bootstrap configures both
storage seams against the same-origin route when NEXT_PUBLIC_PERSISTENCE=1,
riding the existing lazy migrations so prior browser data reaches the
server per-course on first open. Dev auth (bearer token + client-asserted
learner header) lives in one overridable module and is loudly documented
as development-grade. Verified end-to-end against the real stack:
document PUT/GET and runtime session create land in Postgres; bad tokens 401.

Co-authored-by: Codex <codex@openai.com>

* fix(persistence): review round — structural bootstrap ordering, retryable init, honest failure surfaces

The bootstrap side-effect import moves into the two storage seam entry
modules, so any module graph that can resolve a store necessarily
evaluates it first — no client-entry ordering luck, and the two configure
calls are all-or-nothing. A failed server init clears its cached promise
(next request retries instead of permanent 500s). listStages rethrows
backend failures and the dashboard surfaces a persistence-unavailable
error instead of rendering an empty list that reads as data loss. Docs
state the build-time nature of NEXT_PUBLIC_PERSISTENCE, the real token
boundary (any visitor can extract it and impersonate any learner —
localhost/trusted-network only), and the correct postgres password
rotation. Dev-token compare is timing-safe; the handler singleton lives
on globalThis so HMR cannot leak pools.

Co-authored-by: Codex <codex@openai.com>

* fix(persistence): review response — no-confidentiality wording + adapter round-trip coverage

The token docs now state plainly that the NEXT_PUBLIC token is compiled
into the public bundle and provides no confidentiality or user isolation
(its only role is keeping unrelated scanners off a trusted network). The
Fetch/Node adapter — the route's most bug-prone code — gains a round-trip
integration test: PUT body streaming, 201 with multi-value headers, 204
empty body, and encoded path segments reaching the handler un-decoded.

---------

Co-authored-by: Codex <codex@openai.com>
2026-07-23 16:28:03 +08:00

62 lines
2.1 KiB
TypeScript

import { BrowserKVStore, HttpDocumentStore, type HttpDocumentHeadersHook } from '@openmaic/storage';
import { HttpRuntimeStore, type HttpRuntimeHeadersHook } from '@openmaic/storage/runtime/http';
import {
assertDocumentStorageConfigurable,
configureDocumentStorage,
type DocumentStorageOptions,
} from '@/lib/document-store/config';
import { assertRuntimeStorageConfigurable, configureRuntimeStorage } from '@/lib/runtime/config';
import { getLearnerKey } from '@/lib/runtime/learner-key';
if (typeof window !== 'undefined' && process.env.NEXT_PUBLIC_PERSISTENCE === '1') {
const deviceKv = new BrowserKVStore();
let learnerKeyPromise: Promise<string> | undefined;
const learnerKey = (): Promise<string> =>
(learnerKeyPromise ??= getLearnerKey(deviceKv).catch((error) => {
learnerKeyPromise = undefined;
throw error;
}));
const token = process.env.NEXT_PUBLIC_PERSISTENCE_TOKEN;
const headers = async (): Promise<Record<string, string>> => {
const resolvedLearnerKey = await learnerKey();
return {
'x-learner-key': resolvedLearnerKey,
...(token ? { authorization: `Bearer ${token}` } : {}),
};
};
const runtimeOptions = {
store: () =>
new HttpRuntimeStore({
baseUrl: '/api/persistence',
headers: headers satisfies HttpRuntimeHeadersHook,
}),
learnerKey,
};
const documentOptions: DocumentStorageOptions = {
store: ({ validateScene, validateStage }) =>
new HttpDocumentStore({
baseUrl: '/api/persistence',
headers: headers satisfies HttpDocumentHeadersHook,
validateScene,
validateStage,
}),
};
try {
// Both checks are mutation-free. Once both pass, the synchronous configure
// calls cannot leave only one seam configured.
assertRuntimeStorageConfigurable();
assertDocumentStorageConfigurable();
configureRuntimeStorage(runtimeOptions);
configureDocumentStorage(documentOptions);
} catch (error) {
console.error(
'FATAL: server-backed persistence bootstrap failed; no storage seam changes were applied',
error,
);
}
}