@fragno-dev/core 0.1.11 → 0.2.2

package/dist/api/fragment-instantiator.js

@@ -1,22 +1,58 @@
 import { instantiatedFragmentFakeSymbol } from "../internal/symbols.js";
 import { resolveRouteFactories } from "./route.js";
+import { recordTraceEvent } from "../internal/trace-context.js";
 import { FragnoApiError } from "./error.js";
+import { parseFragnoResponse } from "./fragno-response.js";
+import { bindServicesToContext } from "./bind-services.js";
 import { getMountRoute } from "./internal/route.js";
+import { MutableRequestState } from "./mutable-request-state.js";
+import { RequestContextStorage } from "./request-context-storage.js";
 import { RequestInputContext } from "./request-input-context.js";
 import { RequestOutputContext } from "./request-output-context.js";
-import { MutableRequestState } from "./mutable-request-state.js";
 import { RequestMiddlewareInputContext, RequestMiddlewareOutputContext } from "./request-middleware.js";
-import { parseFragnoResponse } from "./fragno-response.js";
-import { RequestContextStorage } from "./request-context-storage.js";
-import { bindServicesToContext } from "./bind-services.js";
 import { addRoute, createRouter, findRoute } from "rou3";
 
 //#region src/api/fragment-instantiator.ts
+const requestSourceSymbol = Symbol.for("fragno-request-source");
+const requestRouteSymbol = Symbol.for("fragno-request-route");
+const requestWaitUntilSymbol = Symbol.for("fragno-request-wait-until");
+const serializeHeadersForTrace = (headers) => Array.from(headers.entries()).sort(([a], [b]) => a.localeCompare(b));
+const serializeQueryForTrace = (query) => Array.from(query.entries()).sort(([a], [b]) => a.localeCompare(b));
+const serializeBodyForTrace = (body) => {
+	if (body instanceof FormData) return {
+		type: "form-data",
+		entries: Array.from(body.entries()).map(([key, value]) => {
+			if (value instanceof Blob) return [key, {
+				type: "blob",
+				size: value.size,
+				mime: value.type
+			}];
+			return [key, value];
+		})
+	};
+	if (body instanceof Blob) return {
+		type: "blob",
+		size: body.size,
+		mime: body.type
+	};
+	if (body instanceof ReadableStream) return { type: "stream" };
+	return body;
+};
+const INTERNAL_ROUTE_PREFIX = "/_internal";
+function normalizeRoutePrefix(prefix) {
+	if (!prefix.startsWith("/")) prefix = `/${prefix}`;
+	return prefix.endsWith("/") && prefix.length > 1 ? prefix.slice(0, -1) : prefix;
+}
+function joinRoutePath(prefix, path) {
+	const normalizedPrefix = normalizeRoutePrefix(prefix);
+	if (!path || path === "/") return normalizedPrefix;
+	return `${normalizedPrefix}${path.startsWith("/") ? path : `/${path}`}`;
+}
 /**
 * Instantiated fragment class with encapsulated state.
 * Provides the same public API as the old FragnoInstantiatedFragment but with better encapsulation.
 */
