@nestia/core 14.0.0 → 14.0.1

package/native/transform.cjs

@@ -16,16 +16,65 @@ const path = require("node:path");
 //   - When the `@nestia/core` plugin itself is disabled, this descriptor is
 //     never evaluated, so the SDK contributor is never linked either.
 function createTtscPlugin(context) {
+  const typia = assertTypiaVersion(context);
   const plugin = {
     name: "@nestia/core",
     source: path.resolve(__dirname, "cmd", "ttsc-nestia"),
     composes: ["typia/lib/transform"],
+    // a typia upgrade must evaluate the version check again
+    hostInputs: typia,
   };
   const sdk = resolveSdkContributorSource(context);
   if (sdk !== null) plugin.contributors = [{ name: "sdk", source: sdk }];
   return plugin;
 }
 
+// The typia transform this host runs is compiled from the typia Go source
+// nestia's own `go.mod` pins, never from the typia package the project installs,
+// while the code it emits calls that installed package's runtime. A project
+// resolving another typia version would run mismatched code with no error until
+// a call reaches the difference (#1663), so the build stops and names both
+// versions. The version nestia is built for is the typia @nestia/core itself
+// resolves, which its exact dependency holds at the Go pin's release.
+//
+// Returns the typia manifests read, for ttsc to watch.
+function assertTypiaVersion(context) {
+  const expected = resolveTypiaManifest([__dirname]);
+  const actual =
+    context && typeof context.projectRoot === "string"
+      ? resolveTypiaManifest([context.projectRoot])
+      : null;
+  if (
+    expected !== null &&
+    actual !== null &&
+    expected.version !== actual.version
+  )
+    throw new Error(
+      [
+        `@nestia/core runs the typia ${expected.version} transform, but this project resolves typia ${actual.version} (${actual.file}).`,
+        `The generated code would call typia ${actual.version}'s runtime with typia ${expected.version}'s output.`,
+        `Install typia@${expected.version}, or a @nestia/core release built for typia ${actual.version}.`,
+      ].join(" "),
+    );
+  return [
+    ...new Set(
+      [expected, actual]
+        .filter((manifest) => manifest !== null)
+        .map((manifest) => manifest.file),
+    ),
+  ];
+}
+
+function resolveTypiaManifest(paths) {
+  try {
+    const file = require.resolve("typia/package.json", { paths });
+    const version = JSON.parse(fs.readFileSync(file, "utf8")).version;
+    return typeof version === "string" ? { file, version } : null;
+  } catch {
+    return null;
+  }
+}
+
 function resolveSdkContributorSource(context) {
   const paths = [__dirname];
   if (context && typeof context.projectRoot === "string")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/core",
-  "version": "14.0.0",
+  "version": "14.0.1",
   "description": "Super-fast validation decorators of NestJS",
   "main": "lib/index.js",
   "exports": {
@@ -8,10 +8,7 @@
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
     },
-    "./lib/transform": {
-      "types": "./lib/transform.d.ts",
-      "default": "./lib/transform.js"
-    },
+    "./lib/transform": "./native/transform.cjs",
     "./native/transform.cjs": "./native/transform.cjs",
     "./package.json": "./package.json"
   },
@@ -49,24 +46,24 @@
     "@typia/utils": "^15.0.0",
     "get-function-location": "^2.0.0",
     "glob": "^11.0.3",
-    "path-parser": "^6.1.0",
+    "path-to-regexp": "^8.4.2",
     "raw-body": "^2.0.0",
     "reflect-metadata": ">=0.1.12",
-    "rxjs": ">=6.0.3",
+    "rxjs": ">=7.1.0",
     "tgrid": "^1.1.0",
-    "typia": "^15.0.0",
+    "typia": "15.0.0",
     "ws": "^7.5.3",
-    "@nestia/fetcher": "^14.0.0"
+    "@nestia/fetcher": "^14.0.1"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.18.0",
-    "@nestjs/common": ">=7.0.1",
-    "@nestjs/core": ">=7.0.1",
+    "@nestjs/common": ">=11.0.0",
+    "@nestjs/core": ">=11.0.0",
     "reflect-metadata": ">=0.1.12",
-    "rxjs": ">=6.0.3",
+    "rxjs": ">=7.1.0",
     "ttsc": ">=0.19.2",
-    "typia": "^15.0.0",
-    "@nestia/fetcher": "^14.0.0"
+    "typia": "15.0.0",
+    "@nestia/fetcher": "^14.0.1"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/sdk": {
@@ -110,7 +107,7 @@
   "scripts": {
     "build": "rimraf lib && ttsc",
     "dev": "ttsc --watch",
-    "test:go": "cd test && go test ./..."
+    "test:go": "cd test && go test -count=1 ./..."
   },
   "types": "lib/index.d.ts"
 }

