@flowdular/sdk 0.2.3 → 0.3.0

package/packages/server/src/log.ts

@@ -0,0 +1,291 @@
+import { currentTrace } from './trace/context.ts';
+import {
+	serverErrorSink,
+	type ErrorSink,
+	NO_ERRORS,
+} from './trace/error-sink.ts';
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export type LogFormat = 'json' | 'text';
+
+export interface LogFields {
+	readonly [key: string]: unknown;
+}
+
+export interface LogEvent {
+	/** Correlates a line with the response that carries the same id. */
+	readonly requestId?: string;
+	readonly endpoint?: string;
+	readonly module?: string;
+	readonly err?: unknown;
+	/** Free-form context. Credential-shaped keys are redacted before writing. */
+	readonly fields?: LogFields;
+}
+
+export interface Logger {
+	readonly level: LogLevel;
+	readonly format: LogFormat;
+	debug(message: string, event?: LogEvent): void;
+	info(message: string, event?: LogEvent): void;
+	warn(message: string, event?: LogEvent): void;
+	error(message: string, event?: LogEvent): void;
+}
+
+export interface LoggerOptions {
+	/** Defaults to `FD_LOG_FORMAT`, else json in production and text elsewhere. */
+	readonly format?: LogFormat;
+	/** Defaults to `FD_LOG_LEVEL`, else info. */
+	readonly level?: LogLevel;
+	readonly environment?: NodeJS.ProcessEnv;
+	/** Defaults to the console: warn and error on stderr, the rest on stdout. */
+	readonly write?: (level: LogLevel, line: string) => void;
+	readonly now?: () => Date;
+	/**
+	 * Where error lines are reported beyond the log stream. Defaults to none;
+	 * `serverLogger()` takes the one the deployment configured.
+	 */
+	readonly errorSink?: ErrorSink;
+}
+
+const LEVELS: Readonly<Record<LogLevel, number>> = Object.freeze({
+	debug: 10,
+	info: 20,
+	warn: 30,
+	error: 40,
+});
+
+/* Over-approximates on purpose: a field that merely looks like a credential is
+   worth losing, a credential that reaches a log file is not. */
+const SENSITIVE_KEY =
+	/authorization|cookie|password|token|secret|credential|api[-_]?key|session/i;
+const REDACTED = '[redacted]';
+const TRUNCATED = '[truncated]';
+/* A log line is a diagnostic, not a transport. Depth, breadth and string length
+   are bounded so one hostile or cyclic field cannot grow the process. */
+const MAX_DEPTH = 4;
+const MAX_ENTRIES = 32;
+const MAX_STRING = 2_048;
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/g;
+
+interface LoggedError {
+	readonly name: string;
+	readonly message?: string;
+	readonly stack?: string;
+}
+
+function bounded(value: string): string {
+	return value.length <= MAX_STRING
+		? value
+		: `${value.slice(0, MAX_STRING)}${TRUNCATED}`;
+}
+
+/* A request id arrives from a header and a field from whatever produced it, so
+   a control character in either would forge a second line in text format. A
+   stack is exempt: its own newlines are what makes it readable. */
+function boundedString(value: string): string {
+	return bounded(value).replace(CONTROL_CHARACTER, ' ');
+}
+
+function sanitize(value: unknown, depth: number): unknown {
+	if (value === null) return null;
+	switch (typeof value) {
+		case 'string':
+			return boundedString(value);
+		case 'number':
+			return Number.isFinite(value) ? value : String(value);
+		case 'boolean':
+			return value;
+		case 'bigint':
+			return value.toString();
+		case 'undefined':
+			return undefined;
+		case 'function':
+		case 'symbol':
+			return '[unserializable]';
+		default:
+			break;
+	}
+	if (depth >= MAX_DEPTH) return TRUNCATED;
+	if (value instanceof Error) {
+		return { name: value.name, message: boundedString(value.message) };
+	}
+	if (Array.isArray(value)) {
+		const items = value
+			.slice(0, MAX_ENTRIES)
+			.map((entry) => sanitize(entry, depth + 1));
+		return value.length > MAX_ENTRIES ? [...items, TRUNCATED] : items;
+	}
+	const result: Record<string, unknown> = {};
+	let remaining = MAX_ENTRIES;
+	for (const [key, entry] of Object.entries(value as object)) {
+		if (remaining === 0) {
+			result['...'] = TRUNCATED;
+			break;
+		}
+		remaining -= 1;
+		result[key] = SENSITIVE_KEY.test(key)
+			? REDACTED
+			: sanitize(entry, depth + 1);
+	}
+	return result;
+}
+
+/**
+ * Keeps only the shape a log reader needs. A caller that must not publish an
+ * error message passes `{ name }` instead of the error itself.
+ */
+function loggedError(value: unknown, withStack: boolean): LoggedError {
+	if (value instanceof Error) {
+		return {
+			name: value.name,
+			message: boundedString(value.message),
+			...(withStack && value.stack ? { stack: bounded(value.stack) } : {}),
+		};
+	}
+	if (typeof value === 'object' && value !== null) {
+		const record = value as { name?: unknown; message?: unknown };
+		return {
+			name: typeof record.name === 'string' ? record.name : 'non-error',
+			...(typeof record.message === 'string'
+				? { message: boundedString(record.message) }
+				: {}),
+		};
+	}
+	return { name: 'non-error' };
+}
+
+function textLine(record: Record<string, unknown>): string {
+	const { time, level, msg, err, ...rest } = record as {
+		time: string;
+		level: string;
+		msg: string;
+		err?: LoggedError;
+	} & Record<string, unknown>;
+	const parts = [`${time} ${level.toUpperCase()} ${msg}`];
+	for (const [key, value] of Object.entries(rest)) {
+		parts.push(
+			`${key}=${typeof value === 'string' ? value : JSON.stringify(value)}`,
+		);
+	}
+	if (err) {
+		parts.push(`err=${err.message ? `${err.name}: ${err.message}` : err.name}`);
+	}
+	return err?.stack ? `${parts.join(' ')}\n${err.stack}` : parts.join(' ');
+}
+
+function parseFormat(value: string | undefined): LogFormat | undefined {
+	const normalized = value?.trim().toLowerCase();
+	return normalized === 'json' || normalized === 'text'
+		? normalized
+		: undefined;
+}
+
+function parseLevel(value: string | undefined): LogLevel | undefined {
+	const normalized = value?.trim().toLowerCase();
+	return normalized && normalized in LEVELS
+		? (normalized as LogLevel)
+		: undefined;
+}
+
+export function createLogger(options: LoggerOptions = {}): Logger {
+	const environment = options.environment ?? process.env;
+	const production = environment.NODE_ENV === 'production';
+	const configuredFormat = parseFormat(environment.FD_LOG_FORMAT);
+	const configuredLevel = parseLevel(environment.FD_LOG_LEVEL);
+	const format =
+		options.format ?? configuredFormat ?? (production ? 'json' : 'text');
+	const level = options.level ?? configuredLevel ?? 'info';
+	const threshold = LEVELS[level];
+	const now = options.now ?? (() => new Date());
+	const write =
+		options.write ??
+		((entryLevel: LogLevel, line: string) => {
+			if (entryLevel === 'warn' || entryLevel === 'error') console.error(line);
+			else console.log(line);
+		});
+	/* A stack can carry file paths and inlined values, so production publishes
+	   one only when the operator asked for debug output. */
+	const withStack = !production || level === 'debug';
+
+	const errorSink = options.errorSink ?? NO_ERRORS;
+
+	const emit = (
+		entryLevel: LogLevel,
+		message: string,
+		event: LogEvent | undefined,
+	) => {
+		if (LEVELS[entryLevel] < threshold) return;
+		const record: Record<string, unknown> = {
+			time: now().toISOString(),
+			level: entryLevel,
+			msg: boundedString(message),
+		};
+		/* Ambient, so every line of a served request correlates with the span the
+		   endpoint opened without a caller threading an id through its helpers. */
+		const trace = currentTrace();
+		if (trace) {
+			record.traceId = trace.traceId;
+			record.spanId = trace.spanId;
+		}
+		if (event?.requestId) record.requestId = boundedString(event.requestId);
+		if (event?.endpoint) record.endpoint = boundedString(event.endpoint);
+		if (event?.module) record.module = boundedString(event.module);
+		if (event?.fields) record.fields = sanitize(event.fields, 0);
+		if (event?.err !== undefined) {
+			record.err = loggedError(event.err, withStack);
+		}
+		write(
+			entryLevel,
+			format === 'json' ? JSON.stringify(record) : textLine(record),
+		);
+		if (entryLevel !== 'error' || errorSink.kind === 'none') return;
+		/* Foreign code behind a configured URL: a throw here would fail the very
+		   line that is already reporting a failure. */
+		try {
+			const err = record.err as LoggedError | undefined;
+			errorSink.report({
+				at: Date.parse(record.time as string) || 0,
+				name: err?.name ?? 'error',
+				message: err?.message ?? (record.msg as string),
+				...(event?.endpoint ? { endpoint: event.endpoint } : {}),
+				...(event?.module ? { module: event.module } : {}),
+				...(event?.requestId ? { requestId: event.requestId } : {}),
+				...(trace ? { traceId: trace.traceId, spanId: trace.spanId } : {}),
+			});
+		} catch {
+			/* An unreachable sink must never turn one failure into two. */
+		}
+	};
+
+	const logger: Logger = {
+		level,
+		format,
+		debug: (message, event) => emit('debug', message, event),
+		info: (message, event) => emit('info', message, event),
+		warn: (message, event) => emit('warn', message, event),
+		error: (message, event) => emit('error', message, event),
+	};
+	if (environment.FD_LOG_FORMAT?.trim() && !configuredFormat) {
+		logger.warn('FD_LOG_FORMAT is not "json" or "text"; using the default', {
+			fields: { format },
+		});
+	}
+	if (environment.FD_LOG_LEVEL?.trim() && !configuredLevel) {
+		logger.warn(
+			'FD_LOG_LEVEL is not "debug", "info", "warn" or "error"; using the default',
+			{ fields: { level } },
+		);
+	}
+	return logger;
+}
+
+let processLogger: Logger | undefined;
+
+/**
+ * The logger of this process, built from the environment on first use so a
+ * deployment's `.env` is already loaded. Tests and libraries that need their
+ * own sink call `createLogger` instead.
+ */
+export function serverLogger(): Logger {
+	return (processLogger ??= createLogger({ errorSink: serverErrorSink() }));
+}

