create-flowdular 0.2.6 → 0.3.1

package/template/default/platform/src/server/metrics.ts

@@ -0,0 +1,100 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+	defineEndpoint,
+	jsonResponse,
+	serverMetrics,
+	type MetricsRegistry,
+} from '@flowdular/sdk/server';
+import type { ServerRoute } from '@octanejs/app-core';
+
+const CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8';
+const BEARER = /^Bearer (.+)$/i;
+
+export interface MetricsRoutesOptions {
+	readonly environment?: NodeJS.ProcessEnv;
+	readonly metrics?: MetricsRegistry;
+	readonly version?: string;
+}
+
+function exposed(value: string | undefined): boolean {
+	if (value === undefined || value.trim() === '') return false;
+	if (value === 'true') return true;
+	if (value === 'false') return false;
+	throw new Error('FD_METRICS must be true or false.');
+}
+
+/* Both this source file and the bundled server entry sit two directories below
+   platform/package.json, which the container image ships next to dist/. */
+export function platformVersion(): string {
+	try {
+		const manifest: unknown = JSON.parse(
+			readFileSync(
+				join(import.meta.dirname, '..', '..', 'package.json'),
+				'utf8',
+			),
+		);
+		const version = (manifest as { version?: unknown }).version;
+		return typeof version === 'string' && version ? version : 'unknown';
+	} catch {
+		return 'unknown';
+	}
+}
+
+/* Comparing digests keeps the operands the same length, so neither the timing
+   nor a length check tells a caller how long the configured token is. */
+function tokenMatches(header: string | null, token: string): boolean {
+	const presented = BEARER.exec(header ?? '')?.[1];
+	if (presented === undefined) return false;
+	return timingSafeEqual(
+		createHash('sha256').update(presented).digest(),
+		createHash('sha256').update(token).digest(),
+	);
+}
+
+/**
+ * Prometheus exposition for this process. Composed only when `FD_METRICS=true`,
+ * and readable only with `FD_METRICS_TOKEN` when that is set. The series carry
+ * endpoint ids, never a request path, a session or tenant data.
+ */
+export function createMetricsRoutes(
+	options: MetricsRoutesOptions = {},
+): readonly ServerRoute[] {
+	const environment = options.environment ?? process.env;
+	if (!exposed(environment.FD_METRICS)) return [];
+	const token = environment.FD_METRICS_TOKEN?.trim() || null;
+	const metrics = options.metrics ?? serverMetrics();
+	metrics.setBuildVersion(options.version ?? platformVersion());
+	const endpoint = defineEndpoint({
+		id: 'system.metrics',
+		path: '/api/metrics',
+		methods: ['GET'],
+		access: { kind: 'public' },
+		handler: ({ octane }) => {
+			if (
+				token &&
+				!tokenMatches(octane.request.headers.get('authorization'), token)
+			) {
+				const denied = jsonResponse(
+					{
+						error: {
+							code: 'UNAUTHENTICATED',
+							message: 'Authentication is required.',
+						},
+					},
+					401,
+				);
+				denied.headers.set('www-authenticate', 'Bearer');
+				return denied;
+			}
+			return new Response(metrics.expose(), {
+				headers: {
+					'content-type': CONTENT_TYPE,
+					'cache-control': 'no-store',
+				},
+			});
+		},
+	});
+	return [endpoint.serverRoute];
+}

package/template/default/platform/src/server/storage.ts