package/src/adaptors/McpAdaptor.ts

@@ -3,9 +3,18 @@ import {
   HttpException,
   INestApplication,
 } from "@nestjs/common";
-import { NestContainer } from "@nestjs/core";
+import { RouteParamtypes } from "@nestjs/common/enums/route-paramtypes.enum";
+import { ContextId, NestContainer } from "@nestjs/core";
+import { ExternalContextCreator } from "@nestjs/core/helpers/external-context-creator";
+import { Injector } from "@nestjs/core/injector/injector";
+import { InstanceWrapper } from "@nestjs/core/injector/instance-wrapper";
+import { Module } from "@nestjs/core/injector/module";
 
 import { IMcpRouteReflect } from "../decorators/internal/IMcpRouteReflect";
+import {
+  create_external_context_creator,
+  get_request_context_id,
+} from "./internal/external_context";
 
 /**
  * MCP (Model Context Protocol) adaptor.
@@ -23,6 +32,11 @@ import { IMcpRouteReflect } from "../decorators/internal/IMcpRouteReflect";
  * registration API of `McpServer` is bypassed by accessing the low-level
  * `.server` handler.
  *
+ * A tool call passes the guards, interceptors, pipes, and exception filters
+ * NestJS applies to an HTTP route on the same method, with the MCP HTTP request
+ * as the execution context. The endpoint is mounted at `path` as given, outside
+ * the application's global prefix.
+ *
  * Error mapping follows the MCP specification:
  *
  * - Unknown tool name: JSON-RPC `-32601`.
@@ -69,7 +83,12 @@ export class McpAdaptor {
 
     const tools: McpAdaptor.ITool[] = [];
     const container = (app as any).container as NestContainer;
-    for (const module of container.getModules().values()) {
+    const injector: Injector = new Injector();
+    for (const [moduleKey, module] of container.getModules()) {
+      const creator: ExternalContextCreator = create_external_context_creator(
+        container,
+        moduleKey,
+      );
       for (const wrapper of module.controllers.values()) {
         const instance = wrapper.instance;
         if (!instance) continue;
@@ -94,15 +113,18 @@ export class McpAdaptor {
             const params: IMcpRouteReflect.IArgument[] =
               Reflect.getMetadata("nestia/McpRoute/Parameters", proto, key) ??
               [];
-            const paramValidator = params.find(
-              (p) => p.category === "params",
-            )?.validate;
-
             tools.push({
               meta,
               source: `${wrapper.metatype?.name ?? proto.constructor?.name ?? "UnknownController"}.${String(key)}`,
-              validateArgs: paramValidator,
-              handler: async (args) => method.call(instance, args),
+              handler: createHandler({
+                container,
+                injector,
+                creator,
+                module,
+                wrapper,
+                key,
+                argument: params.find((p) => p.category === "params"),
+              }),
             });
           }
         }
@@ -153,25 +175,14 @@ export class McpAdaptor {
           );
 
         const args = reqMsg.params.arguments ?? {};
-        if (tool.validateArgs) {
-          const err: Error | null = tool.validateArgs(args);
-          if (err !== null) {
-            const body =
-              err instanceof BadRequestException
-                ? (err.getResponse() as any)
-                : undefined;
-            throw new McpError(ErrorCode.InvalidParams, err.message, {
-              errors: body?.errors,
-              path: body?.path,
-              expected: body?.expected,
-              value: body?.value,
-              reason: body?.reason,
-            });
-          }
-        }
-
         try {
-          const result = await tool.handler(args);
+          const result = await tool.handler({
+            request: req,
+            response: res,
+            args,
+          });
+          if (tookOver(res)) return { content: [] };
+          if (result instanceof Error) throw result;
           if (result === undefined) return { content: [] };
           return {
             content: [
@@ -183,6 +194,17 @@ export class McpAdaptor {
             ],
           };
         } catch (e) {
+          if (tookOver(res)) return { content: [] };
+          if (INVALID_ARGUMENTS.has(e as object)) {
+            const body = (e as BadRequestException).getResponse() as any;
+            throw new McpError(ErrorCode.InvalidParams, (e as Error).message, {
+              errors: body?.errors,
+              path: body?.path,
+              expected: body?.expected,
+              value: body?.value,
+              reason: body?.reason,
+            });
+          }
           if (e instanceof HttpException) {
             return {
               content: [{ type: "text" as const, text: e.message }],
@@ -211,6 +233,103 @@ export class McpAdaptor {
   }
 }
 
+/**
+ * The tool's call through the enhancers NestJS applies to a route of the same
+ * method: guards, interceptors, pipes, and exception filters, bound to the
+ * method, its controller, or globally. The MCP HTTP request is the execution
+ * context, so a guard reading `switchToHttp().getRequest()` works unchanged.
+ *
+ * The arguments reach the method through the pipes as its body would, validated
+ * by typia at that stage: after the guards, as `@TypedBody()` is. An invalid
+ * argument is thrown as the validator's `BadRequestException`, which an
+ * exception filter may map; unmapped, it becomes JSON-RPC `-32602`.
+ *
+ * A controller that is request-scoped, itself or through an enhancer or a
+ * dependency, is built per request with its enhancers, as NestJS builds it for
+ * an HTTP route; the static instance is only a placeholder without them.
+ */
+const createHandler = (props: {
+  container: NestContainer;
+  injector: Injector;
+  creator: ExternalContextCreator;
+  module: Module;
+  wrapper: InstanceWrapper;
+  key: string;
+  argument: IMcpRouteReflect.IArgument | undefined;
+}): McpAdaptor.ITool["handler"] => {
+  // the arguments stand at the params' position, or first when undecorated
+  const index: number = props.argument?.index ?? 0;
+  Reflect.defineMetadata(
+    PARAMS_METADATA,
+    { [`${RouteParamtypes.BODY}:${index}`]: { index, data: undefined } },
+    props.wrapper.instance.constructor,
+    props.key,
+  );
+  const validate = props.argument?.validate;
+  const create = (instance: any, contextId?: ContextId) =>
+    props.creator.create(
+      instance,
+      instance[props.key],
+      props.key,
+      PARAMS_METADATA,
+      {
+        // [request, response, next] as an HTTP route has, then the arguments
+        exchangeKeyForValue: (_type, _data, [, , , args]) => {
+          const error: Error | null = validate ? validate(args) : null;
+          if (error === null) return args;
+          INVALID_ARGUMENTS.add(error);
+          throw error;
+        },
+      },
+      contextId,
+      contextId && props.wrapper.id,
+    );
+  let target: ((...args: any[]) => Promise<unknown>) | undefined;
+  return async (input) => {
+    const call = (fn: (...args: any[]) => Promise<unknown>) =>
+      fn(input.request, input.response, undefined, input.args);
+    // resolved at the first call, so global enhancers init() registers count
+    if (props.wrapper.isDependencyTreeStatic())
+      return call((target ??= create(props.wrapper.instance)));
+    const contextId: ContextId = get_request_context_id(
+      props.container,
+      input.request as object,
+      props.wrapper.isDependencyTreeDurable(),
+    );
+    const instance: object = await props.injector.loadPerContext(
+      props.wrapper.instance,
+      props.module,
+      props.module.controllers,
+      contextId,
+    );
+    return call(create(instance, contextId));
+  };
+};
+
+/**
+ * Whether an exception filter already wrote the HTTP response itself. The
+ * response it wrote stands, so the transport's own is dropped: writing again
+ * would throw, and the transport would destroy the connection mid-response.
+ */
+const tookOver = (response: any): boolean => {
+  const raw: any = response.raw ?? response;
+  if (raw.headersSent !== true) return false;
+  raw.writeHead = () => raw;
+  raw.flushHeaders = () => {};
+  raw.write = () => true;
+  raw.end = (...args: unknown[]) => {
+    const callback: unknown = args.find((a) => typeof a === "function");
+    if (typeof callback === "function") queueMicrotask(() => callback());
+    return raw;
+  };
+  return true;
+};
+
+const PARAMS_METADATA = "nestia/McpRoute/ExternalParameters";
+
+/** The validators' exceptions, told apart from a handler's own. */
+const INVALID_ARGUMENTS: WeakSet<object> = new WeakSet();
+
 const assertUniqueTools = (tools: McpAdaptor.ITool[]): void => {
   const dict: Map<string, McpAdaptor.ITool[]> = new Map();
   for (const tool of tools) {
@@ -278,7 +397,10 @@ export namespace McpAdaptor {
   export interface ITool {
     meta: IMcpRouteReflect;
     source: string;
-    handler: (args: unknown) => Promise<unknown>;
-    validateArgs?: (input: any) => Error | null;
+    handler: (input: {
+      request: unknown;
+      response: unknown;
+      args: unknown;
+    }) => Promise<unknown>;
   }
 }

package/src/adaptors/WebSocketAdaptor.ts

@@ -1,5 +1,9 @@
 /// <reference path="../typings/get-function-location.d.ts" />
-import { INestApplication, VersioningType } from "@nestjs/common";
+import {
+  HttpException,
+  INestApplication,
+  VersioningType,
+} from "@nestjs/common";
 import {
   HOST_METADATA,
   MODULE_PATH,
@@ -14,7 +18,6 @@ import { Module } from "@nestjs/core/injector/module";
 import getFunctionLocation from "get-function-location";
 import { IncomingMessage, Server } from "http";
 import path from "path";
-import { Path } from "path-parser";
 import { Duplex } from "stream";
 import { WebSocketAcceptor } from "tgrid";
 import typia from "typia";
@@ -23,6 +26,7 @@ import WebSocket from "ws";
 import { IWebSocketRouteReflect } from "../decorators/internal/IWebSocketRouteReflect";
 import { ArrayUtil } from "../utils/ArrayUtil";
 import { VersioningStrategy } from "../utils/VersioningStrategy";
+import { RoutePathMatcher } from "./internal/RoutePathMatcher";
 
 export class WebSocketAdaptor {
   public static async upgrade(
@@ -62,25 +66,19 @@ export class WebSocketAdaptor {
           })();
           for (const op of this.operators) {
             const params: Record<string, string> | null = op.parser.test(path);
-            if (params !== null)
-              try {
-                await op.handler({ params, acceptor });
-              } catch (error) {
-                if (
-                  acceptor.state === WebSocketAcceptor.State.OPEN ||
-                  acceptor.state === WebSocketAcceptor.State.ACCEPTING
-                )
-                  await acceptor.reject(
-                    1008,
-                    error instanceof Error
-                      ? JSON.stringify({ ...error })
-                      : "unknown error",
-                  );
-              } finally {
-                return;
-              }
+            if (params === null) continue;
+            try {
+              await op.handler({ params, acceptor });
+            } catch (error) {
+              await terminate({ acceptor, socket: client, error });
+            }
+            return;
           }
-          await acceptor.reject(1002, `WebSocket API not found`);
+          await terminate({
+            acceptor,
+            socket: client,
+            error: new WebSocketRejection(1002, "WebSocket API not found"),
+          });
         },
       ),
     );
@@ -107,10 +105,10 @@ const visitApplication = async (
       return versioning === undefined || versioning.type !== VersioningType.URI
         ? undefined
         : {
+            // as NestJS's RoutePathFactory.getVersionPrefix(): `false` is no
+            // prefix at all, and only an absent one is the default "v"
             prefix:
-              versioning.prefix === undefined || versioning.prefix === false
-                ? "v"
-                : versioning.prefix,
+              versioning.prefix === false ? "" : (versioning.prefix ?? "v"),
             defaultVersion: versioning.defaultVersion,
           };
     })(),
