@h-ai/serv 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/index.d.ts

@@ -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`）。
  *
@@ -281,7 +263,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 +271,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` 的顶层配置结构。
@@ -359,11 +340,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 +427,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 +439,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>;
@@ -523,7 +493,7 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
                 }[];
             } | undefined;
         };
-        apiPrefix: `/api/${string}`;
+        apiPrefix: `/${string}`;
         openapi: false | {
             path: `/${string}`;
         };
@@ -535,12 +505,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[];
@@ -1368,7 +1332,7 @@ declare const serv: {
     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: (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;
 };
 
-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 { 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 ServRuntimeSecurityPolicy, type ServRuntimeSecurityPolicyInput, type ServServerConfig, type ServServerConfigInput, ServSession, type ServStorageAssetsConfig, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };

package/dist/index.js

@@ -1,13 +1,13 @@
-import { validateInputOrFail, resolveRequestLocale, localizeZodError } from './chunk-TWMOZPGU.js';
-import { servM, WILDCARD_ROLE, WILDCARD_PERMISSION, implement, buildHaiErrorBody } from './chunk-I3F7RN4I.js';
+import { validateInputOrFail, resolveRequestLocale, localizeZodError } from './chunk-IQZQTAEW.js';
+import { servM, WILDCARD_ROLE, WILDCARD_PERMISSION, implement, buildHaiErrorBody } from './chunk-FEG22LCX.js';
 import process from 'process';
 import { upgradeWebSocket, serve } from '@hono/node-server';
+import { posix } from 'path';
 import { apiContract, AUDIO_WS_PATH, AudioWsClientMessageSchema } from '@h-ai/api-contract';
 import { audit } from '@h-ai/audit';
 import { core, RequestAccessConfigSchema, TrustedProxiesSchema, HaiCommonError, err, ok } from '@h-ai/core';
 import { TRANSPORT_PLAINTEXT_RANGE, createTransportBodyPolicy, TRANSPORT_PROTOCOL, authenticateTransportRequest, TransportTimeError, createTransportErrorResponse, TransportBodyTooLargeError, readTransportBody, TRANSPORT_BODY_LIMITS, isValidSM2PublicKey } from '@h-ai/crypto';
 import { OpenAPIHandler } from '@orpc/openapi/fetch';
-import { RPCHandler } from '@orpc/server/fetch';
 import { Hono } from 'hono';
 import { WebSocketServer } from 'ws';
 import { Buffer } from 'buffer';
@@ -548,75 +548,6 @@ function toArrayBuffer(data) {
   new Uint8Array(buffer).set(data);
   return buffer;
 }
-function readRemoteAddress(metadata) {
-  if (!metadata || typeof metadata !== "object" || !("remoteAddress" in metadata) || typeof metadata.remoteAddress !== "string")
-    return void 0;
-  return core.access.normalizeClientIp(metadata.remoteAddress);
-}
-
-// src/pipelines/serv-pipeline-require-internal-rpc.ts
-var pipelineLogger = core.logger.child({ module: "serv", scope: "pipeline" });
-var cachedGetConnInfo;
-async function resolveGetConnInfo() {
-  if (cachedGetConnInfo !== void 0)
-    return cachedGetConnInfo;
-  try {
-    const mod = await import('@hono/node-server/conninfo');
-    cachedGetConnInfo = mod.getConnInfo;
-  } catch (cause) {
-    pipelineLogger.warn("getConnInfo unavailable in this runtime; loopback/private-network access modes will fail closed", { error: cause });
-    cachedGetConnInfo = null;
-  }
-  return cachedGetConnInfo;
-}
-var LOOPBACK_IPS = /* @__PURE__ */ new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1", "localhost"]);
-function requireInternalRPC(config) {
-  return async (c, next) => {
-    const locale = resolveRequestLocale(c.req.raw.headers);
-    if (config.access === "gateway-only") {
-      const headerName = config.gatewayHeader ?? "x-hai-internal-rpc";
-      const received = c.req.header(headerName);
-      if (!config.gatewaySecret || !received || !core.string.constantTimeEqual(received, config.gatewaySecret))
-        return c.json(buildHaiErrorBody(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale })), 403);
-      return next();
-    }
-    const ip = await getRequestRemoteAddress(c) ?? "";
-    if (config.access === "loopback" && !isLoopbackIP(ip))
-      return c.json(buildHaiErrorBody(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale })), 403);
-    if (config.access === "private-network" && !isPrivateNetworkIP(ip))
-      return c.json(buildHaiErrorBody(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale })), 403);
-    return next();
-  };
-}
-async function getRequestRemoteAddress(c) {
-  const remoteAddress = readRemoteAddress(c.env);
-  if (remoteAddress)
-    return remoteAddress;
-  const getConnInfo = await resolveGetConnInfo();
-  if (!getConnInfo)
-    return void 0;
-  try {
-    return getConnInfo(c).remote.address;
-  } catch {
-    return void 0;
-  }
-}
-function normalizeIpAddress(ip) {
-  return ip.startsWith("::ffff:") ? ip.slice("::ffff:".length) : ip;
-}
-function isLoopbackIP(ip) {
-  const normalized = normalizeIpAddress(ip);
-  return LOOPBACK_IPS.has(ip) || LOOPBACK_IPS.has(normalized);
-}
-function isPrivateNetworkIP(ip) {
-  const normalized = normalizeIpAddress(ip);
-  if (isLoopbackIP(ip))
-    return true;
-  if (normalized.startsWith("10.") || normalized.startsWith("192.168."))
-    return true;
-  const second = Number(normalized.split(".")[1]);
-  return normalized.startsWith("172.") && Number.isInteger(second) && second >= 16 && second <= 31;
-}
 
 // src/pipelines/serv-pipeline-security-headers.ts
 function securityHeaders() {
@@ -627,9 +558,14 @@ function securityHeaders() {
     await next();
   };
 }
