* 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>
62 lines
2.1 KiB
TypeScript
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,
|
|
);
|
|
}
|
|
}
|