@deepexi/datasense-connector 3.0.1 → 3.1.0

package/src/testing/import-guard.ts

@@ -0,0 +1,221 @@
+/**
+ * 本地源码加载器的导入检查（不执行任何代码，只用调用方传入的 TypeScript 编译器 API 解析语法树）。
+ *
+ * 两层：
+ * 1. `findForbiddenSourceSyntax`：与 shared `server/connector-source-guard.ts` 的同名函数规则相同（SDK 不依赖 shared，
+ *    这里另写一份，`test/testing/import-guard.test.ts` 用同一批样例对照两份实现）：
+ *    - 任何 import 属性 / 断言（静态 `import`、`export … from` 的 `with` / `assert`，动态 `import(x, options)` 的第二参）；
+ *    - `macro:` 开头的说明符；
+ *    - SDK 只认精确的 `@deepexi/datasense-connector`：子路径（含 `/testing`）与改名前的旧包名都拒绝；
+ *    - TypeScript 解析出的语法错误。
+ * 2. `classifySpecifier`：转译后代码里每个 `require(…)` 的说明符（与服务端打包插件的白名单相同）：只允许相对路径与
+ *    `@deepexi/datasense-connector`；`node:*` 与 Node 内置模块、裸包名、绝对路径与 URL 说明符都拒绝；逃出源码根的相对路径
+ *    单独报 `PATH_ESCAPE`。
+ */
+import type * as TS from 'typescript';
+
+export type TypeScriptApi = typeof TS;
+
+export interface SourceGuardDiagnostic {
+  /** 相对源码根目录的路径。 */
+  file: string;
+  /** 从 1 开始。 */
+  line: number;
+  /** 从 0 开始。 */
+  column: number;
+  message: string;
+  /** `syntax`：语法错误；`import`：禁用的导入写法。 */
+  kind: 'syntax' | 'import';
+}
+
+export const CONNECTOR_SDK_SPECIFIER = '@deepexi/datasense-connector';
+/** 改名前的包名（拼接而成，让仓库里旧包名零出现的 grep 守卫保持干净）。 */
+const RETIRED_SDK_SPECIFIER = ['@mu-ontos', 'connector-sdk'].join('/');
+const MACRO_SPECIFIER = /^macro:/i;
+
+/** Node 内置模块（不依赖 `node:module`：这份检查不该因运行时不同而结论不同）。 */
+const NODE_BUILTINS: ReadonlySet<string> = new Set([
+  'assert', 'async_hooks', 'buffer', 'child_process', 'cluster', 'console', 'constants', 'crypto', 'dgram', 'diagnostics_channel',
+  'dns', 'domain', 'events', 'fs', 'http', 'http2', 'https', 'inspector', 'module', 'net', 'os', 'path', 'perf_hooks', 'process',
+  'punycode', 'querystring', 'readline', 'repl', 'stream', 'string_decoder', 'sys', 'timers', 'tls', 'trace_events', 'tty', 'url',
+  'util', 'v8', 'vm', 'wasi', 'worker_threads', 'zlib', 'test', 'sqlite', 'sea',
+]);
+
+export function asTypeScript(value: unknown): TypeScriptApi {
+  const api = (value !== null && typeof value === 'object' && 'default' in value && typeof (value as { default?: unknown }).default === 'object'
+    ? (value as { default: unknown }).default
+    : value) as Partial<TypeScriptApi> | null;
+  if (!api || typeof api.createSourceFile !== 'function' || typeof api.transpileModule !== 'function') {
+    throw new TypeError('options.typescript must be the TypeScript compiler API (import ts from "typescript")');
+  }
+  return api as TypeScriptApi;
+}
+
+function scriptKindOf(ts: TypeScriptApi, filePath: string): TS.ScriptKind {
+  if (filePath.endsWith('.tsx')) return ts.ScriptKind.TSX;
+  if (filePath.endsWith('.jsx')) return ts.ScriptKind.JSX;
+  if (/\.[cm]?js$/.test(filePath)) return ts.ScriptKind.JS;
+  return ts.ScriptKind.TS;
+}
+
+function sdkSpecifierProblem(specifier: string): string | null {
+  if (specifier === RETIRED_SDK_SPECIFIER || specifier.startsWith(`${RETIRED_SDK_SPECIFIER}/`)) {
+    return `import '${specifier}' is not allowed; the SDK package is now '${CONNECTOR_SDK_SPECIFIER}'`;
+  }
+  if (specifier.startsWith(`${CONNECTOR_SDK_SPECIFIER}/`)) {
+    return `import '${specifier}' is not allowed; import '${CONNECTOR_SDK_SPECIFIER}' itself`;
+  }
+  return null;
+}
+
+function literalSpecifier(ts: TypeScriptApi, node: TS.Node | undefined): string | null {
+  if (node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))) return node.text;
+  return null;
+}
+
+/** 检查一个源码文件，返回全部违规（空数组表示通过）。规则与 shared 的 `findForbiddenSourceSyntax` 相同。 */
+export function findForbiddenSourceSyntax(ts: TypeScriptApi, filePath: string, content: string): SourceGuardDiagnostic[] {
+  const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, scriptKindOf(ts, filePath));
+  const problems: SourceGuardDiagnostic[] = [];
+  const report = (position: number, message: string, kind: SourceGuardDiagnostic['kind']): void => {
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(position);
+    problems.push({ file: filePath, line: line + 1, column: character, message, kind });
+  };
+
+  // 公开类型里没有 `parseDiagnostics`，但运行时一直存在（shared 的守卫同样这样取）。
+  const parseDiagnostics = (sourceFile as unknown as { parseDiagnostics?: readonly TS.DiagnosticWithLocation[] }).parseDiagnostics ?? [];
+  for (const diagnostic of parseDiagnostics) {
+    report(diagnostic.start ?? 0, `syntax error: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ')}`, 'syntax');
+  }
+
+  const checkSpecifier = (node: TS.Node | undefined): void => {
+    const specifier = literalSpecifier(ts, node);
+    if (!node || specifier === null) return;
+    if (MACRO_SPECIFIER.test(specifier)) {
+      report(node.getStart(sourceFile), `import '${specifier}' is not allowed; connectors cannot use Bun macros`, 'import');
+      return;
+    }
+    const sdkProblem = sdkSpecifierProblem(specifier);
+    if (sdkProblem !== null) report(node.getStart(sourceFile), sdkProblem, 'import');
+  };
+  const attributesMessage = (keyword: string): string =>
+    `import attributes ('${keyword} { … }') are not allowed; connectors cannot use Bun macros or other import attributes`;
+
+  const visit = (node: TS.Node): void => {
+    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+      checkSpecifier(node.moduleSpecifier);
+      if (node.attributes) {
+        report(node.attributes.getStart(sourceFile), attributesMessage(node.attributes.token === ts.SyntaxKind.AssertKeyword ? 'assert' : 'with'), 'import');
+      }
+    } else if (ts.isImportEqualsDeclaration(node)) {
+      if (ts.isExternalModuleReference(node.moduleReference)) checkSpecifier(node.moduleReference.expression);
+    } else if (ts.isCallExpression(node)) {
+      const callee = node.expression;
+      if (callee.kind === ts.SyntaxKind.ImportKeyword) {
+        checkSpecifier(node.arguments[0]);
+        const options = node.arguments[1];
+        if (options) report(options.getStart(sourceFile), attributesMessage('with'), 'import');
+      } else if (ts.isIdentifier(callee) && callee.text === 'require') {
+        checkSpecifier(node.arguments[0]);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return problems;
+}
+
+/** 转译后 CommonJS 代码里的 `require(…)`：`specifier` 为 null 表示参数不是字面量（运行时才知道导入什么）。 */
+export function collectRequires(ts: TypeScriptApi, filePath: string, output: string): Array<{ specifier: string | null; line: number }> {
+  const sourceFile = ts.createSourceFile(`${filePath}.js`, output, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+  const found: Array<{ specifier: string | null; line: number }> = [];
+  const visit = (node: TS.Node): void => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'require') {
+      const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+      found.push({ specifier: literalSpecifier(ts, node.arguments[0]), line: line + 1 });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return found;
+}
+
+/**
+ * 源码里写出的值导入说明符（`import` / `export … from` / `import()` / `require()` 的字面量；`import type` 与 `export type` 不算）。
+ * 转译会删掉没用到的导入，只看转译结果会放过 `import fs from 'node:fs'` 这类写了没用的导入，所以源码这一层也要归类。
+ */
+export function collectSourceSpecifiers(ts: TypeScriptApi, filePath: string, content: string): Array<{ specifier: string; line: number }> {
+  const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, scriptKindOf(ts, filePath));
+  const found: Array<{ specifier: string; line: number }> = [];
+  const add = (node: TS.Node | undefined): void => {
+    const specifier = literalSpecifier(ts, node);
+    if (!node || specifier === null) return;
+    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+    found.push({ specifier, line: line + 1 });
+  };
+  const visit = (node: TS.Node): void => {
+    if (ts.isImportDeclaration(node)) {
+      if (!node.importClause?.isTypeOnly) add(node.moduleSpecifier);
+    } else if (ts.isExportDeclaration(node)) {
+      if (!node.isTypeOnly) add(node.moduleSpecifier);
+    } else if (ts.isImportEqualsDeclaration(node)) {
+      if (!node.isTypeOnly && ts.isExternalModuleReference(node.moduleReference)) add(node.moduleReference.expression);
+    } else if (ts.isCallExpression(node)) {
+      const callee = node.expression;
+      if (callee.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(callee) && callee.text === 'require')) add(node.arguments[0]);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return found;
+}
+
+export type SpecifierClass =
+  | { kind: 'sdk' }
+  | { kind: 'relative'; target: string }
+  | { kind: 'escape' }
+  | { kind: 'forbidden'; message: string };
+
+function packageNameOf(specifier: string): string {
+  const parts = specifier.split('/');
+  if (specifier.startsWith('@')) return parts.slice(0, 2).join('/');
+  return parts[0] ?? specifier;
+}
+
+/** POSIX 路径规整（`a/./b/../c` → `a/c`），保留开头的 `..`。 */
+function normalizePosix(input: string): string {
+  const out: string[] = [];
+  for (const segment of input.split('/')) {
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') {
+      if (out.length > 0 && out[out.length - 1] !== '..') out.pop();
+      else out.push('..');
+    } else {
+      out.push(segment);
+    }
+  }
+  return out.length === 0 ? '.' : out.join('/');
+}
+
+/** 一个 `require` 说明符的归类；`importer` 是相对源码根目录的路径。 */
+export function classifySpecifier(specifier: string, importer: string): SpecifierClass {
+  if (specifier === CONNECTOR_SDK_SPECIFIER) return { kind: 'sdk' };
+  const isRelative = specifier === '.' || specifier === '..' || specifier.startsWith('./') || specifier.startsWith('../');
+  if (isRelative) {
+    const slash = importer.lastIndexOf('/');
+    const baseDir = slash === -1 ? '' : importer.slice(0, slash);
+    const target = normalizePosix(baseDir ? `${baseDir}/${specifier}` : specifier);
+    if (target === '..' || target.startsWith('../')) return { kind: 'escape' };
+    return { kind: 'relative', target };
+  }
+  const sdkProblem = sdkSpecifierProblem(specifier);
+  if (sdkProblem !== null) return { kind: 'forbidden', message: sdkProblem };
+  if (MACRO_SPECIFIER.test(specifier)) return { kind: 'forbidden', message: `import '${specifier}' is not allowed; connectors cannot use Bun macros` };
+  if (specifier.startsWith('node:') || specifier.startsWith('bun:') || specifier === 'bun' || NODE_BUILTINS.has(packageNameOf(specifier))) {
+    return { kind: 'forbidden', message: `import '${specifier}' is not allowed; connectors cannot use Node.js or Bun built-in modules` };
+  }
+  if (specifier.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(specifier)) {
+    return { kind: 'forbidden', message: `import '${specifier}' is not allowed; only relative imports and '${CONNECTOR_SDK_SPECIFIER}' are allowed` };
+  }
+  return { kind: 'forbidden', message: `import '${specifier}' is not allowed; connectors can only depend on '${CONNECTOR_SDK_SPECIFIER}'` };
+}

package/src/testing/index.ts

@@ -0,0 +1,43 @@
+/**
+ * `@deepexi/datasense-connector/testing`：在作者自己的机器上运行连接器（vitest 与 CLI 共用）。
+ *
+ * - `loadLocalConnector`：读 `.ontos/descriptor.json`，按虚拟入口契约把源码目录转译成打包串，并收集能力目录下的测试用例；
+ * - `runTests`：跑本地连接器的全部测试用例并统计覆盖（`TestReport`）；`runConnectorTests` 是只给文件的版本（runner 用）；
+ * - `createVmExecutor`：在空环境变量的子进程里用与平台 runner 相同的 guest 会话执行（CLI 用）；
+ * - `runStream` / `runCheck` / `runPush` / `runSuggestColumns`：在当前进程里执行已导入的连接器模块
+ *   （`{ descriptor, implementations }`，vitest 用）；`runOperation(executor, …)`：经任一执行器执行一次连接器操作；
+ * - `createLocalGateway`：本地模拟网关，应答 guest 的出站 HTTP、数据库、加密、缓存与凭证调用（主机求交、限流、句柄替换与平台一致）；
+ * - 用例：`createRecorder` 挂在网关的 `onExchange` 上录制、`serializeFixture` / `parseFixtures` / `readFixtureDir` 读写
+ *   `<能力目录>/tests/<用例名>/`，`createReplayHost` / `runFixture` / `runFixtures` 不联网回放并做合规检查；
+ * - `createMockExternalSystem`：连接器操作单元测试用的模拟外部系统（按路由应答、排好成功 / 拒绝 / 超时，记下请求），
+ *   它的 `fetch` 交给 `createLocalGateway({ fetch })`；
+ * - 纯函数 `inferRecordSchema`、`checkCompliance`（不依赖 Node 模块）。
+ *
+ * 连接器源码不要导入本入口：平台打包时只认 `@deepexi/datasense-connector` 本身，子路径一律拒绝。
+ */
+export type { GuestJob, HostMethod, LocalHost, LocalRunErrorCode, LocalRunResult, GuestExecutor, SourceLoadErrorCode } from './types';
+export { LocalRunError, SourceLoadError } from './types';
+export type { LocalExchange, LocalGatewayOptions } from './gateway';
+export { createLocalGateway } from './gateway';
+export type { OperationRunInput, StreamRunInput, VmExecutorOptions } from './engine';
+export { createInProcessExecutor, createVmExecutor, runCheck, runOperation, runPush, runStream, runSuggestColumns } from './engine';
+export type { GuestOperationResult } from '../runtime/protocol';
+export type { LocalConnector } from './source-loader';
+export { DESCRIPTOR_FILE, GENERATED_TYPES_FILE, loadLocalConnector } from './source-loader';
+export type { OperationCaseGap, RunTestsOptions, TestReport } from './run-tests';
+export { descriptorCapabilities, operationCaseGaps, runConnectorTests, runTests, testCoverage } from './run-tests';
+export { CREDENTIAL_HEADER_NAMES, redactHeaders, redactQuery, redactSecretValues, redactUrl, secretRedactionTexts } from './redaction';
+export type {
+  ConnectorFixtureFile, FixtureCase, FixtureExchange, FixtureExpectation, FixtureRequest, LoadedFixture, OperationFixtureExpectation, SuggestFixtureExpectation,
+} from './fixtures';
+export { FixtureFormatError, parseFixtures, readFixtureDir, serializeFixture } from './fixtures';
+export type { FixtureRecorder } from './recorder';
+export { createRecorder } from './recorder';
+export type { FixtureCaseResult, FixtureMismatch, ReplayHost, RunFixtureOptions } from './replay';
+export { createReplayHost, FixtureReplayError, runFixture, runFixtures } from './replay';
+export type { MockCall, MockExternalSystem, MockRequest, MockResponse, MockRouteHandler, MockStep } from './mock-external-system';
+export { createMockExternalSystem } from './mock-external-system';
+export type { InferredColumnType } from './schema';
+export { inferRecordSchema } from './schema';
+export type { ComplianceCode, ComplianceFinding, ComplianceInput, ComplianceTable } from './compliance';
+export { checkCompliance, COMPLIANCE_CODES } from './compliance';

package/src/testing/local-db.ts

@@ -0,0 +1,226 @@
+/**
+ * 本地 `ctx.db`：用 `postgres` 驱动连作者本机配置的 PostgreSQL，形状与平台的数据库代理一致（`DbQueryResponse` / `DbNextResponse`）。
+ *
+ * - 每次查询 `reserve()` 一条独占连接，`BEGIN READ ONLY` + `statement_timeout`，服务端游标每批 1000 行；
+ *   取完、被关闭或网关关闭时结束事务并归还连接（与 connector `egress/db.ts` 相同）。
+ * - 驱动由调用方注入（CLI 静态导入后经 `LocalGatewayOptions.postgres` 传入），否则动态 `import('postgres')`；
+ *   导入不了时 `LocalRunError('DB_DRIVER_MISSING')`。SDK 只把 `postgres` 列为可选 peerDependency，不打进 dist。
+ */
+import { randomUUID } from 'node:crypto';
+import type { DbNextResponse, DbQueryResponse } from '../runtime/protocol';
+import { redactSecretValues } from './redaction';
+import { LocalRunError } from './types';
+
+export interface LocalDbTarget {
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: string;
+  ssl?: boolean;
+}
+
+/** 与平台相同的取值（shared 的 `DB_CURSOR_BATCH_ROWS` / `DB_STATEMENT_TIMEOUT_MS`）。 */
+const BATCH_ROWS = 1000;
+const STATEMENT_TIMEOUT_MS = 300_000;
+const APPLICATION_NAME = 'datasense-connector-local';
+/** date、time、timestamp、timetz 按原文返回，避免按本机时区换算。 */
+const RAW_TEXT_OIDS = [1082, 1083, 1114, 1266];
+
+// ---------------------------------------------------------------------------
+// postgres.js 用到的最小结构（不依赖它的类型，SDK 的声明文件里不出现 postgres）
+
+interface PgRows extends ReadonlyArray<Record<string, unknown>> {
+  columns?: Array<{ name: string; type: number }> | null;
+}
+interface PgPending extends PromiseLike<unknown> {
+  cursor(rows: number): AsyncIterable<PgRows>;
+}
+interface PgReserved {
+  unsafe(text: string, params?: unknown[]): PgPending;
+  release(): void;
+}
+interface PgSql {
+  reserve(): Promise<PgReserved>;
+  end(options?: { timeout?: number }): Promise<void>;
+}
+type PgFactory = (options: Record<string, unknown>) => PgSql;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** 驱动模块（`import('postgres')` 的结果或 `postgres` 函数本身）→ 工厂函数。 */
+function factoryOf(driver: unknown): PgFactory | null {
+  if (typeof driver === 'function') return driver as PgFactory;
+  if (isRecord(driver) && typeof driver.default === 'function') return driver.default as PgFactory;
+  return null;
+}
+
+async function loadDriver(injected: unknown): Promise<PgFactory> {
+  if (injected !== undefined && injected !== null) {
+    const factory = factoryOf(injected);
+    if (!factory) throw new LocalRunError('DB_DRIVER_MISSING', 'the injected postgres driver is not the postgres.js module');
+    return factory;
+  }
+  // 说明符放进变量：打包器与类型检查都不去解析 postgres（它是可选 peerDependency）。
+  const specifier = 'postgres';
+  let loaded: unknown;
+  try {
+    loaded = await import(specifier);
+  } catch {
+    throw new LocalRunError('DB_DRIVER_MISSING', 'ctx.db needs the postgres driver: install it next to the connector (npm install --save-dev postgres)');
+  }
+  const factory = factoryOf(loaded);
+  if (!factory) throw new LocalRunError('DB_DRIVER_MISSING', 'the installed postgres package is not the postgres.js driver');
+  return factory;
+}
+
+function toParam(value: unknown): unknown {
+  if (value === undefined) return null;
+  if (isRecord(value)) return JSON.stringify(value);
+  return value;
+}
+
+function toJsonValue(value: unknown): unknown {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value.toISOString();
+  if (typeof value === 'bigint') return value.toString();
+  if (value instanceof Uint8Array) return Buffer.from(value).toString('base64');
+  if (Array.isArray(value)) return value.map(toJsonValue);
+  return value;
+}
+
+function toRows(rows: ReadonlyArray<Record<string, unknown>>): Array<Record<string, unknown>> {
+  return rows.map((row) => {
+    const out: Record<string, unknown> = {};
+    for (const [name, value] of Object.entries(row)) out[name] = toJsonValue(value);
+    return out;
+  });
+}
+
+/** 带 `code` 的宿主调用失败（与平台数据库代理同码）。 */
+export class LocalDbError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'LocalDbError';
+    this.code = code;
+  }
+}
+
+interface Cursor {
+  reserved: PgReserved;
+  iterator: AsyncIterator<PgRows>;
+}
+
+export interface LocalDb {
+  query(request: { sql: string; params: unknown[] }): Promise<DbQueryResponse>;
+  next(cursorId: string): Promise<DbNextResponse>;
+  close(cursorId: string): Promise<void>;
+  end(): Promise<void>;
+}
+
+export function createLocalDb(target: LocalDbTarget, options: { driver?: unknown; secrets: readonly string[] }): LocalDb {
+  let pool: PgSql | null = null;
+  const cursors = new Map<string, Cursor>();
+  const secrets = [...options.secrets, target.password];
+
+  const poolOf = async (): Promise<PgSql> => {
+    if (pool) return pool;
+    const factory = await loadDriver(options.driver);
+    pool = factory({
+      host: target.host,
+      port: target.port,
+      database: target.database,
+      username: target.user,
+      password: target.password,
+      ssl: target.ssl ? 'require' : false,
+      max: 4,
+      idle_timeout: 60,
+      connect_timeout: 10,
+      prepare: false,
+      onnotice: () => {},
+      connection: { application_name: APPLICATION_NAME },
+      types: {
+        rawText: { to: 25, from: RAW_TEXT_OIDS, serialize: (value: unknown) => String(value), parse: (value: string) => value },
+      },
+    });
+    return pool;
+  };
+
+  const failed = (error: unknown): LocalDbError => {
+    if (error instanceof LocalDbError || error instanceof LocalRunError) return error as LocalDbError;
+    const message = redactSecretValues(error instanceof Error ? error.message : String(error), secrets);
+    return new LocalDbError('DB_PROXY_FAILED', `The query to the source database failed: ${message}`);
+  };
+
+  const finish = async (id: string, cursor: Cursor, ok: boolean): Promise<void> => {
+    cursors.delete(id);
+    try {
+      if (ok) await cursor.iterator.return?.();
+      await cursor.reserved.unsafe(ok ? 'commit' : 'rollback');
+    } catch {
+      await Promise.resolve(cursor.reserved.unsafe('rollback')).then(undefined, () => undefined);
+    } finally {
+      cursor.reserved.release();
+    }
+  };
+
+  return {
+    async query(request) {
+      const sql = await poolOf();
+      let reserved: PgReserved | null = null;
+      try {
+        reserved = await sql.reserve();
+        await reserved.unsafe('begin read only');
+        await reserved.unsafe(`set local statement_timeout = ${STATEMENT_TIMEOUT_MS}`);
+        // `cursor()` 强制扩展协议（多语句会被服务端拒绝）。
+        const iterator = reserved.unsafe(request.sql, request.params.map(toParam)).cursor(BATCH_ROWS)[Symbol.asyncIterator]();
+        const first = await iterator.next();
+        const rows: PgRows = first.done ? [] : first.value;
+        const fields = (rows.columns ?? []).map((column) => ({ name: column.name, dataTypeId: column.type }));
+        const id = randomUUID();
+        const cursor: Cursor = { reserved, iterator };
+        reserved = null;
+        if (first.done === true || rows.length < BATCH_ROWS) {
+          await finish(id, cursor, true);
+          return { cursorId: null, fields, rows: toRows(rows), done: true };
+        }
+        cursors.set(id, cursor);
+        return { cursorId: id, fields, rows: toRows(rows), done: false };
+      } catch (error) {
+        if (reserved) {
+          const held: PgReserved = reserved;
+          await Promise.resolve(held.unsafe('rollback')).then(undefined, () => undefined);
+          held.release();
+        }
+        throw failed(error);
+      }
+    },
+    async next(cursorId) {
+      const cursor = cursors.get(cursorId);
+      if (!cursor) throw new LocalDbError('DB_CURSOR_NOT_FOUND', "The cursor doesn't exist or was closed");
+      try {
+        const step = await cursor.iterator.next();
+        const rows: PgRows = step.done ? [] : step.value;
+        const done = step.done === true || rows.length < BATCH_ROWS;
+        if (done) await finish(cursorId, cursor, true);
+        return { rows: toRows(rows), done };
+      } catch (error) {
+        await finish(cursorId, cursor, false);
+        throw failed(error);
+      }
+    },
+    async close(cursorId) {
+      const cursor = cursors.get(cursorId);
+      if (cursor) await finish(cursorId, cursor, true);
+    },
+    async end() {
+      for (const [id, cursor] of [...cursors]) await finish(id, cursor, false);
+      const current = pool;
+      pool = null;
+      if (current) await current.end({ timeout: 5 }).catch(() => undefined);
+    },
+  };
+}