@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/src/server/README.md

@@ -15,6 +15,9 @@ server/
 	App.ts
 	appContext.ts
 	RequestContext.ts
+	registerBrowserJsonFormatting.ts
+	registerHttpErrorHandler.ts
+	publicServerErrorMessage.ts
 	tests/
 	index.ts
 	README.md
@@ -22,7 +25,7 @@ server/
 
 `App` composes framework services but leaves their behavior in the owning
 service modules. It currently discovers database, auth, request context, cache,
-events, logging, URL, queue, scheduler, security, serialization, storage, and
+events, health, logging, URL, queue, scheduler, security, serialization, storage, and
 media services. Application-specific capabilities belong on an application
 subclass and can reuse `service(...)` for lazy singleton ownership.
 
@@ -44,6 +47,15 @@ The public surface includes:
 - `activeAppDatabase()` and `activeAppRequestContext()`, which expose optional
   low-level context to framework internals.
 - `RequestContext` and `RequestContextValues` for request-isolated values.
+- `registerHttpErrorHandler(...)` for the shared Fastify error boundary and
+  `publicServerErrorMessage(...)` for other server-owned error renderers.
+- `registerBrowserJsonFormatting(...)` for servers with their own error handler;
+  the shared error boundary installs it automatically.
+
+Standalone HTTP hosts can import the formatting hook from
+`@db3.ai/app/server/browser-json`. This narrow entry point does not load `App`
+or its database, AI, storage, and queue dependencies when the host bundles only
+the hook into an isolated website runtime.
 
 Normal application code should use `app().db`, `app().queue`, and the other
 service getters. `activeAppDatabase()` is a framework escape hatch, not a
@@ -164,7 +176,78 @@ request-owned store.
 
 ## Shutdown And Failure Behaviour
 
-`App.close()` clears the active reference when it owns it, detaches the Scheduler recorder,
+### Browser JSON navigation
+
+Visit a JSON route such as `/health` directly in a browser to see indented
+JSON. `registerHttpErrorHandler(server)` installs this behavior once for every
+route on that Fastify server. A server with its own error handler can use the
+framework hook independently before registering routes:
+
+```ts
+import { registerBrowserJsonFormatting } from '@db3.ai/app/server';
+
+registerBrowserJsonFormatting(server);
+```
+
+Only a GET request with `Sec-Fetch-Mode: navigate` receives readable spacing.
+A browser `fetch()`, POST, API client, or request without navigation metadata
+keeps compact JSON. Detection does not depend on `User-Agent` or `Accept`, which
+cannot reliably distinguish a page visit from a JavaScript request. The body
+remains `application/json` with the same data and HTTP status.
+
+The send hook runs after Fastify's response schema has filtered the payload and,
+when registered through the shared error boundary, after its production error
+sanitizer. It preserves existing `Vary` fields and adds `Sec-Fetch-Mode` so a
+cache keeps the two representations separate. Streams, encoded responses,
+attachments, responses with integrity headers, and JSON bodies over 1,000,000
+characters remain untouched. Depth and formatted-size limits also bound this
+browser-only work. Formatting removes a pre-set `Content-Length` so Fastify can
+write the correct length.
+
+### HTTP errors
+
+Install the framework boundary immediately after creating Fastify, **before any
+routes or plugins** (including awaited plugin registration):
+
+```ts
+import Fastify from 'fastify';
+import { registerHttpErrorHandler } from '@db3.ai/app/server';
+
+const server = Fastify({ logger: true });
+registerHttpErrorHandler(server);
+```
+
+Production, staging, unknown and unset `NODE_ENV` values receive only
+`{ error: 'server_error', message: 'Unexpected server error', reference }` for
+5xx responses. The final send hook replaces serialized bodies as well as thrown
+errors, including bodies returned by child-plugin error handlers or shaped by
+route response schemas. It preserves the HTTP failure status and disables caching.
+Captured SQL exceptions remain 500 errors even if a child handler tries to
+return them with a client or success status.
+SQL text, driver codes, provider payloads, stacks and nested exception metadata
+are never copied into that public envelope.
+
+Explicit `dev`, `develop`, `development`, `local` and `test` environments retain
+diagnostic messages. The original exception is logged through `request.log`
+with the same generated reference in every environment. Applications must enable
+and retain their server logs; Fastify with logging disabled has no log sink.
+The optional `onServerError(error, context)` observer can retain a support record.
+Explicitly returned 5xx bodies are retained in the server-only `responseBody`
+context/log field. Observer failures are logged without changing the public body.
+
+Fastify request-validation/parsing failures retain their 4xx status and message;
+missing ActiveRecord records return 404. Use `mapError` only for known application
+errors with deliberately public client messages. A third-party `statusCode: 400`
+does not make an exception safe. Mapped 5xx messages are still hidden in production.
+
+This boundary protects the ordinary Fastify reply lifecycle. Responses written
+directly to the raw socket, already-started streams, errors embedded inside
+successful 2xx data, and later send hooks that rewrite the body need their own
+safe public protocol. Do not return raw exceptions through those paths. CLI and
+worker exceptions keep their server-side diagnostics; database errors themselves
+are never mutated or stripped of information.
+
+`App.close()` first closes mounted WebSocket connections, then clears the active reference when it owns it, detaches the Scheduler recorder,
 clears Events listeners, awaits Cache and Log shutdown, closes the
 framework-owned default database, and clears cached service instances.
 Application subclasses remain responsible for closing any additional resources
