@servora/proto-utils 0.0.2 → 0.1.1

package/src/client/request.ts

@@ -0,0 +1,233 @@
+/**
+ * @servora/proto-utils/client — 通用 HTTP 请求处理器
+ *
+ * 为 proto 生成的 TypeScript client 提供标准 RequestHandler 实现，包含：
+ * - Bearer token 自动注入
+ * - Token 自动刷新（单例防重复）
+ * - 结构化 ApiError（区分 http / network / timeout）
+ * - 全局 onError 回调（延迟到宏任务，避免与 toast.promise 竞态）
+ *
+ * 消费方通过 @servora/proto-utils 使用本实现，ofetch 由本包依赖提供。
+ */
+
+import type { FetchOptions } from "ofetch";
+import { ofetch } from "ofetch";
+
+export type RequestType = {
+  path: string;
+  method: string;
+  body: string | null;
+};
+
+export type RequestMeta = {
+  service: string;
+  method: string;
+};
+
+export type RequestHandler = (
+  request: RequestType,
+  meta: RequestMeta,
+) => Promise<unknown>;
+
+export interface TokenStore {
+  getAccessToken: () => string | null;
+  getRefreshToken: () => string | null;
+  setTokens: (accessToken: string, refreshToken: string) => void;
+  clear: () => void;
+}
+
+export interface RequestHandlerOptions {
+  baseUrl?: string;
+  tokenStore?: TokenStore;
+  contextHeaders?: (meta: RequestMeta) => Record<string, string>;
+  timeoutMs?: number;
+  onError?: (error: ApiError, meta: RequestMeta) => void;
+  autoRefreshToken?: boolean;
+}
+
+export type ApiErrorKind = "http" | "network" | "timeout";
+
+export class ApiError extends Error {
+  readonly kind: ApiErrorKind;
+  readonly httpStatus?: number;
+  readonly responseBody?: unknown;
+  readonly service: string;
+  readonly method: string;
+
+  constructor(opts: {
+    kind: ApiErrorKind;
+    message: string;
+    httpStatus?: number;
+    responseBody?: unknown;
+    service: string;
+    method: string;
+    cause?: unknown;
+  }) {
+    super(opts.message, { cause: opts.cause });
+    this.name = "ApiError";
+    this.kind = opts.kind;
+    this.httpStatus = opts.httpStatus;
+    this.responseBody = opts.responseBody;
+    this.service = opts.service;
+    this.method = opts.method;
+  }
+}
+
+function ensureLeadingSlash(path: string): string {
+  return path.startsWith("/") ? path : `/${path}`;
+}
+
+const REFRESH_PATH = "/v1/auth/refresh-token";
+const AUTH_PATH_PREFIX = "/v1/auth/";
+
+export function createRequestHandler(
+  options: RequestHandlerOptions = {},
+): RequestHandler {
+  const {
+    baseUrl = "",
+    tokenStore,
+    contextHeaders,
+    timeoutMs = 30_000,
+    onError,
+    autoRefreshToken = false,
+  } = options;
+
+  let refreshPromise: Promise<boolean> | null = null;
+
+  async function tryRefreshToken(): Promise<boolean> {
+    if (!tokenStore) return false;
+    const refreshToken = tokenStore.getRefreshToken();
+    if (!refreshToken) return false;
+
+    if (refreshPromise) return refreshPromise;
+
+    refreshPromise = (async () => {
+      try {
+        const data = await ofetch<{
+          accessToken: string;
+          refreshToken: string;
+        }>(REFRESH_PATH, {
+          baseURL: baseUrl,
+          method: "POST",
+          body: { refreshToken },
+          timeout: timeoutMs,
+        });
+        tokenStore.setTokens(data.accessToken, data.refreshToken);
+        return true;
+      } catch {
+        tokenStore.clear();
+        return false;
+      } finally {
+        refreshPromise = null;
+      }
+    })();
+
+    return refreshPromise;
+  }
+
+  async function doRequest(
+    request: RequestType,
+    meta: RequestMeta,
+    isRetry = false,
+  ): Promise<unknown> {
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+    };
+
+    if (request.body) {
+      headers["Content-Type"] = "application/json";
+    }
+
+    if (tokenStore) {
+      const token = tokenStore.getAccessToken();
+      if (token) {
+        headers.Authorization = `Bearer ${token}`;
+      }
+    }
+
+    if (contextHeaders) {
+      Object.assign(headers, contextHeaders(meta));
+    }
+
+    const fetchOptions: FetchOptions = {
+      baseURL: baseUrl,
+      method: request.method as FetchOptions["method"],
+      headers,
+      timeout: timeoutMs,
+    };
+
+    if (request.body) {
+      fetchOptions.body = request.body;
+    }
+
+    const normalizedPath = ensureLeadingSlash(request.path);
+
+    try {
+      return await ofetch(normalizedPath, fetchOptions);
+    } catch (err: unknown) {
+      const fetchError =
+        err != null && typeof err === "object"
+          ? (err as Record<string, unknown>)
+          : {};
+      const response = fetchError.response as
+        | { status: number; _data?: unknown }
+        | undefined;
+
+      if (response) {
+        const status = response.status;
+        const body = response._data;
+
+        const apiErr = new ApiError({
+          kind: "http",
+          message: `HTTP ${status} on ${meta.service}.${meta.method}`,
+          httpStatus: status,
+          responseBody: body,
+          service: meta.service,
+          method: meta.method,
+          cause: err,
+        });
+
+        if (
+          autoRefreshToken &&
+          status === 401 &&
+          !isRetry &&
+          !normalizedPath.startsWith(AUTH_PATH_PREFIX)
+        ) {
+          const refreshed = await tryRefreshToken();
+          if (refreshed) {
+            return doRequest(request, meta, true);
+          }
+        }
+
+        // 延迟到宏任务再调 onError，让 promise 链先跑完（含 toast.promise 的 _mark），
+        // 避免全局 handler 与 sonner.promise error callback 同时弹出双重 toast。
+        if (onError) {
+          const _err = apiErr;
+          setTimeout(() => onError(_err, meta), 0);
+        }
+        throw apiErr;
+      }
+
+      const rawMessage =
+        typeof fetchError.message === "string" ? fetchError.message : "";
+      const kind: ApiErrorKind = rawMessage.toLowerCase().includes("timeout")
+        ? "timeout"
+        : "network";
+
+      const apiErr = new ApiError({
+        kind,
+        message: `${kind} error on ${meta.service}.${meta.method}: ${rawMessage}`,
+        service: meta.service,
+        method: meta.method,
+        cause: err,
+      });
+      if (onError) {
+        const _err = apiErr;
+        setTimeout(() => onError(_err, meta), 0);
+      }
+      throw apiErr;
+    }
+  }
+
+  return doRequest;
+}