+function readRemoteAddress(metadata) {
+  if (!metadata || typeof metadata !== "object" || !("remoteAddress" in metadata) || typeof metadata.remoteAddress !== "string")
+    return void 0;
+  return core.access.normalizeClientIp(metadata.remoteAddress);
+}
 var ApiPrefixSchema = z.custom(
-  (value) => typeof value === "string" && value.startsWith("/api/"),
-  "apiPrefix must start with /api/"
+  (value) => typeof value === "string" && /^\/[\w.-]+(?:\/[\w.-]+)*$/.test(value) && !value.split("/").some((segment) => segment === "." || segment === ".."),
+  { error: () => servM("serv_invalidApiPrefix") }
 );
 var AbsolutePathSchema = z.custom(
   (value) => typeof value === "string" && value.startsWith("/"),
@@ -653,15 +589,6 @@ var HealthHttpConfigInputSchema = z.union([
     readyPath: AbsolutePathSchema.optional().default("/ready")
   })
 ]);
-var RpcHttpConfigInputSchema = z.union([
-  z.literal(false),
-  z.object({
-    prefix: AbsolutePathSchema.default("/rpc"),
-    access: z.enum(["loopback", "private-network", "gateway-only"]).default("loopback"),
-    gatewayHeader: z.string().optional(),
-    gatewaySecret: z.string().optional()
-  })
-]);
 var TransportRuntimeConfigInputSchema = z.union([
   z.literal(false),
   z.object({
@@ -688,8 +615,7 @@ var ServHttpConfigInputSchema = z.object({
   apiPrefix: ApiPrefixSchema.default("/api/v1"),
   openapi: OpenAPIHttpConfigInputSchema.default(false),
   docs: DocsHttpConfigInputSchema.default(false),
-  health: HealthHttpConfigInputSchema.default({ path: "/health", readyPath: "/ready" }),
-  rpc: RpcHttpConfigInputSchema.default(false)
+  health: HealthHttpConfigInputSchema.default({ path: "/health", readyPath: "/ready" })
 });
 var ServConfigSchema = z.object({
   server: ServerConfigInputSchema.optional(),
@@ -1402,14 +1328,13 @@ function createApp(options) {
     audioWsServers.set(app, new WebSocketServer({ noServer: true }));
   }
   mountOpenAPIRoutes(app, options.procedures, http.apiPrefix, createContext);
-  if (http.rpc !== false)
-    mountRPCRoutes(app, options.procedures, http.rpc, createContext);
   if (http.openapi !== false) {
     app.get(http.openapi.path, async (c) => c.json(await getSpec()));
   }
   if (http.docs !== false) {
     const docs = http.docs;
-    app.get(SCALAR_ROUTE, async (c) => {
+    const docsDirectory = docs.path.slice(0, docs.path.lastIndexOf("/") + 1);
+    app.get(`${docsDirectory}${SCALAR_ROUTE.slice(1)}`, async (c) => {
       const content = await getScalarScript();
       if (!content)
         return c.notFound();
@@ -1423,8 +1348,8 @@ function createApp(options) {
         if (!context.session)
           return c.json(buildHaiErrorBody(HaiCommonError.UNAUTHORIZED, servM("serv_errorUnauthorized", { locale: resolveRequestLocale(c.req.raw.headers) })), 401);
       }
-      const specUrl = http.openapi === false ? void 0 : http.openapi.path;
-      return c.html(createDocsPage(await getSpec(), { specUrl }));
+      const specUrl = http.openapi === false ? void 0 : posix.relative(docsDirectory, http.openapi.path) || ".";
+      return c.html(createDocsPage(await getSpec(), { specUrl, scriptUrl: SCALAR_ROUTE.slice(1) }));
     });
   }
   return app;
@@ -1442,12 +1367,6 @@ function mountOpenAPIRoutes(app, procedures, apiPrefix, createContext) {
   const handler = new OpenAPIHandler(procedures);
   app.on([...API_METHODS], `${apiPrefix}/*`, (c, next) => handleORPC(c, next, apiPrefix, handler, createContext));
 }
-function mountRPCRoutes(app, procedures, rpcConfig, createContext) {
-  const handler = new RPCHandler(procedures);
-  const prefix = rpcConfig.prefix;
-  app.use(`${prefix}/*`, requireInternalRPC(rpcConfig));
-  app.on([...API_METHODS], `${prefix}/*`, (c, next) => handleORPC(c, next, prefix, handler, createContext));
-}
 async function handleORPC(c, next, prefix, handler, createContext) {
   const context = await createContext({ request: c.req.raw, remoteAddress: readRemoteAddress(c.env) });
   const { matched, response } = await core.context.run({ requestId: context.requestId, userId: context.session?.userId, scopeId: context.scopeId }, () => handler.handle(c.req.raw, { prefix, context }));