@faapi/faapi 6.7.0 → 6.9.0

package/dist/{routeTypes-CsL7xtqu.d.ts → routeTypes-CuGMDCGB.d.ts}

@@ -249,6 +249,84 @@ interface TaskDriver {
     retry?(name: string, id: string): Promise<void>;
 }
 
+/**
+ * 日志子系统类型契约（logger.md）
+ *
+ * Logger 跨越 handler（ctx.log / 参数 log）、任务（taskCtx.log）与任意业务代码
+ * （createLogger）多条路径，类型是各路径形状一致的单一来源；
+ * LogEntry 为纯数据（可结构化克隆），是隔离任务日志跨线程回传的契约。
+ */
+/** 日志级别（阈值序：debug < info < warn < error） */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * 单条日志（sink 的输入，纯数据可结构化克隆）
+ *
+ * time 为 ISO 字符串（写入时刻生成）；scope/fields 可省略。
+ */
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    time: string;
+    scope?: string;
+    fields?: Record<string, unknown>;
+}
+/**
+ * 日志输出目标（默认 console 文本，可整体接管接 pino/winston/文件）
+ *
+ * sink 内抛错会被吞掉（日志永不影响业务流程）。
+ */
+type LogSink = (entry: LogEntry) => void;
+/**
+ * 日志器接口
+ *
+ * 方法签名统一为 `message` 在前、结构化字段可选在后；
+ * `child(scope)` 返回新 Logger（scope 以 `:` 合并、fields 浅合并，父子互不影响）。
+ */
+interface Logger {
+    debug(message: string, fields?: Record<string, unknown>): void;
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+    child(scope: string): Logger;
+}
+/**
+ * 日志器构造选项（实例级覆盖全局）
+ *
+ * 命名带 CreateLogger 前缀：公开导出避免与请求日志中间件的 `LoggerOptions`
+ * （middleware/logger.ts，先于本模块存在）冲突。
+ */
+interface CreateLoggerOptions {
+    /** 实例级级别（覆盖全局 level） */
+    level?: LogLevel;
+    /** 实例级 sink（覆盖全局 sink；显式接管不受全局 `log: false` 影响） */
+    sink?: LogSink;
+    /** 构造字段（随每条日志携带，调用处 fields 同名键覆盖） */
+    fields?: Record<string, unknown>;
+}
+/**
+ * `config.log` 的对象形状（config 侧另接受 boolean：false 全静默、true 默认）
+ *
+ * level 解析顺序：显式值 > `LOG_LEVEL` 环境变量 > 模式默认（`dir` 文件模式不过滤，
+ * 其余模式 `'info'`；非法值启动报错）。`sink` 与 `dir` 互斥，同时配置启动报错。
+ */
+interface LogConfig {
+    /** 实例级级别（覆盖全局 level） */
+    level?: LogLevel;
+    /** 自定义输出管道（整体接管，与 `dir` 互斥） */
+    sink?: LogSink;
+    /**
+     * 文件日志目录（egg 风格）：配置即启用内置文件管道——默认 `app.log` 全量 +
+     * `error.log` 仅 error（dup 语义）；请求日志自动并入（`accessLog` 缺省 true）
+     */
+    dir?: string;
+    /** true 时按级别四文件 `debug.log`/`info.log`/`warn.log`/`error.log`（各只含对应级别） */
+    splitByLevel?: boolean;
+    /** 文件模式下是否保留 console 双写（默认 true；false 纯文件） */
+    stdout?: boolean;
+    /** 请求日志是否并入统一管道；缺省 = `dir` 配置时 true（见 middleware/logger.md） */
+    accessLog?: boolean;
+}
+
 /**
  * 隔离执行器签名（taskQueue 按任务 meta.timeoutMs 调用；测试可注入 spy）
  */
