@faapi/faapi 4.0.0 → 4.2.0

package/README.md

@@ -48,6 +48,11 @@ node dist/main             # 启动生产服务器
 - 洋葱模型中间件：`(ctx, next) => {}`
 - 依赖注入：注入器按参数名匹配 handler 参数
 - WebSocket 路由：导出 `WS` 函数声明
+- SSE 流式响应：`ctx.sse()` 流式推送（LLM 输出、通知推送）
+- 响应压缩：`compression: true`，gzip/deflate/br 协商，SSE 自动跳过
+- ETag/304 协商：`etag: true`，GET/HEAD 弱 ETag 自动生成与协商
+- 优雅停机：SIGTERM/SIGINT 默认注册，drain 在途请求（`FAAPI_SHUTDOWN_TIMEOUT_MS` 可调）
+- app 级注册表：tool/agent/skill 注册表随 app 实例创建与销毁，多 app 同进程隔离
 - SSE 流式响应：`ctx.sse()` 推送
 - 动态路由：`[id]` / `[...slug]` / `(group)`
 - MCP 集成：LLM 可查询路由 schema

package/dist/cli/index.js

@@ -132,6 +132,15 @@ function toStrippedProdImportPath(sourceFile, rootDir) {
   if (!rel.startsWith(".")) rel = "./" + rel;
   return toProdExtension(rel);
 }
