@faapi/faapi 0.0.0-canary.0 → 0.0.0-canary.0f443f9

package/dist/cli/index.js

@@ -613,16 +613,17 @@ var init_normalizePatterns = __esm({
 // src/cli/parseArgs.ts
 function parseArgs(argv) {
   const cli = cac("faapi");
-  cli.option("--port <port>", "Server port (env: PORT)").option("--app-dir <dir>", "App directory", { default: "app" }).option("--cors", "Enable CORS (default in dev mode)").option("--no-cors", "Disable CORS").option("--static <dir>", "Static files directory", { default: void 0 }).option("--no-static", "Disable static file serving").option("--types <path>", "Output path for generated types file").option("--config <path>", "Path to config file (faapi.config.ts)");
+  cli.option("--port <port>", "Server port (env: PORT)").option("--app-dir <dir>", "App directory (src by default)", { default: "src" }).option("--cors", "Enable CORS (default in dev mode)").option("--no-cors", "Disable CORS").option("--static <dir>", "Static files directory", { default: void 0 }).option("--no-static", "Disable static file serving").option("--types <path>", "Output path for generated types file").option("--config <path>", "Path to config file (faapi.config.ts)");
   const { args, options } = cli.parse(["", "", ...argv]);
   const rawPatterns = args.map(String).filter((a) => a !== "dev");
   const patterns = normalizePatterns(rawPatterns);
   const port = options.port ? Number(options.port) : Number(process.env.PORT) || 3e3;
-  const appDir = String(options.appDir ?? "app");
+  const appDir = String(options.appDir ?? "src");
   const cors2 = options.cors !== false;
   const staticDir = options.static === false ? void 0 : options.static;
+  const defaultPattern = appDir === "." ? "api/**/*.ts" : `${appDir}/api/**/*.ts`;
   return {
-    patterns: patterns.length > 0 ? patterns : [`${appDir}/api/**/*.ts`],
+    patterns: patterns.length > 0 ? patterns : [defaultPattern],
     port,
     appDir,
     cors: cors2,
@@ -695,7 +696,7 @@ function isCatchAllSegment(segment) {
 function isRouteGroup(segment) {
   return /^\(.+\)$/.test(segment);
 }
-function filePathToUrlPath(filePath, appDir = "app") {
+function filePathToUrlPath(filePath, appDir = ".") {
   const withoutPrefix = filePath.startsWith(appDir + "/") ? filePath.slice(appDir.length + 1) : filePath;
   const lastSlashIndex = withoutPrefix.lastIndexOf("/");
   const dirPath = lastSlashIndex === -1 ? "" : withoutPrefix.slice(0, lastSlashIndex);
@@ -850,7 +851,7 @@ async function hasWsExport(absPath) {
   }
 }
 async function scanRoutes(rootDir, patterns, appDir) {
-  const dir = appDir ?? "app";
+  const dir = appDir ?? ".";
   const files = await fg(patterns, {
     cwd: rootDir,
     onlyFiles: true,
@@ -1232,7 +1233,7 @@ function formatSetCookie(name, value, options) {
   if (options?.sameSite) cookie += `; SameSite=${options.sameSite}`;
   return cookie;
 }
-function createContext(request, params, config = {}) {
+function createContext(request, params, config = {}, ip = "") {
   const url = new URL(request.url);
   const meta = { headers: {}, setCookies: [] };
   const parsedCookies = parseCookies(request.headers.get("cookie") ?? "");
@@ -1247,6 +1248,7 @@ function createContext(request, params, config = {}) {
     headers: request.headers,
     method: request.method,
     path: url.pathname,
+    ip,
     cookies: cookiesObj,
     config,
     meta,
@@ -1396,6 +1398,65 @@ var init_inputType = __esm({
   }
 });
 
+// src/errors/FaapiError.ts
+var FaapiError;
+var init_FaapiError = __esm({
+  "src/errors/FaapiError.ts"() {
+    "use strict";
+    FaapiError = class extends Error {
+      constructor(code, message, statusCode) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.name = "FaapiError";
+      }
+      code;
+      statusCode;
+    };
+  }
+});
+
+// src/errors/httpErrors.ts
+function deriveStatusCode(issues) {
+  const has400 = issues.some((i) => i.code === "INVALID_FORMAT" || i.code === "MISSING_FIELD");
+  return has400 ? 400 : 422;
+}
+var ValidationError, RouteNotFoundError, MethodNotAllowedError, InternalError;
+var init_httpErrors = __esm({
+  "src/errors/httpErrors.ts"() {
+    "use strict";
+    init_FaapiError();
+    ValidationError = class extends FaapiError {
+      constructor(message, issues) {
+        super("VALIDATION_ERROR", message, deriveStatusCode(issues));
+        this.issues = issues;
+        this.name = "ValidationError";
+      }
+      issues;
+    };
+    RouteNotFoundError = class extends FaapiError {
+      constructor(path10) {
+        super("ROUTE_NOT_FOUND", `Route not found: ${path10}`, 404);
+        this.name = "RouteNotFoundError";
+      }
+    };
+    MethodNotAllowedError = class extends FaapiError {
+      constructor(method, path10, allowedMethods) {
+        super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path10}`, 405);
+        this.allowedMethods = allowedMethods;
+        this.name = "MethodNotAllowedError";
+      }
+      allowedMethods;
+    };
+    InternalError = class extends FaapiError {
+      constructor(message) {
+        super("INTERNAL_ERROR", message, 500);
+        this.name = "InternalError";
+      }
+    };
+  }
+});
+
 // src/runtime/resolveInput.ts
 async function resolveInput(method, request) {
   const inputType = getInputTypeForMethod(method);
@@ -1404,12 +1465,33 @@ async function resolveInput(method, request) {
     if (contentType.includes("multipart/form-data")) {
       return parseMultipart(request);
     }
+    if (contentType.includes("application/x-www-form-urlencoded")) {
+      const text2 = await request.text();
+      if (text2.trim() === "") return null;
+      const params = new URLSearchParams(text2);
+      const obj = {};
+      for (const [key, value] of params) {
+        obj[key] = value;
+      }
+      return obj;
+    }
     const text = await request.text();
+    if (text.trim() === "") {
+      return null;
+    }
     const result = parseJsonBody(text);
-    if (result.success) {
-      return result.data;
+    if (!result.success) {
+      throw new ValidationError("\u8BF7\u6C42\u4F53\u4E0D\u662F\u5408\u6CD5\u7684 JSON", [
+        {
+          path: "body",
+          code: "INVALID_FORMAT",
+          expected: "JSON",
+          received: "text",
+          message: "\u8BF7\u6C42\u4F53\u4E0D\u662F\u5408\u6CD5\u7684 JSON"
+        }
+      ]);
     }
-    return null;
+    return result.data;
   }
   const url = new URL(request.url);
   return queryToObject(url.searchParams);
@@ -1421,6 +1503,7 @@ var init_resolveInput = __esm({
     init_parseJsonBody();
     init_parseMultipart();
     init_inputType();
+    init_httpErrors();
   }
 });
 
@@ -1623,6 +1706,7 @@ var init_resolveInjection = __esm({
       ctx: "context",
       // 别名
       cookies: "cookies",
+      ip: "ip",
       files: "files",
       fields: "fields"
     };
@@ -1642,6 +1726,8 @@ function getBuiltinInjectionValue(type, ctx, body) {
       return ctx;
     case "cookies":
       return ctx.cookies;
+    case "ip":
+      return ctx.ip;
     case "body":
       return body;
     case "files":
@@ -1805,61 +1891,6 @@ var init_sendNodeResponse = __esm({
   }
 });
 
-// src/errors/FaapiError.ts
-var FaapiError;
-var init_FaapiError = __esm({
-  "src/errors/FaapiError.ts"() {
-    "use strict";
-    FaapiError = class extends Error {
-      constructor(code, message, statusCode) {
-        super(message);
-        this.code = code;
-        this.statusCode = statusCode;
-        this.name = "FaapiError";
-      }
-      code;
-      statusCode;
-    };
-  }
-});
-
-// src/errors/httpErrors.ts
-var ValidationError, RouteNotFoundError, MethodNotAllowedError, InternalError;
-var init_httpErrors = __esm({
-  "src/errors/httpErrors.ts"() {
-    "use strict";
-    init_FaapiError();
-    ValidationError = class extends FaapiError {
-      constructor(message, issues) {
-        super("VALIDATION_ERROR", message, 400);
-        this.issues = issues;
-        this.name = "ValidationError";
-      }
-      issues;
-    };
-    RouteNotFoundError = class extends FaapiError {
-      constructor(path10) {
-        super("ROUTE_NOT_FOUND", `Route not found: ${path10}`, 404);
-        this.name = "RouteNotFoundError";
-      }
-    };
-    MethodNotAllowedError = class extends FaapiError {
-      constructor(method, path10, allowedMethods) {
-        super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path10}`, 405);
-        this.allowedMethods = allowedMethods;
-        this.name = "MethodNotAllowedError";
-      }
-      allowedMethods;
-    };
-    InternalError = class extends FaapiError {
-      constructor(message) {
-        super("INTERNAL_ERROR", message, 500);
-        this.name = "InternalError";
-      }
-    };
-  }
-});
-
 // src/validator/schemaRegistry.ts
 var SchemaRegistry, schemaRegistry;
 var init_schemaRegistry = __esm({
@@ -1971,6 +2002,20 @@ function coerceValue(value, type, path10, issues) {
         return value.map((item, i) => coerceValue(item, type.element, `${path10}[${i}]`, issues));
       }
       return value;
+    case "tuple": {
+      if (!Array.isArray(value)) return value;
+      const restElement = type.elements.find((e) => e.rest);
+      return value.map((item, i) => {
+        const elem = type.elements[i];
+        if (elem && !elem.rest) {
+          return coerceValue(item, elem.type, `${path10}[${i}]`, issues);
+        }
+        if (restElement) {
+          return coerceValue(item, restElement.type, `${path10}[${i}]`, issues);
+        }
+        return item;
+      });
+    }
     case "union":
       for (const member of type.members) {
         const tempIssues = [];
@@ -1980,6 +2025,12 @@ function coerceValue(value, type, path10, issues) {
         }
       }
       return value;
+    case "literal":
+      if (typeof type.value === "number" && typeof value === "string" && value.trim() !== "") {
+        const num = Number(value);
+        if (!Number.isNaN(num)) return num;
+      }
+      return value;
     case "object":
       if (typeof value === "object" && value !== null && !Array.isArray(value)) {
         const obj = value;
@@ -2005,6 +2056,9 @@ function coerceStringToNumber(value, path10, issues) {
   if (value.trim() === "") {
     issues.push({
       path: path10,
+      code: "COERCE_FAILED",
+      expected: "number",
+      received: "string",
       message: `\u5B57\u6BB5 "${path10}" \u7C7B\u578B\u8F6C\u6362\u5931\u8D25\uFF1A\u65E0\u6CD5\u5C06 "${value}" \u8F6C\u4E3A number`
     });
     return value;
@@ -2013,6 +2067,9 @@ function coerceStringToNumber(value, path10, issues) {
   if (Number.isNaN(num)) {
     issues.push({
       path: path10,
+      code: "COERCE_FAILED",
+      expected: "number",
+      received: "string",
       message: `\u5B57\u6BB5 "${path10}" \u7C7B\u578B\u8F6C\u6362\u5931\u8D25\uFF1A\u65E0\u6CD5\u5C06 "${value}" \u8F6C\u4E3A number`
     });
     return value;
@@ -2028,6 +2085,9 @@ function coerceStringToBoolean(value, path10, issues) {
   }
   issues.push({
     path: path10,
+    code: "COERCE_FAILED",
+    expected: "boolean",
+    received: "string",
     message: `\u5B57\u6BB5 "${path10}" \u7C7B\u578B\u8F6C\u6362\u5931\u8D25\uFF1A\u65E0\u6CD5\u5C06 "${value}" \u8F6C\u4E3A boolean`
   });
   return value;
@@ -2074,6 +2134,28 @@ var init_validateInput = __esm({
   }
 });
 
+// src/utils/getClientIp.ts
+function getClientIp(req) {
+  const xff = req.headers["x-forwarded-for"];
+  if (typeof xff === "string" && xff.length > 0) {
+    const first = xff.split(",")[0]?.trim();
+    if (first) return first;
+  }
+  const remote = req.socket.remoteAddress;
+  if (remote) {
+    if (remote.startsWith("::ffff:")) {
+      return remote.slice(7);
+    }
+    return remote;
+  }
+  return "";
+}
+var init_getClientIp = __esm({
+  "src/utils/getClientIp.ts"() {
+    "use strict";
+  }
+});
+
 // src/middleware/cors.ts
 function cors(options = {}) {
   const {
@@ -2275,7 +2357,12 @@ function resolveTypeNode(typeNode, checker, visited = /* @__PURE__ */ new Set())
     case ts2.SyntaxKind.BooleanKeyword:
       return { kind: "boolean" };
     case ts2.SyntaxKind.BigIntKeyword:
-      return { kind: "bigint" };
+      throw new SchemaExtractionError(
+        typeNode.getText(),
+        "bigint \u65E0\u6CD5\u901A\u8FC7 HTTP/JSON \u4F20\u8F93,\u8BF7\u6539\u7528 string \u6216 number"
+      );
+    case ts2.SyntaxKind.SymbolKeyword:
+      throw new SchemaExtractionError(typeNode.getText(), "symbol \u65E0\u6CD5\u901A\u8FC7 HTTP/JSON \u4F20\u8F93");
     case ts2.SyntaxKind.NullKeyword:
       return { kind: "null" };
     case ts2.SyntaxKind.UndefinedKeyword:
@@ -2320,8 +2407,35 @@ function resolveTypeNode(typeNode, checker, visited = /* @__PURE__ */ new Set())
     };
   }
   if (ts2.isTupleTypeNode(typeNode)) {
-    const elements = typeNode.elements.map((e) => resolveTypeNode(e, checker, visited));
-    return { kind: "array", element: { kind: "union", members: elements } };
+    const elements = typeNode.elements.map((e) => {
+      if (ts2.isRestTypeNode(e)) {
+        const inner = resolveTypeNode(e.type, checker, visited);
+        if (inner.kind === "array") {
+          return { type: inner.element, optional: false, rest: true };
+        }
+        return { type: inner, optional: false, rest: true };
+      }
+      if (ts2.isNamedTupleMember(e)) {
+        return {
+          type: resolveTypeNode(e.type, checker, visited),
+          optional: !!e.questionToken,
+          rest: false
+        };
+      }
+      if (ts2.isOptionalTypeNode(e)) {
+        return {
+          type: resolveTypeNode(e.type, checker, visited),
+          optional: true,
+          rest: false
+        };
+      }
+      return {
+        type: resolveTypeNode(e, checker, visited),
+        optional: false,
+        rest: false
+      };
+    });
+    return { kind: "tuple", elements };
   }
   if (ts2.isUnionTypeNode(typeNode)) {
     const members = typeNode.types.map((t) => resolveTypeNode(t, checker, visited));
@@ -2492,6 +2606,9 @@ function resolveTypeReference(typeNode, checker, visited = /* @__PURE__ */ new S
       "Promise \u8FD0\u884C\u65F6\u65E0\u6CD5\u6821\u9A8C\uFF0C\u8BF7\u52FF\u5728 query/body \u7C7B\u578B\u4E2D\u4F7F\u7528"
     );
   }
+  if (typeName === "Function") {
+    throw new SchemaExtractionError(typeNode.getText(), "Function \u65E0\u6CD5\u901A\u8FC7 HTTP/JSON \u4F20\u8F93");
+  }
   if (visited.has(typeName)) {
     return { kind: "ref", name: typeName };
   }
@@ -2507,11 +2624,38 @@ function resolveTypeReference(typeNode, checker, visited = /* @__PURE__ */ new S
         if (ts2.isTypeAliasDeclaration(declaration)) {
           return resolveTypeNode(declaration.type, checker, visited);
         }
+        if (ts2.isEnumDeclaration(declaration)) {
+          return resolveEnumDeclaration(declaration);
+        }
       }
     }
   }
   throw new SchemaExtractionError(typeNode.getText(), `\u65E0\u6CD5\u89E3\u6790\u7684\u5F15\u7528\u7C7B\u578B "${typeName}"`);
 }
+function resolveEnumDeclaration(node) {
+  const members = [];
+  let nextNumericValue = 0;
+  for (const member of node.members) {
+    if (member.initializer) {
+      if (ts2.isStringLiteral(member.initializer)) {
+        members.push({ kind: "literal", value: member.initializer.text });
+      } else if (ts2.isNumericLiteral(member.initializer)) {
+        const num = Number(member.initializer.text);
+        members.push({ kind: "literal", value: num });
+        nextNumericValue = num + 1;
+      } else {
+        throw new SchemaExtractionError(
+          node.name.text,
+          `enum \u6210\u5458 "${member.name.getText()}" \u7684\u521D\u59CB\u5316\u503C\u7C7B\u578B\u4E0D\u652F\u6301,\u4EC5\u652F\u6301 string/number \u5B57\u9762\u91CF`
+        );
+      }
+    } else {
+      members.push({ kind: "literal", value: nextNumericValue });
+      nextNumericValue++;
+    }
+  }
+  return { kind: "union", members };
+}
 function resolveInterfaceDeclaration(node, checker, visited = /* @__PURE__ */ new Set()) {
   const properties = [];
   const propMap = /* @__PURE__ */ new Map();
@@ -2563,6 +2707,34 @@ var init_resolveTypeNode = __esm({
 });
 
 // src/ast/generateValidatorCode.ts
+function runtimeTypeToExpected(type) {
+  switch (type.kind) {
+    case "string":
+    case "number":
+    case "boolean":
+    case "null":
+    case "undefined":
+    case "bigint":
+    case "date":
+    case "any":
+    case "unknown":
+      return type.kind;
+    case "literal":
+      return typeof type.value === "string" ? `'${type.value}'` : String(type.value);
+    case "array":
+      return `${runtimeTypeToExpected(type.element)}[]`;
+    case "tuple":
+      return `[${type.elements.map((e) => (e.rest ? "..." : "") + runtimeTypeToExpected(e.type) + (e.optional ? "?" : "")).join(", ")}]`;
+    case "object":
+      return "object";
+    case "union":
+      return type.members.map(runtimeTypeToExpected).join(" | ");
+    case "record":
+      return `Record<${runtimeTypeToExpected(type.key)}, ${runtimeTypeToExpected(type.value)}>`;
+    case "ref":
+      return type.name;
+  }
+}
 function generateValidatorSource(typeInfo, resolveType) {
   const ctx = new CodeGenContext(resolveType);
   collectNamedTypes(typeInfo.runtimeType, typeInfo.name, ctx);
@@ -2578,7 +2750,7 @@ function generateValidatorSource(typeInfo, resolveType) {
     const body = generateObjectValidation(type, "value", "issues", ctx, "path");
     return `function validate_${name}(value, path, issues) {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-    issues.push({ path, message: '\u671F\u671B\u5BF9\u8C61' });
+    issues.push({ path, code: 'TYPE_MISMATCH', expected: 'object', received: typeof value, message: '\u671F\u671B\u5BF9\u8C61' });
     return;
   }
   if (!validate_${name}.__visited) validate_${name}.__visited = new WeakSet();
@@ -2613,6 +2785,11 @@ function collectNamedTypesFromType(type, ctx) {
     case "array":
       collectNamedTypesFromType(type.element, ctx);
       break;
+    case "tuple":
+      for (const elem of type.elements) {
+        collectNamedTypesFromType(elem.type, ctx);
+      }
+      break;
     case "union":
       for (const member of type.members) {
         collectNamedTypesFromType(member, ctx);
@@ -2649,7 +2826,7 @@ function generateObjectValidation(type, varName, issuesVar, ctx, pathExpr) {
     const hasCheck = `'${prop.name}' in ${varName}`;
     if (!prop.optional) {
       lines.push(
-        `if (!${hasCheck}) ${issuesVar}.push({ path: ${propPath}, message: '\u7F3A\u5C11\u5FC5\u586B\u5B57\u6BB5 "${prop.name}"' });`
+        `if (!${hasCheck}) ${issuesVar}.push({ path: ${propPath}, code: 'MISSING_FIELD', expected: '${prop.name}', received: 'undefined', message: '\u7F3A\u5C11\u5FC5\u586B\u5B57\u6BB5 "${prop.name}"' });`
       );
       lines.push(`else {`);
     } else {
@@ -2668,21 +2845,23 @@ function generateValueValidation(type, varName, issuesVar, ctx, pathExpr) {
       return "";
     // 不校验
     case "string":
-      return `if (typeof ${varName} !== 'string') ${issuesVar}.push({ path: ${path10}, message: '\u671F\u671B string\uFF0C\u5B9E\u9645 ' + typeof ${varName} });`;
+      return `if (typeof ${varName} !== 'string') ${issuesVar}.push({ path: ${path10}, code: 'TYPE_MISMATCH', expected: 'string', received: typeof ${varName}, message: '\u671F\u671B string\uFF0C\u5B9E\u9645 ' + typeof ${varName} });`;
     case "number":
-      return `if (typeof ${varName} !== 'number' || Number.isNaN(${varName})) ${issuesVar}.push({ path: ${path10}, message: '\u671F\u671B number\uFF0C\u5B9E\u9645 ' + typeof ${varName} });`;
+      return `if (typeof ${varName} !== 'number' || Number.isNaN(${varName})) ${issuesVar}.push({ path: ${path10}, code: 'TYPE_MISMATCH', expected: 'number', received: typeof ${varName}, message: '\u671F\u671B number\uFF0C\u5B9E\u9645 ' + typeof ${varName} });`;
     case "boolean":
-      return `if (typeof ${varName} !== 'boolean') ${issuesVar}.push({ path: ${path10}, message: '\u671F\u671B boolean\uFF0C\u5B9E\u9645 ' + typeof ${varName} });`;
+      return `if (typeof ${varName} !== 'boolean') ${issuesVar}.push({ path: ${path10}, code: 'TYPE_MISMATCH', expected: 'boolean', received: typeof ${varName}, message: '\u671F\u671B boolean\uFF0C\u5B9E\u9645 ' + typeof ${varName} });`;
     case "bigint":
-      return `if (typeof ${varName} !== 'bigint') ${issuesVar}.push({ path: ${path10}, message: '\u671F\u671B bigint\uFF0C\u5B9E\u9645 ' + typeof ${varName} });`;
+      return `if (typeof ${varName} !== 'bigint') ${issuesVar}.push({ path: ${path10}, code: 'TYPE_MISMATCH', expected: 'bigint', received: typeof ${varName}, message: '\u671F\u671B bigint\uFF0C\u5B9E\u9645 ' + typeof ${varName} });`;
     case "null":
-      return `if (${varName} !== null) ${issuesVar}.push({ path: ${path10}, message: '\u671F\u671B null\uFF0C\u5B9E\u9645 ' + typeof ${varName} });`;
+      return `if (${varName} !== null) ${issuesVar}.push({ path: ${path10}, code: 'TYPE_MISMATCH', expected: 'null', received: typeof ${varName}, message: '\u671F\u671B null\uFF0C\u5B9E\u9645 ' + typeof ${varName} });`;
     case "undefined":
-      return `if (${varName} !== undefined) ${issuesVar}.push({ path: ${path10}, message: '\u671F\u671B undefined' });`;
+      return `if (${varName} !== undefined) ${issuesVar}.push({ path: ${path10}, code: 'TYPE_MISMATCH', expected: 'undefined', received: typeof ${varName}, message: '\u671F\u671B undefined' });`;
     case "literal":
-      return `if (${varName} !== ${JSON.stringify(type.value)}) ${issuesVar}.push({ path: ${path10}, message: '\u671F\u671B\u5B57\u9762\u91CF ${JSON.stringify(type.value)}\uFF0C\u5B9E\u9645 ' + JSON.stringify(${varName}) });`;
+      return `if (${varName} !== ${JSON.stringify(type.value)}) ${issuesVar}.push({ path: ${path10}, code: 'INVALID_VALUE', expected: ${JSON.stringify(JSON.stringify(type.value))}, received: JSON.stringify(${varName}), message: '\u671F\u671B\u5B57\u9762\u91CF ${JSON.stringify(type.value)}\uFF0C\u5B9E\u9645 ' + JSON.stringify(${varName}) });`;
     case "date":
-      return `if (!(${varName} instanceof Date) || Number.isNaN(${varName}.getTime())) ${issuesVar}.push({ path: ${path10}, message: '\u671F\u671B Date \u5B9E\u4F8B' });`;
+      return `if (${varName} instanceof Date) { /* Date \u5B9E\u4F8B,\u901A\u8FC7 */ }
+else if (typeof ${varName} !== 'string') ${issuesVar}.push({ path: ${path10}, code: 'TYPE_MISMATCH', expected: 'Date | ISO 8601 string', received: typeof ${varName}, message: '\u671F\u671B Date \u6216 ISO 8601 \u5B57\u7B26\u4E32\uFF0C\u5B9E\u9645 ' + typeof ${varName} });
+else if (!/^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,3})?(Z|[+-]\\d{2}:?\\d{2})?)?$/.test(${varName}) || isNaN(new Date(${varName}).getTime())) ${issuesVar}.push({ path: ${path10}, code: 'INVALID_FORMAT', expected: 'ISO 8601', received: String(${varName}), message: '\u4E0D\u662F\u5408\u6CD5\u7684 ISO 8601 \u65E5\u671F\u5B57\u7B26\u4E32: ' + ${varName} });`;
     case "array": {
       const id = ctx.nextVarId();
       const itemVar = `item${id}`;
@@ -2695,21 +2874,71 @@ function generateValueValidation(type, varName, issuesVar, ctx, pathExpr) {
         ctx,
         elemPath
       );
-      return `if (!Array.isArray(${varName})) ${issuesVar}.push({ path: ${path10}, message: '\u671F\u671B\u6570\u7EC4\uFF0C\u5B9E\u9645 ' + typeof ${varName} });
+      return `if (!Array.isArray(${varName})) ${issuesVar}.push({ path: ${path10}, code: 'TYPE_MISMATCH', expected: 'array', received: typeof ${varName}, message: '\u671F\u671B\u6570\u7EC4\uFF0C\u5B9E\u9645 ' + typeof ${varName} });
 else for (let ${indexVar} = 0; ${indexVar} < ${varName}.length; ${indexVar}++) { const ${itemVar} = ${varName}[${indexVar}]; ${elemValidation} }`;
     }
+    case "tuple": {
+      const minRequired = type.elements.filter((e) => !e.optional && !e.rest).length;
+      const fixedCount = type.elements.filter((e) => !e.rest).length;
+      const restElement = type.elements.find((e) => e.rest);
+      const id = ctx.nextVarId();
+      const itemVar = `t${id}`;
+      const indexVar = `ti${id}`;
+      const lines = [];
+      lines.push(
+        `if (!Array.isArray(${varName})) ${issuesVar}.push({ path: ${path10}, code: 'TYPE_MISMATCH', expected: 'tuple', received: typeof ${varName}, message: '\u671F\u671B\u5143\u7EC4\uFF08\u6570\u7EC4\uFF09\uFF0C\u5B9E\u9645 ' + typeof ${varName} });`
+      );
+      lines.push(`else {`);
+      lines.push(
+        `if (${varName}.length < ${minRequired}) ${issuesVar}.push({ path: ${path10}, code: 'MISSING_FIELD', expected: 'tuple length >= ${minRequired}', received: 'length ' + ${varName}.length, message: '\u5143\u7EC4\u957F\u5EA6\u4E0D\u8DB3\uFF0C\u671F\u671B\u81F3\u5C11 ${minRequired}\uFF0C\u5B9E\u9645 ' + ${varName}.length });`
+      );
+      if (!restElement) {
+        lines.push(
+          `if (${varName}.length > ${fixedCount}) ${issuesVar}.push({ path: ${path10}, code: 'INVALID_VALUE', expected: 'tuple length = ${fixedCount}', received: 'length ' + ${varName}.length, message: '\u5143\u7EC4\u957F\u5EA6\u8D85\u51FA\uFF0C\u671F\u671B ${fixedCount}\uFF0C\u5B9E\u9645 ' + ${varName}.length });`
+        );
+      }
+      for (let i = 0; i < type.elements.length; i++) {
+        const elem = type.elements[i];
+        if (elem.rest) continue;
+        const elemPath = `${path10} + '[' + ${i} + ']'`;
+        const elemAccess = `${varName}[${i}]`;
+        if (elem.optional) {
+          lines.push(`if (${i} < ${varName}.length && ${elemAccess} !== undefined) {`);
+        } else {
+          lines.push(`if (${i} < ${varName}.length) {`);
+        }
+        lines.push(`  ${generateValueValidation(elem.type, elemAccess, issuesVar, ctx, elemPath)}`);
+        lines.push(`}`);
+      }
+      if (restElement) {
+        const restPath = `${path10} + '[' + ${indexVar} + ']'`;
+        const restValidation = generateValueValidation(
+          restElement.type,
+          itemVar,
+          issuesVar,
+          ctx,
+          restPath
+        );
+        lines.push(
+          `for (let ${indexVar} = ${fixedCount}; ${indexVar} < ${varName}.length; ${indexVar}++) { const ${itemVar} = ${varName}[${indexVar}]; ${restValidation} }`
+        );
+      }
+      lines.push(`}`);
+      return lines.join("\n");
+    }
     case "union": {
       const tempVar = `tempIssues_${Math.random().toString(36).slice(2, 8)}`;
       const memberChecks = type.members.map((member) => {
         const check = generateValueValidation(member, varName, tempVar, ctx, path10);
         return `(() => { const ${tempVar} = []; ${check}; return ${tempVar}.length === 0; })()`;
       });
-      return `if (!(${memberChecks.join(" || ")})) ${issuesVar}.push({ path: ${path10}, message: '\u503C ' + JSON.stringify(${varName}) + ' \u4E0D\u5339\u914D\u8054\u5408\u7C7B\u578B' });`;
+      const expected = runtimeTypeToExpected(type);
+      return `if (!(${memberChecks.join(" || ")})) ${issuesVar}.push({ path: ${path10}, code: 'TYPE_MISMATCH', expected: ${JSON.stringify(expected)}, received: typeof ${varName}, message: '\u503C ' + JSON.stringify(${varName}) + ' \u4E0D\u5339\u914D\u8054\u5408\u7C7B\u578B ${expected.replace(/'/g, "\\'")}' });`;
     }
     case "record": {
       const valuePath = `${path10} + '.' + key`;
       const valueValidation = generateValueValidation(type.value, "val", issuesVar, ctx, valuePath);
-      return `if (typeof ${varName} !== 'object' || ${varName} === null || Array.isArray(${varName})) ${issuesVar}.push({ path: ${path10}, message: '\u671F\u671B\u5BF9\u8C61\uFF0C\u5B9E\u9645 ' + typeof ${varName} });
+      return `if (typeof ${varName} !== 'object' || ${varName} === null || Array.isArray(${varName})) ${issuesVar}.push({ path: ${path10}, code: 'TYPE_MISMATCH', expected: 'object', received: typeof ${varName}, message: '\u671F\u671B\u5BF9\u8C61\uFF0C\u5B9E\u9645 ' + typeof ${varName} });
 else for (const [key, val] of Object.entries(${varName})) { ${valueValidation} }`;
     }
     case "object": {
@@ -2723,7 +2952,7 @@ else for (const [key, val] of Object.entries(${varName})) { ${valueValidation} }
 function generateInlineObjectValidation(type, varName, issuesVar, ctx, pathExpr) {
   const lines = [];
   lines.push(
-    `if (typeof ${varName} !== 'object' || ${varName} === null || Array.isArray(${varName})) ${issuesVar}.push({ path: ${pathExpr}, message: '\u671F\u671B\u5BF9\u8C61\uFF0C\u5B9E\u9645 ' + typeof ${varName} });`
+    `if (typeof ${varName} !== 'object' || ${varName} === null || Array.isArray(${varName})) ${issuesVar}.push({ path: ${pathExpr}, code: 'TYPE_MISMATCH', expected: 'object', received: typeof ${varName}, message: '\u671F\u671B\u5BF9\u8C61\uFF0C\u5B9E\u9645 ' + typeof ${varName} });`
   );
   lines.push("else {");
   for (const prop of type.properties) {
@@ -2732,7 +2961,7 @@ function generateInlineObjectValidation(type, varName, issuesVar, ctx, pathExpr)
     const hasCheck = `'${prop.name}' in ${varName}`;
     if (!prop.optional) {
       lines.push(
-        `  if (!${hasCheck}) ${issuesVar}.push({ path: ${propPath}, message: '\u7F3A\u5C11\u5FC5\u586B\u5B57\u6BB5 "${prop.name}"' });`
+        `  if (!${hasCheck}) ${issuesVar}.push({ path: ${propPath}, code: 'MISSING_FIELD', expected: '${prop.name}', received: 'undefined', message: '\u7F3A\u5C11\u5FC5\u586B\u5B57\u6BB5 "${prop.name}"' });`
       );
       lines.push(`  else {`);
     } else {
@@ -3138,21 +3367,24 @@ function nodeHttpToWebHeaders(req) {
   return headers;
 }
 function buildErrorResponse(err, ctx, errorFormat) {
-  try {
-    return errorFormat ? errorFormat(err, ctx) : formatErrorResponse(err);
-  } catch {
+  if (errorFormat) {
     try {
-      return formatErrorResponse(err);
+      const res = errorFormat(err, ctx);
+      if (res) return res;
     } catch {
-      return new Response(
-        JSON.stringify({ error: { code: "INTERNAL_ERROR", message: "Internal Server Error" } }),
-        {
-          status: 500,
-          headers: { "Content-Type": "application/json" }
-        }
-      );
     }
   }
+  try {
+    return formatErrorResponse(err);
+  } catch {
+    return new Response(
+      JSON.stringify({ error: { code: "INTERNAL_ERROR", message: "Internal Server Error" } }),
+      {
+        status: 500,
+        headers: { "Content-Type": "application/json" }
+      }
+    );
+  }
 }
 var init_serverUtils = __esm({
   "src/server/serverUtils.ts"() {
@@ -3261,7 +3493,7 @@ function attachWebSocket(options) {
     const host = req.headers.host ?? "localhost";
     const url = `http://${host}${req.url ?? "/"}`;
     const request = new Request(url, { method: "GET", headers });
-    const ctx = createContext(request, params, config);
+    const ctx = createContext(request, params, config, getClientIp(req));
     const meta = ctx.meta;
     let upgraded = false;
     const finalHandler = async () => {
@@ -3318,6 +3550,7 @@ var init_handleWsUpgrade = __esm({
     init_createContext();
     init_invokeHandler();
     init_importWithCacheBust();
+    init_getClientIp();
     init_serverUtils();
     init_wsHandler();
   }
@@ -3380,12 +3613,7 @@ function findAllowedMethods(routes, path10) {
       continue;
     }
     if (route.isDynamic) {
-      const params = matchDynamicPath(
-        route.urlPath,
-        path10,
-        route.paramNames,
-        route.isCatchAll
-      );
+      const params = matchDynamicPath(route.urlPath, path10, route.paramNames, route.isCatchAll);
       if (params !== null) {
         methods.add(route.method);
       }
@@ -3446,7 +3674,7 @@ async function handleRequest(routes, rootDir, req, res, corsMiddleware, staticDi
   const request = toWebRequest(req);
   const method = request.method.toUpperCase();
   const urlPath = new URL(request.url).pathname;
-  const ctx = createContext(request, {}, config);
+  const ctx = createContext(request, {}, config, getClientIp(req));
   const meta = ctx.meta;
   const routePipeline = async () => {
     const match = matchRoute(routes, method, urlPath);
@@ -3531,6 +3759,7 @@ var init_createServer = __esm({
     init_httpErrors();
     init_validateInput();
     init_inputType();
+    init_getClientIp();
     init_cors();
     init_serveStatic();
     init_schemaRegistry();
@@ -3555,7 +3784,8 @@ function startServer(options) {
     config,
     wsRoutes,
     middlewares,
-    injectors
+    injectors,
+    beforeListen
   } = options;
   const server = createServer({
     routes,
@@ -3570,26 +3800,57 @@ function startServer(options) {
     middlewares,
     injectors
   });
-  return new Promise((resolve3) => {
-    server.listen(port, () => {
-      const address = server.address();
-      const actualPort = typeof address === "object" && address !== null ? address.port : port;
-      console.log("faapi dev server started");
-      console.log(`- Local: http://localhost:${actualPort}`);
-      console.log("- Loaded routes:");
-      for (const route of routes) {
-        const method = route.method.padEnd(6);
-        console.log(`  ${method}${route.urlPath}  ${route.filePath}`);
-      }
-      if (wsRoutes && wsRoutes.length > 0) {
-        console.log("- WebSocket routes:");
-        for (const route of wsRoutes) {
-          console.log(`  WS     ${route.urlPath}  ${route.filePath}`);
+  return (async () => {
+    if (beforeListen) {
+      await beforeListen(server);
+    }
+    return new Promise((resolve3) => {
+      server.listen(port, () => {
+        const address = server.address();
+        const actualPort = typeof address === "object" && address !== null ? address.port : port;
+        console.log("faapi dev server started");
+        console.log(`- Local: http://localhost:${actualPort}`);
+        console.log("- Loaded routes:");
+        for (const route of routes) {
+          const method = route.method.padEnd(6);
+          console.log(`  ${method}${route.urlPath}  ${route.filePath}`);
         }
-      }
-      resolve3(server);
+        if (wsRoutes && wsRoutes.length > 0) {
+          console.log("- WebSocket routes:");
+          for (const route of wsRoutes) {
+            console.log(`  WS     ${route.urlPath}  ${route.filePath}`);
+          }
+        }
+        resolve3(server);
+      });
     });
-  });
+  })();
+}
+function applyPluginWrappers(server, handlerWrappers, upgradeWrappers) {
+  if (handlerWrappers.length > 0) {
+    const listeners = server.listeners("request");
+    const original = listeners[0];
+    if (original) {
+      server.removeAllListeners("request");
+      let handler = original;
+      for (const wrap of handlerWrappers) {
+        handler = wrap(handler);
+      }
+      server.on("request", handler);
+    }
+  }
+  if (upgradeWrappers.length > 0) {
+    const listeners = server.listeners("upgrade");
+    const original = listeners[0];
+    server.removeAllListeners("upgrade");
+    let upgrade = original;
+    for (const wrap of upgradeWrappers) {
+      upgrade = wrap(upgrade);
+    }
+    if (upgrade) {
+      server.on("upgrade", upgrade);
+    }
+  }
 }
 var init_startServer = __esm({
   "src/server/startServer.ts"() {
@@ -5531,7 +5792,20 @@ var init_loadConfig = __esm({
 
 // src/cli/loadPlugins.ts
 async function loadPlugins(declarations, ctx) {
-  if (!declarations || declarations.length === 0) return;
+  const handlerWrappers = [];
+  const upgradeWrappers = [];
+  if (!declarations || declarations.length === 0) {
+    return { handlerWrappers, upgradeWrappers };
+  }
+  const fullCtx = {
+    ...ctx,
+    wrapHandler: (fn) => {
+      handlerWrappers.push(fn);
+    },
+    wrapUpgradeHandler: (fn) => {
+      upgradeWrappers.push(fn);
+    }
+  };
   const loaded = /* @__PURE__ */ new Set();
   for (const decl of declarations) {
     const { specifier, options, enable } = resolveDeclaration(decl);
@@ -5548,12 +5822,15 @@ async function loadPlugins(declarations, ctx) {
         console.warn(`! Plugin ${specifier} has no setup function, skipping`);
         continue;
       }
-      await plugin.setup({ ...ctx, options });
+      await plugin.setup({ ...fullCtx, options });
       console.log(`- Plugin loaded: ${plugin.name ?? specifier}`);
     } catch (err) {
-      console.warn(`! Failed to load plugin ${specifier}: ${err instanceof Error ? err.message : String(err)}`);
+      console.warn(
+        `! Failed to load plugin ${specifier}: ${err instanceof Error ? err.message : String(err)}`
+      );
     }
   }
+  return { handlerWrappers, upgradeWrappers };
 }
 function resolveDeclaration(decl) {
   if (typeof decl === "string") {
@@ -5590,10 +5867,11 @@ function isProductionMode(rootDir) {
   return fs6.existsSync(path9.resolve(rootDir, "dist", "faapi-schema.js"));
 }
 function adjustForProd(patterns, appDir) {
-  const prodPatterns = patterns.map(
-    (p) => p.replace(/\.ts$/g, ".js").replace(/^app\//, "dist/app/")
-  );
-  const prodAppDir = appDir === "app" ? "dist/app" : `dist/${appDir}`;
+  const prodPatterns = patterns.map((p) => p.replace(/\.ts$/g, ".js")).map((p) => {
+    if (p.startsWith("dist/")) return p;
+    return `dist/${p}`;
+  });
+  const prodAppDir = appDir === "." ? "dist" : `dist/${appDir}`;
   return { patterns: prodPatterns, appDir: prodAppDir };
 }
 async function startCommand(argv) {
@@ -5637,6 +5915,7 @@ async function startCommand(argv) {
     await generateTypes(sorted, rootDir, typesPath);
     console.log(`- Types generated: ${typesPath}`);
   }
+  const pluginConfig = config ? Object.fromEntries(Object.entries(config).filter(([k]) => !isFaapiConfigKey(k))) : {};
   const server = await startServer({
     port: args.port,
     routes: sorted,
@@ -5649,7 +5928,17 @@ async function startCommand(argv) {
     config: config ?? void 0,
     wsRoutes,
     middlewares: config?.middlewares,
-    injectors: config?.injectors
+    injectors: config?.injectors,
+    // beforeListen：加载插件并应用 handler 包装（在 server.listen 之前）
+    beforeListen: async (server2) => {
+      const { handlerWrappers, upgradeWrappers } = await loadPlugins(config?.plugins, {
+        rootDir,
+        routes: sorted,
+        server: server2,
+        config: pluginConfig
+      });
+      applyPluginWrappers(server2, handlerWrappers, upgradeWrappers);
+    }
   });
   if (config?.lifecycle?.onReady) {
     await config.lifecycle.onReady({
@@ -5682,15 +5971,6 @@ async function startCommand(argv) {
       types: args.types
     });
   }
-  const pluginConfig = config ? Object.fromEntries(
-    Object.entries(config).filter(([k]) => !isFaapiConfigKey(k))
-  ) : {};
-  await loadPlugins(config?.plugins, {
-    rootDir,
-    routes: sorted,
-    server,
-    config: pluginConfig
-  });
 }
 function isFaapiConfigKey(key) {
   return FAAPI_CONFIG_KEYS.has(key);
@@ -5712,8 +5992,6 @@ var init_startCommand = __esm({
     init_loadPlugins();
     FAAPI_CONFIG_KEYS = /* @__PURE__ */ new Set([
       "port",
-      "appDir",
-      "patterns",
       "staticDir",
       "cors",
       "responseFormat",