@@ -279,6 +357,18 @@ interface TaskWorkerOptions {
      * taskCtx.registries）——语义层从 `TaskRegistriesView` 生成，缺省为空视图
      */
     registries?: TaskRegistriesSnapshot;
+    /**
+     * 任务日志配置（纯数据，postMessage 传入，worker 内联重建日志器注入 taskCtx.log；
+     * 缺省时 taskCtx.log 为 undefined）：scope/fields 与进程内路径一致（`task:<name>`
+     * + jobId/task/attempt），level 为宿主侧生效的全局级别（worker 侧预过滤，
+     * 宿主 writeLogEntry 再次过滤；undefined = 宿主未配置阈值——文件管道默认全量，
+     * worker 侧同样不过滤）
+     */
+    log?: {
+        level?: LogLevel;
+        scope?: string;
+        fields?: Record<string, unknown>;
+    };
     /** 外部取消信号（驱动停机超时 abort）——abort 同样触发两段式取消 */
     externalSignal?: AbortSignal;
     /**
@@ -286,6 +376,12 @@ interface TaskWorkerOptions {
      * 消息回传宿主（语义层记入 `TaskJob.progress`）；不传则进度消息被忽略
      */
     onProgress?: (value: unknown) => void;
+    /**
+     * 日志回调：worker 内 taskCtx.log 的条目经 `{ type: 'log' }` 消息回传宿主，
+     * 由语义层接 writeLogEntry 走统一管道（自定义 sink 同样覆盖隔离任务）；
+     * 不传则日志条目被忽略。宽限期（取消判定后）到达的条目不采纳（超时判定即终局）
+     */
+    onLog?: (entry: LogEntry) => void;
 }
 declare function runTaskInWorker(options: TaskWorkerOptions): Promise<unknown>;
 
@@ -521,6 +617,13 @@ interface TaskContext {
      * 不可克隆按执行错误处理）。仅 running 状态生效，终态后调用被忽略。
      */
     progress?: (value: unknown) => void;
+    /**
+     * 任务级日志器（可选字段；框架两条执行路径均注入，直接构造 TaskContext 的
+     * 测试/自定义执行器可不传）——scope `task:<name>`，字段自动携带
+     * jobId/task/attempt，输出走 `config.log` 统一管道（详见 logger/logger.md）。
+     * 隔离执行时条目经 postMessage 回传宿主输出，fields 需可结构化克隆。
+     */
+    log?: Logger;
 }
 /**
  * 任务模块形态（task.ts 编译产物中与执行相关的导出）
@@ -773,6 +876,21 @@ interface FaapiContext {
      * 无 app 编排（编程式直调 ctx）时为 undefined
      */
     tasks?: TaskClient;
+    /**
+     * 请求 ID：请求头 `x-request-id` 第一段（网关透传场景跨服务串联），无则 crypto.randomUUID() 生成。
+     * ctx.log 与请求日志中间件的条目均携带该字段，业务日志与请求日志可经此关联
+     */
+    requestId: string;
+    /**
+     * 请求级日志器（scope `http`，自动携带 requestId/method/path 字段，详见 logger/logger.md）
+     *
+     * ```ts
+     * export function GET(ctx) {
+     *   ctx.log.info('listing users');
+     * }
+     * ```
+     */
+    log: Logger;
     request: Request;
     params: Record<string, string>;
     query: URLSearchParams;