-var FragnoInstantiatedFragment = class {
+var FragnoInstantiatedFragment = class FragnoInstantiatedFragment {
 	[instantiatedFragmentFakeSymbol] = instantiatedFragmentFakeSymbol;
 	#name;
 	#routes;
@@ -30,7 +66,7 @@ var FragnoInstantiatedFragment = class {
 	#contextStorage;
 	#createRequestStorage;
 	#options;
-	#linkedFragments;
+	#internalData;
 	constructor(params) {
 		this.#name = params.name;
 		this.#routes = params.routes;
@@ -42,7 +78,7 @@ var FragnoInstantiatedFragment = class {
 		this.#contextStorage = params.storage;
 		this.#createRequestStorage = params.createRequestStorage;
 		this.#options = params.options;
-		this.#linkedFragments = params.linkedFragments ?? {};
+		this.#internalData = params.internalData ?? {};
 		this.#router = createRouter();
 		for (const routeConfig of this.#routes) addRoute(this.#router, routeConfig.method.toUpperCase(), routeConfig.path, routeConfig);
 		this.handler = this.handler.bind(this);
@@ -66,7 +102,7 @@ var FragnoInstantiatedFragment = class {
 		return {
 			deps: this.#deps,
 			options: this.#options,
-			linkedFragments: this.#linkedFragments
+			...this.#internalData
 		};
 	}
 	/**
@@ -78,17 +114,45 @@ var FragnoInstantiatedFragment = class {
 		this.#middlewareHandler = handler;
 		return this;
 	}
-	#withRequestStorage(callback) {
+	#withRequestStorage(callback, source = "context", routeInfo, lifecycleContext) {
 		if (!this.#serviceThisContext && !this.#handlerThisContext) return callback();
 		const storageData = this.#createRequestStorage ? this.#createRequestStorage() : {};
+		if (storageData && typeof storageData === "object") {
+			const metadataTarget = storageData;
+			metadataTarget[requestSourceSymbol] = source;
+			if (routeInfo) metadataTarget[requestRouteSymbol] = routeInfo;
+			if (lifecycleContext?.waitUntil) metadataTarget[requestWaitUntilSymbol] = lifecycleContext.waitUntil;
+		}
 		return this.#contextStorage.run(storageData, callback);
 	}
 	inContext(callback) {
 		if (this.#handlerThisContext) {
 			const boundCallback = callback.bind(this.#handlerThisContext);
-			return this.#withRequestStorage(boundCallback);
+			return this.#withRequestStorage(boundCallback, "context");
 		}
-		return this.#withRequestStorage(callback);
+		return this.#withRequestStorage(callback, "context");
+	}
+	/**
+	* Execute multiple service calls within a handler context.
+	* If called outside a request context, it will create one automatically.
+	* Pass a factory so service calls are created inside the active context.
+	* Primarily used by database fragments (handlerTx).
+	*/
+	async callServices(serviceCalls) {
+		const handlerContext = this.#handlerThisContext;
+		if (!handlerContext?.handlerTx) throw new Error("callServices is only supported for fragments with handlerTx (database fragments).");
+		let callWasArray = false;
+		const execute = () => {
+			return handlerContext.handlerTx().withServiceCalls(() => {
+				const calls = serviceCalls();
+				callWasArray = Array.isArray(calls);
+				return callWasArray ? calls : [calls];
+			}).execute();
+		};
+		const result = this.#contextStorage.hasStore() ? await execute() : await this.#withRequestStorage(execute, "context");
+		if (callWasArray) return result;
+		const [first] = result;
+		return first;
 	}
 	/**
 	* Get framework-specific handlers for this fragment.
@@ -147,7 +211,7 @@ var FragnoInstantiatedFragment = class {
 	* Main request handler for this fragment.
 	* Handles routing, middleware, and error handling.
 	*/
-	async handler(req) {
+	async handler(req, lifecycleContext) {
 		const url = new URL(req.url);
 		const pathname = url.pathname;
 		const matchRoute = pathname.startsWith(this.#mountRoute) ? pathname.slice(this.#mountRoute.length) : null;
@@ -160,30 +224,65 @@ var FragnoInstantiatedFragment = class {
 			error: `Fragno: Route for '${this.#name}' not found`,
 			code: "ROUTE_NOT_FOUND"
 		}, { status: 404 });
+		const routeConfig = route.data;
+		const expectedContentType = routeConfig.contentType ?? "application/json";
 		let requestBody = void 0;
 		let rawBody = void 0;
 		if (req.body instanceof ReadableStream) {
-			rawBody = await req.clone().text();
-			if (rawBody) try {
-				requestBody = JSON.parse(rawBody);
-			} catch {
-				requestBody = void 0;
+			const requestContentType = (req.headers.get("content-type") ?? "").toLowerCase();
+			if (expectedContentType === "multipart/form-data") {
+				if (!requestContentType.includes("multipart/form-data")) return Response.json({
+					error: `This endpoint expects multipart/form-data, but received: ${requestContentType || "no content-type"}`,
+					code: "UNSUPPORTED_MEDIA_TYPE"
+				}, { status: 415 });
+				try {
+					requestBody = await req.formData();
+				} catch {
+					return Response.json({
+						error: "Failed to parse multipart form data",
+						code: "INVALID_REQUEST_BODY"
+					}, { status: 400 });
+				}
+			} else if (expectedContentType === "application/octet-stream") {
+				if (!requestContentType.includes("application/octet-stream")) return Response.json({
+					error: `This endpoint expects application/octet-stream, but received: ${requestContentType || "no content-type"}`,
+					code: "UNSUPPORTED_MEDIA_TYPE"
+				}, { status: 415 });
+				requestBody = req.body ?? new ReadableStream();
+			} else {
+				if (requestContentType.includes("multipart/form-data")) return Response.json({
+					error: `This endpoint expects JSON, but received multipart/form-data. Use a route with contentType: "multipart/form-data" for file uploads.`,
+					code: "UNSUPPORTED_MEDIA_TYPE"
+				}, { status: 415 });
+				rawBody = await req.clone().text();
+				if (rawBody) try {
+					requestBody = JSON.parse(rawBody);
+				} catch {
+					requestBody = void 0;
+				}
 			}
 		}
+		const decodedRouteParams = {};
+		for (const [key, value] of Object.entries(route.params ?? {})) decodedRouteParams[key] = decodeURIComponent(value);
 		const requestState = new MutableRequestState({
-			pathParams: route.params ?? {},
+			pathParams: decodedRouteParams,
 			searchParams: url.searchParams,
 			body: requestBody,
 			headers: new Headers(req.headers)
 		});
+		const fullRoutePath = this.#mountRoute && this.#mountRoute !== "/" ? `${this.#mountRoute}${routeConfig.path}` : routeConfig.path;
+		const routeInfo = {
+			method: routeConfig.method,
+			path: routeConfig.path,
+			mountRoute: this.#mountRoute,
+			fullPath: fullRoutePath
+		};
 		const executeRequest = async () => {
-			if (this.#middlewareHandler) {
-				const middlewareResult = await this.#executeMiddleware(req, route, requestState);
-				if (middlewareResult !== void 0) return middlewareResult;
-			}
+			const middlewareResult = await this.#executeMiddleware(req, route, requestState);
+			if (middlewareResult !== void 0) return middlewareResult;
 			return this.#executeHandler(req, route, requestState, rawBody);
 		};
-		return this.#withRequestStorage(executeRequest);
+		return this.#withRequestStorage(executeRequest, "route", routeInfo, lifecycleContext);
 	}
 	/**
 	* Call a route directly with typed inputs and outputs.
@@ -202,7 +301,8 @@ var FragnoInstantiatedFragment = class {
 			error: `Route ${method} ${path} not found`,
 			code: "ROUTE_NOT_FOUND"
 		}, { status: 404 });
-		const { pathParams = {}, body, query, headers } = inputOptions || {};
+		const { pathParams = {}, query, headers } = inputOptions || {};
+		const body = inputOptions && "body" in inputOptions ? inputOptions.body : void 0;
 		const searchParams = query instanceof URLSearchParams ? query : query ? new URLSearchParams(query) : new URLSearchParams();
 		const requestHeaders = headers instanceof Headers ? headers : headers ? new Headers(headers) : new Headers();
 		const inputContext = new RequestInputContext({
@@ -215,7 +315,23 @@ var FragnoInstantiatedFragment = class {
 			inputSchema: route.inputSchema,
 			shouldValidateInput: true
 		});
+		recordTraceEvent({
+			type: "route-input",
+			method: route.method,
+			path: route.path,
+			pathParams: pathParams ?? {},
+			queryParams: serializeQueryForTrace(searchParams),
+			headers: serializeHeadersForTrace(requestHeaders),
+			body: serializeBodyForTrace(body)
+		});
 		const outputContext = new RequestOutputContext(route.outputSchema);
+		const fullRoutePath = this.#mountRoute && this.#mountRoute !== "/" ? `${this.#mountRoute}${route.path}` : route.path;
+		const routeInfo = {
+			method: route.method,
+			path: route.path,
+			mountRoute: this.#mountRoute,
+			fullPath: fullRoutePath
+		};
 		const executeHandler = async () => {
 			try {
 				const thisContext = this.#handlerThisContext ?? {};
@@ -229,27 +345,50 @@ var FragnoInstantiatedFragment = class {
 				}, { status: 500 });
 			}
 		};
-		return this.#withRequestStorage(executeHandler);
+		return this.#withRequestStorage(executeHandler, "route", routeInfo);
 	}
 	/**
 	* Execute middleware for a request.
 	* Returns undefined if middleware allows the request to continue to the handler.
 	*/
 	async #executeMiddleware(req, route, requestState) {
-		if (!this.#middlewareHandler || !route) return;
+		if (!route) return;
 		const { path } = route.data;
-		const middlewareInputContext = new RequestMiddlewareInputContext(this.#routes, {
+		return FragnoInstantiatedFragment.#runMiddlewareForFragment(this, {
+			req,
 			method: req.method,
 			path,
-			request: req,
-			state: requestState
+			requestState
+		});
+	}
+	static async #runMiddlewareForFragment(fragment, options) {
+		if (!fragment.#middlewareHandler) return;
+		const middlewareInputContext = new RequestMiddlewareInputContext(options.routes ?? fragment.#routes, {
+			method: options.method,
+			path: options.path,
+			request: options.req,
+			state: options.requestState
 		});
-		const middlewareOutputContext = new RequestMiddlewareOutputContext(this.#deps, this.#services);
+		const middlewareOutputContext = new RequestMiddlewareOutputContext(fragment.#deps, fragment.#services);
 		try {
-			const middlewareResult = await this.#middlewareHandler(middlewareInputContext, middlewareOutputContext);
+			const middlewareResult = await fragment.#middlewareHandler(middlewareInputContext, middlewareOutputContext);
+			recordTraceEvent({
+				type: "middleware-decision",
+				method: options.method,
+				path: options.path,
+				outcome: middlewareResult ? "deny" : "allow",
+				status: middlewareResult?.status
+			});
 			if (middlewareResult !== void 0) return middlewareResult;
 		} catch (error) {
 			console.error("Error in middleware", error);
+			recordTraceEvent({
+				type: "middleware-decision",
+				method: options.method,
+				path: options.path,
+				outcome: "deny",
+				status: error instanceof FragnoApiError ? error.status : 500
+			});
 			if (error instanceof FragnoApiError) return error.toResponse();
 			return Response.json({
 				error: "Internal server error",
@@ -275,6 +414,15 @@ var FragnoInstantiatedFragment = class {
 			state: requestState,
 			rawBody
 		});
+		recordTraceEvent({
+			type: "route-input",
+			method: req.method,
+			path,
+			pathParams: inputContext.pathParams,
+			queryParams: serializeQueryForTrace(requestState.searchParams),
+			headers: serializeHeadersForTrace(requestState.headers),
+			body: serializeBodyForTrace(requestState.body)
+		});
 		const outputContext = new RequestOutputContext(outputSchema);
 		try {
 			const contextForHandler = this.#handlerThisContext ?? {};
@@ -313,20 +461,12 @@ function instantiateFragment(definition, config, routesOrFactories, options, ser
 			deps = {};
 		} else throw error;
 	}
-	const linkedFragmentInstances = {};
-	const linkedFragmentServices = {};
-	if (definition.linkedFragments) for (const [name, callback] of Object.entries(definition.linkedFragments)) {
-		const linkedFragment = callback({
-			config,
-			options,
-			serviceDependencies: serviceImplementations
-		});
-		linkedFragmentInstances[name] = linkedFragment;
-		const services$1 = linkedFragment.services;
-		for (const [serviceName, service] of Object.entries(services$1)) linkedFragmentServices[serviceName] = service;
-	}
+	const mountRoute = getMountRoute({
+		name: definition.name,
+		mountRoute: options.mountRoute
+	});
 	const defineService = (services$1) => services$1;
-	const privateServices = { ...linkedFragmentServices };
+	const privateServices = {};
 	if (definition.privateServices) for (const [serviceName, factory] of Object.entries(definition.privateServices)) {
 		const serviceFactory = factory;
 		try {
@@ -398,16 +538,25 @@ function instantiateFragment(definition, config, routesOrFactories, options, ser
 	const serviceContext = contexts?.serviceContext;
 	const handlerContext = contexts?.handlerContext;
 	const boundServices = serviceContext ? bindServicesToContext(services, serviceContext) : services;
-	const routes = resolveRouteFactories({
+	const internalData = definition.internalDataFactory?.({
 		config,
+		options,
 		deps,
 		services: boundServices,
 		serviceDeps: serviceImplementations ?? {}
-	}, routesOrFactories);
-	const mountRoute = getMountRoute({
-		name: definition.name,
-		mountRoute: options.mountRoute
-	});
+	}) ?? {};
+	const context = {
+		config,
+		deps,
+		services: boundServices,
+		serviceDeps: serviceImplementations ?? {}
+	};
+	const routes = resolveRouteFactories(context, routesOrFactories);
+	const prefixedInternalRoutes = (definition.internalRoutes ? resolveRouteFactories(context, definition.internalRoutes) : []).map((route) => ({
+		...route,
+		path: joinRoutePath(INTERNAL_ROUTE_PREFIX, route.path)
+	}));
+	const finalRoutes = prefixedInternalRoutes.length > 0 ? [...routes, ...prefixedInternalRoutes] : routes;
 	const createRequestStorageWithContext = definition.createRequestStorage ? () => definition.createRequestStorage({
 		config,
 		options,
@@ -415,7 +564,7 @@ function instantiateFragment(definition, config, routesOrFactories, options, ser
 	}) : void 0;
 	return new FragnoInstantiatedFragment({
 		name: definition.name,
-		routes,
+		routes: finalRoutes,
 		deps,
 		services: boundServices,
 		mountRoute,
@@ -424,7 +573,7 @@ function instantiateFragment(definition, config, routesOrFactories, options, ser
 		storage,
 		createRequestStorage: createRequestStorageWithContext,
 		options,
-		linkedFragments: linkedFragmentInstances
+		internalData
 	});
 }
 /**