package/src/gen/servora/audit/v1/index.ts

@@ -0,0 +1,64 @@
+// Code generated by protoc-gen-typescript-http. DO NOT EDIT.
+/* eslint-disable camelcase */
+// @ts-nocheck
+
+// AuditMode 表达审计开关三态。
+// 引入「服务级默认 + 方法级覆盖」机制后，proto3 bool 默认值与「未指定」无法区分；
+// 用 enum 三态可让方法级显式继承（UNSPECIFIED）/ 显式覆盖（DISABLED/ENABLED）语义清晰。
+// 迁移说明：从 v0.x 起替代原 `bool enabled` 字段；旧写法 `enabled: true` 迁移为
+// `mode: AUDIT_MODE_ENABLED`，`enabled: false` 迁移为 `mode: AUDIT_MODE_DISABLED`，
+// 未指定保留为 `AUDIT_MODE_UNSPECIFIED` 表示继承服务级默认。
+export type AuditMode =
+  | "AUDIT_MODE_UNSPECIFIED"
+  | "AUDIT_MODE_DISABLED"
+  | "AUDIT_MODE_ENABLED";
+// ExtensionMapping 将一个 CloudEvents 扩展属性映射到请求/响应字段或字面值。
+// 用于在注解中声明运行时需要从请求/响应消息中提取哪些值作为事件扩展属性。
+export type ExtensionMapping = {
+  // CloudEvents 扩展属性名称（如 "mutation"、"resourcetype"）。
+  name: string | undefined;
+  // 从请求/响应消息的 proto field path 提取（如 "req.id"、"resp.name"）。
+  fromField?: string;
+  // 字面值，直接写入事件扩展属性。
+  literal?: servoracloudeventsv1_CloudEvent_CloudEventAttributeValue;
+};
+
+// The CloudEvent specification defines seven attribute value types.
+export type servoracloudeventsv1_CloudEvent_CloudEventAttributeValue = {
+  ceBoolean?: boolean;
+  ceInteger?: number;
+  ceString?: string;
+  ceBytes?: string;
+  ceUri?: string;
+  ceUriRef?: string;
+  ceTimestamp?: wellKnownTimestamp;
+};
+
+// Encoded using RFC 3339, where generated output will always be Z-normalized
+// and uses 0, 3, 6 or 9 fractional digits.
+// Offsets other than "Z" are also accepted.
+type wellKnownTimestamp = string;
+
+// AuditRule 声明一个 RPC 方法的审计规则。
+// 与 CloudEvents 对齐：event_type 和 severity 映射到 CloudEvents type 与扩展属性，
+// extensions 允许声明式地从请求/响应中提取任意扩展属性。
+export type AuditRule = {
+  // 是否产生审计事件。UNSPECIFIED 表示沿用服务级默认或框架默认。
+  mode: AuditMode | undefined;
+  // CloudEvents type 属性值（如 "servora.audit.resource_mutation"）。
+  eventType: string | undefined;
+  // 事件严重级别（如 "info"、"warning"、"critical"）。
+  // 映射到 CloudEvents 扩展属性 "severity"。
+  severity: string | undefined;
+  // detail message 的 proto field path（如 "req"），
+  // 运行时序列化后作为 CloudEvent data 载荷。留空则不附带详情。
+  detailMessageField: string | undefined;
+  // 目标 ID 的 proto field path（如 "req.id"、"resp.id"）。
+  // 由 protoc-gen-servora-audit 生成提取函数，留空则不提取。
+  targetIdField: string | undefined;
+  // 额外的 CloudEvents 扩展属性映射。
+  extensions: ExtensionMapping[] | undefined;
+};
+
+
+// @@protoc_insertion_point(typescript-http-eof)

