@fragno-dev/core 0.1.11 → 0.2.0

package/src/api/fragment-instantiator.ts

@@ -27,10 +27,73 @@ import type { FragnoPublicConfig } from "./shared-types";
 import { RequestContextStorage } from "./request-context-storage";
 import { bindServicesToContext, type BoundServices } from "./bind-services";
 import { instantiatedFragmentFakeSymbol } from "../internal/symbols";
+import { recordTraceEvent } from "../internal/trace-context";
 
 // Re-export types needed by consumers
 export type { BoundServices };
 
+type InternalRoutePrefix = "/_internal";
+
+type JoinInternalRoutePath<TPath extends string> = TPath extends "" | "/"
+  ? InternalRoutePrefix
+  : TPath extends `/${string}`
+    ? `${InternalRoutePrefix}${TPath}`
+    : `${InternalRoutePrefix}/${TPath}`;
+
+type PrefixInternalRoute<TRoute> =
+  TRoute extends FragnoRouteConfig<
+    infer TMethod,
+    infer TPath,
+    infer TInputSchema,
+    infer TOutputSchema,
+    infer TErrorCode,
+    infer TQueryParameters,
+    infer TThisContext
+  >
+    ? FragnoRouteConfig<
+        TMethod,
+        JoinInternalRoutePath<TPath>,
+        TInputSchema,
+        TOutputSchema,
+        TErrorCode,
+        TQueryParameters,
+        TThisContext
+      >
+    : never;
+
+type PrefixInternalRoutes<TRoutes extends readonly AnyFragnoRouteConfig[]> =
+  TRoutes extends readonly [...infer TRoutesTuple]
+    ? { [K in keyof TRoutesTuple]: PrefixInternalRoute<TRoutesTuple[K]> }
+    : readonly AnyFragnoRouteConfig[];
+
+type ExtractRoutesFromFragment<T> =
+  T extends FragnoInstantiatedFragment<
+    infer TRoutes,
+    infer _TDeps,
+    infer _TServices,
+    infer _TServiceThisContext,
+    infer _THandlerThisContext,
+    infer _TRequestStorage,
+    infer _TOptions,
+    infer _TLinkedFragments
+  >
+    ? TRoutes
+    : never;
+
+type InternalLinkedRoutes<TLinkedFragments> =
+  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment>
+    ? TLinkedFragments extends { _fragno_internal: infer TInternal }
+      ? ExtractRoutesFromFragment<TInternal> extends readonly AnyFragnoRouteConfig[]
+        ? PrefixInternalRoutes<ExtractRoutesFromFragment<TInternal>>
+        : readonly []
+      : readonly []
+    : readonly [];
+
+export type RoutesWithInternal<
+  TRoutes extends readonly AnyFragnoRouteConfig[],
+  TLinkedFragments,
+> = readonly [...TRoutes, ...InternalLinkedRoutes<TLinkedFragments>];
+
 /**
  * Helper type to extract the instantiated fragment type from a fragment definition.
  * This is useful for typing functions that accept instantiated fragments based on their definition.
@@ -59,7 +122,7 @@ export type InstantiatedFragmentFromDefinition<
     infer TLinkedFragments
   >
     ? FragnoInstantiatedFragment<
-        readonly AnyFragnoRouteConfig[], // Routes are dynamic, so we use a generic array
+        RoutesWithInternal<readonly AnyFragnoRouteConfig[], TLinkedFragments>,
         TDeps,
         BoundServices<TBaseServices & TServices>,
         TServiceThisContext,
@@ -79,6 +142,34 @@ type ReactRouterHandlers = {
   action: (args: { request: Request }) => Promise<Response>;
 };
 
+const serializeHeadersForTrace = (headers: Headers): [string, string][] =>
+  Array.from(headers.entries()).sort(([a], [b]) => a.localeCompare(b));
+
+const serializeQueryForTrace = (query: URLSearchParams): [string, string][] =>
+  Array.from(query.entries()).sort(([a], [b]) => a.localeCompare(b));
+
+const serializeBodyForTrace = (body: RequestBodyType): unknown => {
+  if (body instanceof FormData) {
+    const entries = Array.from(body.entries()).map(([key, value]) => {
+      if (value instanceof Blob) {
+        return [key, { type: "blob", size: value.size, mime: value.type }] as const;
+      }
+      return [key, value] as const;
+    });
+    return { type: "form-data", entries };
+  }
+
+  if (body instanceof Blob) {
+    return { type: "blob", size: body.size, mime: body.type };
+  }
+
+  if (body instanceof ReadableStream) {
+    return { type: "stream" };
+  }
+
+  return body;
+};
+
 type SolidStartHandlers = {
   GET: (args: { request: Request }) => Promise<Response>;
   POST: (args: { request: Request }) => Promise<Response>;
@@ -131,6 +222,66 @@ export type AnyFragnoInstantiatedFragment = FragnoInstantiatedFragment<
   any
 >;
 
+const INTERNAL_LINKED_FRAGMENT_NAME = "_fragno_internal";
+const INTERNAL_ROUTE_PREFIX = "/_internal";
+
+type InternalLinkedRouteMeta = {
+  fragment: AnyFragnoInstantiatedFragment;
+  originalPath: string;
+  routes: readonly AnyFragnoRouteConfig[];
+};
+
+type InternalLinkedRouteConfig = AnyFragnoRouteConfig & {
+  __internal?: InternalLinkedRouteMeta;
+};
+
+function normalizeRoutePrefix(prefix: string): string {
+  if (!prefix.startsWith("/")) {
+    prefix = `/${prefix}`;
+  }
+  return prefix.endsWith("/") && prefix.length > 1 ? prefix.slice(0, -1) : prefix;
+}
+
+function joinRoutePath(prefix: string, path: string): string {
+  const normalizedPrefix = normalizeRoutePrefix(prefix);
+  if (!path || path === "/") {
+    return normalizedPrefix;
+  }
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `${normalizedPrefix}${normalizedPath}`;
+}
+
+function collectLinkedFragmentRoutes(
+  linkedFragments: Record<string, AnyFragnoInstantiatedFragment>,
+): InternalLinkedRouteConfig[] {
+  const linkedRoutes: InternalLinkedRouteConfig[] = [];
+
+  for (const [name, fragment] of Object.entries(linkedFragments)) {
+    if (name !== INTERNAL_LINKED_FRAGMENT_NAME) {
+      continue;
+    }
+
+    const internalRoutes = (fragment.routes ?? []) as readonly AnyFragnoRouteConfig[];
+    if (internalRoutes.length === 0) {
+      continue;
+    }
+
+    for (const route of internalRoutes) {
+      linkedRoutes.push({
+        ...route,
+        path: joinRoutePath(INTERNAL_ROUTE_PREFIX, route.path),
+        __internal: {
+          fragment,
+          originalPath: route.path,
+          routes: internalRoutes,
+        },
+      });
+    }
+  }
+
+  return linkedRoutes;
+}
+
 export interface FragnoFragmentSharedConfig<
   TRoutes extends readonly FragnoRouteConfig<
     HTTPMethod,
@@ -176,6 +327,7 @@ export class FragnoInstantiatedFragment<
   #createRequestStorage?: () => TRequestStorage;
   #options: TOptions;
   #linkedFragments: TLinkedFragments;
+  #internalData: Record<string, unknown>;
 
   constructor(params: {
     name: string;
@@ -189,6 +341,7 @@ export class FragnoInstantiatedFragment<
     createRequestStorage?: () => TRequestStorage;
     options: TOptions;
     linkedFragments?: TLinkedFragments;
+    internalData?: Record<string, unknown>;
   }) {
     this.#name = params.name;
     this.#routes = params.routes;
@@ -201,6 +354,7 @@ export class FragnoInstantiatedFragment<
     this.#createRequestStorage = params.createRequestStorage;
     this.#options = params.options;
     this.#linkedFragments = params.linkedFragments ?? ({} as TLinkedFragments);
+    this.#internalData = params.internalData ?? {};
 
     // Build router
     this.#router =
@@ -249,6 +403,7 @@ export class FragnoInstantiatedFragment<
       deps: this.#deps,
       options: this.#options,
       linkedFragments: this.#linkedFragments,
+      ...this.#internalData,
     };
   }
 
@@ -409,31 +564,90 @@ export class FragnoInstantiatedFragment<
       );
     }
 
-    // Parse request body
+    // Get the expected content type from route config (default: application/json)
+    const routeConfig = route.data as InternalLinkedRouteConfig;
+    const expectedContentType = routeConfig.contentType ?? "application/json";
+
+    // Parse request body based on route's expected content type
     let requestBody: RequestBodyType = undefined;
     let rawBody: string | undefined = undefined;
 
     if (req.body instanceof ReadableStream) {
-      // Clone request to make sure we don't consume body stream
-      const clonedReq = req.clone();
-
-      // Get raw text
-      rawBody = await clonedReq.text();
+      const requestContentType = (req.headers.get("content-type") ?? "").toLowerCase();
+
+      if (expectedContentType === "multipart/form-data") {
+        // Route expects FormData (file uploads)
+        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 },
+          );
+        }
 
-      // Parse JSON if body is not empty
-      if (rawBody) {
         try {
-          requestBody = JSON.parse(rawBody);
+          requestBody = await req.formData();
         } catch {
-          // If JSON parsing fails, keep body as undefined
-          // This handles cases where body is not JSON
-          requestBody = undefined;
+          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<Uint8Array>();
+      } else {
+        // Route expects JSON (default)
+        // Note: We're lenient here - we accept requests without Content-Type header
+        // or with application/json. We reject multipart/form-data for JSON routes.
+        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 },
+          );
+        }
+
+        // Clone request to make sure we don't consume body stream
+        const clonedReq = req.clone();
+
+        // Get raw text
+        rawBody = await clonedReq.text();
+
+        // Parse JSON if body is not empty
+        if (rawBody) {
+          try {
+            requestBody = JSON.parse(rawBody);
+          } catch {
+            // If JSON parsing fails, keep body as undefined
+            // This handles cases where body is not JSON
+            requestBody = undefined;
+          }
         }
       }
     }
 
+    // URL decode path params from rou3 (which returns encoded values)
+    const decodedRouteParams: Record<string, string> = {};
+    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),
@@ -441,11 +655,27 @@ export class FragnoInstantiatedFragment<
 
     // Execute middleware and handler
     const executeRequest = async (): Promise<Response> => {
-      // Middleware execution (if present)
-      if (this.#middlewareHandler) {
-        const middlewareResult = await this.#executeMiddleware(req, route, requestState);
-        if (middlewareResult !== undefined) {
-          return middlewareResult;
+      // Parent middleware execution
+      const middlewareResult = await this.#executeMiddleware(req, route, requestState);
+      if (middlewareResult !== undefined) {
+        return middlewareResult;
+      }
+
+      // Internal fragment middleware execution (if linked)
+      const internalMeta = routeConfig.__internal;
+      if (internalMeta) {
+        const internalResult = await FragnoInstantiatedFragment.#runMiddlewareForFragment(
+          internalMeta.fragment as AnyFragnoInstantiatedFragment,
+          {
+            req,
+            method: routeConfig.method,
+            path: internalMeta.originalPath,
+            requestState,
+            routes: internalMeta.routes,
+          },
+        );
+        if (internalResult !== undefined) {
+          return internalResult;
         }
       }
 
@@ -527,6 +757,16 @@ export class FragnoInstantiatedFragment<
       shouldValidateInput: true, // Enable validation for production use
     });
 
+    recordTraceEvent({
+      type: "route-input",
+      method: route.method,
+      path: route.path,
+      pathParams: (pathParams ?? {}) as Record<string, string>,
+      queryParams: serializeQueryForTrace(searchParams),
+      headers: serializeHeadersForTrace(requestHeaders),
+      body: serializeBodyForTrace(body),
+    });
+
     // Construct RequestOutputContext
     const outputContext = new RequestOutputContext(route.outputSchema);
 
@@ -563,32 +803,73 @@ export class FragnoInstantiatedFragment<
     route: ReturnType<typeof findRoute>,
     requestState: MutableRequestState,
   ): Promise<Response | undefined> {
-    if (!this.#middlewareHandler || !route) {
+    if (!route) {
       return undefined;
     }
 
     const { path } = route.data as AnyFragnoRouteConfig;
-
-    const middlewareInputContext = new RequestMiddlewareInputContext(this.#routes, {
+    return FragnoInstantiatedFragment.#runMiddlewareForFragment(this, {
+      req,
       method: req.method as HTTPMethod,
       path,
-      request: req,
-      state: requestState,
+      requestState,
     });
+  }
+
+  static async #runMiddlewareForFragment(
+    fragment: AnyFragnoInstantiatedFragment,
+    options: {
+      req: Request;
+      method: HTTPMethod;
+      path: string;
+      requestState: MutableRequestState;
+      routes?: readonly AnyFragnoRouteConfig[];
+    },
+  ): Promise<Response | undefined> {
+    if (!fragment.#middlewareHandler) {
+      return undefined;
+    }
+
+    const middlewareInputContext = new RequestMiddlewareInputContext(
+      (options.routes ?? fragment.#routes) as readonly AnyFragnoRouteConfig[],
+      {
+        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(
+      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 !== undefined) {
         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();
       }
@@ -627,6 +908,16 @@ export class FragnoInstantiatedFragment<
       rawBody,
     });
 
+    recordTraceEvent({
+      type: "route-input",
+      method: req.method,
+      path,
+      pathParams: inputContext.pathParams as Record<string, string>,
+      queryParams: serializeQueryForTrace(requestState.searchParams),
+      headers: serializeHeadersForTrace(requestState.headers),
+      body: serializeBodyForTrace(requestState.body),
+    });
+
     const outputContext = new RequestOutputContext(outputSchema);
 
     try {
@@ -700,7 +991,7 @@ export function instantiateFragment<
   serviceImplementations?: TServiceDependencies,
   instantiationOptions?: InstantiationOptions,
 ): FragnoInstantiatedFragment<
-  FlattenRouteFactories<TRoutesOrFactories>,
+  RoutesWithInternal<FlattenRouteFactories<TRoutesOrFactories>, TLinkedFragments>,
   TDeps,
   BoundServices<TBaseServices & TServices>,
   TServiceThisContext,
@@ -888,6 +1179,13 @@ export function instantiateFragment<
 
   const serviceContext = contexts?.serviceContext;
   const handlerContext = contexts?.handlerContext;
+  const internalData =
+    definition.internalDataFactory?.({
+      config,
+      options,
+      deps,
+      linkedFragments: linkedFragmentInstances,
+    }) ?? {};
 
   // 9. Bind services to serviceContext (restricted)
   // Services get the restricted context (for database fragments, this excludes execute methods)
@@ -900,7 +1198,12 @@ export function instantiateFragment<
     services: boundServices,
     serviceDeps: serviceImplementations ?? ({} as TServiceDependencies),
   };
-  const routes = resolveRouteFactories(context, routesOrFactories);
+  const routes = resolveRouteFactories(context, routesOrFactories) as AnyFragnoRouteConfig[];
+  const linkedRoutes = collectLinkedFragmentRoutes(
+    linkedFragmentInstances as Record<string, AnyFragnoInstantiatedFragment>,
+  );
+  const finalRoutes =
+    linkedRoutes.length > 0 ? [...routes, ...linkedRoutes] : (routes as AnyFragnoRouteConfig[]);
 
   // 11. Calculate mount route
   const mountRoute = getMountRoute({
@@ -918,7 +1221,10 @@ export function instantiateFragment<
   // Handlers get handlerContext which may have more capabilities than serviceContext
   return new FragnoInstantiatedFragment({
     name: definition.name,
-    routes,
+    routes: finalRoutes as unknown as RoutesWithInternal<
+      FlattenRouteFactories<TRoutesOrFactories>,
+      TLinkedFragments
+    >,
     deps,
     services: boundServices as BoundServices<TBaseServices & TServices>,
     mountRoute,
@@ -928,6 +1234,7 @@ export function instantiateFragment<
     createRequestStorage: createRequestStorageWithContext,
     options,
     linkedFragments: linkedFragmentInstances,
+    internalData: internalData as Record<string, unknown>,
   });
 }
 
@@ -1004,7 +1311,7 @@ interface IFragnoInstantiatedFragment {
     deps: unknown;
     options: unknown;
     linkedFragments: unknown;
-  };
+  } & Record<string, unknown>;
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   withMiddleware(handler: any): this;
@@ -1178,7 +1485,7 @@ export class FragmentInstantiationBuilder<
    * Build and return the instantiated fragment
    */
   build(): FragnoInstantiatedFragment<
-    FlattenRouteFactories<TRoutesOrFactories>,
+    RoutesWithInternal<FlattenRouteFactories<TRoutesOrFactories>, TLinkedFragments>,
     TDeps,
     BoundServices<TBaseServices & TServices>,
     TServiceThisContext,

package/src/api/internal/path-runtime.test.ts

@@ -77,6 +77,13 @@ describe("matchPathParams (runtime extraction)", () => {
     expect(matchPathParams("/users/:id", "/users/123/")).toEqual({ id: "123" });
   });
 
+  test("URL decodes named params", () => {
+    expect(matchPathParams("/users/:name", "/users/a%20b")).toEqual({ name: "a b" });
+    expect(matchPathParams("/files/:path", "/files/folder%2Fsubfolder")).toEqual({
+      path: "folder/subfolder",
+    });
+  });
+
   test("pattern longer than path fills empty strings for remaining params", () => {
     // Remaining ":id" becomes empty string
     expect(matchPathParams("/users/:id", "/users")).toEqual({ id: "" });