@db3.ai/app 0.1.0-beta.1

package/src/ssr/vite/fastifyViteSsr.ts

@@ -0,0 +1,279 @@
+import { readFile } from 'node:fs/promises';
+import type { Server as HttpServer } from 'node:http';
+import { isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { FastifyPluginAsync } from 'fastify';
+import type { ViteDevServer } from 'vite';
+
+import type { SsrRenderer, SsrRequest, SsrState } from '../contracts';
+import { fastifySsr } from '../fastify';
+import type { FastifyViteSsrOptions, ViteSsrServerModule } from './contracts';
+import { applyViteSsrManifest, type ViteSsrManifest } from './viteSsrManifest';
+
+const DEFAULT_TEMPLATE = 'index.html';
+const DEFAULT_DEVELOPMENT_ENTRY = '/src/entry-server.ts';
+const DEFAULT_CLIENT_OUT_DIR = 'dist/client';
+const DEFAULT_SERVER_ENTRY = 'dist/server/entry-server.js';
+const DEFAULT_MANIFEST = 'dist/client/.vite/ssr-manifest.json';
+const DEFAULT_RENDER_EXPORT = 'render';
+const DEVELOPMENT_ASSET_ROUTES = [
+	'/@vite/*',
+	'/@id/*',
+	'/@fs/*',
+	'/src/*',
+	'/node_modules/*',
+] as const;
+
+/**
+ * Creates a Fastify plugin that owns Vite development and production SSR.
+ *
+ * The adapter loads application code through Vite in development, immutable
+ * build artifacts in production, optional static assets, and route-specific
+ * manifest links. Vue, routing and page data remain application concerns.
+ *
+ * @param options - Vite application paths and explicit SSR route ownership.
+ * @returns Fastify plugin ready to register on a web-delivery process.
+ *
+ * @example
+ * await server.register(fastifyViteSsr({
+ * 	root: import.meta.dirname,
+ * 	routes: ['/blog', '/blog/*'],
+ * 	staticAssets: {
+ * 		prefix: '/site-assets/',
+ * 		directory: 'dist/client/site-assets',
+ * 	},
+ * }));
+ */
+export function fastifyViteSsr<TState extends object = SsrState>(
+	options: FastifyViteSsrOptions<TState>,
+): FastifyPluginAsync {
+	return async function platformFastifyViteSsr(server): Promise<void> {
+		if (!options.routes.length) {
+			throw new Error('Vite SSR requires at least one explicit page route.');
+		}
+
+		const mode = options.mode ?? (process.env.NODE_ENV === 'production' ? 'production' : 'development');
+
+		if (mode === 'development') {
+			const runtime = await developmentRuntime(server.server, options);
+
+			await server.register((await import('@fastify/middie')).default);
+			server.use(runtime.vite.middlewares);
+			registerDevelopmentAssetRoutes(server);
+			server.addHook('onClose', async () => {
+				await runtime.vite.close();
+			});
+			await server.register(fastifySsr({
+				routes: options.routes,
+				template: runtime.template,
+				render: runtime.render,
+			}));
+
+			return;
+		}
+
+		if (options.staticAssets) {
+			await server.register((await import('@fastify/static')).default, {
+				root: applicationPath(options.root, options.staticAssets.directory),
+				prefix: normalizedAssetPrefix(options.staticAssets.prefix),
+				index: false,
+			});
+		}
+
+		const runtime = await productionRuntime(options);
+
+		await server.register(fastifySsr({
+			routes: options.routes,
+			template: runtime.template,
+			render: runtime.render,
+		}));
+	};
+}
+
+/**
+ * Registers the Vite URL namespaces needed by browser development requests.
+ *
+ * Fastify resolves a route before running encapsulated middleware. These
+ * fallback routes keep Vite's middleware reachable for source styles, module
+ * transforms, dependency chunks, and its HMR client without claiming unrelated
+ * application page URLs. When Vite does not handle a matching request, the
+ * application's ordinary not-found boundary remains authoritative.
+ *
+ * @param server - Encapsulated Fastify instance hosting the Vite middleware.
+ */
+function registerDevelopmentAssetRoutes(server: Parameters<FastifyPluginAsync>[0]): void {
+	for (const route of DEVELOPMENT_ASSET_ROUTES) {
+		server.get(route, (_request, reply) => reply.callNotFound());
+	}
+}
+
+/** Vite development runtime loaded once for one Fastify server. */
+interface DevelopmentRuntime<TState extends object> {
+	/** Active Vite middleware server. */
+	vite: ViteDevServer;
+	/** Request-aware transformed HTML template loader. */
+	template: (request: SsrRequest) => Promise<string>;
+	/** Hot-reloaded application renderer. */
+	render: SsrRenderer<TState>;
+}
+
+/** Immutable production renderer and HTML shell. */
+interface ProductionRuntime<TState extends object> {
+	/** Transformed client-build document template. */
+	template: string;
+	/** Built application renderer with manifest integration. */
+	render: SsrRenderer<TState>;
+}
+
+/**
+ * Creates Vite middleware and hot server-entry loading for development.
+ *
+ * @param httpServer - Fastify's underlying HTTP server used for Vite HMR.
+ * @param options - Vite SSR application options.
+ * @returns Development runtime consumed by the transport adapter.
+ */
+async function developmentRuntime<TState extends object>(
+	httpServer: HttpServer,
+	options: FastifyViteSsrOptions<TState>,
+): Promise<DevelopmentRuntime<TState>> {
+	const { createServer } = await import('vite');
+	const vite = await createServer({
+		root: options.root,
+		configFile: options.viteConfigFile
+			? applicationPath(options.root, options.viteConfigFile)
+			: undefined,
+		appType: 'custom',
+		server: {
+			middlewareMode: true,
+			hmr: { server: httpServer },
+		},
+	});
+	const templatePath = applicationPath(options.root, options.template ?? DEFAULT_TEMPLATE);
+	const developmentEntry = options.developmentEntry ?? DEFAULT_DEVELOPMENT_ENTRY;
+	const renderExport = options.renderExport ?? DEFAULT_RENDER_EXPORT;
+
+	return {
+		vite,
+		template: async request => {
+			const template = await readFile(templatePath, 'utf8');
+
+			return vite.transformIndexHtml(request.url, template);
+		},
+		render: async context => {
+			try {
+				const module = await vite.ssrLoadModule(developmentEntry) as ViteSsrServerModule<TState>;
+				const render = moduleRenderer<TState>(module, renderExport);
+
+				return await render(context);
+			} catch (error) {
+				vite.ssrFixStacktrace(error as Error);
+				throw error;
+			}
+		},
+	};
+}
+
+/**
+ * Loads immutable production templates, server code and optional manifest data.
+ *
+ * @param options - Vite SSR application options.
+ * @returns Production runtime consumed by the transport adapter.
+ */
+async function productionRuntime<TState extends object>(
+	options: FastifyViteSsrOptions<TState>,
+): Promise<ProductionRuntime<TState>> {
+	const clientOutDir = options.clientOutDir ?? DEFAULT_CLIENT_OUT_DIR;
+	const templatePath = applicationPath(
+		options.root,
+		join(clientOutDir, options.template ?? DEFAULT_TEMPLATE),
+	);
+	const serverEntry = applicationPath(options.root, options.serverEntry ?? DEFAULT_SERVER_ENTRY);
+	const renderExport = options.renderExport ?? DEFAULT_RENDER_EXPORT;
+	const [template, module, manifest] = await Promise.all([
+		readFile(templatePath, 'utf8'),
+		import(pathToFileURL(serverEntry).href) as Promise<ViteSsrServerModule<TState>>,
+		loadManifest(options),
+	]);
+	const render = moduleRenderer<TState>(module, renderExport);
+
+	return {
+		template,
+		render: async context => {
+			const result = await render(context);
+
+			applyViteSsrManifest(context, manifest, {
+				preloadJavaScript: options.preloadJavaScript,
+			});
+
+			return result;
+		},
+	};
+}
+
+/**
+ * Loads the optional production SSR manifest.
+ *
+ * @param options - Vite SSR application options.
+ * @returns Parsed manifest or an empty map when explicitly disabled.
+ */
+async function loadManifest<TState extends object>(
+	options: FastifyViteSsrOptions<TState>,
+): Promise<ViteSsrManifest> {
+	if (options.manifest === false) return {};
+
+	const path = applicationPath(options.root, options.manifest ?? DEFAULT_MANIFEST);
+	const value = JSON.parse(await readFile(path, 'utf8')) as unknown;
+
+	if (!value || typeof value !== 'object' || Array.isArray(value)) {
+		throw new Error(`Vite SSR manifest must contain an object: ${path}`);
+	}
+
+	return value as ViteSsrManifest;
+}
+
+/**
+ * Resolves the configured server-entry renderer and validates its contract.
+ *
+ * @param module - Loaded development or production module namespace.
+ * @param name - Named renderer export.
+ * @returns Framework-compatible application renderer.
+ */
+function moduleRenderer<TState extends object>(
+	module: ViteSsrServerModule<TState>,
+	name: string,
+): SsrRenderer<TState> {
+	const render = module[name];
+
+	if (typeof render !== 'function') {
+		throw new Error(`Vite SSR server entry must export a "${name}" renderer.`);
+	}
+
+	return render as SsrRenderer<TState>;
+}
+
+/**
+ * Resolves an application-owned path without changing absolute paths.
+ *
+ * @param root - Absolute application root.
+ * @param path - Absolute or application-relative path.
+ * @returns Absolute filesystem path.
+ */
+function applicationPath(root: string, path: string): string {
+	return isAbsolute(path) ? path : resolve(root, path);
+}
+
+/**
+ * Normalizes a Fastify static prefix to an absolute trailing-slash path.
+ *
+ * @param prefix - Application-provided public asset prefix.
+ * @returns Normalized Fastify route prefix.
+ */
+function normalizedAssetPrefix(prefix: string): string {
+	const value = `/${prefix.trim().replace(/^\/+|\/+$/g, '')}/`;
+
+	if (value === '//') {
+		throw new Error('Vite SSR static asset prefix cannot be empty.');
+	}
+
+	return value;
+}

package/src/ssr/vite/index.ts

@@ -0,0 +1,4 @@
+export type * from './contracts';
+export { fastifyViteSsr } from './fastifyViteSsr';
+export { applyViteSsrManifest } from './viteSsrManifest';
+export type { ApplyViteSsrManifestOptions, ViteSsrManifest } from './viteSsrManifest';

package/src/ssr/vite/viteSsrManifest.ts

@@ -0,0 +1,92 @@
+import type { SsrRenderContext } from '../contracts';
+
+/** Vite SSR manifest mapping rendered module ids to their client build files. */
+export type ViteSsrManifest = Record<string, string[]>;
+
+/** Controls which client files should be preloaded for a rendered request. */
+export interface ApplyViteSsrManifestOptions {
+	/** Whether JavaScript module chunks should be preloaded for hydration. */
+	preloadJavaScript?: boolean;
+}
+
+/**
+ * Adds request-used Vite assets to the single document-head pipeline.
+ *
+ * @param context - Request-owned SSR context populated by the Vue renderer.
+ * @param manifest - Production Vite SSR manifest.
+ * @param options - Client preload policy for the current application.
+ */
+export function applyViteSsrManifest<TState extends object>(
+	context: SsrRenderContext<TState>,
+	manifest: ViteSsrManifest,
+	options: ApplyViteSsrManifestOptions = {},
+): void {
+	const seen = new Set(context.head.link
+		.map(link => typeof link.href === 'string' ? link.href : '')
+		.filter(Boolean));
+
+	for (const moduleId of context.modules) {
+		for (const file of manifest[moduleId] ?? []) {
+			const href = assetHref(file);
+
+			if (!href || seen.has(href)) continue;
+
+			const attributes = preloadAttributes(href, options);
+
+			if (!attributes) continue;
+
+			context.head.link.push(attributes);
+			seen.add(href);
+		}
+	}
+}
+
+/**
+ * Normalizes one manifest file to a root-relative public URL.
+ *
+ * @param file - File path emitted by Vite.
+ * @returns Root-relative public URL or an empty string.
+ */
+function assetHref(file: string): string {
+	const value = file.trim();
+
+	if (!value) return '';
+
+	return value.startsWith('/') ? value : `/${value}`;
+}
+
+/**
+ * Maps a built asset to the corresponding preload or stylesheet element.
+ *
+ * @param href - Root-relative public asset URL.
+ * @param options - JavaScript preload policy.
+ * @returns Document-head attributes or null for unsupported assets.
+ */
+function preloadAttributes(
+	href: string,
+	options: ApplyViteSsrManifestOptions,
+): Record<string, string | boolean> | null {
+	if (href.endsWith('.css')) {
+		return { rel: 'stylesheet', href };
+	}
+
+	if (href.endsWith('.js')) {
+		return options.preloadJavaScript === false
+			? null
+			: { rel: 'modulepreload', crossorigin: true, href };
+	}
+
+	if (href.endsWith('.woff2')) {
+		return { rel: 'preload', href, as: 'font', type: 'font/woff2', crossorigin: true };
+	}
+
+	if (href.endsWith('.woff')) {
+		return { rel: 'preload', href, as: 'font', type: 'font/woff', crossorigin: true };
+	}
+
+	if (/\.(avif|gif|jpe?g|png|webp)$/.test(href)) {
+		return { rel: 'preload', href, as: 'image' };
+	}
+
+	return null;
+}

package/src/storage/README.md

@@ -0,0 +1,310 @@
+# @db3.ai/app/storage
+
+## Stream failure and recovery lab
+
+Copy `src/storage/examples/` from the installed package into `examples/` and run
+`npx tsx examples/runStreamExport.ts`. The lab streams 50,000 rows, interrupts a
+staged write, preserves the last successful export and removes partial bytes.
+It needs only temporary local storage and removes that directory afterwards.
+`tests/examples/runStreamExport.test.ts` is the consumer-copyable behavioral
+check. Remote moves and HTTP disconnects need separate adapter/driver tests.
+
+`@db3.ai/app/storage` provides a Laravel-style storage service with named
+disks. App code can write to the default disk through `app.storage` or select a
+configured disk with `app.storage.disk(name)`.
+
+The storage service is the lower-level file API. Managed file records, ULID
+references, and database-backed file metadata should sit above this layer.
+
+## Configure disks
+
+```ts
+import { App } from '@db3.ai/app';
+
+const app = new App({
+	storage: {
+		default: 'local',
+		disks: {
+			local: {
+				driver: 'local',
+				root: 'storage/app',
+			},
+			agent: {
+				driver: 'local',
+				root: 'storage/agent',
+				url: 'https://example.test/storage/agent',
+			},
+			spaces: {
+				driver: 's3',
+				bucket: 'example-assets',
+				region: 'nyc3',
+				endpoint: 'https://nyc3.digitaloceanspaces.com',
+				url: 'https://example-assets.nyc3.digitaloceanspaces.com',
+				accessKeyId: process.env.SPACES_ACCESS_KEY_ID,
+				secretAccessKey: process.env.SPACES_SECRET_ACCESS_KEY,
+			},
+		},
+	},
+});
+```
+
+If no storage config is supplied, `local` is available and writes under
+`storage/app` relative to the process working directory. The local driver is
+backed by Flystorage's `FileStorage` and `LocalStorageAdapter`.
+
+## Day-To-Day Usage
+
+Most app code should use the default disk unless it has a good reason to choose
+a specific backend. `write(...)` and `put(...)` do the same thing. `put(...)`
+matches Laravel naming, while `write(...)` is convenient in the REPL.
+
+### Write A Text File
+
+```ts
+await app().storage.write('my/test-file.txt', 'hello i am a test file');
+```
+
+Or, using the Laravel-style name:
+
+```ts
+await app().storage.put('my/test-file.txt', 'hello i am a test file');
+```
+
+### Read A Text File
+
+```ts
+const text = await app().storage.readToString('my/test-file.txt');
+```
+
+`getText(...)` is also available when you want to pass a Node text encoding.
+
+### Read A Stream
+
+`read(...)` follows Flystorage's API and returns a readable stream:
+
+```ts
+const stream = await app().storage.read('my/test-file.txt');
+```
+
+Use `get(...)` when you intentionally want the whole file buffered:
+
+```ts
+const buffer = await app().storage.readToBuffer('my/test-file.txt');
+const bytes = await app().storage.readToUint8Array('my/test-file.txt');
+```
+
+`get(...)` is also available as a shorter alias for `readToBuffer(...)`.
+
+### Write JSON
+
+```ts
+await app().storage.write('reports/latest.json', JSON.stringify({
+	status: 'ready',
+}, null, '\t'), {
+	mimeType: 'application/json',
+});
+```
+
+### Write Bytes
+
+```ts
+await app().storage.write('images/avatar.png', imageBytes, {
+	mimeType: 'image/png',
+	visibility: 'private',
+});
+```
+
+### Check, Delete, And Inspect Files
+
+```ts
+await app().storage.exists('my/test-file.txt');
+await app().storage.missing('my/missing-file.txt');
+await app().storage.size('my/test-file.txt');
+await app().storage.lastModified('my/test-file.txt');
+await app().storage.mimeType('images/avatar.png');
+await app().storage.delete('my/test-file.txt');
+```
+
+### List Directory Contents
+
+`list(...)` returns a lazy, provider-neutral async listing for local and remote
+disks. Set `deep` when descendants below the immediate directory are needed:
+
+```ts
+const listing = app().storage.disk('local').list('reports', {
+	deep: true,
+});
+
+for await (const entry of listing) {
+	console.log(entry.type, entry.path, entry.lastModified);
+}
+```
+
+Collect a listing when the complete result is intentionally needed in memory:
+
+```ts
+const entries = await app().storage.disk('local').list('reports', {
+	deep: true,
+}).toArray();
+```
+
+Pass an empty path or omit it to list from the disk root. Listings expose the
+same framework entry shape for every driver; callers do not need to know whether
+the selected disk is local or S3-compatible.
+
+For local disks, `path(...)` returns the absolute filesystem path:
+
+```ts
+app().storage.path('my/test-file.txt');
+```
+
+Remote disks such as S3 do not expose local paths, so use `url(...)` when a
+public URL is configured:
+
+```ts
+await app().storage.url('images/avatar.png');
+```
+
+### Use A Named Disk
+
+```ts
+await app().storage.disk('agent').write('generated-images/example.txt', 'hello agent disk');
+
+const text = await app().storage.disk('agent').getText('generated-images/example.txt');
+```
+
+`drive(name)` is also available as an alias for `disk(name)`:
+
+```ts
+await app().storage.drive('agent').write('notes/example.txt', 'stored on the agent disk');
+```
+
+## Try It In Tinker
+
+From the repo root, start the CLI REPL:
+
+```sh
+npm run tinker
+```
+
+An application tinker context can expose both `app` and `app()` styles. Top-level
+`await` is supported, so each command waits for the storage operation to finish
+before the prompt returns:
+
+```ts
+await app().storage.write('my/test-file.txt', 'hello i am a test file')
+await app().storage.read('my/test-file.txt')
+await app().storage.readToString('my/test-file.txt')
+await app().storage.readToBuffer('my/test-file.txt')
+await app().storage.readToUint8Array('my/test-file.txt')
+await app().storage.exists('my/test-file.txt')
+await app().storage.delete('my/test-file.txt')
+```
+
+If you prefer property access, this works too:
+
+```ts
+await app.storage.write('my/test-file.txt', 'hello from app.storage')
+```
+
+## Use The Default Disk
+
+```ts
+await app.storage.put('reports/latest.json', JSON.stringify({
+	status: 'ready',
+}));
+
+const text = await app.storage.getText('reports/latest.json');
+```
+
+## Use A Named Disk
+
+```ts
+const agent = app.storage.disk('agent');
+
+await agent.write('generated-images/example.png', imageBytes, {
+	mimeType: 'image/png',
+	visibility: 'private',
+});
+
+const bytes = await agent.get('generated-images/example.png');
+```
+
+## Stream Large Files
+
+Use explicit stream methods when files should not be buffered into memory:
+
+```ts
+await app.storage.disk('agent').writeStream('uploads/source-video.mp4', requestStream, {
+	mimeType: 'video/mp4',
+});
+
+const stream = await app.storage.disk('agent').readStream('uploads/source-video.mp4');
+```
+
+`read(...)` is also available and matches Flystorage's stream-returning method:
+
+```ts
+const stream = await app.storage.disk('agent').read('uploads/source-video.mp4');
+```
+
+These methods are backed by Flystorage streams, so they are the preferred API
+for large uploads, exports, and future remote disks such as S3. The framework
+wrapper passes stream objects through to the driver and does not buffer them
+before writing or reading.
+
+## S3-Compatible Disks
+
+Use `driver: 's3'` for AWS S3 and services that support the S3 protocol:
+
+```ts
+const storage = new Storage({
+	default: 'spaces',
+	disks: {
+		spaces: {
+			driver: 's3',
+			bucket: 'example-assets',
+			region: 'nyc3',
+			endpoint: 'https://nyc3.digitaloceanspaces.com',
+			url: 'https://example-assets.nyc3.digitaloceanspaces.com',
+			accessKeyId: env.required('SPACES_ACCESS_KEY_ID'),
+			secretAccessKey: env.required('SPACES_SECRET_ACCESS_KEY'),
+		},
+	},
+});
+```
+
+`endpoint` is optional for AWS S3 and useful for providers such as DigitalOcean
+Spaces, MinIO, and other S3-compatible services. Use `forcePathStyle: true`
+when the provider expects path-style bucket URLs.
+
+## Path safety
+
+Storage paths are always relative to the disk root. Absolute paths, null bytes,
+and parent-directory traversal are rejected before the driver touches the
+filesystem. File operations reject empty paths; `list('')` deliberately allows
+an empty path to list the disk root.
+
+## Runnable example and testing
+
+The [storage lab](./examples/runStorage.ts) writes and reads JSON and a streamed
+CSV, lists the resulting paths, checks traversal rejection and deletes a file.
+It uses a real temporary local disk, removes that directory afterwards and does
+not need SQL or cloud credentials. Copy the shipped example into `examples`
+and run `npx tsx examples/runStorage.ts` in the consuming app.
+
+The Storage website page includes the exact Vitest test for that copied file.
+Framework contributors run `npm run test:service --workspace packages/app -- storage`.
+Local behaviour is not evidence that an S3 account, bucket policy or interrupted
+upload works correctly. Verify those against dedicated provider test resources.
+
+## Local disk URLs
+
+The local driver can build URLs only when `url` is configured:
+
+```ts
+const url = await app.storage.disk('agent').url('generated-images/example.png');
+```
+
+This method only returns the URL. Routes remain responsible for authentication,
+ownership checks, headers, and response shaping.