@@ -282,16 +280,16 @@ const visitMethod = (props: {
       ].join("\n"),
     );
 
-  const versions: string[] = VersioningStrategy.merge(props.config.versioning)([
-    ...(props.controller.versions ?? []),
-    ...VersioningStrategy.cast(
+  const versions: string[] = VersioningStrategy.merge(props.config.versioning)({
+    controller: props.controller.versions,
+    method: VersioningStrategy.cast(
       Reflect.getMetadata(VERSION_METADATA, props.method.value),
     ),
-  ]);
+  });
   for (const v of versions)
     for (const cp of wrapPaths(props.controller.prefixes))
       for (const mp of wrapPaths(route.paths)) {
-        const parser: Path = new Path(
+        const parser: RoutePathMatcher = new RoutePathMatcher(
           "/" +
             [
               props.config.globalPrefix ?? "",
@@ -350,10 +348,12 @@ const visitMethod = (props: {
                 } else if (p.category === "param")
                   args.push(p.assert(input.params[p.field]!));
                 else if (p.category === "query") {
+                  // the query is all after the first "?", which it may hold too
+                  const index: number = input.acceptor.path.indexOf("?");
                   const query: any | Error = p.validate(
                     new URLSearchParams(
-                      input.acceptor.path.indexOf("?") !== -1
-                        ? input.acceptor.path.split("?")[1]
+                      index !== -1
+                        ? input.acceptor.path.substring(index + 1)
                         : "",
                     ),
                   );
@@ -361,13 +361,8 @@ const visitMethod = (props: {
                   args.push(query);
                 }
             } catch (exp) {
-              await input.acceptor.reject(
-                1003,
-                exp instanceof Error
-                  ? JSON.stringify({ ...exp })
-                  : "unknown error",
-              );
-              return;
+              // an invalid handshake: rejected before the handler runs
+              throw new WebSocketRejection(1003, exp);
             }
             await props.method.value.call(props.controller.instance, ...args);
           },
@@ -375,6 +370,109 @@ const visitMethod = (props: {
       }
 };
 
+/**
+ * A handshake rejected on purpose, with its close code: 1002 for no route, 1003
+ * for a header, param, or query failing its type.
+ */
+class WebSocketRejection {
+  public constructor(
+    public readonly code: number,
+    public readonly cause: unknown,
+  ) {}
+}
+
+/**
+ * Ends a WebSocket request that failed, so the client always learns it: a
+ * handshake not accepted yet is rejected, 1008 for an error of the route
+ * itself, and an accepted connection is closed with 1011. When tgrid refuses
+ * either, as it does while `accept()` is still running, the socket is closed
+ * directly. Nothing escapes, as the upgrade callback has no one to catch it.
+ */
+const terminate = async (props: {
+  acceptor: WebSocketAcceptor<any, any, any>;
+  socket: WebSocket;
+  error: unknown;
+}): Promise<void> => {
+  const reason: string = closeReason(
+    props.error instanceof WebSocketRejection ? props.error.cause : props.error,
+  );
+  const state: WebSocketAcceptor.State = props.acceptor.state;
+  if (
+    state === WebSocketAcceptor.State.REJECTING ||
+    state === WebSocketAcceptor.State.CLOSING ||
+    state === WebSocketAcceptor.State.CLOSED
+  )
+    return; // the route already ends the connection itself
+  const code: number =
+    state !== WebSocketAcceptor.State.NONE
+      ? 1011
+      : props.error instanceof WebSocketRejection
+        ? props.error.code
+        : 1008;
+  try {
+    if (state === WebSocketAcceptor.State.NONE)
+      return await props.acceptor.reject(code, reason);
+    else if (state === WebSocketAcceptor.State.OPEN)
+      return await props.acceptor.close(code, reason);
+  } catch {}
+  try {
+    props.socket.close(code, reason);
+  } catch {
+    props.socket.terminate();
+  }
+};
+
+/**
+ * The reason a close frame carries: the error's message, cut to the 123 bytes
+ * of UTF-8 a close reason may hold, never inside a character. A longer reason
+ * makes `ws` throw instead of closing, and the client waits forever.
+ *
+ * A validator's `BadRequestException` carries a generic message, so the
+ * property it names is preferred: typia's `reason` from an assertion, or the
+ * first of the `errors` from a validation.
+ */
+const closeReason = (error: unknown): string => {
+  const message: string =
+    invalidProperty(error) ??
+    (error instanceof Error
+      ? error.message
+      : typeof error === "string"
+        ? error
+        : "unknown error");
+  const encoded: Buffer = Buffer.from(message, "utf8");
+  if (encoded.length <= MAX_CLOSE_REASON_BYTES) return message;
+  let end: number = MAX_CLOSE_REASON_BYTES;
+  // back off continuation bytes (10xxxxxx) to a character boundary
+  while (end > 0 && (encoded[end]! & 0xc0) === 0x80) --end;
+  return encoded.subarray(0, end).toString("utf8");
+};
+
+const invalidProperty = (error: unknown): string | null => {
+  if (!(error instanceof HttpException)) return null;
+  const response: unknown = error.getResponse();
+  if (typeof response !== "object" || response === null) return null;
+  const { reason, errors } = response as {
+    reason?: unknown;
+    errors?: unknown;
+  };
+  if (typeof reason === "string") return reason;
+  if (Array.isArray(errors) && errors.length !== 0) {
+    const first: { path?: unknown; expected?: unknown } = errors[0];
+    if (typeof first?.path === "string" && typeof first.expected === "string")
+      return [
+        `invalid type on ${first.path}, expect to be ${first.expected}`,
+        errors.length > 1 ? ` (and ${errors.length - 1} more)` : "",
+      ].join("");
+  }
+  return null;
+};
+
+/**
+ * RFC 6455 §5.5: a control frame's payload is at most 125 bytes, 2 of them the
+ * code.
+ */
+const MAX_CLOSE_REASON_BYTES: number = 123;
+
 const wrapPaths = (value: string[]) => (value.length === 0 ? [""] : value);
 const getOwnPropertyNames = (prototype: any): string[] => {
   const result: Set<string> = new Set();
@@ -402,7 +500,7 @@ interface IController {
   modulePrefix: string;
 }
 interface IOperator {
-  parser: Path;
+  parser: RoutePathMatcher;
   handler: (props: {
     params: Record<string, string>;
     acceptor: WebSocketAcceptor<any, any, any>;