@@ -0,0 +1,172 @@
+import { defineEndpoint } from '@flowdular/sdk/server';
+import {
+	createStoragePort,
+	createStorageKeyring,
+	openStorageReadToken,
+	StorageError,
+	storageConfigFromEnvironment,
+	STORAGE_READ_ROUTE_PREFIX,
+	type StorageConfig,
+	type StoragePort,
+	type StoragePortOptions,
+} from '@flowdular/sdk/storage';
+import type { Keyring } from '@flowdular/sdk/kernel';
+import type { ServerRoute } from '@octanejs/app-core';
+
+export {
+	createStoragePort,
+	createStorageKeyring,
+	storageConfigFromEnvironment,
+	STORAGE_READ_ROUTE_PREFIX,
+};
+export type {
+	StorageConfig as PlatformStorageConfig,
+	StoragePort as PlatformStoragePort,
+	StoragePortOptions as PlatformStoragePortOptions,
+};
+
+const RATE_LIMIT = 600;
+const RATE_WINDOW_MS = 60_000;
+const RATE_CAPACITY = 4_096;
+
+/**
+ * Fixed window per caller, bounded. Expired windows are dropped once the map
+ * reaches capacity, so a flood of distinct tokens cannot grow it without limit.
+ */
+class ReadRateLimiter {
+	readonly #windows = new Map<string, { count: number; startedAt: number }>();
+
+	allow(key: string, now: number): boolean {
+		const current = this.#windows.get(key);
+		if (current && now - current.startedAt < RATE_WINDOW_MS) {
+			current.count += 1;
+			return current.count <= RATE_LIMIT;
+		}
+		if (this.#windows.size >= RATE_CAPACITY) this.#evict(now);
+		this.#windows.set(key, { count: 1, startedAt: now });
+		return true;
+	}
+
+	#evict(now: number): void {
+		for (const [key, window] of this.#windows) {
+			if (now - window.startedAt >= RATE_WINDOW_MS) this.#windows.delete(key);
+		}
+		while (this.#windows.size >= RATE_CAPACITY) {
+			const oldest = this.#windows.keys().next();
+			if (oldest.done) return;
+			this.#windows.delete(oldest.value);
+		}
+	}
+}
+
+const ADDRESS_PATTERN = /^[0-9a-fA-F.:]{3,45}$/;
+
+/* Octane hands routes a Web Request without the socket address, so the client
+   is only known behind a proxy this deployment trusts. Without one the window
+   is keyed by the token, which still bounds replay of a single read URL. The
+   capability itself is what resists guessing: a token carries a 16 byte
+   authentication tag. */
+function limiterKey(
+	request: Request,
+	trustProxy: boolean,
+	token: string,
+): string {
+	if (trustProxy) {
+		const first = request.headers.get('x-forwarded-for')?.split(',')[0]?.trim();
+		if (first && ADDRESS_PATTERN.test(first))
+			return `ip:${first.toLowerCase()}`;
+	}
+	return `token:${token.slice(0, 32)}`;
+}
+
+function notFound(requestId: string): Response {
+	return Response.json(
+		{
+			error: {
+				code: 'NOT_FOUND',
+				message: 'The requested object is not available.',
+			},
+			requestId,
+		},
+		{ status: 404, headers: { 'cache-control': 'private, no-store' } },
+	);
+}
+
+export interface StorageRoutesOptions {
+	readonly storage: StoragePort;
+	readonly keyring: Keyring;
+	readonly environment?: NodeJS.ProcessEnv | undefined;
+	readonly clock?: (() => Date) | undefined;
+}
+
+/**
+ * `GET /api/storage/objects/:token` streams the decrypted body of one object.
+ * The token is the capability: it is sealed under the storage keyring, names
+ * the tenant, module, object and expiry, and needs no session, which is why
+ * this route has no 401 and answers 404 to everything it cannot serve. A
+ * different answer for an expired token, a forged one and a deleted object
+ * would tell a caller which of the three it holds.
+ */
+export function createStorageRoutes(
+	options: StorageRoutesOptions,
+): readonly ServerRoute[] {
+	const environment = options.environment ?? process.env;
+	const trustProxy = environment.FD_TRUST_PROXY === 'true';
+	const clock = options.clock ?? (() => new Date());
+	const limiter = new ReadRateLimiter();
+	const endpoint = defineEndpoint({
+		id: 'system.storage.read',
+		path: `${STORAGE_READ_ROUTE_PREFIX}:token`,
+		methods: ['GET'],
+		access: { kind: 'public' },
+		handler: async ({ octane, requestId }) => {
+			const token = octane.params.token ?? '';
+			const now = clock();
+			if (
+				!limiter.allow(
+					limiterKey(octane.request, trustProxy, token),
+					now.getTime(),
+				)
+			) {
+				return Response.json(
+					{
+						error: { code: 'RATE_LIMITED', message: 'Too many object reads.' },
+						requestId,
+					},
+					{
+						status: 429,
+						headers: {
+							'cache-control': 'private, no-store',
+							'retry-after': '60',
+						},
+					},
+				);
+			}
+			const reference = openStorageReadToken(options.keyring, token, now);
+			if (!reference) return notFound(requestId);
+			let result;
+			try {
+				result = await options.storage.get(reference);
+			} catch (error) {
+				/* A frame this keyring cannot open is indistinguishable from an absent
+				   object to the reader, and saying so would leak that it exists. An
+				   adapter outage is a real 500 and stays one. */
+				if (error instanceof StorageError && error.code === 'OBJECT_CORRUPT') {
+					return notFound(requestId);
+				}
+				throw error;
+			}
+			if (!result) return notFound(requestId);
+			return new Response(result.body, {
+				headers: {
+					'content-type': result.object.contentType,
+					'content-length': String(result.object.bytes),
+					'content-disposition': 'attachment',
+					'cache-control': 'private, no-store',
+					'x-content-type-options': 'nosniff',
+				},
+			});
+		},
+	});
+	return [endpoint.serverRoute];
+}