@@ -217,3 +300,13 @@ specific real framework component they need, then call `close()` or
 and [`RequestContext.ts`](./RequestContext.ts). Behavioural tests live at
 `packages/app/src/server/tests/` in the source repository and are not included
 in the installed runtime package.
+
+## Composing feature apps
+
+Set the host directory and call `await application.apps.boot()` before serving
+requests. DB3 discovers apps/{id}/manifest.json and marked direct npm dependencies.
+A root App.ts extends AppService; app().social resolves the optional service.
+Generated declarations preserve its type. Explicit defineApp maps are supported
+for programmatic composition; an empty map disables discovery. App.close()
+releases app-owned resources before shared services. See [Apps](../apps/README.md)
+for local folders, npm packaging, owned migrations and administrator controls.

package/src/server/contracts/HttpErrorHandlerOptions.ts

@@ -0,0 +1,29 @@
+import type { FastifyRequest } from 'fastify';
+
+/** Application-owned mapping for deliberate HTTP failures, never arbitrary provider errors. */
+export interface HttpErrorResponse {
+	/** HTTP failure status between 400 and 599. */
+	statusCode: number;
+	/** Public client-error copy. Production 5xx bodies are always replaced. */
+	body: { error: string; message: string };
+}
+
+/** Server-only diagnostics passed to an application's support-record store. */
+export interface HttpServerErrorContext {
+	/** Request whose logger and ID correlate the failure. */
+	request: FastifyRequest;
+	/** Actual HTTP response status. */
+	statusCode: number;
+	/** Framework-generated reference shared by logs and the public response. */
+	reference: string;
+	/** Explicitly returned error body, if no exception reached the handler. Never public in production. */
+	responseBody?: string;
+}
+
+/** Application integration points for the framework's HTTP error boundary. */
+export interface HttpErrorHandlerOptions {
+	/** Map only known application errors; returning undefined uses framework classification. */
+	mapError?: (error: unknown) => HttpErrorResponse | undefined;
+	/** Retain extra support records after framework logging. Failures here cannot leak diagnostics. */
+	onServerError?: (error: unknown, context: HttpServerErrorContext) => void;
+}

package/src/server/contracts/index.ts

@@ -0,0 +1 @@
+export type { HttpErrorHandlerOptions, HttpErrorResponse, HttpServerErrorContext } from './HttpErrorHandlerOptions';

package/src/server/examples/createFirstServer.ts