package/src/gen/servora/authn/v1/index.ts

@@ -0,0 +1,25 @@
+// Code generated by protoc-gen-typescript-http. DO NOT EDIT.
+/* eslint-disable camelcase */
+// @ts-nocheck
+
+// AuthnRule 声明 RPC 方法的认证策略。
+export type AuthnRule = {
+  // 认证模式。
+  mode: AuthnRule_Mode | undefined;
+  // 接受的认证机制；空列表表示沿用框架默认引擎。
+  // 取值是各 wrapper 子包持有的私有 method 字符串常量（如 `jwt`、`mtls`、`api_key`、`aksk`）；
+  // framework 不枚举这些值，业务自定义引擎也可填任意字符串。
+  // 多个值表示"任一通过即可"。
+  schemes: string[] | undefined;
+};
+
+// Mode 表达认证模式三态。
+export type AuthnRule_Mode =
+  // 未指定，等价"未写注解"：私有 + 框架默认引擎（fail-closed 默认）。
+  | "MODE_UNSPECIFIED"
+  // 显式公开。schemes 必须为空。
+  | "MODE_PUBLIC"
+  // 必须用 schemes 指定的认证机制。schemes 必须非空。
+  | "MODE_REQUIRED";
+
+// @@protoc_insertion_point(typescript-http-eof)

package/src/gen/servora/authz/v1/index.ts