+function toProdImportFromImporter(importer, rootDir, relFromDist) {
+  const importerRel = path3.relative(toRealPath(path3.resolve(rootDir)), toRealPath(importer)).split(path3.sep).join("/");
+  const importerProdDir = path3.posix.dirname(toProdExtension(importerRel));
+  if (importerProdDir === ".") return relFromDist;
+  const target = relFromDist.replace(/^\.\//, "");
+  let rel = path3.posix.relative(importerProdDir, target);
+  if (!rel.startsWith(".")) rel = "./" + rel;
+  return rel;
+}
 function resolveRelativeSpecifier(importer, specifier) {
   const importerDir = path3.dirname(importer);
   const base = path3.resolve(importerDir, specifier);
@@ -179,9 +188,10 @@ function createAliasPlugin(config, options) {
               }
               if (appDirAbs && importerOutsideAppDir && isInsideDir(resolved, appDirAbs)) {
                 modified = true;
-                return `${prefix}${quote}${toStrippedProdImportPath(
-                  resolved,
-                  options.rootDir
+                return `${prefix}${quote}${toProdImportFromImporter(
+                  importer,
+                  options.rootDir,
+                  toStrippedProdImportPath(resolved, options.rootDir)
                 )}${quote}`;
               }
               modified = true;
@@ -196,9 +206,10 @@ function createAliasPlugin(config, options) {
               if (fs3.existsSync(file)) {
                 modified = true;
                 if (appDirAbs && importerOutsideAppDir && isInsideDir(file, appDirAbs)) {
-                  return `${prefix}${quote}${toStrippedProdImportPath(
-                    file,
-                    options.rootDir
+                  return `${prefix}${quote}${toProdImportFromImporter(
+                    importer,
+                    options.rootDir,
+                    toStrippedProdImportPath(file, options.rootDir)
                   )}${quote}`;
                 }
                 return `${prefix}${quote}${toProdImportPath(file, importer)}${quote}`;
@@ -209,9 +220,10 @@ function createAliasPlugin(config, options) {
               if (fs3.existsSync(file)) {
                 modified = true;
                 if (appDirAbs && importerOutsideAppDir && isInsideDir(file, appDirAbs)) {
-                  return `${prefix}${quote}${toStrippedProdImportPath(
-                    file,
-                    options.rootDir
+                  return `${prefix}${quote}${toProdImportFromImporter(
+                    importer,
+                    options.rootDir,
+                    toStrippedProdImportPath(file, options.rootDir)
                   )}${quote}`;
                 }
                 return `${prefix}${quote}${toProdImportPath(file, importer)}${quote}`;
@@ -368,31 +380,13 @@ function createExternalRelativePlugin() {
     }
   };
 }
-async function compileConfig(options) {
-  const { rootDir, dist } = options;
-  const baseConfigName = findBaseConfig(rootDir);
-  if (!baseConfigName) {
-    return { generated: false, outputFile: "", skipped: false };
-  }
-  const absDist = path5.resolve(rootDir, dist);
-  await fs5.promises.mkdir(absDist, { recursive: true });
-  const outputFile = path5.resolve(absDist, "faapi-config.js");
-  const cacheKey = `${toRealPath(rootDir)}::${dist}`;
-  const cached = compileConfigCache.get(cacheKey);
-  if (cached && await isCacheFresh(cached)) {
-    return { generated: true, outputFile: cached.outputFile, skipped: true };
-  }
-  compileConfigCache.delete(cacheKey);
-  const configEntryPoints = [path5.resolve(rootDir, baseConfigName)];
-  const { insideFiles: appDirFiles, outsideFiles: nonAppDirFiles } = await collectRelativeImports(
-    configEntryPoints,
-    rootDir
-  );
+async function compileProjectModules(entryPoints, rootDir, dist) {
+  const { insideFiles, outsideFiles } = await collectRelativeImports(entryPoints, rootDir);
   const esbuild = await import("esbuild");
   const aliasPlugins = buildAliasPlugins(rootDir);
-  const step1aEntries = [...configEntryPoints, ...nonAppDirFiles];
+  const absDist = path5.resolve(rootDir, dist);
   await esbuild.build({
-    entryPoints: step1aEntries,
+    entryPoints: [...entryPoints, ...outsideFiles],
     outdir: absDist,
     outbase: rootDir,
     bundle: false,
@@ -403,10 +397,10 @@ async function compileConfig(options) {
     plugins: aliasPlugins,
     logLevel: "silent"
   });
-  if (appDirFiles.length > 0) {
+  if (insideFiles.length > 0) {
     const appOutbase = path5.resolve(rootDir, "src");
     await esbuild.build({
-      entryPoints: appDirFiles,
+      entryPoints: insideFiles,
       outdir: absDist,
       outbase: appOutbase,
       bundle: false,
@@ -418,9 +412,33 @@ async function compileConfig(options) {
       logLevel: "silent"
     });
   }
+  return { insideFiles, outsideFiles };
+}
+async function compileConfig(options) {
+  const { rootDir, dist } = options;
+  const baseConfigName = findBaseConfig(rootDir);
+  if (!baseConfigName) {
+    return { generated: false, outputFile: "", skipped: false };
+  }
+  const absDist = path5.resolve(rootDir, dist);
+  await fs5.promises.mkdir(absDist, { recursive: true });
+  const outputFile = path5.resolve(absDist, "faapi-config.js");
+  const cacheKey = `${toRealPath(rootDir)}::${dist}`;
+  const cached = compileConfigCache.get(cacheKey);
+  if (cached && await isCacheFresh(cached)) {
+    return { generated: true, outputFile: cached.outputFile, skipped: true };
+  }
+  compileConfigCache.delete(cacheKey);
+  const configEntryPoints = [path5.resolve(rootDir, baseConfigName)];
+  const { insideFiles: appDirFiles, outsideFiles: nonAppDirFiles } = await compileProjectModules(
+    configEntryPoints,
+    rootDir,
+    dist
+  );
   const baseImport = `import base from './${toProdImport(baseConfigName)}';`;
   const exportDefault = "export default base;";
   const entryCode = [baseImport, exportDefault].join("\n");
+  const esbuild = await import("esbuild");
   await esbuild.build({
     stdin: { contents: entryCode, resolveDir: absDist, loader: "ts" },
     outfile: outputFile,
@@ -7519,7 +7537,7 @@ import { createSecureServer as createHttp2SecureServer } from "http2";
 import { readFileSync } from "fs";
 import { Readable as Readable3 } from "stream";
 import path22 from "path";
-function toWebRequest(req, bodyLimit = DEFAULT_BODY_LIMIT) {
+function toWebRequest(req, bodyLimit = DEFAULT_BODY_LIMIT, requestSignal) {
   const forwardedProto = req.headers["x-forwarded-proto"];
   const protocol = Array.isArray(forwardedProto) ? forwardedProto[0]?.split(",")[0]?.trim() ?? "http" : forwardedProto?.split(",")[0]?.trim() ?? "http";
   const host = req.headers.host ?? "localhost";
@@ -7527,7 +7545,10 @@ function toWebRequest(req, bodyLimit = DEFAULT_BODY_LIMIT) {
   const headers = nodeHttpToWebHeaders(req);
   const method = req.method ?? "GET";
   if (method === "GET" || method === "HEAD") {
-    return { request: new Request(url.toString(), { method, headers }), url };
+    return {
+      request: new Request(url.toString(), { method, headers, signal: requestSignal }),
+      url
+    };
   }
   const contentLength = req.headers["content-length"];
   if (contentLength !== void 0) {
@@ -7543,7 +7564,8 @@ function toWebRequest(req, bodyLimit = DEFAULT_BODY_LIMIT) {
       method,
       headers,
       body: limitedStream,
-      duplex: "half"
+      duplex: "half",
+      signal: requestSignal
     }),
     url
   };
@@ -7682,8 +7704,8 @@ function createServer(options) {
   });
   return { server, routesRef };
 }
-function prepareRequest(req, config, bodyLimit, trustedProxy, registries) {
-  const { request, url } = toWebRequest(req, bodyLimit);
+function prepareRequest(req, config, bodyLimit, trustedProxy, registries, requestSignal) {
+  const { request, url } = toWebRequest(req, bodyLimit, requestSignal);
   const method = request.method.toUpperCase();
   const urlPath = url.pathname;
   const ctx = createContextFromUrl(
@@ -7768,8 +7790,19 @@ async function sendErrorResponse(err, meta, res, onError, ctx) {
 async function handleRequest(routes, rootDir, dist, req, res, outerMiddlewares, onError, config, globalInjectors, bodyLimit, trustedProxy, registries) {
   let meta = { headers: {}, setCookies: [] };
   let ctx;
+  const abortController = new AbortController();
+  res.on("close", () => {
+    if (!res.writableEnded) abortController.abort();
+  });
   try {
-    const prepared = prepareRequest(req, config, bodyLimit, trustedProxy, registries);
+    const prepared = prepareRequest(
+      req,
+      config,
+      bodyLimit,
+      trustedProxy,
+      registries,
+      abortController.signal
+    );
     ctx = prepared.ctx;
     meta = prepared.meta;
     const { request, url, method, urlPath } = prepared;
@@ -7855,8 +7888,9 @@ var init_startServer = __esm({
 
 // src/cli/loadPlugins.ts
 import path23 from "path";
+import fs17 from "fs";
 import { pathToFileURL as pathToFileURL2 } from "url";
-async function loadPlugins(declarations, ctx, rootDir) {
+async function loadPlugins(declarations, ctx, rootDir, dist) {
   const handlerWrappers = [];
   const upgradeWrappers = [];
   const failures = [];
@@ -7893,7 +7927,7 @@ async function loadPlugins(declarations, ctx, rootDir) {
     }
     loaded.add(specifier);
     try {
-      const mod = await import(resolveSpecifier(specifier, rootDir));
+      const mod = await importPluginModule(specifier, rootDir ?? process.cwd(), dist);
       const plugin = mod.default ?? mod;
       if (typeof plugin.setup !== "function") {
         failures.push({ specifier, reason: "plugin has no setup function" });
@@ -7916,15 +7950,70 @@ async function loadPlugins(declarations, ctx, rootDir) {
   }
   return { handlerWrappers, upgradeWrappers, failures };
 }
-function resolveSpecifier(specifier, rootDir) {
-  if (specifier.startsWith("./") || specifier.startsWith("../")) {
-    const base = rootDir ?? process.cwd();
-    return pathToFileURL2(path23.resolve(base, specifier)).href;
+function resolveLocalPluginSource(specifier, baseDir) {
+  const base = path23.isAbsolute(specifier) ? specifier : path23.resolve(baseDir, specifier);
+  if ((TS_EXTS.test(base) || JS_EXTS.test(base)) && fs17.existsSync(base)) return base;
+  for (const ext of [".ts", ".js"]) {
+    if (fs17.existsSync(base + ext)) return base + ext;
+  }
+  for (const indexExt of ["/index.ts", "/index.js"]) {
+    if (fs17.existsSync(base + indexExt)) return base + indexExt;
+  }
+  return null;
+}
+function mirrorProductPath(sourcePath, baseDir, distDir) {
+  let rel = path23.relative(baseDir, sourcePath).replace(/\\/g, "/");
+  if (rel.startsWith("src/")) rel = rel.slice(4);
+  return path23.resolve(distDir, rel.replace(TS_EXTS, ".js"));
+}
+function isSourceNewer(sourcePath, productPath) {
+  try {
+    return fs17.statSync(sourcePath).mtimeMs > fs17.statSync(productPath).mtimeMs;
+  } catch {
+    return true;
+  }
+}
+async function importPluginModule(specifier, baseDir, dist) {
+  const isRelative = specifier.startsWith("./") || specifier.startsWith("../");
+  if (!isRelative && !path23.isAbsolute(specifier)) {
+    return import(specifier);
+  }
+  const distDir = dist ? path23.resolve(baseDir, dist) : null;
+  const sourcePath = resolveLocalPluginSource(specifier, baseDir);
+  const productPath = sourcePath && distDir ? mirrorProductPath(sourcePath, baseDir, distDir) : null;
+  if (productPath !== null && fs17.existsSync(productPath) && (sourcePath === null || !isSourceNewer(sourcePath, productPath))) {
+    return import(pathToFileURL2(productPath).href);
+  }
+  if (sourcePath && TS_EXTS.test(sourcePath)) {
+    if (!isDevOnDemandEnabled() || !distDir) {
+      throw new Error(
+        `Local plugin "${specifier}" has no up-to-date build artifact (dist is stale or missing). Run "faapi build" first, or use "faapi dev" for on-demand compilation.`
+      );
+    }
+    const relFromRoot = path23.relative(baseDir, sourcePath).replace(/\\/g, "/");
+    if (relFromRoot.startsWith("src/")) {
+      await ensureCompiled(sourcePath, baseDir, dist);
+    } else {
+      await compileProjectModules([sourcePath], baseDir, dist);
+    }
+    if (productPath && fs17.existsSync(productPath)) {
+      return import(pathToFileURL2(productPath).href);
+    }
   }
-  if (path23.isAbsolute(specifier)) {
-    return pathToFileURL2(specifier).href;
+  if (sourcePath && JS_EXTS.test(sourcePath)) {
+    return import(pathToFileURL2(sourcePath).href);
   }
-  return specifier;
+  const candidates = [
+    `${specifier}.ts`,
+    `${specifier}/index.ts`,
+    `${specifier}.js`,
+    `${specifier}/index.js`
+  ].map((c) => path23.isAbsolute(c) ? c : path23.join(baseDir, c));
+  throw new Error(
+    `Cannot find local plugin "${specifier}" (resolved from ${baseDir}). Expected one of:
+  ${candidates.join("\n  ")}
+Create the plugin file (export default { name, setup(ctx) {...} }) or fix the path.`
+  );
 }
 function resolveDeclaration(decl) {
   if (typeof decl === "string") {
@@ -7942,19 +8031,24 @@ function resolveDeclaration(decl) {
   }
   throw new Error(`Invalid plugin declaration: ${JSON.stringify(decl)}`);
 }
+var TS_EXTS, JS_EXTS;
 var init_loadPlugins = __esm({
   "src/cli/loadPlugins.ts"() {
     "use strict";
+    init_compileOnDemand();
+    init_compileConfig();
+    TS_EXTS = /\.(ts|tsx|mts|cts)$/;
+    JS_EXTS = /\.(js|mjs|cjs|jsx)$/;
   }
 });
 
 // src/cli/createAppCore.ts
-import fs17 from "fs";
+import fs18 from "fs";
 import path24 from "path";
 import { PassThrough, Readable as Readable4 } from "stream";
 async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries) {
   const toolsPath = path24.resolve(rootDir, dist, TOOLS_FILE2);
-  if (!fs17.existsSync(toolsPath)) {
+  if (!fs18.existsSync(toolsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(toolsPath);
@@ -7964,7 +8058,7 @@ async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries
 }
 async function loadAndHydrateAgents(rootDir, dist, registries = defaultRegistries) {
   const agentsPath = path24.resolve(rootDir, dist, AGENTS_FILE2);
-  if (!fs17.existsSync(agentsPath)) {
+  if (!fs18.existsSync(agentsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(agentsPath);
@@ -8005,7 +8099,7 @@ async function createAppBase(options) {
   const rootDir = options?.rootDir ?? process.cwd();
   const dist = options?.dist ?? process.env.FAAPI_DIST ?? DEFAULT_DIST;
   const routesPath = path24.resolve(rootDir, dist, ROUTES_FILE);
-  if (!fs17.existsSync(routesPath)) {
+  if (!fs18.existsSync(routesPath)) {
     throw new Error(
       `[faapi] ${dist}/${ROUTES_FILE} \u4E0D\u5B58\u5728\uFF0C\u8BF7\u5148\u6267\u884C \`faapi build\`\uFF08\u6216 \`faapi dev\`\uFF09\u751F\u6210\u4EA7\u7269\u3002`
     );
@@ -8057,7 +8151,8 @@ async function createAppBase(options) {
       server,
       config: pluginConfig
     },
-    rootDir
+    rootDir,
+    dist
   );
   applyPluginWrappers(server, handlerWrappers, upgradeWrappers);
   let closed = false;
@@ -8070,6 +8165,16 @@ async function createAppBase(options) {
     async listen(listenPort) {
       const envPort = process.env.PORT ? Number(process.env.PORT) : void 0;
       const actualPort = listenPort ?? options?.port ?? envPort ?? DEFAULT_PORT;
+      if (config?.lifecycle?.onBoot) {
+        try {
+          await config.lifecycle.onBoot({ rootDir, routes: sorted, server, registries });
+          console.log("- onBoot hook executed");
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          console.error(`[faapi] onBoot hook failed: ${message}`);
+          throw err;
+        }
+      }
       return new Promise((resolve3, reject) => {
         const onListenError = (err) => {
           if (err.code === "EADDRINUSE") {
@@ -8447,14 +8552,14 @@ __export(buildCommand_exports, {
   buildCommand: () => buildCommand
 });
 import path26 from "path";
-import fs18 from "fs";
+import fs19 from "fs";
 async function buildCommand(options) {
   const rootDir = options?.rootDir ?? process.cwd();
   const outdir = options?.dist ?? DEFAULT_DIST2;
   const absOut = path26.resolve(rootDir, outdir);
   const realRoot = toRealPath(path26.resolve(rootDir));
   if (isInsideDir(toRealPath(absOut), realRoot)) {
-    fs18.rmSync(absOut, { recursive: true, force: true });
+    fs19.rmSync(absOut, { recursive: true, force: true });
   } else {
     console.warn(
       `! Output directory "${outdir}" is outside the project root, skipping clean (stale artifacts may remain)`
@@ -8463,9 +8568,9 @@ async function buildCommand(options) {
   await compileConfig({ rootDir, dist: outdir });
   const _config = await loadConfig(rootDir, outdir);
   const pkgPath = path26.resolve(rootDir, "package.json");
-  if (fs18.existsSync(pkgPath)) {
+  if (fs19.existsSync(pkgPath)) {
     try {
-      const pkg = JSON.parse(fs18.readFileSync(pkgPath, "utf-8"));
+      const pkg = JSON.parse(fs19.readFileSync(pkgPath, "utf-8"));
       if (pkg.type !== "module") {
         console.warn(
           '! package.json is missing "type": "module" \u2014 build output is ESM and `node dist/main` will fail without it'
@@ -8489,6 +8594,18 @@ async function buildCommand(options) {
     console.warn("  ! No source files found, nothing to build");
     return;
   }
+  const localPluginSources = extractLocalPluginSources(_config?.plugins, rootDir);
+  if (localPluginSources.length > 0) {
+    console.log("\n[2.5/8] Compiling local plugins...");
+    const outside = localPluginSources.filter((p) => {
+      const rel = path26.relative(rootDir, p).replace(/\\/g, "/");
+      return !rel.startsWith("src/");
+    });
+    if (outside.length > 0) {
+      await compileProjectModules(outside, rootDir, outdir);
+    }
+    console.log(`  Compiled ${localPluginSources.length} local plugin(s)`);
+  }
   console.log("\n[3/8] Scanning routes...");
   const { routes, wsRoutes } = await scanRoutes(rootDir, ROUTE_PATTERNS, outdir);
   const sorted = sortRoutes(routes);
@@ -8534,10 +8651,31 @@ loadEnv(process.cwd());
 const app = await createProdApp(${createProdAppArgs});
 await app.listen();
 `;
-  await fs18.promises.writeFile(mainPath, mainContent, "utf-8");
+  await fs19.promises.writeFile(mainPath, mainContent, "utf-8");
   console.log(`  Written to ${mainPath}`);
   console.log("\nfaapi build completed");
 }
+function extractLocalPluginSources(declarations, rootDir) {
+  if (!declarations || declarations.length === 0) return [];
+  const sources = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const decl of declarations) {
+    let specifier;
+    if (typeof decl === "string") specifier = decl;
+    else if (Array.isArray(decl)) specifier = decl[0];
+    else if ("path" in decl) specifier = decl.path;
+    if (!specifier) continue;
+    if (!specifier.startsWith("./") && !specifier.startsWith("../") && !path26.isAbsolute(specifier)) {
+      continue;
+    }
+    const source = resolveLocalPluginSource(specifier, rootDir);
+    if (source && !seen.has(source)) {
+      seen.add(source);
+      sources.push(source);
+    }
+  }
+  return sources;
+}
 var DEFAULT_DIST2;
 var init_buildCommand = __esm({
   "src/cli/buildCommand.ts"() {
@@ -8557,6 +8695,7 @@ var init_buildCommand = __esm({
     init_prodPaths();
     init_compileConfig();
     init_loadConfig();
+    init_loadPlugins();
     init_prodPaths();
     DEFAULT_DIST2 = "dist";
   }