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

206 lines
6.8 KiB
TypeScript

import type { IncomingMessage, RequestListener, ServerResponse } from 'node:http';
import { Readable } from 'node:stream';
import { PgDocumentStore, ensureDocumentSchema } from '@openmaic/storage/document/pg';
import { PgRuntimeStore, ensureSchema } from '@openmaic/storage/runtime/pg';
import { createStorageHttpHandler } from '@openmaic/storage/server';
import {
nodePostgresTransaction,
type ConnectableQueryable,
} from '@openmaic/storage/server/reference';
import { Pool } from 'pg';
import { validateAppScene, validateAppStage } from '@/lib/document-store/validators';
import { authenticatePersistenceRequest } from '@/lib/persistence/server-auth';
export const runtime = 'nodejs';
const ROUTE_PREFIX = '/api/persistence';
type PoolFactory = (connectionString: string) => Pool;
interface PersistenceHandlerState {
connectionString?: string;
handlerPromise?: Promise<RequestListener>;
}
const HANDLER_STATE_KEY = Symbol.for('openmaic.persistence-route.handler');
const globalState = globalThis as typeof globalThis & {
[key: symbol]: PersistenceHandlerState | undefined;
};
const handlerState = (globalState[HANDLER_STATE_KEY] ??= {});
function jsonError(status: number, code: string, message: string): Response {
return Response.json({ error: { code, message } }, { status });
}
async function createPersistenceHandler(
connectionString: string,
poolFactory: PoolFactory,
): Promise<RequestListener> {
const pool = poolFactory(connectionString);
const queryable = pool as unknown as ConnectableQueryable;
try {
await ensureSchema(queryable);
await ensureDocumentSchema(queryable);
const withTransaction = nodePostgresTransaction(queryable);
const runtimeStore = new PgRuntimeStore(queryable, { withTransaction });
const documentStore = new PgDocumentStore(queryable, {
withTransaction,
validateScene: validateAppScene,
validateStage: validateAppStage,
});
return createStorageHttpHandler(runtimeStore, documentStore, {
authenticate: authenticatePersistenceRequest,
authorizeMerge: async () => false,
authorizeAdmin: async () => false,
authorizeDocuments: async () => true,
validateScene: validateAppScene,
validateStage: validateAppStage,
});
} catch (error) {
await pool.end().catch(() => {});
throw error;
}
}
function getPersistenceHandler(
connectionString: string,
poolFactory: PoolFactory,
): Promise<RequestListener> {
if (handlerState.handlerPromise && handlerState.connectionString === connectionString) {
return handlerState.handlerPromise;
}
handlerState.connectionString = connectionString;
const initialization = createPersistenceHandler(connectionString, poolFactory).catch((error) => {
// Do not poison the singleton with a rejected promise. createPersistenceHandler
// has already closed its failed pool, and the next request gets a clean retry.
if (handlerState.handlerPromise === initialization) {
handlerState.handlerPromise = undefined;
handlerState.connectionString = undefined;
}
throw error;
});
handlerState.handlerPromise = initialization;
return initialization;
}
function nodeRequest(request: Request): IncomingMessage {
const url = new URL(request.url);
const pathname = url.pathname.startsWith(ROUTE_PREFIX)
? url.pathname.slice(ROUTE_PREFIX.length) || '/'
: url.pathname;
const body = request.body
? Readable.fromWeb(
request.body as unknown as import('node:stream/web').ReadableStream<Uint8Array>,
)
: Readable.from([]);
return Object.assign(body, {
method: request.method,
url: `${pathname}${url.search}`,
headers: Object.fromEntries(request.headers.entries()),
}) as IncomingMessage;
}
function setHeaders(target: Headers, source: Record<string, string | number | string[]>): void {
for (const [name, value] of Object.entries(source)) {
if (Array.isArray(value)) {
for (const item of value) target.append(name, item);
} else {
target.set(name, String(value));
}
}
}
function runNodeHandler(handler: RequestListener, request: Request): Promise<Response> {
return new Promise<Response>((resolve, reject) => {
let status = 200;
const headers = new Headers();
let headersSent = false;
const response = {
get headersSent() {
return headersSent;
},
writeHead(
statusCode: number,
statusMessageOrHeaders?: string | Record<string, string | number | string[]>,
outgoingHeaders?: Record<string, string | number | string[]>,
) {
status = statusCode;
headersSent = true;
const values =
typeof statusMessageOrHeaders === 'string' ? outgoingHeaders : statusMessageOrHeaders;
if (values) setHeaders(headers, values);
return this;
},
end(chunk?: string | Uint8Array) {
headersSent = true;
resolve(
new Response(
chunk === undefined
? undefined
: typeof chunk === 'string'
? chunk
: Buffer.from(chunk).toString(),
{
status,
headers,
},
),
);
return this;
},
destroy(error?: Error) {
reject(error ?? new Error('Persistence HTTP handler destroyed the response'));
return this;
},
} as unknown as ServerResponse;
try {
handler(nodeRequest(request), response);
} catch (error) {
reject(error);
}
});
}
interface PersistenceRequestDeps {
poolFactory?: PoolFactory;
}
export async function handlePersistenceRequest(
request: Request,
deps: PersistenceRequestDeps = {},
): Promise<Response> {
const connectionString = process.env.DATABASE_URL;
if (!connectionString) {
return jsonError(404, 'PERSISTENCE_NOT_CONFIGURED', 'server persistence not configured');
}
if (!process.env.PERSISTENCE_DEV_TOKEN) {
return jsonError(
503,
'PERSISTENCE_DEV_TOKEN_MISSING',
'server persistence requires PERSISTENCE_DEV_TOKEN (development auth only)',
);
}
try {
const poolFactory = deps.poolFactory ?? ((value) => new Pool({ connectionString: value }));
return await runNodeHandler(
await getPersistenceHandler(connectionString, poolFactory),
request,
);
} catch (error) {
console.error('Embedded persistence route initialization failed', error);
return jsonError(500, 'PERSISTENCE_INIT_FAILED', 'server persistence initialization failed');
}
}
export const GET = (request: Request) => handlePersistenceRequest(request);
export const POST = (request: Request) => handlePersistenceRequest(request);
export const PUT = (request: Request) => handlePersistenceRequest(request);
export const PATCH = (request: Request) => handlePersistenceRequest(request);
export const DELETE = (request: Request) => handlePersistenceRequest(request);