@@ -0,0 +1,28 @@
+// Code generated by protoc-gen-typescript-http. DO NOT EDIT.
+/* eslint-disable camelcase */
+// @ts-nocheck
+
+// AuthzMode defines the authorization mode for an RPC method.
+export type AuthzMode =
+  // Unspecified — treated as fail-closed.
+  | "AUTHZ_MODE_UNSPECIFIED"
+  // Skip authorization entirely (public endpoint).
+  | "AUTHZ_MODE_NONE"
+  // Perform an authorization check using action / resource_type / resource_id_field.
+  | "AUTHZ_MODE_CHECK";
+// AuthzRule binds authorization requirements to an RPC method.
+// action and resource_type are free strings matching the authorization model.
+export type AuthzRule = {
+  // Authorization mode.
+  mode: AuthzMode | undefined;
+  // Action to check, e.g. "admin", "can_delete", "view".
+  action: string | undefined;
+  // Resource type, e.g. "platform", "video", "server".
+  resourceType: string | undefined;
+  // Proto field name in the request that carries the resource ID, e.g. "id".
+  // When empty, a static default resource ID is used (singleton/platform-level checks).
+  resourceIdField: string | undefined;
+};
+
+
+// @@protoc_insertion_point(typescript-http-eof)

package/src/gen/servora/cloudevents/v1/index.ts

@@ -0,0 +1,49 @@
+// Code generated by protoc-gen-typescript-http. DO NOT EDIT.
+/* eslint-disable camelcase */
+// @ts-nocheck
+
+export type CloudEvent = {
+  // Required Attributes
+  id: string | undefined;
+  source: string | undefined;
+  specVersion: string | undefined;
+  type: string | undefined;
+  // Optional & Extension Attributes
+  attributes: { [key: string]: CloudEvent_CloudEventAttributeValue } | undefined;
+  binaryData?: string;
+  textData?: string;
+  protoData?: wellKnownAny;
+};
+
+// The CloudEvent specification defines seven attribute value types.
+export type CloudEvent_CloudEventAttributeValue = {
+  ceBoolean?: boolean;
+  ceInteger?: number;
+  ceString?: string;
+  ceBytes?: string;
+  ceUri?: string;
+  ceUriRef?: string;
+  ceTimestamp?: wellKnownTimestamp;
+};
+
+// Encoded using RFC 3339, where generated output will always be Z-normalized
+// and uses 0, 3, 6 or 9 fractional digits.
+// Offsets other than "Z" are also accepted.
+type wellKnownTimestamp = string;
+
+// If the Any contains a value that has a special JSON mapping,
+// it will be converted as follows:
+// {"@type": xxx, "value": yyy}.
+// Otherwise, the value will be converted into a JSON object,
+// and the "@type" field will be inserted to indicate the actual data type.
+interface wellKnownAny {
+  "@type": string;
+  [key: string]: unknown;
+}
+
+export type CloudEventBatch = {
+  events: CloudEvent[] | undefined;
+};
+
+
+// @@protoc_insertion_point(typescript-http-eof)

package/src/gen/servora/conf/v1/index.ts

@@ -0,0 +1,32 @@
+// Code generated by protoc-gen-typescript-http. DO NOT EDIT.
+/* eslint-disable camelcase */
+// @ts-nocheck
+
+// SectionRule 声明一个配置 message 在外部 yaml / json 配置中的定位键。
+// 应用方通过 bootstrap.Scan 按该 key 在 kratos config 中定向 scan。
+export type SectionRule = {
+  // 配置文件中的定位键（支持 dotted path，如 "audit" 或 "authn.oidc"）。
+  // 不应留空。
+  key: string | undefined;
+  // 是否允许该 section 在配置中缺失而不报错。
+  // optional=true：缺失静默跳过 scan，但 message 仍会经 ApplyDefaults 填默认值；
+  // optional=false（默认）：缺失视为配置错误。
+  optional: boolean | undefined;
+};
+
+// FieldRule 声明一个配置字段的默认值与必填语义。
+// default 与 required 互斥使用：required=true 表示用户必须显式提供（零值不接受），
+// default 表示用户未提供时填入字面量。
+export type FieldRule = {
+  // 字段默认值的字面量表达。
+  // - string 字段：直接字面量（如 "tcp"）；
+  // - 数字 / bool 字段：可解析为对应类型的字符串（如 "8080" / "true"）；
+  // - google.protobuf.Duration：Go duration 字符串（如 "24h" / "5s"）；
+  // - repeated 标量：逗号分隔（如 "GET,POST,OPTIONS"）。
+  default: string | undefined;
+  // 是否必填。若 true，由 plugin 生成 Validate() 在零值时返回 error。
+  required: boolean | undefined;
+};
+
+
+// @@protoc_insertion_point(typescript-http-eof)

