@h-ai/serv 1.0.0-beta.2 → 1.0.0-beta.20

package/dist/index.d.ts

@@ -1,17 +1,17 @@
 import * as _h_ai_core from '@h-ai/core';
 import { HaiResult, TrustedProxies, RequestAccessConfigInput, ValidationFormError } from '@h-ai/core';
+import { ProcedureHandler, ErrorMap, Meta, ProcedureHandlerOptions, ORPCErrorConstructorMap, Router, ContractRouter } from '@orpc/server';
 import { AIFunctions, AudioWsStartMessage, AudioFormat } from '@h-ai/ai';
 import { AnyContractRouter, OpenAPI } from '@orpc/contract';
-import { ProcedureHandler, ErrorMap, Meta, ProcedureHandlerOptions, ORPCErrorConstructorMap, Router } from '@orpc/server';
-import { a as ServSession, S as ServContext, b as ServIam, R as RefreshCookieConfig, C as CreateServContext, c as ServRequestMetadata, p as parseRequestContext, d as buildAuthContextFactory } from './serv-context-DE1JH5bd.js';
-export { e as CreateServContextInput, N as NativeRefreshTokenTransportConfig, f as RefreshTokenPair } from './serv-context-DE1JH5bd.js';
+import { a as ServSession, S as ServContext, b as ServIam, R as RefreshCookieConfig, C as CreateServContext, c as ServRequestMetadata, d as CreateServContextInput } from './serv-context-DSsS_ksL.js';
+export { N as NativeRefreshTokenTransportConfig, e as RefreshTokenPair } from './serv-context-DSsS_ksL.js';
 import { MiddlewareHandler } from 'hono';
 import { z, ZodType } from 'zod';
 import { TransportServerKeyRing, CryptoFunctions, TransportKeyStore } from '@h-ai/crypto';
 import { ServerType } from '@hono/node-server';
 import { AddressInfo } from 'node:net';
-import { i as implement } from './serv-router-BJk04-oS.js';
-export { A as AuthenticatedServContext, S as ServImplementer, a as ServRouteHandler, b as ServRoutePath, c as ServRouterBuilder } from './serv-router-BJk04-oS.js';
+import { S as ServImplementer } from './serv-router-DWjYC0zD.js';
+export { A as AuthenticatedServContext, a as ServRouteHandler, b as ServRoutePath, c as ServRouterBuilder } from './serv-router-DWjYC0zD.js';
 import { StorageFunctions } from '@h-ai/storage';
 
 /**
@@ -138,7 +138,7 @@ type ServProcedureHandler<TInput, TOutput, TContext extends ServContext = ServCo
 /**
  * @h-ai/serv — HTTP 配置
  *
- * 提供用于控制 API 前缀、OpenAPI、docs、健康检查、内部 RPC 与传输加密策略的配置结构，
+ * 提供用于控制 API 前缀、OpenAPI、docs、健康检查与传输加密策略的配置结构，
  * 并由 zod 负责默认值填充与边界校验。
  * @module serv-config
  */
@@ -217,24 +217,6 @@ interface ServHealthHttpConfig {
     readonly path: `/${string}`;
     readonly readyPath?: `/${string}`;
 }
-/**
- * 内部 RPC endpoint 配置。
- *
- * @example
- * ```ts
- * import type { ServRpcHttpConfig } from '@h-ai/serv'
- * import { serv } from '@h-ai/serv'
- *
- * const rpc: ServRpcHttpConfig = { prefix: '/rpc', access: 'loopback' }
- * // 缺少可信连接信息时拒绝；跨节点来源通过明确网关/网络策略控制。
- * ```
- */
-interface ServRpcHttpConfig {
-    readonly prefix: `/${string}`;
-    readonly access: 'loopback' | 'private-network' | 'gateway-only';
-    readonly gatewayHeader?: string;
-    readonly gatewaySecret?: string;
-}
 /**
  * 传输加密运行时配置（对应 `config/_serv.yml`）。
  *
@@ -250,6 +232,10 @@ interface ServRpcHttpConfig {
 interface ServTransportRuntimeConfig {
     /** 双向明文 UTF-8 字节上限；省略使用 1 MiB，范围 1 KiB～64 MiB。 */
     readonly maxPlaintextBytes?: number;
+    /** 请求时间允许领先服务器的秒数，默认 30，整数范围 0～300。 */
+    readonly maxFutureSkewSeconds?: number;
+    /** 请求从签发起的有效秒数，默认 300，整数范围 1～600。 */
+    readonly maxRequestAgeSeconds?: number;
     /** 按完整路径段匹配的明文容量；* 匹配单段。 */
     readonly routePlaintextBytes?: Readonly<Record<string, number>>;
     readonly keyExchangePath: `/${string}`;