@@ -1,5 +1,6 @@
 import Fastify, { type FastifyInstance } from 'fastify';
-import { App } from '@db3.ai/app/server';
+import { App, registerHttpErrorHandler } from '@db3.ai/app/server';
+import { registerHealthRoute } from '@db3.ai/app/health/fastify';
 
 /**
  * Creates a small HTTP application without opening a port or database.
@@ -11,10 +12,11 @@ import { App } from '@db3.ai/app/server';
  * @returns HTTP server with framework cleanup attached to its close lifecycle.
  */
 export function createFirstServer(greeting = 'Hello'): FastifyInstance {
-	const application = new App({ config: { greeting } });
+	const application = new App({ config: { greeting }, health: { service: 'first-application' } });
 	const server = Fastify();
+	registerHttpErrorHandler(server);
 	server.addHook('onClose', async () => { await application.close(); });
-	server.get('/health', async () => ({ status: 'ready' }));
+	registerHealthRoute(server, { app: application });
 	server.get<{ Params: { name: string } }>('/hello/:name', {
 		schema: { params: { type: 'object', required: ['name'], properties: { name: { type: 'string', minLength: 1, maxLength: 80 } } } },
 	}, async request => application.requestContext.run(async () => {

package/src/server/index.ts

@@ -1,3 +1,7 @@
+export * from './contracts';
+export { publicServerErrorMessage } from './publicServerErrorMessage';
+export { registerBrowserJsonFormatting } from './registerBrowserJsonFormatting';
+export { registerHttpErrorHandler } from './registerHttpErrorHandler';
 export {
 	App,
 	type AppOptions,

package/src/server/publicServerErrorMessage.ts

@@ -0,0 +1,17 @@
+import { isDevelopmentEnvironment, unknownErrorMessage } from '@db3.ai/pure';
+
+/**
+ * Returns internal diagnostics only for explicitly named development environments.
+ *
+ * Production, staging, unknown and unset environments fail closed. This policy
+ * applies to every exception, without relying on database-specific signatures.
+ *
+ * @param error - Original server-side failure; never modified by this function.
+ * @param environment - Runtime environment, defaulting to NODE_ENV.
+ * @returns Detailed development message or the generic public failure message.
+ */
+export function publicServerErrorMessage(error: unknown, environment = process.env.NODE_ENV): string {
+	return isDevelopmentEnvironment(environment)
+		? unknownErrorMessage(error) || 'Unexpected server error'
+		: 'Unexpected server error';
+}

package/src/server/registerBrowserJsonFormatting.ts

@@ -0,0 +1,94 @@
+import type { FastifyInstance, FastifyReply } from 'fastify';
+
+const MAX_PRETTY_JSON_CHARS = 1_000_000;
+const MAX_PRETTY_JSON_DEPTH = 64;
+const MAX_FORMATTED_JSON_CHARS = 4_000_000;
+const JSON_CONTENT_TYPE = /^application\/json(?:\s*;|$)/i;
+const JSON_TOKENS = /"(?:\\.|[^"\\])*"|[{}\[\],:]|[^\s{}\[\],:"]+/g;
+const BODY_PRESERVING_HEADERS = ['content-encoding', 'content-disposition', 'etag', 'content-digest', 'digest', 'content-md5'];
+
+/**
+ * Formats small JSON responses for browser page navigations across a Fastify server.
+ *
+ * Register before routes and plugins so their replies inherit the send hook. The
+ * hook runs after Fastify response-schema serialization and only reformats GET
+ * requests with `Sec-Fetch-Mode: navigate`. Browser fetches, other methods,
+ * streams, encoded bodies, and responses with integrity headers retain their
+ * original bytes. Large JSON bodies remain compact to bound browser-only work.
+ *
+ * @param server - Fastify server that owns the response lifecycle.
+ * @example
+ * const server = Fastify();
+ * registerBrowserJsonFormatting(server);
+ */
+export function registerBrowserJsonFormatting(server: FastifyInstance): void {
+	server.addHook('onSend', (request, reply, payload, done) => {
+		if (request.method !== 'GET' || typeof payload !== 'string' || payload.length > MAX_PRETTY_JSON_CHARS) return done(null, payload);
+		const contentType = reply.getHeader('content-type');
+		if (typeof contentType !== 'string' || !JSON_CONTENT_TYPE.test(contentType)) return done(null, payload);
+		if (BODY_PRESERVING_HEADERS.some(header => reply.hasHeader(header))) return done(null, payload);
+
+		varyByFetchMode(reply);
+		if (request.headers['sec-fetch-mode'] !== 'navigate') return done(null, payload);
+
+		try {
+			JSON.parse(payload);
+			const formatted = formatJsonTokens(payload);
+			if (formatted === payload) return done(null, payload);
+			reply.removeHeader('content-length');
+			return done(null, formatted);
+		} catch {
+			return done(null, payload);
+		}
+	});
+}
+
+/**
+ * Inserts spacing around validated JSON tokens without changing numeric or string literals.
+ *
+ * @param source - Valid serialized JSON whose original value tokens must be retained.
+ * @returns Indented JSON, or the original body when depth or output limits are reached.
+ */
+function formatJsonTokens(source: string): string {
+	const tokens = source.match(JSON_TOKENS);
+	if (!tokens) return source;
+	let depth = 0;
+	let formatted = '';
+
+	for (let index = 0; index < tokens.length; index++) {
+		const token = tokens[index]!;
+		if (token === '{' || token === '[') {
+			const next = tokens[index + 1];
+			if (next === (token === '{' ? '}' : ']')) {
+				formatted += token + next;
+				index++;
+			} else {
+				if (depth >= MAX_PRETTY_JSON_DEPTH) return source;
+				formatted += token + '\n' + '  '.repeat(++depth);
+			}
+		} else if (token === '}' || token === ']') {
+			formatted += '\n' + '  '.repeat(--depth) + token;
+		} else if (token === ',') {
+			formatted += ',\n' + '  '.repeat(depth);
+		} else if (token === ':') {
+			formatted += ': ';
+		} else {
+			formatted += token;
+		}
+		if (formatted.length > MAX_FORMATTED_JSON_CHARS) return source;
+	}
+
+	return formatted;
+}
+
+/**
+ * Keeps cached compact and browser-readable JSON variants separate.
+ *
+ * @param reply - Response whose existing Vary fields must be preserved.
+ */
+function varyByFetchMode(reply: FastifyReply): void {
+	const existing = reply.getHeader('vary');
+	const values = existing === undefined ? '' : String(existing);
+	if (values === '*' || values.split(',').some(value => value.trim().toLowerCase() === 'sec-fetch-mode')) return;
+	reply.header('vary', values ? `${values}, Sec-Fetch-Mode` : 'Sec-Fetch-Mode');
+}

package/src/server/registerHttpErrorHandler.ts

@@ -0,0 +1,96 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import { errorCodeForStatus, isDevelopmentEnvironment, isSqlError } from '@db3.ai/pure';
+import { ulid } from '@db3.ai/pure/ulid';
+import { RecordNotFoundError } from '../db';
+import { publicServerErrorMessage } from './publicServerErrorMessage';
+import { registerBrowserJsonFormatting } from './registerBrowserJsonFormatting';
+import type * as server from './contracts';
+
+/**
+ * Installs framework error logging and production-safe HTTP responses.
+ *
+ * Call immediately after constructing Fastify, before registering any routes or
+ * plugins. The inherited send hook also sanitizes explicit 5xx responses and
+ * child-plugin error handlers. Only deliberate mapped client errors and Fastify
+ * request errors retain public messages. Browser JSON formatting is installed
+ * after this boundary so it only sees the safe serialized response. Never send
+ * internal errors as 2xx data.
+ *
+ * @param fastify - HTTP host, still owned and closed by the caller.
+ * @param options - Application error classification and support-record observer.
+ * @example
+ * const server = Fastify({ logger: true });
+ * registerHttpErrorHandler(server);
+ * server.get('/example', async () => loadExample());
+ */
+export function registerHttpErrorHandler(fastify: FastifyInstance, options: server.HttpErrorHandlerOptions = {}): void {
+	const failures = new WeakMap<FastifyReply, { error: unknown; reference?: string }>();
+
+	/** Records the original exception once, keeping support-store failures private. */
+	function recordFailure(request: FastifyRequest, reply: FastifyReply, error: unknown, responseBody?: string): string {
+		const existing = failures.get(reply);
+		if (existing?.reference) return existing.reference;
+		const reference = ulid();
+		failures.set(reply, { error, reference });
+		const context = { request, statusCode: reply.statusCode, reference, responseBody };
+		request.log.error({ err: error, requestMethod: request.method, requestUrl: request.url, statusCode: reply.statusCode, reference, responseBody }, 'Request failed with server error');
+		try {
+			options.onServerError?.(error, context);
+		} catch (observerError) {
+			request.log.error({ err: observerError, reference }, 'Server error observer failed');
+		}
+		return reference;
+	}
+
+	fastify.addHook('onError', (_request, reply, error, done) => {
+		failures.set(reply, { error });
+		done();
+	});
+
+	fastify.setErrorHandler((error, request, reply) => {
+		const mapped = isSqlError(error) ? undefined : options.mapError?.(error);
+		const response = mapped && Number.isInteger(mapped.statusCode) && mapped.statusCode >= 400 && mapped.statusCode <= 599
+			? mapped
+			: defaultErrorResponse(error);
+		reply.type('application/json').code(response.statusCode);
+		if (response.statusCode < 500) return reply.send(response.body);
+		const reference = recordFailure(request, reply, error);
+		return reply.send({ ...response.body, reference });
+	});
+
+	fastify.addHook('onSend', (request, reply, payload, done) => {
+		const failure = failures.get(reply);
+		if (reply.statusCode < 500) {
+			if (!isSqlError(failure?.error)) return done(null, payload);
+			// A child handler cannot make a database failure public by labelling
+			// it a client error or a successful response.
+			reply.code(500);
+		}
+		const responseBody = typeof payload === 'string' ? payload : Buffer.isBuffer(payload) ? payload.toString('utf8') : undefined;
+		const reference = recordFailure(request, reply, failure?.error ?? new Error(`HTTP ${reply.statusCode} response`), responseBody);
+		if (isDevelopmentEnvironment(process.env.NODE_ENV)) return done(null, payload);
+
+		// Replace the serialized body too: route schemas and child handlers must
+		// not reintroduce stack traces, SQL, provider codes or arbitrary metadata.
+		if (payload && typeof payload === 'object' && 'destroy' in payload && typeof payload.destroy === 'function') payload.destroy();
+		reply.removeHeader('content-length');
+		reply.removeHeader('content-encoding');
+		reply.type('application/json').header('cache-control', 'no-store');
+		return done(null, JSON.stringify({ error: 'server_error', message: publicServerErrorMessage(failure?.error), reference }));
+	});
+	registerBrowserJsonFormatting(fastify);
+}
+
+/** Classifies framework client errors without trusting third-party status codes. */
+function defaultErrorResponse(error: unknown): server.HttpErrorResponse {
+	if (!isSqlError(error) && error instanceof RecordNotFoundError) {
+		return { statusCode: 404, body: { error: 'not_found', message: error.message } };
+	}
+	if (!isSqlError(error) && error instanceof Error) {
+		const { code, statusCode } = error as Error & { code?: unknown; statusCode?: unknown };
+		if (typeof code === 'string' && code.startsWith('FST_') && typeof statusCode === 'number' && Number.isInteger(statusCode) && statusCode >= 400 && statusCode < 500) {
+			return { statusCode, body: { error: errorCodeForStatus(statusCode), message: error.message } };
+		}
+	}
+	return { statusCode: 500, body: { error: 'server_error', message: publicServerErrorMessage(error) } };
+}

package/src/ssr/README.md

@@ -147,6 +147,12 @@ In development the adapter uses Vite middleware mode, transforms the HTML shell
 per request, hot-loads `/src/entry-server.ts`, and makes Vite's source, module,
 dependency, filesystem, and HMR URL namespaces available to the browser. Unknown
 page URLs still fall through to the application's ordinary not-found boundary.
+For a site organized into `client/` and feature folders, set
+`developmentEntry: '/client/entry-server.ts'` and
+`developmentAssetRoutes: ['/client/*', '/apps/*']`. These explicit source routes
+extend Vite's built-in development namespaces. They do not change page routing
+or expose those source directories in production. Keep API routes with the host;
+do not include them in `developmentAssetRoutes`.
 In production it reads `dist/client/index.html`, imports
 `dist/server/entry-server.js`, serves the configured asset directory, and maps
 `context.modules` through Vite's SSR manifest. Set `preloadJavaScript: false`

package/src/ssr/vite/contracts/ViteSsrOptions.ts

@@ -31,6 +31,8 @@ export interface FastifyViteSsrOptions<TState extends object = SsrState> {
 	template?: string;
 	/** Vite development server-entry module id. */
 	developmentEntry?: string;
+	/** Additional development-only Vite source routes, for example ['/client/*', '/apps/*']. */
+	developmentAssetRoutes?: readonly string[];
 	/** Production client build directory containing the transformed template. */
 	clientOutDir?: string;
 	/** Production server bundle exporting the application renderer. */

package/src/ssr/vite/fastifyViteSsr.ts

@@ -59,7 +59,7 @@ export function fastifyViteSsr<TState extends object = SsrState>(
 
 			await server.register((await import('@fastify/middie')).default);
 			server.use(runtime.vite.middlewares);
-			registerDevelopmentAssetRoutes(server);
+			registerDevelopmentAssetRoutes(server, options.developmentAssetRoutes);
 			server.addHook('onClose', async () => {
 				await runtime.vite.close();
 			});
@@ -100,9 +100,10 @@ export function fastifyViteSsr<TState extends object = SsrState>(
  * application's ordinary not-found boundary remains authoritative.
  *
  * @param server - Encapsulated Fastify instance hosting the Vite middleware.
+ * @param additionalRoutes - Explicit browser source namespaces owned by this application.
  */
-function registerDevelopmentAssetRoutes(server: Parameters<FastifyPluginAsync>[0]): void {
-	for (const route of DEVELOPMENT_ASSET_ROUTES) {
+function registerDevelopmentAssetRoutes(server: Parameters<FastifyPluginAsync>[0], additionalRoutes: readonly string[] = []): void {
+	for (const route of new Set([...DEVELOPMENT_ASSET_ROUTES, ...additionalRoutes])) {
 		server.get(route, (_request, reply) => reply.callNotFound());
 	}
 }

package/src/storage/drivers/FlystorageDisk.ts

@@ -1,8 +1,8 @@
 import type { FileStorage } from '@flystorage/file-storage';
 import type { Readable } from 'node:stream';
 
-import { storageContentsToBuffer } from '../contents';
-import { mimeTypeFromPath } from '../mime';
+import { storageContentsToBuffer } from '../storageContentsToBuffer';
+import { mimeTypeFromPath } from '../mimeTypeFromPath';
 import { normalizeStorageDirectoryPath, normalizeStoragePath } from '../path';
 import type { StorageListing, StorageListOptions } from '../contracts';
 import type { StorageContents, StorageDisk, StoragePutOptions } from '../types';

package/src/storage/index.ts

@@ -1,7 +1,7 @@
 export * from './Storage';
-export * from './contents';
+export * from './storageContentsToBuffer';
 export * from './contracts';
 export * from './drivers';
-export * from './mime';
+export * from './mimeTypeFromPath';
 export * from './path';
 export * from './types';