package/template/default/platform/src/server/tracing.ts

@@ -0,0 +1,85 @@
+import {
+	createOtlpSpanExporter,
+	errorSinkConfigFromEnvironment,
+	serverErrorSink,
+	traceConfigFromEnvironment,
+	type ErrorSink,
+	type SpanExporter,
+} from '@flowdular/sdk/server';
+import { platformVersion } from './metrics.ts';
+
+export interface PlatformObservabilityOptions {
+	readonly environment?: NodeJS.ProcessEnv;
+	readonly version?: string;
+}
+
+/* Batches one disposal drains from the error sink: the queue bound divided by
+   the batch, and one over, because a report may be queued while it drains. */
+const SINK_FLUSHES = 4;
+
+/**
+ * Sends what the error sink still holds. One flush sends one batch and the
+ * queue holds more than one, so a single flush on the way out would strand the
+ * rest. The loop ends on an empty queue, on a flush that moved nothing, or on
+ * the bound, so an unreachable webhook can never hold a shutdown open.
+ */
+export async function drainErrorSink(sink: ErrorSink): Promise<void> {
+	for (let batch = 0; batch < SINK_FLUSHES; batch += 1) {
+		const queued = sink.stats().queued;
+		if (queued === 0) return;
+		await sink.flush();
+		if (sink.stats().queued >= queued) return;
+	}
+}
+
+export interface PlatformObservability {
+	/** Null when `FD_TRACE_EXPORTER` is none, which is the default. */
+	readonly exporter: SpanExporter | null;
+	/** The sink logged errors are reported through; `none` holds nothing. */
+	readonly errorSink: ErrorSink;
+	/** Drains both egresses. Safe to call more than once. */
+	dispose(): Promise<void>;
+}
+
+/**
+ * Composes the two optional observability egresses for this deployment.
+ *
+ * Both configurations are read here, at boot, so a deployment that misspelled
+ * a variable fails to start rather than quietly sending nothing. Spans are
+ * always recorded into the bounded in-process buffer; only the export is
+ * optional, and neither egress ever runs on a request path.
+ *
+ * The error sink is the process singleton the logger already reports through,
+ * so this only validates it and drains it on shutdown: a process that stops
+ * must not orphan the reports it queued.
+ */
+export function createPlatformObservability(
+	options: PlatformObservabilityOptions = {},
+): PlatformObservability {
+	const environment = options.environment ?? process.env;
+	const trace = traceConfigFromEnvironment(environment);
+	/* Validated here and discarded: `serverErrorSink()` builds the live one from
+	   the same variables, and a second sink would double every report. */
+	errorSinkConfigFromEnvironment(environment);
+	const errorSink = serverErrorSink();
+	const exporter =
+		trace.exporter === 'otlp' && trace.url
+			? createOtlpSpanExporter({
+					url: trace.url,
+					headers: trace.headers,
+					environment,
+					serviceName: 'flowdular',
+					serviceVersion: options.version ?? platformVersion(),
+				})
+			: null;
+	return {
+		exporter,
+		errorSink,
+		async dispose(): Promise<void> {
+			/* Disposal drains the span buffer, so what this process recorded while
+			   it stopped is still evidence about the stop. */
+			await exporter?.dispose();
+			await drainErrorSink(errorSink);
+		},
+	};
+}

package/template/default/specs/application.yaml

@@ -0,0 +1,15 @@
+# The platform spec of this application. "flowdular spec validate --all"
+# validates it together with every modules/*/spec/module.yaml.
+schemaVersion: 1
+id: application.app-name
+version: 0.1.0
+status: approved
+principles:
+  - spec-before-implementation
+  - default-deny
+  - tenant-scoped-data
+repositoryRoots:
+  platform: platform
+  modules: modules
+  infrastructure: infra
+  agentConfiguration: .ai