package/src/gen/servora/core/v1/index.ts

@@ -0,0 +1,221 @@
+// Code generated by protoc-gen-typescript-http. DO NOT EDIT.
+/* eslint-disable camelcase */
+// @ts-nocheck
+
+export type Bootstrap = {
+  app: App | undefined;
+  server: Server | undefined;
+  data: Data | undefined;
+  registry: Registry | undefined;
+  source: Source | undefined;
+  obs: Observability | undefined;
+};
+
+export type App = {
+  env: string | undefined;
+  name: string | undefined;
+  version: string | undefined;
+  // field 5 reserved (was App.Log, moved to Bootstrap.obs.log)
+  metadata: { [key: string]: string } | undefined;
+  externalUrl: string | undefined;
+};
+
+// 通信服务端配置
+export type Server = {
+  http: Server_HTTP | undefined;
+  grpc: Server_GRPC | undefined;
+};
+
+export type Server_HTTP = {
+  listen: Server_Listen | undefined;
+  tls: servorasecuritytlsv1_TLS | undefined;
+  advertise: Server_Advertise | undefined;
+};
+
+// 监听配置（面向 net.Listen 参数）
+export type Server_Listen = {
+  network: string | undefined;
+  addr: string | undefined;
+  timeout: wellKnownDuration | undefined;
+};
+
+// Generated output always contains 0, 3, 6, or 9 fractional digits,
+// depending on required precision, followed by the suffix "s".
+// Accepted are any fractional digits (also none) as long as they fit
+// into nano-seconds precision and the suffix "s" is required.
+type wellKnownDuration = string;
+
+export type servorasecuritytlsv1_TLS = {
+  enable: boolean | undefined;
+  certPath: string | undefined;
+  keyPath: string | undefined;
+  caPath: string | undefined;
+};
+
+// 服务注册端点覆盖（用于注册中心对外公布地址）
+export type Server_Advertise = {
+  endpoint: string | undefined;
+  host: string | undefined;
+};
+
+export type Server_GRPC = {
+  listen: Server_Listen | undefined;
+  tls: servorasecuritytlsv1_TLS | undefined;
+  advertise: Server_Advertise | undefined;
+};
+
+// 数据源配置（仅保留 database / client 等核心数据源）
+export type Data = {
+  database: Data_Database | undefined;
+  client: Data_Client | undefined;
+};
+
+export type Data_Database = {
+  driver: string | undefined;
+  source: string | undefined;
+};
+
+export type Data_Client = {
+  services: Data_Client_Service[] | undefined;
+};
+
+export type Data_Client_Service = {
+  name: string | undefined;
+  endpoints: Data_Client_Endpoint[] | undefined;
+};
+
+export type Data_Client_Endpoint = {
+  protocol: string | undefined;
+  endpoint: string | undefined;
+  timeout: wellKnownDuration | undefined;
+  tls: servorasecuritytlsv1_TLS | undefined;
+  options: wellKnownStruct | undefined;
+};
+
+// Any JSON value.
+type wellKnownStruct = Record<string, unknown>;
+
+// 注册中心配置
+export type Registry = {
+  consul?: Consul;
+  etcd?: Etcd;
+  nacos?: Nacos;
+  kubernetes?: Kubernetes;
+};
+
+// 通用 Consul 配置
+export type Consul = {
+  addr: string | undefined;
+  scheme: string | undefined;
+  token: string | undefined;
+  datacenter: string | undefined;
+  timeout: wellKnownDuration | undefined;
+  tags: string[] | undefined;
+  key: string | undefined;
+};
+
+// 通用 Etcd 配置
+export type Etcd = {
+  endpoints: string[] | undefined;
+  username: string | undefined;
+  password: string | undefined;
+  timeout: wellKnownDuration | undefined;
+  key: string | undefined;
+  namespace: string | undefined;
+};
+
+// 通用 Nacos 配置
+export type Nacos = {
+  addr: string | undefined;
+  port: number | undefined;
+  namespace: string | undefined;
+  group: string | undefined;
+  username: string | undefined;
+  password: string | undefined;
+  timeout: wellKnownDuration | undefined;
+  dataId: string | undefined;
+};
+
+// 通用 Kubernetes 配置
+export type Kubernetes = {
+  enable: boolean | undefined;
+};
+
+// 配置中心配置
+export type Source = {
+  consul?: Consul;
+  etcd?: Etcd;
+  nacos?: Nacos;
+};
+
+// 可观测性配置
+export type Observability = {
+  log: Log | undefined;
+  trace: Trace | undefined;
+  metrics: Metrics | undefined;
+};
+
+// 日志配置（与 App 同级，所有 message/enum nested）
+export type Log = {
+  level: Log_LogLevel | undefined;
+  backends: Log_LogBackend[] | undefined;
+};
+
+export type Log_LogLevel =
+  | "LOG_LEVEL_UNSPECIFIED"
+  | "LOG_LEVEL_DEBUG"
+  | "LOG_LEVEL_INFO"
+  | "LOG_LEVEL_WARN"
+  | "LOG_LEVEL_ERROR";
+export type Log_LogBackend = {
+  stdout?: Log_StdoutBackend;
+  file?: Log_FileBackend;
+  otel?: Log_OtelBackend;
+  noop?: Log_NoopBackend;
+};
+
+export type Log_StdoutBackend = {
+  format: Log_LogFormat | undefined;
+};
+
+export type Log_LogFormat =
+  | "LOG_FORMAT_UNSPECIFIED"
+  | "LOG_FORMAT_JSON"
+  | "LOG_FORMAT_TEXT";
+export type Log_FileBackend = {
+  path: string | undefined;
+  maxSize: number | undefined;
+  maxBackups: number | undefined;
+  maxAge: number | undefined;
+  compress: boolean | undefined;
+  format: Log_LogFormat | undefined;
+};
+
+export type Log_OtelBackend = {
+  endpoint: string | undefined;
+  protocol: Log_OtelProtocol | undefined;
+  insecure: boolean | undefined;
+};
+
+export type Log_OtelProtocol =
+  | "OTEL_PROTOCOL_UNSPECIFIED"
+  | "OTEL_PROTOCOL_GRPC"
+  | "OTEL_PROTOCOL_HTTP_PROTOBUF";
+export type Log_NoopBackend = {
+};
+
+// 链路追踪配置
+export type Trace = {
+  endpoint: string | undefined;
+  insecure: boolean | undefined;
+  samplingRatio: number | undefined;
+  caPath: string | undefined;
+};
+
+// Metrics 配置
+export type Metrics = {
+  enable: boolean | undefined;
+};
+
+
+// @@protoc_insertion_point(typescript-http-eof)