package/packages/server/src/mail/config.ts

@@ -0,0 +1,184 @@
+import { serverLogger } from '../log.ts';
+import { MAIL_ADAPTERS, type MailAdapterId } from './contracts.ts';
+
+/* Mail is configured by the process environment, the way storage and the
+   database are, so a deployment never forks the platform composition to send a
+   message. auth.core owned these variables before the port existed; its names
+   are still read, once, with a deprecation warning naming the replacement. */
+
+export interface MailVariableNames {
+	readonly transport: string;
+	readonly from: string;
+	readonly url: string;
+	readonly rejectUnauthorized: string;
+	readonly requireTLS: string;
+}
+
+export interface MailConfig {
+	readonly adapter: MailAdapterId;
+	readonly production: boolean;
+	/** `Name <address>` or an address. Empty unless the adapter is smtp. */
+	readonly from: string;
+	readonly smtp: {
+		readonly url: string;
+		readonly rejectUnauthorized: boolean;
+		readonly requireTLS: boolean;
+	};
+	/**
+	 * The variable each value was actually read from. Every refusal names one of
+	 * these, so an operator reading the message finds the key they set.
+	 */
+	readonly variables: MailVariableNames;
+	/** Deprecated names this environment still relies on, in the order read. */
+	readonly deprecated: readonly string[];
+}
+
+const CANONICAL: MailVariableNames = {
+	transport: 'FD_MAIL_TRANSPORT',
+	from: 'FD_MAIL_FROM',
+	url: 'FD_MAIL_SMTP_URL',
+	rejectUnauthorized: 'FD_MAIL_SMTP_TLS_REJECT_UNAUTHORIZED',
+	requireTLS: 'FD_MAIL_SMTP_REQUIRE_TLS',
+};
+
+const DEPRECATED: MailVariableNames = {
+	transport: 'FD_AUTH_MAIL_TRANSPORT',
+	from: 'FD_AUTH_MAIL_FROM',
+	url: 'FD_AUTH_SMTP_URL',
+	rejectUnauthorized: 'FD_AUTH_SMTP_TLS_REJECT_UNAUTHORIZED',
+	requireTLS: 'FD_AUTH_SMTP_REQUIRE_TLS',
+};
+
+/** The boolean auth.core used before a transport could be named. */
+const DEVELOPMENT_MAIL = 'FD_AUTH_DEVELOPMENT_MAIL';
+
+/* One line per retired variable per process. An operator needs the notice once;
+   a poll loop or a test that reads the environment repeatedly does not need it
+   at every read. The set is bounded by the number of variables. */
+const warned = new Set<string>();
+
+function warnDeprecated(variable: string, replacement: string): void {
+	if (warned.has(variable)) return;
+	warned.add(variable);
+	serverLogger().warn('deprecated mail variable', {
+		module: 'mail',
+		fields: { variable, replacement },
+	});
+}
+
+interface ReadValue {
+	readonly value: string;
+	readonly variable: string;
+}
+
+function booleanValue(read: ReadValue, fallback: boolean): boolean {
+	if (read.value === '') return fallback;
+	if (read.value === 'true') return true;
+	if (read.value === 'false') return false;
+	throw new Error(`${read.variable} must be true or false.`);
+}
+
+function transportId(read: ReadValue): MailAdapterId {
+	const found = MAIL_ADAPTERS.find((candidate) => candidate === read.value);
+	if (!found) {
+		throw new Error(
+			`${read.variable} must be one of ${MAIL_ADAPTERS.join(', ')}.`,
+		);
+	}
+	return found;
+}
+
+/**
+ * The mail configuration of a deployment. Refuses the development adapter in
+ * production here rather than at the first message, so a deployment that would
+ * silently drop its mail never finishes booting.
+ */
+export function mailConfigFromEnvironment(
+	environment: NodeJS.ProcessEnv = process.env,
+): MailConfig {
+	const production = environment.NODE_ENV === 'production';
+	const deprecated: string[] = [];
+	const variables: Record<keyof MailVariableNames, string> = { ...CANONICAL };
+
+	/* Which family a refusal names for a variable nobody set: the one the
+	   deployment is already editing, so an operator on the retired names is told
+	   about the key next to the one they set rather than about a third spelling. */
+	let missing: MailVariableNames = CANONICAL;
+
+	const read = (key: keyof MailVariableNames): ReadValue => {
+		const current = environment[CANONICAL[key]]?.trim() ?? '';
+		if (current !== '') return { value: current, variable: CANONICAL[key] };
+		const legacy = environment[DEPRECATED[key]]?.trim() ?? '';
+		if (legacy === '') return { value: '', variable: missing[key] };
+		variables[key] = DEPRECATED[key];
+		deprecated.push(DEPRECATED[key]);
+		warnDeprecated(DEPRECATED[key], CANONICAL[key]);
+		return { value: legacy, variable: DEPRECATED[key] };
+	};
+
+	const configured = read('transport');
+	if (configured.variable === DEPRECATED.transport) missing = DEPRECATED;
+	const developmentMail = booleanValue(
+		{
+			value: environment[DEVELOPMENT_MAIL]?.trim() ?? '',
+			variable: DEVELOPMENT_MAIL,
+		},
+		false,
+	);
+	if (developmentMail) {
+		deprecated.push(DEVELOPMENT_MAIL);
+		warnDeprecated(DEVELOPMENT_MAIL, `${CANONICAL.transport}=development`);
+	}
+	const adapter =
+		configured.value !== ''
+			? transportId(configured)
+			: developmentMail
+				? 'development'
+				: 'none';
+	if (developmentMail && adapter !== 'development') {
+		throw new Error(
+			`${DEVELOPMENT_MAIL} cannot be combined with ${configured.variable}=${adapter}.`,
+		);
+	}
+	if (production && adapter === 'development') {
+		/* The in-memory adapter accepts every message and delivers none. In
+		   production that is silent data loss, not a convenience. */
+		throw new Error(
+			`${configured.value !== '' ? `${configured.variable}=development` : DEVELOPMENT_MAIL} is only allowed outside production.`,
+		);
+	}
+	if (adapter !== 'smtp') {
+		return {
+			adapter,
+			production,
+			from: '',
+			smtp: { url: '', rejectUnauthorized: true, requireTLS: true },
+			variables: { ...variables },
+			deprecated,
+		};
+	}
+	const url = read('url');
+	if (url.value === '') {
+		throw new Error(
+			`${url.variable} is required when ${configured.variable} is smtp.`,
+		);
+	}
+	const from = read('from');
+	if (from.value === '') {
+		throw new Error(
+			`${from.variable} is required when ${configured.variable} is smtp.`,
+		);
+	}
+	return {
+		adapter,
+		production,
+		from: from.value,
+		smtp: {
+			url: url.value,
+			rejectUnauthorized: booleanValue(read('rejectUnauthorized'), true),
+			requireTLS: booleanValue(read('requireTLS'), true),
+		},
+		variables: { ...variables },
+		deprecated,
+	};
+}