@classytic/arc 1.1.0 → 2.1.3

package/dist/createApp-D2D5XXaV.mjs

@@ -0,0 +1,559 @@
+import { t as __exportAll } from "./chunk-C7Uep-_p.mjs";
+import { n as PUBLIC_SCOPE } from "./types-Beqn1Un7.mjs";
+import Fastify from "fastify";
+import qs from "qs";
+
+//#region src/factory/presets.ts
+/**
+* Production preset - strict security, performance optimized
+*/
+const productionPreset = {
+	logger: {
+		level: "info",
+		redact: {
+			paths: [
+				"req.headers.authorization",
+				"req.headers.cookie",
+				"req.headers[\"set-cookie\"]",
+				"*.password",
+				"*.secret",
+				"*.token",
+				"*.accessToken",
+				"*.refreshToken",
+				"*.creditCard"
+			],
+			censor: "[REDACTED]"
+		}
+	},
+	trustProxy: true,
+	helmet: { contentSecurityPolicy: { directives: {
+		defaultSrc: ["'self'"],
+		styleSrc: ["'self'", "'unsafe-inline'"],
+		scriptSrc: ["'self'"],
+		imgSrc: [
+			"'self'",
+			"data:",
+			"https:"
+		]
+	} } },
+	cors: {
+		origin: false,
+		credentials: true,
+		methods: [
+			"GET",
+			"POST",
+			"PUT",
+			"DELETE",
+			"PATCH",
+			"OPTIONS"
+		],
+		allowedHeaders: [
+			"Content-Type",
+			"Authorization",
+			"Accept"
+		]
+	},
+	rateLimit: {
+		max: 100,
+		timeWindow: "1 minute"
+	},
+	underPressure: {
+		exposeStatusRoute: true,
+		maxEventLoopDelay: 1e3,
+		maxHeapUsedBytes: 1024 * 1024 * 1024,
+		maxRssBytes: 1024 * 1024 * 1024
+	}
+};
+/**
+* Development preset - relaxed security, verbose logging
+*/
+const developmentPreset = {
+	logger: {
+		level: "debug",
+		transport: {
+			target: "pino-pretty",
+			options: {
+				colorize: true,
+				translateTime: "SYS:HH:MM:ss",
+				ignore: "pid,hostname"
+			}
+		}
+	},
+	trustProxy: true,
+	helmet: { contentSecurityPolicy: false },
+	cors: {
+		origin: true,
+		credentials: true,
+		methods: [
+			"GET",
+			"POST",
+			"PUT",
+			"DELETE",
+			"PATCH",
+			"OPTIONS"
+		],
+		allowedHeaders: [
+			"Content-Type",
+			"Authorization",
+			"Accept"
+		]
+	},
+	rateLimit: {
+		max: 1e3,
+		timeWindow: "1 minute"
+	},
+	underPressure: {
+		exposeStatusRoute: true,
+		maxEventLoopDelay: 5e3
+	}
+};
+/**
+* Testing preset - minimal setup, fast startup
+*/
+const testingPreset = {
+	logger: false,
+	trustProxy: false,
+	helmet: false,
+	cors: false,
+	rateLimit: false,
+	underPressure: false,
+	sensible: true,
+	multipart: { limits: {
+		fileSize: 1024 * 1024,
+		files: 5
+	} }
+};
+/**
+* Edge/Serverless preset - minimal cold-start overhead
+*
+* Optimized for AWS Lambda, Vercel, Cloudflare Workers, and similar environments.
+* Disables all heavy plugins that add cold-start latency:
+* - Security headers (handled by API Gateway / CDN)
+* - Rate limiting (handled by API Gateway / CDN)
+* - Health monitoring (Lambda has its own health checks)
+* - File uploads (use pre-signed URLs instead)
+* - Raw body parsing (register per-route if needed)
+*
+* Arc core plugins (requestId, health, gracefulShutdown) are also disabled
+* since the serverless runtime manages request lifecycle.
+*/
+const edgePreset = {
+	logger: { level: "warn" },
+	trustProxy: true,
+	helmet: false,
+	cors: false,
+	rateLimit: false,
+	underPressure: false,
+	sensible: true,
+	multipart: false,
+	rawBody: false,
+	arcPlugins: {
+		requestId: false,
+		health: false,
+		gracefulShutdown: false,
+		emitEvents: true
+	}
+};
+/**
+* Get preset by name
+*/
+function getPreset(name) {
+	switch (name) {
+		case "production": return productionPreset;
+		case "development": return developmentPreset;
+		case "testing": return testingPreset;
+		case "edge": return edgePreset;
+		default: throw new Error(`Unknown preset: ${name}`);
+	}
+}
+
+//#endregion
+//#region src/factory/createApp.ts
+/**
+* ArcFactory - Production-ready Fastify application factory
+*
+* Enforces security best practices by making plugins opt-out instead of opt-in.
+* A developer must explicitly disable security features rather than forget to enable them.
+*
+* Note: Arc is database-agnostic. Connect your database separately and provide
+* adapters when defining resources. This allows multiple databases, custom
+* connection pooling, and full control over your data layer.
+*
+* @example
+* // 1. Connect your database(s) separately
+* import mongoose from 'mongoose';
+* await mongoose.connect(process.env.MONGO_URI);
+*
+* // 2. Create Arc app (no database config needed)
+* const app = await createApp({
+*   preset: 'production',
+*   auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
+*   cors: { origin: ['https://example.com'] },
+* });
+*
+* // 3. Register resources with your adapters
+* await app.register(productResource.toPlugin());
+*
+* @example
+* // Multiple databases example
+* const primaryDb = await mongoose.connect(process.env.PRIMARY_DB);
+* const analyticsDb = mongoose.createConnection(process.env.ANALYTICS_DB);
+*
+* const orderResource = defineResource({
+*   adapter: createMongooseAdapter({ model: OrderModel, repository: orderRepo }),
+* });
+*
+* const analyticsResource = defineResource({
+*   adapter: createMongooseAdapter({ model: AnalyticsModel, repository: analyticsRepo }),
+* });
+*/
+var createApp_exports = /* @__PURE__ */ __exportAll({
+	ArcFactory: () => ArcFactory,
+	createApp: () => createApp
+});
+const PLUGIN_REGISTRY = {
+	cors: {
+		package: "@fastify/cors",
+		loader: () => import("@fastify/cors").then((m) => m.default)
+	},
+	helmet: {
+		package: "@fastify/helmet",
+		loader: () => import("@fastify/helmet").then((m) => m.default)
+	},
+	rateLimit: {
+		package: "@fastify/rate-limit",
+		loader: () => import("@fastify/rate-limit").then((m) => m.default)
+	},
+	underPressure: {
+		package: "@fastify/under-pressure",
+		loader: () => import("@fastify/under-pressure").then((m) => m.default)
+	},
+	sensible: {
+		package: "@fastify/sensible",
+		loader: () => import("@fastify/sensible").then((m) => m.default)
+	},
+	multipart: {
+		package: "@fastify/multipart",
+		loader: () => import("@fastify/multipart").then((m) => m.default),
+		optional: true
+	},
+	rawBody: {
+		package: "fastify-raw-body",
+		loader: () => import("fastify-raw-body").then((m) => m.default),
+		optional: true
+	}
+};
+async function loadPlugin(name, logger) {
+	const entry = PLUGIN_REGISTRY[name];
+	if (!entry) throw new Error(`Unknown plugin: ${name}`);
+	try {
+		return await entry.loader();
+	} catch (error) {
+		const err = error;
+		const isModuleNotFound = err.message.includes("Cannot find module") || err.message.includes("Cannot find package") || err.message.includes("MODULE_NOT_FOUND") || err.message.includes("Could not resolve");
+		if (isModuleNotFound && entry.optional) {
+			logger?.warn(`Optional plugin '${name}' skipped (${entry.package} not installed)`);
+			return null;
+		}
+		if (isModuleNotFound) throw new Error(`Plugin '${name}' requires package '${entry.package}' which is not installed.\nInstall it with: npm install ${entry.package}\nOr disable this plugin by setting ${name}: false in createApp options.`);
+		throw new Error(`Failed to load plugin '${name}': ${err.message}`);
+	}
+}
+/**
+* Create a production-ready Fastify application with Arc framework
+*
+* Security plugins are enabled by default (opt-out):
+* - helmet (security headers)
+* - cors (cross-origin requests)
+* - rateLimit (DDoS protection)
+* - underPressure (health monitoring)
+*
+* Note: Compression is not included due to known Fastify 5 issues.
+* Use a reverse proxy (Nginx, Caddy) or CDN for compression.
+*
+* @param options - Application configuration
+* @returns Configured Fastify instance
+*/
+async function createApp(options) {
+	if (options.debug !== void 0 && options.debug !== false) {
+		const { configureArcLogger } = await import("./logger-ByrvQWZO.mjs").then((n) => n.r);
+		configureArcLogger({ debug: options.debug });
+	}
+	const authConfig = options.auth;
+	const isAuthDisabled = authConfig === false;
+	if (!isAuthDisabled && authConfig && authConfig.type === "jwt") {
+		if (!authConfig.jwt?.secret && !authConfig.authenticate) throw new Error("createApp: JWT secret required when Arc auth is enabled.\nProvide auth.jwt.secret, auth.authenticate, or set auth: false to disable.\nExample: auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } }");
+	}
+	if (options.runtime === "distributed") {
+		const MEMORY_NAMES = new Set(["memory", "memory-cache"]);
+		const missing = [];
+		const eventsTransport = options.stores?.events;
+		if (!eventsTransport || MEMORY_NAMES.has(eventsTransport.name)) missing.push("events transport");
+		const cacheStore = options.stores?.cache;
+		if (!cacheStore || MEMORY_NAMES.has(cacheStore.name)) missing.push("cache store");
+		const idempotencyStore = options.stores?.idempotency;
+		if (!idempotencyStore || MEMORY_NAMES.has(idempotencyStore.name)) missing.push("idempotency store");
+		if (options.arcPlugins?.queryCache) {
+			const qcStore = options.stores?.queryCache;
+			if (!qcStore || MEMORY_NAMES.has(qcStore.name)) missing.push("queryCache store");
+		}
+		if (missing.length > 0) throw new Error(`[Arc] runtime: 'distributed' requires Redis/durable adapters.\nMissing: ${missing.join(", ")}.\nProvide Redis-backed stores or use runtime: 'memory' for development.`);
+	}
+	const config = {
+		...options.preset ? getPreset(options.preset) : {},
+		...options
+	};
+	let fastify = Fastify({
+		logger: config.logger ?? true,
+		trustProxy: config.trustProxy ?? false,
+		routerOptions: { querystringParser: (str) => qs.parse(str) },
+		ajv: { customOptions: {
+			coerceTypes: true,
+			useDefaults: true,
+			removeAdditional: false,
+			keywords: ["example"]
+		} }
+	});
+	if (config.typeProvider === "typebox") try {
+		const { TypeBoxValidatorCompiler } = await import("@fastify/type-provider-typebox");
+		fastify.setValidatorCompiler(TypeBoxValidatorCompiler);
+		fastify.log.debug("TypeBox type provider enabled");
+	} catch {
+		fastify.log.warn("typeProvider: \"typebox\" requested but @fastify/type-provider-typebox is not installed. Install it with: npm install @sinclair/typebox @fastify/type-provider-typebox");
+	}
+	fastify.removeContentTypeParser("application/json");
+	fastify.addContentTypeParser("application/json", { parseAs: "string" }, (_req, body, done) => {
+		if (!body || body.length === 0) return done(null, void 0);
+		try {
+			done(null, JSON.parse(body));
+		} catch (err) {
+			done(err);
+		}
+	});
+	if (config.helmet !== false) {
+		const helmet = await loadPlugin("helmet");
+		await fastify.register(helmet, config.helmet ?? {});
+		fastify.log.debug("Helmet (security headers) enabled");
+	} else fastify.log.warn("Helmet disabled - security headers not applied");
+	if (config.cors !== false) {
+		const cors = await loadPlugin("cors");
+		const corsOptions = config.cors ?? {};
+		if (config.preset === "production" && (!corsOptions || !("origin" in corsOptions))) throw new Error("CORS origin must be explicitly configured in production.\nSet cors.origin to allowed domains or set cors: false to disable.\nExample: cors: { origin: ['https://yourdomain.com'] }\nDocs: https://github.com/classytic/arc#security");
+		await fastify.register(cors, corsOptions);
+		fastify.log.debug("CORS enabled");
+	} else fastify.log.warn("CORS disabled");
+	if (config.rateLimit !== false) {
+		const rateLimit = await loadPlugin("rateLimit");
+		const rateLimitOpts = config.rateLimit ?? {
+			max: 100,
+			timeWindow: "1 minute"
+		};
+		await fastify.register(rateLimit, rateLimitOpts);
+		if (config.preset === "production") {
+			if (!(typeof rateLimitOpts === "object" && "store" in rateLimitOpts)) fastify.log.warn("Rate limiting is using in-memory store. In multi-instance deployments, each instance tracks limits independently. Configure a Redis store for distributed rate limiting: rateLimit: { store: new RedisStore({ ... }) }");
+		}
+		fastify.log.debug("Rate limiting enabled");
+	} else fastify.log.warn("Rate limiting disabled");
+	if (config.preset === "production") fastify.log.warn("Response compression is not enabled (Fastify 5 stream issues). Use a reverse proxy (Nginx, Caddy, Cloudflare) for gzip/brotli in production.");
+	if (config.underPressure !== false) {
+		const underPressure = await loadPlugin("underPressure");
+		await fastify.register(underPressure, config.underPressure ?? { exposeStatusRoute: true });
+		fastify.log.debug("Health monitoring (under-pressure) enabled");
+	} else fastify.log.debug("Health monitoring disabled");
+	if (config.sensible !== false) {
+		const sensible = await loadPlugin("sensible");
+		await fastify.register(sensible);
+		fastify.log.debug("Sensible (HTTP helpers) enabled");
+	}
+	if (config.multipart !== false) {
+		const multipart = await loadPlugin("multipart", fastify.log);
+		if (multipart) {
+			await fastify.register(multipart, {
+				limits: {
+					fileSize: 10 * 1024 * 1024,
+					files: 10
+				},
+				throwFileSizeLimit: true,
+				...config.multipart
+			});
+			fastify.log.debug("Multipart (file uploads) enabled");
+		}
+	}
+	if (config.rawBody !== false) {
+		const rawBody = await loadPlugin("rawBody", fastify.log);
+		if (rawBody) {
+			await fastify.register(rawBody, {
+				field: "rawBody",
+				global: false,
+				encoding: "utf8",
+				runFirst: true,
+				...config.rawBody
+			});
+			fastify.log.debug("Raw body parsing enabled");
+		}
+	}
+	const { arcCorePlugin, requestIdPlugin, healthPlugin, gracefulShutdownPlugin } = await import("./plugins/index.mjs");
+	await fastify.register(arcCorePlugin, { emitEvents: config.arcPlugins?.emitEvents !== false });
+	/** Track a plugin in the Arc plugin registry */
+	const trackPlugin = (name, opts) => {
+		fastify.arc.plugins.set(name, {
+			name,
+			options: opts,
+			registeredAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	};
+	trackPlugin("arc-core");
+	if (config.arcPlugins?.events !== false) {
+		const { default: eventPlugin } = await import("./eventPlugin-BEOvaDqo.mjs").then((n) => n.n);
+		const eventOpts = typeof config.arcPlugins?.events === "object" ? config.arcPlugins.events : {};
+		await fastify.register(eventPlugin, {
+			...eventOpts,
+			transport: options.stores?.events
+		});
+		trackPlugin("arc-events", eventOpts);
+		fastify.log.debug(`Arc events plugin enabled (transport: ${fastify.events.transportName})`);
+	}
+	if (config.arcPlugins?.requestId !== false) {
+		await fastify.register(requestIdPlugin);
+		trackPlugin("arc-request-id");
+		fastify.log.debug("Arc requestId plugin enabled");
+	}
+	if (config.arcPlugins?.health !== false) {
+		await fastify.register(healthPlugin);
+		trackPlugin("arc-health");
+		fastify.log.debug("Arc health plugin enabled");
+	}
+	if (config.arcPlugins?.gracefulShutdown !== false) {
+		await fastify.register(gracefulShutdownPlugin);
+		trackPlugin("arc-graceful-shutdown");
+		fastify.log.debug("Arc gracefulShutdown plugin enabled");
+	}
+	if (config.arcPlugins?.caching) {
+		const { default: cachingPlugin } = await import("./caching-GSDJcA6-.mjs").then((n) => n.r);
+		const cachingOpts = config.arcPlugins.caching === true ? {} : config.arcPlugins.caching;
+		await fastify.register(cachingPlugin, cachingOpts);
+		trackPlugin("arc-caching", cachingOpts);
+		fastify.log.debug("Arc caching plugin enabled");
+	}
+	if (config.arcPlugins?.queryCache) {
+		const { queryCachePlugin } = await import("./queryCachePlugin-B6R0d4av.mjs").then((n) => n.n);
+		const qcOpts = config.arcPlugins.queryCache === true ? {} : config.arcPlugins.queryCache;
+		const store = options.stores?.queryCache ?? new (await (import("./memory-B2v7KrCB.mjs").then((n) => n.n))).MemoryCacheStore();
+		await fastify.register(queryCachePlugin, {
+			store,
+			...qcOpts
+		});
+		trackPlugin("arc-query-cache", qcOpts);
+		fastify.log.debug("Arc queryCache plugin enabled");
+	}
+	if (config.arcPlugins?.sse) if (config.arcPlugins?.events === false) fastify.log.warn("SSE plugin requires events plugin (arcPlugins.events). SSE disabled.");
+	else {
+		const { default: ssePlugin } = await import("./sse-DkqQ1uxb.mjs").then((n) => n.r);
+		const sseOpts = config.arcPlugins.sse === true ? {} : config.arcPlugins.sse;
+		await fastify.register(ssePlugin, sseOpts);
+		trackPlugin("arc-sse", sseOpts);
+		fastify.log.debug("Arc SSE plugin enabled");
+	}
+	fastify.decorateRequest("scope", null);
+	fastify.addHook("onRequest", async (request) => {
+		if (!request.scope) request.scope = PUBLIC_SCOPE;
+	});
+	if (isAuthDisabled) fastify.log.debug("Authentication disabled");
+	else if (authConfig) switch (authConfig.type) {
+		case "betterAuth": {
+			const { plugin, openapi } = authConfig.betterAuth;
+			await fastify.register(plugin);
+			trackPlugin("auth-better-auth");
+			if (openapi && !fastify.arc.externalOpenApiPaths.includes(openapi)) fastify.arc.externalOpenApiPaths.push(openapi);
+			fastify.log.debug("Better Auth authentication enabled");
+			break;
+		}
+		case "custom":
+			await fastify.register(authConfig.plugin);
+			trackPlugin("auth-custom");
+			fastify.log.debug("Custom authentication plugin enabled");
+			break;
+		case "authenticator": {
+			const { authenticate } = authConfig;
+			fastify.decorate("authenticate", async function(request, reply) {
+				await authenticate(request, reply);
+			});
+			trackPlugin("auth-authenticator");
+			fastify.log.debug("Custom authenticator enabled");
+			break;
+		}
+		case "jwt": {
+			const { authPlugin } = await import("./auth/index.mjs");
+			const { type: _, ...arcAuthOpts } = authConfig;
+			await fastify.register(authPlugin, arcAuthOpts);
+			trackPlugin("auth-jwt");
+			fastify.log.debug("Arc authentication plugin enabled");
+			break;
+		}
+	}
+	if (config.elevation) {
+		const { elevationPlugin } = await import("./elevation-DSTbVvYj.mjs").then((n) => n.r);
+		await fastify.register(elevationPlugin, config.elevation);
+		trackPlugin("arc-elevation", config.elevation);
+		fastify.log.debug("Elevation plugin enabled");
+	}
+	if (config.errorHandler !== false) {
+		const { errorHandlerPlugin } = await import("./errorHandler-C3GY3_ow.mjs").then((n) => n.n);
+		const errorOpts = typeof config.errorHandler === "object" ? config.errorHandler : { includeStack: config.preset !== "production" };
+		await fastify.register(errorHandlerPlugin, errorOpts);
+		trackPlugin("arc-error-handler", errorOpts);
+		fastify.log.debug("Arc error handler enabled");
+	}
+	if (config.plugins) {
+		await config.plugins(fastify);
+		fastify.log.debug("Custom plugins registered");
+	}
+	if (config.onReady) {
+		const onReady = config.onReady;
+		fastify.addHook("onReady", async () => {
+			await onReady(fastify);
+		});
+	}
+	if (config.onClose) {
+		const onClose = config.onClose;
+		fastify.addHook("onClose", async () => {
+			await onClose(fastify);
+		});
+	}
+	const authMode = isAuthDisabled ? "none" : authConfig ? authConfig.type : "none";
+	fastify.log.info({
+		preset: config.preset ?? "custom",
+		runtime: config.runtime ?? "memory",
+		auth: authMode,
+		helmet: config.helmet !== false,
+		cors: config.cors !== false,
+		rateLimit: config.rateLimit !== false
+	}, "Arc application created");
+	return fastify;
+}
+/**
+* Quick factory for common scenarios
+*/
+const ArcFactory = {
+	async production(options) {
+		return createApp({
+			...options,
+			preset: "production"
+		});
+	},
+	async development(options) {
+		return createApp({
+			...options,
+			preset: "development"
+		});
+	},
+	async testing(options) {
+		return createApp({
+			...options,
+			preset: "testing"
+		});
+	}
+};
+
+//#endregion
+export { getPreset as a, developmentPreset as i, createApp as n, productionPreset as o, createApp_exports as r, testingPreset as s, ArcFactory as t };