@@ -1030,7 +1148,8 @@ interface LoggerOptions {
  * 错误用 try/catch 捕获，记录后重新抛出（让上层处理）。
  * 成功时从 next() 返回的 Response 读取状态码。
  *
- * log 函数每次请求时读取（options.log ?? console.log），运行时替换 console.log 会生效。
+ * log 函数每次请求时读取（options.log ?? defaultLog），运行时替换 console.log 或
+ * 切换全局日志配置均会生效。
  */
 declare function logger(options?: LoggerOptions): FaapiMiddleware;
 
@@ -1137,4 +1256,4 @@ interface RouteInfo {
     output: RouteOutputSchema | null;
 }
 
-export { helmet as $, type AppRegistries as A, type TaskDriverJob as B, type CorsOptions as C, type TaskDriverProcess as D, type TaskDriverRecord as E, type FaapiContext as F, type TaskFailedInfo as G, type HelmetOptions as H, type InjectorMap as I, type TaskJob as J, type TaskJobStatus as K, type LoggerOptions as L, type TaskMetadata as M, type TaskModule as N, type TaskRegistriesSnapshot as O, type TaskRegistriesView as P, type ToolCore as Q, type RouteManifest as R, type SkillRegistry as S, type TaskClient as T, type ToolPathMeta as U, type ToolRegistry as V, type WsRouteManifest as W, cors as X, createAppRegistries as Y, createTaskRegistriesView as Z, createTaskRegistry as _, type FaapiMiddleware as a, logger as a0, type TaskFailedHandler as b, type TaskQueueDeps as c, type TaskQueue as d, type TaskDriver as e, type TaskRegistry as f, type TaskManifest as g, type ToolMetadata as h, type AgentCore as i, type AgentMetadata as j, type AgentHandleFactory as k, type AgentHandleStore as l, type AgentPathMeta as m, type AgentRegistry as n, type AgentToolDescriptor as o, type FaapiContextConfig as p, type FaapiTaskMeta as q, type FailOptions as r, type Injector as s, type RouteInfo as t, type RouteInputSchema as u, type RouteOutputSchema as v, type RouteParamSchema as w, type SseEvent as x, type SseWriter as y, type TaskContext as z };
+export { type ToolPathMeta as $, type AppRegistries as A, type RouteInputSchema as B, type CorsOptions as C, type RouteOutputSchema as D, type RouteParamSchema as E, type FaapiContext as F, type SseEvent as G, type HelmetOptions as H, type InjectorMap as I, type SseWriter as J, type TaskContext as K, type LoggerOptions as L, type TaskDriverJob as M, type TaskDriverProcess as N, type TaskDriverRecord as O, type TaskFailedInfo as P, type TaskJob as Q, type RouteManifest as R, type SkillRegistry as S, type TaskClient as T, type TaskJobStatus as U, type TaskMetadata as V, type WsRouteManifest as W, type TaskModule as X, type TaskRegistriesSnapshot as Y, type TaskRegistriesView as Z, type ToolCore as _, type LogConfig as a, type ToolRegistry as a0, cors as a1, createAppRegistries as a2, createTaskRegistriesView as a3, createTaskRegistry as a4, helmet as a5, logger as a6, type FaapiMiddleware as b, type TaskFailedHandler as c, type TaskQueueDeps as d, type TaskQueue as e, type TaskDriver as f, type TaskRegistry as g, type TaskManifest as h, type ToolMetadata as i, type AgentCore as j, type AgentMetadata as k, type CreateLoggerOptions as l, type Logger as m, type AgentHandleFactory as n, type AgentHandleStore as o, type AgentPathMeta as p, type AgentRegistry as q, type AgentToolDescriptor as r, type FaapiContextConfig as s, type FaapiTaskMeta as t, type FailOptions as u, type Injector as v, type LogEntry as w, type LogLevel as x, type LogSink as y, type RouteInfo as z };

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { F as FaapiContext, a as FaapiMiddleware, I as InjectorMap, R as RouteManifest, W as WsRouteManifest, C as CorsOptions, H as HelmetOptions, L as LoggerOptions } from './routeTypes-CsL7xtqu.js';
+import { F as FaapiContext, b as FaapiMiddleware, I as InjectorMap, R as RouteManifest, W as WsRouteManifest, C as CorsOptions, H as HelmetOptions, L as LoggerOptions } from './routeTypes-CuGMDCGB.js';
 import { Server } from 'node:http';
 import { WebSocket } from 'ws';
 

package/dist/testing.js

@@ -245,7 +245,109 @@ function formatErrorResponse(error, config) {
   return jsonOk(body, 500);
 }
 
+// src/logger/formatEntry.ts
+function serializeFieldValue(value) {
+  if (value instanceof Error) {
+    return { name: value.name, message: value.message, stack: value.stack };
+  }
+  return value;
+}
+function formatEntry(entry) {
+  let line = `[${entry.time}] ${entry.level.toUpperCase()} `;
+  if (entry.scope) line += `[${entry.scope}] `;
+  line += entry.message;
+  if (entry.fields !== void 0) {
+    const plain = Object.fromEntries(
+      Object.entries(entry.fields).map(([k, v]) => [k, serializeFieldValue(v)])
+    );
+    try {
+      line += ` ${JSON.stringify(plain)}`;
+    } catch (err) {
+      line += ` [unserializable fields: ${err instanceof Error ? err.message : String(err)}]`;
+    }
+  }
+  return line;
+}
+
+// src/logger/logger.ts
+var LEVEL_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
+var globalState = { level: null, sink: null, fileSink: null, stdout: true, accessLog: false, disabled: false };
+function globalThreshold() {
+  if (globalState.level) return globalState.level;
+  if (globalState.fileSink) return void 0;
+  return "info";
+}
+function belowThreshold(level, threshold) {
+  return threshold !== void 0 && LEVEL_RANK[level] < LEVEL_RANK[threshold];
+}
+var consoleSink = (entry) => {
+  console[CONSOLE_METHOD[entry.level]](formatEntry(entry));
+};
+var CONSOLE_METHOD = {
+  debug: "debug",
+  info: "info",
+  warn: "warn",
+  error: "error"
+};
+function globalDispatch(entry) {
+  if (globalState.disabled) return;
+  if (globalState.sink) {
+    globalState.sink(entry);
+    return;
+  }
+  if (globalState.fileSink) {
+    globalState.fileSink.write(entry);
+    if (globalState.stdout) consoleSink(entry);
+    return;
+  }
+  consoleSink(entry);
+}
+function writeLogEntry(entry) {
+  if (belowThreshold(entry.level, globalThreshold())) return;
+  globalDispatch(entry);
+}
+function isAccessLogPiped() {
+  return !globalState.disabled && globalState.accessLog;
+}
+function createLogger(scope, options) {
+  const baseScope = scope;
+  const baseFields = options?.fields;
+  const write = (level, message, callFields, scopeSuffix) => {
+    const threshold = options?.level ?? globalThreshold();
+    if (belowThreshold(level, threshold)) return;
+    const entry = {
+      level,
+      message,
+      time: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const fullScope = scopeSuffix === void 0 ? baseScope : baseScope === void 0 ? scopeSuffix : `${baseScope}:${scopeSuffix}`;
+    if (fullScope !== void 0) entry.scope = fullScope;
+    if (baseFields !== void 0 || callFields !== void 0) {
+      entry.fields = { ...baseFields, ...callFields };
+    }
+    if (options?.sink) {
+      options.sink(entry);
+    } else {
+      globalDispatch(entry);
+    }
+  };
+  const makeLogger = (scopeSuffix) => ({
+    debug: (message, fields) => write("debug", message, fields, scopeSuffix),
+    info: (message, fields) => write("info", message, fields, scopeSuffix),
+    warn: (message, fields) => write("warn", message, fields, scopeSuffix),
+    error: (message, fields) => write("error", message, fields, scopeSuffix),
+    child: (childScope) => makeLogger(scopeSuffix === void 0 ? childScope : `${scopeSuffix}:${childScope}`)
+  });
+  return makeLogger(void 0);
+}
+
 // src/runtime/createContext.ts
+function resolveRequestId(request) {
+  const header = request.headers.get("x-request-id");
+  const first = header?.split(",")[0]?.trim();
+  if (first) return first;
+  return crypto.randomUUID();
+}
 function parseCookies(cookieHeader) {
   const cookies = /* @__PURE__ */ new Map();
   if (!cookieHeader) return cookies;
@@ -279,7 +381,13 @@ function createContextFromUrl(request, url, params, config = {}, ip = "", regist
   for (const [key, val] of parsedCookies) {
     cookiesObj[key] = val;
   }
+  const requestId = resolveRequestId(request);
+  const log = createLogger("http", {
+    fields: { requestId, method: request.method, path: url.pathname }
+  });
   const ctx = {
+    requestId,
+    log,
     request,
     params,
     query: url.searchParams,
@@ -553,8 +661,10 @@ var PARAM_TYPE_MAP = {
   // Phase 2.3
   agents: "agents",
   // Phase 2.3
-  tasks: "tasks"
+  tasks: "tasks",
   // 任务子系统：TaskClient（入队/查询）
+  log: "log"
+  // 请求级日志器（ctx.log 同一实例：scope http，自动带 requestId 等字段）
 };
 var injectionCache = /* @__PURE__ */ new WeakMap();
 function resolveInjection(fn) {
@@ -872,6 +982,9 @@ function getBuiltinInjectionValue(type, ctx, body) {
     // 任务子系统：注入 TaskClient（入队/查询）；未注册工厂（无 app 编排）时 undefined
     case "tasks":
       return ctx.registries ? ctx.registries.taskHandle.get(ctx) : void 0;
+    // 请求级日志器：与 ctx.log 同一实例（scope http，自动带 requestId/method/path 字段）
+    case "log":
+      return ctx.log;
     default:
       return void 0;
   }
@@ -4093,14 +4206,34 @@ function etag(options = {}) {
 }
 
 // src/middleware/logger.ts
+function levelForStatus(status) {
+  if (status >= 500) return "error";
+  if (status >= 400) return "warn";
+  return "info";
+}
+function defaultLog(entry, text) {
+  if (isAccessLogPiped()) {
+    const logEntry = {
+      level: levelForStatus(entry.status),
+      message: text,
+      time: (/* @__PURE__ */ new Date()).toISOString(),
+      scope: "access",
+      fields: entry
+    };
+    writeLogEntry(logEntry);
+    return;
+  }
+  console.log(entry);
+}
 function logger(options = {}) {
   return async (ctx, next) => {
-    const log = options.log ?? console.log;
+    const log = options.log ?? defaultLog;
     const start = Date.now();
     try {
       const response = await next();
       const duration = Date.now() - start;
       const entry = {
+        requestId: ctx.requestId,
         method: ctx.method,
         path: ctx.path,
         status: response.status,
@@ -4113,6 +4246,7 @@ function logger(options = {}) {
       const message = err instanceof Error ? err.message : String(err);
       const status = err?.statusCode ?? 500;
       const entry = {
+        requestId: ctx.requestId,
         method: ctx.method,
         path: ctx.path,
         status,