package/src/gen/servora/infra/db/clickhouse/v1/index.ts

@@ -0,0 +1,33 @@
+// Code generated by protoc-gen-typescript-http. DO NOT EDIT.
+/* eslint-disable camelcase */
+// @ts-nocheck
+
+export type ClickHouse = {
+  addrs: string[] | undefined;
+  database: string | undefined;
+  username: string | undefined;
+  password: string | undefined;
+  dialTimeout: wellKnownDuration | undefined;
+  readTimeout: wellKnownDuration | undefined;
+  maxOpenConns: number | undefined;
+  maxIdleConns: number | undefined;
+  connMaxLifetime: wellKnownDuration | undefined;
+  tls: servorasecuritytlsv1_TLS | undefined;
+  compression: string | undefined;
+};
+
+// Generated output always contains 0, 3, 6, or 9 fractional digits,
+// depending on required precision, followed by the suffix "s".
+// Accepted are any fractional digits (also none) as long as they fit
+// into nano-seconds precision and the suffix "s" is required.
+type wellKnownDuration = string;
+
+export type servorasecuritytlsv1_TLS = {
+  enable: boolean | undefined;
+  certPath: string | undefined;
+  keyPath: string | undefined;
+  caPath: string | undefined;
+};
+
+
+// @@protoc_insertion_point(typescript-http-eof)