@@ -281,7 +267,7 @@ interface ServCorsRuntimeConfig {
  * import type { ServHttpConfig } from '@h-ai/serv'
  * import { serv } from '@h-ai/serv'
  *
- * const http: ServHttpConfig = { trustedProxies: 'auto', access: false, apiPrefix: '/api/v1', openapi: false, docs: false, health: { path: '/health' }, rpc: false }
+ * const http: ServHttpConfig = { trustedProxies: 'auto', access: false, apiPrefix: '/api/v1', openapi: false, docs: false, health: { path: '/health' } }
  * ```
  */
 interface ServHttpConfig {
@@ -289,11 +275,10 @@ interface ServHttpConfig {
     readonly trustedProxies: TrustedProxies;
     /** 每次请求的 IP/时间策略；默认 false，内联与独立文件二选一。 */
     readonly access: RequestAccessConfigInput;
-    readonly apiPrefix: `/api/${string}`;
+    readonly apiPrefix: `/${string}`;
     readonly openapi: false | ServOpenAPIHttpConfig;
     readonly docs: false | ServDocsHttpConfig;
     readonly health: false | ServHealthHttpConfig;
-    readonly rpc: false | ServRpcHttpConfig;
 }
 /**
  * `config/_serv.yml` 的顶层配置结构。
@@ -341,6 +326,8 @@ type ServCorsRuntimeConfigInput = Partial<ServCorsRuntimeConfig>;
  */
 type ServTransportRuntimeConfigInput = Partial<{
     readonly maxPlaintextBytes: number | 'auto';
+    readonly maxFutureSkewSeconds: number;
+    readonly maxRequestAgeSeconds: number;
     readonly routePlaintextBytes: Readonly<Record<string, number>>;
     readonly keyExchangePath: `/${string}`;
     readonly excludePaths: readonly `/${string}`[];
@@ -359,11 +346,10 @@ type ServTransportRuntimeConfigInput = Partial<{
 type ServHttpConfigInput = Partial<{
     readonly trustedProxies: TrustedProxies;
     readonly access: RequestAccessConfigInput;
-    readonly apiPrefix: `/api/${string}`;
+    readonly apiPrefix: `/${string}`;
     readonly openapi: false | Partial<ServOpenAPIHttpConfig>;
     readonly docs: false | Partial<ServDocsHttpConfig>;
     readonly health: false | Partial<ServHealthHttpConfig>;
-    readonly rpc: false | Partial<ServRpcHttpConfig>;
 }>;
 /**
  * `config/_serv.yml` 的顶层输入类型。
@@ -447,7 +433,7 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
                 }>>;
             }, z.core.$strict>>>;
         }, z.core.$strict>]>>;
-        apiPrefix: z.ZodDefault<z.ZodCustom<`/api/${string}`, `/api/${string}`>>;
+        apiPrefix: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
         openapi: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
             path: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
         }, z.core.$strip>]>>;
@@ -459,16 +445,6 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
             path: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
             readyPath: z.ZodDefault<z.ZodOptional<z.ZodCustom<`/${string}`, `/${string}`>>>;
         }, z.core.$strip>]>>;
-        rpc: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
-            prefix: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
-            access: z.ZodDefault<z.ZodEnum<{
-                loopback: "loopback";
-                "private-network": "private-network";
-                "gateway-only": "gateway-only";
-            }>>;
-            gatewayHeader: z.ZodOptional<z.ZodString>;
-            gatewaySecret: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>]>>;
     }, z.core.$strip>>;
     cors: z.ZodOptional<z.ZodObject<{
         origin: z.ZodOptional<z.ZodString>;
@@ -479,6 +455,8 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
     }, z.core.$strip>>;
     transport: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
         maxPlaintextBytes: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"auto">]>, z.ZodTransform<number | undefined, number | "auto">>>;
+        maxFutureSkewSeconds: z.ZodOptional<z.ZodNumber>;
+        maxRequestAgeSeconds: z.ZodOptional<z.ZodNumber>;
         routePlaintextBytes: z.ZodOptional<z.ZodRecord<z.ZodCustom<`/${string}`, `/${string}`>, z.ZodNumber>>;
         keyExchangePath: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
         excludePaths: z.ZodDefault<z.ZodArray<z.ZodCustom<`/${string}`, `/${string}`>>>;
@@ -494,7 +472,7 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
         port: number;
     } | undefined;
     http?: {
-        trustedProxies: string[] | "auto";
+        trustedProxies: "auto" | string[];
         access: false | {
             file: string;
         } | {
@@ -509,7 +487,7 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
                 }[];
                 id: string;
                 paths: string[];
-                methods: ("GET" | "HEAD" | "OPTIONS" | "POST" | "PUT" | "PATCH" | "DELETE" | "CONNECT" | "TRACE")[];
+                methods: ("GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "CONNECT" | "TRACE")[];
                 encryption?: "required" | "disabled" | undefined;
             }[];
             global?: {
@@ -523,7 +501,7 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
                 }[];
             } | undefined;
         };
-        apiPrefix: `/api/${string}`;
+        apiPrefix: `/${string}`;
         openapi: false | {
             path: `/${string}`;
         };
@@ -535,12 +513,6 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
             path: `/${string}`;
             readyPath: `/${string}`;
         };
-        rpc: false | {
-            prefix: `/${string}`;
-            access: "loopback" | "private-network" | "gateway-only";
-            gatewayHeader?: string | undefined;
-            gatewaySecret?: string | undefined;
-        };
     } | undefined;
     cors?: {
         allowedHeaders: string[];
@@ -553,6 +525,8 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
         keyExchangePath: `/${string}`;
         excludePaths: `/${string}`[];
         maxPlaintextBytes?: number | undefined;
+        maxFutureSkewSeconds?: number | undefined;
+        maxRequestAgeSeconds?: number | undefined;
         routePlaintextBytes?: Record<`/${string}`, number> | undefined;
     } | undefined;
 }>>;
@@ -577,6 +551,10 @@ interface ServTransportConfig {
     /** 受管服务端密钥环，仅运行时从私有 Secret 注入。 */
     /** 双向业务明文 UTF-8 字节上限；默认 1 MiB，整数范围 1 KiB～64 MiB。 */
     readonly maxPlaintextBytes?: number;
+    /** 请求时间允许领先服务器的秒数，默认 30，整数范围 0～300。 */
+    readonly maxFutureSkewSeconds?: number;
+    /** 请求从签发起的有效秒数，默认 300，整数范围 1～600。 */
+    readonly maxRequestAgeSeconds?: number;
     /** 路由明文容量；* 匹配一个完整路径段。 */
     routePlaintextBytes?: Readonly<Record<string, number>>;
     readonly serverKeyRing: TransportServerKeyRing;
@@ -954,8 +932,8 @@ interface ServListenOptions {
      * 优雅关闭回调（释放业务模块资源）。
      *
      * 传入后 `serv.listen` 自动监听 `SIGINT` / `SIGTERM`，按以下顺序关闭：
-     * 1. 停止接受新 HTTP 连接
-     * 2. 调用此回调释放业务资源
+     * 1. 停止接受新 HTTP 连接，关闭 Audio WebSocket（未配合者最多等待一秒）
+     * 2. 等待监听句柄关闭，再调用此回调释放业务资源
      *
      * 应用层无需手动注册 `process.once('SIGINT', ...)` 或维护 `shuttingDown` 标志。
      */
@@ -983,7 +961,7 @@ interface ServNodeServer {
         readonly host: string;
         readonly port: number;
     };
-    /** 优雅关闭服务器并等待已有连接断开。 */
+    /** 停止接入或取消待完成绑定；关闭语音连接最多等待一秒。并发关闭复用结果，真实监听失败仍会拒绝。 */
     readonly close: () => Promise<void>;
 }
 /**
@@ -1059,6 +1037,23 @@ interface ServCorsConfig {
  */
 declare function cors(config?: ServCorsConfig): ServMiddleware;
 
+/**
+ * 获取 Serv 模块的 i18n 消息。
+ *
+ * 单次调用可通过 `options.locale` 指定该次调用使用的语言，
+ * 用于在请求处理过程中根据 `Accept-Language` 头本地化错误消息，
+ * 而不污染全局 locale（多并发请求安全）。
+ *
+ * @example
+ * ```ts
+ * import { serv } from '@h-ai/serv'
+ *
+ * const message = serv.m('serv_validationStringMin', { locale: 'en-US', params: { min: 3 } })
+ * // 单次 locale 不修改并发请求的全局语言。
+ * ```
+ */
+declare const servM: (key: "serv_transportPlaintextRequired" | "$schema" | "serv_validationFailed" | "serv_validationRequired" | "serv_validationInvalid" | "serv_validationInvalidType" | "serv_validationUnexpectedFields" | "serv_validationStringMin" | "serv_validationStringMax" | "serv_validationNumberMin" | "serv_validationNumberMax" | "serv_validationArrayMin" | "serv_validationArrayMax" | "serv_validationTooSmall" | "serv_validationTooBig" | "serv_validationEmail" | "serv_validationUrl" | "serv_validationUuid" | "serv_validationEnum" | "serv_errorUnauthorized" | "serv_errorForbidden" | "serv_errorInternal" | "serv_storageKeyRequired" | "serv_storageKeyTooLong" | "serv_storageKeyIllegalChars" | "serv_storageKeyDotSegments" | "serv_iamCannotDeleteCurrentUser" | "serv_transportInvalidPayload" | "serv_transportUnknownClient" | "serv_transportClientIdRequired" | "serv_transportClientKeyNotFound" | "serv_transportDecryptFailed" | "serv_transportEncryptFailed" | "serv_transportKeyExchangeFailed" | "serv_transportBusy" | "serv_feedbackUnavailable" | "serv_invalidApiPrefix", options?: _h_ai_core.MessageOptions) => string;
+
 /**
  * @h-ai/serv — OpenAPI 文档
  *
@@ -1142,11 +1137,13 @@ interface ServRuntimeSecurityPolicyInput {
 interface ServRuntimeSecurityPolicy {
     readonly allowOrigin: (origin: string) => boolean;
     readonly isNativeOrigin: (origin: string) => boolean;
+    /** 刷新 Cookie 是否启用 Secure，默认在生产开启。 */
     readonly secureRefreshCookie: boolean;
     readonly exposeApiDocs: boolean;
 }
 /**
  * 校验部署 Origin 并生成 Cookie、文档与跨端 CORS 安全策略。
+ * `HAI_SERV_REFRESH_COOKIE_SECURE` 可覆盖刷新 Cookie 的 Secure 默认值。
  *
  * @param input - 部署环境与显式允许的 Web/原生 Origin
  * @returns 可用于 HTTP 装配的策略
@@ -1337,26 +1334,28 @@ declare function resolveRequestLocale(headers: Headers | Record<string, string |
 declare function validateInputOrFail<TOutput>(schema: ZodType<TOutput>, input: unknown, locale?: string): HaiResult<TOutput>;
 
 /**
- * hai-framework API service runtime 统一入口（扁平 API）。
+ * @h-ai/serv — 公开类型聚合
  *
+ * 将各模块对外暴露的类型集中在此重导出，方便消费方按需 `import type`。
+ * @module serv-types
+ */
+
+/**
+ * Serv 公开命名空间；显式函数签名避免消费者声明引用内部共享构建块。
  * @example
  * ```ts
- * import type { ServContext } from '@h-ai/serv'
- * import { apiContract } from '@h-ai/api-contract'
+ * import type { ServFunctions } from '@h-ai/serv'
  * import { serv } from '@h-ai/serv'
  *
- * const contract = apiContract.create({})
- * const procedures = serv.implement(contract).context<ServContext>().build()
- * const app = serv.createApp({ contract, procedures })
- *
- * const response = await app.request('/health')
- * if (!response.ok) throw new Error('Health request failed')
+ * const runtime: ServFunctions = serv
+ * const context = runtime.parseRequestContext({ request: new Request('https://example.com') })
+ * void context.requestId
  * ```
  */
-declare const serv: {
+interface ServFunctions {
     createApp: typeof createApp;
-    parseRequestContext: typeof parseRequestContext;
-    buildAuthContextFactory: typeof buildAuthContextFactory;
+    parseRequestContext: (input: CreateServContextInput) => ServContext;
+    buildAuthContextFactory: (verifyToken: (accessToken: string) => Promise<HaiResult<ServSession>>) => CreateServContext;
     resolveRequestLocale: typeof resolveRequestLocale;
     listen: typeof listen;
     toFetch: typeof toFetch;
@@ -1364,11 +1363,41 @@ declare const serv: {
     storageAssets: typeof storageAssets;
     createRuntimeSecurityPolicy: typeof createRuntimeSecurityPolicy;
     generateSpec: typeof generateSpec;
-    implement: typeof implement;
+    implement: <TContract extends ContractRouter<Meta>>(contract: TContract) => ServImplementer<TContract>;
     validateInputOrFail: typeof validateInputOrFail;
     WILDCARD_PERMISSION: string;
     WILDCARD_ROLE: string;
-    m: (key: "serv_transportPlaintextRequired" | "$schema" | "serv_validationFailed" | "serv_validationRequired" | "serv_validationInvalid" | "serv_validationInvalidType" | "serv_validationUnexpectedFields" | "serv_validationStringMin" | "serv_validationStringMax" | "serv_validationNumberMin" | "serv_validationNumberMax" | "serv_validationArrayMin" | "serv_validationArrayMax" | "serv_validationTooSmall" | "serv_validationTooBig" | "serv_validationEmail" | "serv_validationUrl" | "serv_validationUuid" | "serv_validationEnum" | "serv_errorUnauthorized" | "serv_errorForbidden" | "serv_errorInternal" | "serv_storageKeyRequired" | "serv_storageKeyTooLong" | "serv_storageKeyIllegalChars" | "serv_storageKeyDotSegments" | "serv_iamCannotDeleteCurrentUser" | "serv_transportInvalidPayload" | "serv_transportUnknownClient" | "serv_transportClientIdRequired" | "serv_transportClientKeyNotFound" | "serv_transportDecryptFailed" | "serv_transportEncryptFailed" | "serv_transportKeyExchangeFailed" | "serv_transportBusy" | "serv_feedbackUnavailable", options?: _h_ai_core.MessageOptions) => string;
-};
+    m: typeof servM;
+}
+
+/**
+ * @h-ai/serv — API service runtime 统一入口
+ *
+ * 将 createApp、parseRequestContext、buildAuthContextFactory、listen、toFetch、openapi、pipeline 工具集合为扁平
+ * 的 `serv` 命名空间，应用层通过这个模块访问所有 runtime 能力而无需直接导入内部文件。
+ *
+ * @module serv-main
+ *
+ */
+
+/**
+ * hai-framework API service runtime 统一入口（扁平 API）。
+ *
+ * @example
+ * ```ts
+ * import type { ServContext } from '@h-ai/serv'
+ * import { apiContract } from '@h-ai/api-contract'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const contract = apiContract.create({})
+ * const procedures = serv.implement(contract).context<ServContext>().build()
+ * const app = serv.createApp({ contract, procedures })
+ *
+ * const response = await app.request('/health')
+ * if (!response.ok) throw new Error('Health request failed')
+ * ```
+ */
+declare const serv: ServFunctions;
 
-export { type AudioTicketGrant, type AudioTicketVerification, type AuthorizedAudioRequest, type CreateServAppOptions, CreateServContext, type GenerateOpenAPISpecOptions, RefreshCookieConfig, type ServAudioConfig, type ServConfig, type ServConfigInput, ServConfigSchema, ServContext, type ServCorsConfig, type ServCorsRuntimeConfig, type ServCorsRuntimeConfigInput, type ServDocsHttpConfig, type ServFetchHandler, type ServHealthHttpConfig, type ServHttpApp, type ServHttpConfig, type ServHttpConfigInput, ServIam, type ServListenOptions, type ServMiddleware, type ServMiddlewareFactory, type ServMiddlewareMount, type ServNodeServer, type ServOpenAPIHttpConfig, type ServProcedureHandler, type ServProcedureOptions, ServRequestMetadata, type ServRpcHttpConfig, type ServRuntimeSecurityPolicy, type ServRuntimeSecurityPolicyInput, type ServServerConfig, type ServServerConfigInput, ServSession, type ServStorageAssetsConfig, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };
+export { CreateServContext, CreateServContextInput, RefreshCookieConfig, ServConfigSchema, ServContext, ServIam, ServImplementer, ServRequestMetadata, ServSession, serv };
+export type { AudioTicketGrant, AudioTicketVerification, AuthorizedAudioRequest, CreateServAppOptions, GenerateOpenAPISpecOptions, ServAudioConfig, ServConfig, ServConfigInput, ServCorsConfig, ServCorsRuntimeConfig, ServCorsRuntimeConfigInput, ServDocsHttpConfig, ServFetchHandler, ServFunctions, ServHealthHttpConfig, ServHttpApp, ServHttpConfig, ServHttpConfigInput, ServListenOptions, ServMiddleware, ServMiddlewareFactory, ServMiddlewareMount, ServNodeServer, ServOpenAPIHttpConfig, ServProcedureHandler, ServProcedureOptions, ServRuntimeSecurityPolicy, ServRuntimeSecurityPolicyInput, ServServerConfig, ServServerConfigInput, ServStorageAssetsConfig, ServTransportConfig, ServTransportRuntimeConfig, ServTransportRuntimeConfigInput, ServValidationFailureBody };