@deepexi/datasense-connector 3.0.1 → 3.1.0

package/test/testing/gateway.test.ts

@@ -0,0 +1,337 @@
+/**
+ * 本地模拟网关：主机求交、元数据地址拦截、句柄替换与遮蔽、限流、数据库驱动缺失；可选的真实 Postgres 只读查询。
+ */
+import { describe, expect, test } from 'bun:test';
+import { defineCheck, definePush, type CheckFn, type ConfigField, type ConnectorDescriptor, type GeneratedDescriptor } from '../../src';
+import type { EgressHttpRequest } from '../../src/runtime/protocol';
+import { createLocalGateway, LocalRunError, runCheck, type LocalExchange } from '../../src/testing';
+import { LocalLimiter } from '../../src/testing/gateway';
+import { localPgUnavailable } from '../fixtures/acceptance';
+import { configField, descriptor, push } from '../fixtures/descriptor';
+
+const pgUnavailable = await localPgUnavailable();
+if (pgUnavailable) console.warn(`[gateway] 本机 :15432 没有 Postgres，跳过真库用例：${pgUnavailable}`);
+
+interface SentRequest { url: string; method: string; headers: Record<string, string> }
+
+function fakeFetch(sent: SentRequest[], respond: (url: string, headers: Record<string, string>) => Response = () => Response.json({ ok: true })): typeof fetch {
+  const impl = async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+    const headers = Object.fromEntries(new Headers(init?.headers).entries());
+    sent.push({ url, method: init?.method ?? 'GET', headers });
+    return respond(url, headers);
+  };
+  return impl as typeof fetch;
+}
+
+function get(url: string, headers: Record<string, string> = {}): EgressHttpRequest {
+  return { method: 'GET', url, headers, query: {}, body: null, bodyEncoding: 'utf8' };
+}
+
+/** 只有 check 的连接器（描述要有至少一个推送 / 数据流，补一个空推送）。 */
+type Loose = GeneratedDescriptor & { config: Record<string, unknown>; secrets: Record<string, string> };
+
+function checkConnector(name: string, run: CheckFn<Loose>, options: { config?: Record<string, ConfigField>; extra?: Partial<ConnectorDescriptor> } = {}) {
+  return {
+    descriptor: descriptor({ name, check: true, config: options.config ?? {}, pushes: { default: push({}) }, ...options.extra }),
+    implementations: { check: defineCheck<Loose>(run), pushes: { default: definePush('default', { map() {} }) } },
+  };
+}
+
+async function rejection(promise: Promise<unknown>): Promise<{ code?: unknown; message?: unknown }> {
+  try {
+    await promise;
+  } catch (error) {
+    return error as { code?: unknown; message?: unknown };
+  }
+  throw new Error('expected the call to fail');
+}
+
+describe('host intersection', () => {
+  test('a host outside hosts is HOST_DENIED and onExchange sees the failed exchange', async () => {
+    const exchanges: LocalExchange[] = [];
+    const sent: SentRequest[] = [];
+    const gateway = createLocalGateway({ hosts: ['api.example.com'], secrets: {}, fetch: fakeFetch(sent), onExchange: (entry) => exchanges.push(entry) });
+    const error = await rejection(gateway.call('http', get('https://other.example.com/x')));
+    expect(error).toBeInstanceOf(LocalRunError);
+    expect(error.code).toBe('HOST_DENIED');
+    expect(sent).toHaveLength(0);
+    expect(exchanges).toHaveLength(1);
+    expect(exchanges[0]?.kind).toBe('http');
+    expect(exchanges[0]?.error?.code).toBe('HOST_DENIED');
+    expect(exchanges[0]?.response).toBeNull();
+  });
+
+  test('the connector sees the platform code EGRESS_HOST_DENIED', async () => {
+    const connector = checkConnector('denied', async (ctx) => {
+      try {
+        await ctx.http.get('https://other.example.com/x');
+      } catch (error) {
+        ctx.log.info(`code=${String((error as { code?: unknown }).code)}`);
+        throw error;
+      }
+    });
+    const gateway = createLocalGateway({ hosts: ['api.example.com'], secrets: {}, fetch: fakeFetch([]) });
+    const result = await runCheck(connector, { config: {}, host: gateway });
+    expect(result.logs.map((log) => log.message)).toContain('code=EGRESS_HOST_DENIED');
+    expect(result.error).not.toBeNull();
+  });
+
+  test('wildcard hosts match subdomains only', async () => {
+    const sent: SentRequest[] = [];
+    const gateway = createLocalGateway({ hosts: ['*.example.com'], secrets: {}, fetch: fakeFetch(sent) });
+    await gateway.call('http', get('https://a.b.example.com/x'));
+    expect((await rejection(gateway.call('http', get('https://example.com/x')))).code).toBe('HOST_DENIED');
+    expect(sent.map((request) => request.url)).toEqual(['https://a.b.example.com/x']);
+  });
+
+  test('cloud metadata addresses stay denied even when listed; 127.0.0.1:8080 is allowed', async () => {
+    const sent: SentRequest[] = [];
+    const gateway = createLocalGateway({ hosts: ['169.254.169.254', '[::ffff:a9fe:a9fe]', '127.0.0.1:8080'], secrets: {}, fetch: fakeFetch(sent) });
+    expect((await rejection(gateway.call('http', get('http://169.254.169.254/')))).code).toBe('HOST_DENIED');
+    expect((await rejection(gateway.call('http', get('http://[::ffff:a9fe:a9fe]/')))).code).toBe('HOST_DENIED');
+    const response = await gateway.call('http', get('http://127.0.0.1:8080/health')) as { status: number };
+    expect(response.status).toBe(200);
+    expect(sent.map((request) => request.url)).toEqual(['http://127.0.0.1:8080/health']);
+  });
+
+  test('a metadata address as the db host is denied', async () => {
+    const gateway = createLocalGateway({
+      hosts: [], secrets: {}, db: { host: '169.254.169.254', port: 5432, database: 'x', user: 'u', password: 'p' },
+    });
+    expect((await rejection(gateway.call('db.query', { sql: 'select 1', params: [] }))).code).toBe('HOST_DENIED');
+  });
+});
+
+describe('secret handles and redaction', () => {
+  test('handles are substituted on the way out; onExchange keeps the handle form; the response is redacted', async () => {
+    const exchanges: LocalExchange[] = [];
+    const sent: SentRequest[] = [];
+    const gateway = createLocalGateway({
+      hosts: ['api.example.com'],
+      secrets: { token: 'abcd1234' },
+      // 上游把收到的鉴权头原样回显
+      fetch: fakeFetch(sent, (_url, headers) => Response.json({ echo: headers.authorization })),
+      onExchange: (entry) => exchanges.push(entry),
+    });
+    const response = await gateway.call('http', get('https://api.example.com/x?key=ontos:secret:token', { Authorization: 'Bearer ontos:secret:token' })) as { body: string };
+    expect(sent[0]?.headers.authorization).toBe('Bearer abcd1234');
+    expect(sent[0]?.url).toBe('https://api.example.com/x?key=abcd1234');
+    expect((exchanges[0]?.request as EgressHttpRequest).headers.Authorization).toBe('Bearer ontos:secret:token');
+    expect(JSON.parse((exchanges[0]?.response as { body: string }).body)).toEqual({ echo: 'Bearer abcd1234' });
+    expect(JSON.parse(response.body)).toEqual({ echo: 'Bearer ***' });
+    expect(gateway.redact('x abcd1234 y')).toBe('x *** y');
+  });
+
+  test('plaintext secrets that reach the logs are replaced with ***', async () => {
+    const sent: SentRequest[] = [];
+    const connector = checkConnector('redact', async (ctx) => {
+      const response = await ctx.http.get<{ echo: string }>('https://api.example.com/me', { headers: { authorization: `Bearer ${ctx.secrets.token}` } });
+      ctx.log.info(`echo ${response.data.echo}`);
+      ctx.log.info(`pin ${ctx.secrets.pin}`);
+      ctx.log.warn(`handle ${ctx.secrets.token}`);
+    }, { config: { token: configField('secret'), pin: configField('secret', { exposeToScript: true }) }, extra: { hosts: ['api.example.com'] } });
+    const gateway = createLocalGateway({
+      hosts: ['api.example.com'],
+      secrets: { token: 'abcd1234', pin: 'pin-5678' },
+      fetch: fakeFetch(sent, (_url, headers) => Response.json({ echo: headers.authorization })),
+    });
+    const result = await runCheck(connector, { config: {}, host: gateway });
+    expect(result.error).toBeNull();
+    expect(sent[0]?.headers.authorization).toBe('Bearer abcd1234');
+    expect(result.logs.map((log) => log.message)).toEqual(['echo Bearer ***', 'pin ***', 'handle ontos:secret:token']);
+    expect(JSON.stringify(result)).not.toContain('abcd1234');
+    expect(JSON.stringify(result)).not.toContain('pin-5678');
+  });
+});
+
+describe('rate limit', () => {
+  test('perSecond 2 with concurrency 1: four requests take at least 1.5 seconds', async () => {
+    const sent: SentRequest[] = [];
+    const gateway = createLocalGateway({ hosts: ['api.example.com'], secrets: {}, rateLimit: { perSecond: 2, concurrency: 1 }, fetch: fakeFetch(sent) });
+    const startedAt = Date.now();
+    await Promise.all([1, 2, 3, 4].map((n) => gateway.call('http', get(`https://api.example.com/${n}`))));
+    expect(Date.now() - startedAt).toBeGreaterThanOrEqual(1450);
+    expect(sent).toHaveLength(4);
+  });
+});
+
+describe('database', () => {
+  const DB = { host: 'localhost', port: 15432, database: 'postgres', user: 'admin', password: 'password' };
+
+  test('an unusable postgres driver is LocalRunError DB_DRIVER_MISSING', async () => {
+    const gateway = createLocalGateway({ hosts: [], secrets: {}, db: DB, postgres: { notTheDriver: true } });
+    const error = await rejection(gateway.call('db.query', { sql: 'select 1', params: [] }));
+    expect(error).toBeInstanceOf(LocalRunError);
+    expect(error.code).toBe('DB_DRIVER_MISSING');
+  });
+
+  test('a run whose ctx.db cannot load the driver ends with DB_DRIVER_MISSING', async () => {
+    const connector = checkConnector('dbcheck', async (ctx) => {
+      for await (const row of ctx.db.query('select 1 as one')) ctx.log.info(JSON.stringify(row));
+    }, { extra: { db: { engine: 'postgresql' } } });
+    const gateway = createLocalGateway({ hosts: [], secrets: {}, db: DB, postgres: { notTheDriver: true } });
+    const result = await runCheck(connector, { config: {}, host: gateway });
+    expect(result.error?.code).toBe('DB_DRIVER_MISSING');
+  });
+
+  test('ctx.db without local db configuration is DB_PROXY_NOT_DECLARED', async () => {
+    const gateway = createLocalGateway({ hosts: [], secrets: {} });
+    expect((await rejection(gateway.call('db.query', { sql: 'select 1', params: [] }))).code).toBe('DB_PROXY_NOT_DECLARED');
+  });
+
+  // 本机没有 :15432 的 Postgres 时跳过
+  test.skipIf(Boolean(pgUnavailable))('a real Postgres (localhost:15432) runs a read-only query with cursor paging', async () => {
+    const gateway = createLocalGateway({ hosts: [], secrets: {}, db: DB });
+    try {
+      const first = await gateway.call('db.query', {
+        sql: 'select g as n, $1::text as tag from generate_series(1, 2500) g', params: ['x'],
+      }) as { cursorId: string | null; fields: Array<{ name: string }>; rows: Array<Record<string, unknown>>; done: boolean };
+      expect(first.fields.map((field) => field.name)).toEqual(['n', 'tag']);
+      expect(first.rows).toHaveLength(1000);
+      expect(first.done).toBe(false);
+      let total = first.rows.length;
+      let done = first.done;
+      while (!done) {
+        const page = await gateway.call('db.next', { cursorId: first.cursorId }) as { rows: unknown[]; done: boolean };
+        total += page.rows.length;
+        done = page.done;
+      }
+      expect(total).toBe(2500);
+      const write = await rejection(gateway.call('db.query', { sql: 'create table sdk_local_db_probe (id int)', params: [] }));
+      expect(write.code).toBe('DB_PROXY_FAILED');
+      expect(String(write.message)).toContain('read-only');
+    } finally {
+      await gateway.close();
+    }
+  });
+});
+
+describe('cache, crypto and secret.reveal', () => {
+  test('cache entries live in memory; crypto substitutes handles; secret.reveal returns plaintext', async () => {
+    const gateway = createLocalGateway({ hosts: [], secrets: { key: 'k-secret' } });
+    expect(await gateway.call('cache.get', { key: 'a' })).toBeNull();
+    await gateway.call('cache.set', { key: 'a', value: 'v', ttlSeconds: 60 });
+    expect((await gateway.call('cache.get', { key: 'a' }) as { value: string }).value).toBe('v');
+    const hmac = await gateway.call('crypto', { op: 'hmac', algorithm: 'sha256', key: 'ontos:secret:key', data: 'payload', encoding: 'hex' }) as { value: string };
+    const { createHmac } = await import('node:crypto');
+    expect(hmac.value).toBe(createHmac('sha256', 'k-secret').update('payload').digest('hex'));
+    expect(await gateway.call('secret.reveal', { field: 'key' })).toEqual({ value: 'k-secret' });
+  });
+});
+
+describe('review fixes: encoded secrets, limiter hand-off, pinned connections', () => {
+  test('URL-encoded and form-encoded secrets are redacted in the redirected url, the body and the recorder', async () => {
+    const secret = 'ab+cd/ef== x';
+    const exchanges: LocalExchange[] = [];
+    const sent: SentRequest[] = [];
+    const gateway = createLocalGateway({
+      hosts: ['api.example.com'],
+      secrets: { token: secret },
+      fetch: fakeFetch(sent, (url) => (url.includes('/start')
+        ? new Response(null, { status: 302, headers: { location: `/next?key=${encodeURIComponent(secret)}` } })
+        : Response.json({ echoed: url, form: new URLSearchParams([['k', secret]]).toString() }))),
+      onExchange: (entry) => exchanges.push(entry),
+    });
+    const response = await gateway.call('http', get('https://api.example.com/start?key=ontos:secret:token')) as { url: string; body: string };
+    expect(sent[0]?.url).toContain(encodeURIComponent(secret));
+    expect(response.url).toBe('https://api.example.com/next?key=***');
+    expect(response.body).not.toContain(encodeURIComponent(secret));
+    expect(response.body).not.toContain('ab%2Bcd%2Fef%3D%3D+x');
+    expect(gateway.redact(`a ${encodeURIComponent(secret)} b`)).toBe('a *** b');
+
+    const { createRecorder } = await import('../../src/testing');
+    const recorder = createRecorder({ secrets: { token: secret }, extraSecrets: ['db-password-1'] });
+    for (const entry of exchanges) recorder.onExchange(entry);
+    recorder.onExchange({ kind: 'db', request: { sql: "select 'db-password-1'", params: [] }, response: { fields: [], rows: [], cursorId: null, done: true }, error: null, durationMs: 1 });
+    const recorded = JSON.stringify(recorder.exchanges());
+    expect(recorded).not.toContain(encodeURIComponent(secret));
+    expect(recorded).not.toContain('ab%2Bcd%2Fef%3D%3D+x');
+    expect(recorded).not.toContain('db-password-1');
+  });
+
+  test('concurrency 1: a slot freed while others wait goes to the next waiter, not to a request arriving in between', async () => {
+    const limiter = new LocalLimiter(1_000_000, 1);
+    let holders = 0;
+    let peak = 0;
+    const hold = async (): Promise<() => void> => {
+      const release = await limiter.acquire();
+      holders += 1;
+      peak = Math.max(peak, holders);
+      return () => {
+        holders -= 1;
+        release();
+      };
+    };
+    const releaseFirst = await hold();
+    const waiter = hold();
+    await Promise.resolve();
+    releaseFirst();
+    // 同一时刻新来的请求：旧实现会让它和被唤醒的等待者同时拿到槽位。
+    const newcomer = hold();
+    const releaseWaiter = await waiter;
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(peak).toBe(1);
+    releaseWaiter();
+    (await newcomer)();
+    expect(peak).toBe(1);
+  });
+
+  test('real network: the connection goes to the checked address with the original Host; every hop re-resolves', async () => {
+    const hosts: string[] = [];
+    const server = Bun.serve({
+      hostname: '127.0.0.1',
+      port: 0,
+      fetch(request) {
+        hosts.push(request.headers.get('host') ?? '');
+        const url = new URL(request.url);
+        if (url.pathname === '/start') return new Response(null, { status: 302, headers: { location: '/end' } });
+        return Response.json({ path: url.pathname });
+      },
+    });
+    try {
+      let calls = 0;
+      const resolve = async () => {
+        calls += 1;
+        return [{ address: '127.0.0.1', family: 4 }];
+      };
+      const gateway = createLocalGateway({ hosts: ['rebind.test'], secrets: {}, resolve });
+      const response = await gateway.call('http', get(`http://rebind.test:${server.port}/start`)) as { status: number; body: string };
+      expect(response.status).toBe(200);
+      expect(JSON.parse(response.body)).toEqual({ path: '/end' });
+      expect(hosts).toEqual([`rebind.test:${server.port}`, `rebind.test:${server.port}`]);
+      expect(calls).toBe(2);
+
+      // 第二次解析换成元数据地址（DNS 重绑定）：在重定向那一跳被拦下，不会连过去。
+      let flips = 0;
+      const rebinding = createLocalGateway({
+        hosts: ['rebind.test'],
+        secrets: {},
+        resolve: async () => (flips++ === 0 ? [{ address: '127.0.0.1', family: 4 }] : [{ address: '169.254.169.254', family: 4 }]),
+      });
+      hosts.length = 0;
+      expect((await rejection(rebinding.call('http', get(`http://rebind.test:${server.port}/start`)))).code).toBe('HOST_DENIED');
+      expect(hosts).toHaveLength(1);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test('real network: an unresolvable host is EGRESS_UPSTREAM_FAILED; a gzip body is decompressed', async () => {
+    const server = Bun.serve({
+      hostname: '127.0.0.1',
+      port: 0,
+      fetch: () => new Response(Bun.gzipSync(Buffer.from('{"ok":true}')), { headers: { 'content-encoding': 'gzip', 'content-type': 'application/json' } }),
+    });
+    try {
+      const failing = createLocalGateway({ hosts: ['nowhere.test'], secrets: {}, resolve: async () => { throw new Error('ENOTFOUND'); } });
+      expect((await rejection(failing.call('http', get('http://nowhere.test/')))).code).toBe('EGRESS_UPSTREAM_FAILED');
+      const gateway = createLocalGateway({ hosts: ['127.0.0.1'], secrets: {} });
+      const response = await gateway.call('http', get(`http://127.0.0.1:${server.port}/`, { 'accept-encoding': 'gzip' })) as { body: string; headers: Record<string, string> };
+      expect(JSON.parse(response.body)).toEqual({ ok: true });
+      expect(response.headers['content-encoding']).toBeUndefined();
+    } finally {
+      server.stop(true);
+    }
+  });
+});

package/test/testing/import-guard.test.ts

@@ -0,0 +1,45 @@
+/**
+ * SDK 的导入检查与 shared `connector-source-guard.ts` 的对照：同一批样例两份实现结论一致（SDK 不能依赖 shared）。
+ */
+import { describe, expect, test } from 'bun:test';
+import ts from 'typescript';
+import { findForbiddenSourceSyntax as sharedGuard } from '../../../shared/src/server/connector-source-guard';
+import { classifySpecifier, findForbiddenSourceSyntax } from '../../src/testing/import-guard';
+
+const RETIRED = ['@mu-ontos', 'connector-sdk'].join('/');
+
+const SAMPLES: Array<[string, string, string]> = [
+  ['clean', 'src/index.ts', "import { defineConnector } from '@deepexi/datasense-connector';\nexport default defineConnector;\n"],
+  ['sdk subpath', 'src/index.ts', "import { runStream } from '@deepexi/datasense-connector/testing';\n"],
+  ['retired sdk', 'src/index.ts', `import { t } from '${RETIRED}';\n`],
+  ['macro scheme', 'src/index.ts', "import x from 'macro:./m';\n"],
+  ['import attributes', 'src/index.ts', "import data from './a.json' with { type: 'json' };\n"],
+  ['assert attributes', 'src/index.ts', "import data from './a.json' assert { type: 'json' };\n"],
+  ['dynamic import with options', 'src/index.ts', "export async function f() { return import('./b', { with: { type: 'macro' } }); }\n"],
+  ['export from subpath', 'src/index.ts', "export { t } from '@deepexi/datasense-connector/runtime';\n"],
+  ['require subpath', 'src/lib.js', "const x = require('@deepexi/datasense-connector/testing');\n"],
+  ['import equals', 'src/index.ts', "import sdk = require('@deepexi/datasense-connector/testing');\n"],
+  ['syntax error', 'src/index.ts', 'export const = 1;\n'],
+  ['tsx', 'src/view.tsx', 'export const x = <div>{1}</div>;\n'],
+  ['node builtin is not a guard concern', 'src/index.ts', "import fs from 'node:fs';\nexport const f = fs;\n"],
+];
+
+describe('findForbiddenSourceSyntax matches shared', () => {
+  test.each(SAMPLES)('%s', async (_name, file, content) => {
+    const local = findForbiddenSourceSyntax(ts, file, content).map(({ kind: _kind, ...rest }) => rest);
+    expect(local).toEqual(await sharedGuard(file, content));
+  });
+});
+
+describe('classifySpecifier', () => {
+  test('sdk, relative, escape and forbidden', () => {
+    expect(classifySpecifier('@deepexi/datasense-connector', 'src/index.ts').kind).toBe('sdk');
+    expect(classifySpecifier('./map', 'src/index.ts').kind).toBe('relative');
+    expect(classifySpecifier('../lib/x', 'src/a/index.ts').kind).toBe('relative');
+    expect(classifySpecifier('../../outside', 'src/index.ts').kind).toBe('escape');
+    expect(classifySpecifier('node:fs', 'src/index.ts').kind).toBe('forbidden');
+    expect(classifySpecifier('fs', 'src/index.ts').kind).toBe('forbidden');
+    expect(classifySpecifier('lodash', 'src/index.ts').kind).toBe('forbidden');
+    expect(classifySpecifier('@deepexi/datasense-connector/testing', 'src/index.ts').kind).toBe('forbidden');
+  });
+});

package/test/testing/mock-external-system.test.ts

@@ -0,0 +1,144 @@
+/**
+ * 模拟外部系统：路由与占位、排好的成功 / 拒绝 / 超时 / 慢响应、请求记录，以及经本地模拟网关跑连接器操作的完整用法。
+ */
+import { describe, expect, test } from 'bun:test';
+import { defineOperation, defineStream, errors } from '../../src';
+import { createInProcessExecutor, createLocalGateway, createMockExternalSystem, runOperation, type MockExternalSystem } from '../../src/testing';
+import { configField, descriptor, operation, stream, table, valueField } from '../fixtures/descriptor';
+
+type D = {
+  config: { baseUrl: string };
+  secrets: Record<never, never>;
+  streams: { orders: { tables: { orders: { id: string } }; params: Record<never, never> } };
+  extensibleStreams: Record<never, never>;
+  pushes: Record<never, never>;
+  operations: { create_order: { input: { sku: string; qty: number }; output: { externalId: string }; idempotency: 'supported' } };
+};
+
+function connectorWith(requestTimeoutMs: number) {
+  return {
+    descriptor: descriptor({
+      name: 'erp', hosts: ['erp.example.com'], config: { baseUrl: configField('string') },
+      streams: { orders: stream({ orders: table({ id: 'string' }, ['id']) }, { syncModes: ['full'] }) },
+      operations: {
+        create_order: operation({ sku: valueField('string'), qty: valueField('integer') }, { externalId: valueField('string') }, { risk: 'high' }),
+      },
+    }),
+    implementations: {
+      streams: { orders: defineStream<D, 'orders'>('orders', async function* () {}) },
+      operations: {
+        create_order: defineOperation<D, 'create_order'>('create_order', {
+          async run(ctx, params, meta) {
+            const res = await ctx.http.post(`${ctx.config.baseUrl}/orders`, {
+              headers: { 'Idempotency-Key': meta.idempotencyKey }, body: params, raw: true, timeoutMs: requestTimeoutMs,
+            });
+            const data = JSON.parse(res.text) as { id?: string; code?: string; message?: string };
+            if (res.status === 422) throw new errors.RejectedError(data.message ?? 'rejected', data.code !== undefined ? { code: data.code } : undefined);
+            if (res.status >= 400) throw new errors.FatalError(`unexpected status ${res.status}`);
+            return { externalId: String(data.id) };
+          },
+        }),
+      },
+    },
+  };
+}
+
+function erp(): MockExternalSystem {
+  let next = 0;
+  return createMockExternalSystem({
+    'POST /orders': () => {
+      next += 1;
+      return { status: 201, body: { id: `SO-${next}` } };
+    },
+    'GET /orders/:id': ({ params }) => ({ body: { id: params.id } }),
+  });
+}
+
+async function createOrder(system: MockExternalSystem, options: { requestTimeoutMs?: number; timeoutMs?: number } = {}) {
+  const host = createLocalGateway({ hosts: ['erp.example.com'], secrets: {}, fetch: system.fetch });
+  try {
+    return await runOperation(createInProcessExecutor(connectorWith(options.requestTimeoutMs ?? 100)), {
+      config: { baseUrl: 'https://erp.example.com' }, operation: 'create_order', params: { sku: 'A-1', qty: 2 },
+      idempotencyKey: 'stable:order-1', host, secretFields: [], ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+    });
+  } finally {
+    await host.close();
+  }
+}
+
+describe('createMockExternalSystem', () => {
+  test("script(['timeout', 'ok'])：第一次请求超时（TRANSIENT_ERROR），第二次成功；calls 记下两次请求与 Idempotency-Key", async () => {
+    const system = erp();
+    system.script('POST /orders', ['timeout', 'ok']);
+
+    const first = await createOrder(system);
+    expect(first).toMatchObject({ ok: false, code: 'TRANSIENT_ERROR' });
+    const second = await createOrder(system);
+    expect(second).toMatchObject({ ok: true, output: { externalId: 'SO-1' } });
+
+    const calls = system.calls('POST /orders');
+    expect(calls).toHaveLength(2);
+    for (const call of calls) {
+      expect(call).toMatchObject({ method: 'POST', path: '/orders', body: { sku: 'A-1', qty: 2 } });
+      expect(call.headers['idempotency-key']).toBe('stable:order-1');
+    }
+  });
+
+  test('执行器超时先到时得到 CANCELED', async () => {
+    const system = erp();
+    system.script('POST /orders', ['timeout']);
+    const result = await createOrder(system, { requestTimeoutMs: 1_000, timeoutMs: 100 });
+    expect(result).toMatchObject({ ok: false, code: 'CANCELED' });
+  });
+
+  test('reject 回 422，操作抛 RejectedError（REJECTED，带外部系统的业务码）', async () => {
+    const system = erp();
+    system.script('POST /orders', ['reject']);
+    const result = await createOrder(system);
+    expect(result).toMatchObject({ ok: false, code: 'REJECTED', external: { code: 'REJECTED' } });
+
+    const response = await system.fetch('https://erp.example.com/orders', { method: 'POST', body: '{}' });
+    expect(response.status).toBe(201);
+  });
+
+  test('{ slowMs } 延迟后照常应答；排完的结果之后回到处理函数', async () => {
+    const system = erp();
+    system.script('POST /orders', [{ slowMs: 30 }]);
+    const startedAt = Date.now();
+    const slow = await system.fetch('https://erp.example.com/orders', { method: 'POST' });
+    expect(Date.now() - startedAt).toBeGreaterThanOrEqual(25);
+    expect(slow.status).toBe(201);
+    expect((await system.fetch('https://erp.example.com/orders', { method: 'POST' })).status).toBe(201);
+  });
+
+  test('路径占位、查询参数、未定义路由 404；calls 不带参数返回全部，reset 清空记录与排好的结果', async () => {
+    const seen: Array<{ query: Record<string, string>; headers: Record<string, string> }> = [];
+    const system = createMockExternalSystem({
+      'get /orders/:id': ({ params, query, headers }) => {
+        seen.push({ query, headers });
+        return { body: { id: params.id } };
+      },
+    });
+    const found = await system.fetch('https://erp.example.com/orders/SO%2F9?expand=lines', { headers: { 'X-Trace': 't1' } });
+    expect(await found.json()).toEqual({ id: 'SO/9' });
+    expect(seen).toEqual([{ query: { expand: 'lines' }, headers: { 'x-trace': 't1' } }]);
+
+    const missing = await system.fetch('https://erp.example.com/customers', { method: 'POST' });
+    expect(missing.status).toBe(404);
+    expect(system.calls().map((call) => `${call.method} ${call.path}`)).toEqual(['GET /orders/SO%2F9', 'POST /customers']);
+    expect(system.calls('GET /orders/:id')).toHaveLength(1);
+
+    system.script('GET /orders/:id', ['reject']);
+    system.reset();
+    expect(system.calls()).toEqual([]);
+    expect((await system.fetch('https://erp.example.com/orders/1')).status).toBe(200);
+  });
+
+  test('路由键不合法、script 未定义的路由或不认识的步骤时抛 TypeError', () => {
+    expect(() => createMockExternalSystem({ '/orders': () => ({}) })).toThrow(TypeError);
+    const system = erp();
+    expect(() => system.script('DELETE /orders', ['ok'])).toThrow(TypeError);
+    expect(() => system.script('POST /orders', ['later' as 'ok'])).toThrow(TypeError);
+    expect(() => system.calls('PUT /x')).toThrow(TypeError);
+  });
+});