@deepexi/datasense-connector 3.0.1 → 3.1.0

package/test/runtime/ctx.test.ts

@@ -0,0 +1,434 @@
+/** `ctx` 的各成员：在 pull 作业里跑数据流，用假宿主回应宿主调用，从 `emit` 的记录里读结果。 */
+import { describe, expect, test } from 'bun:test';
+import type { ConfigField, ConnectorDescriptor } from '../../src/index';
+import type { EgressHttpRequest, EgressHttpResponse, GuestPullBatch } from '../../src/runtime';
+import { configField, descriptor, stream as streamDescriptor, table } from '../fixtures/descriptor';
+import { checkJob, expectFailure, expectResult, HostReject, pullJob, rawConnector, runGuest, type HostHandler, type RunResult } from './helpers';
+
+function itemsDescriptor(options: { config?: Record<string, ConfigField>; extra?: Partial<ConnectorDescriptor> } = {}): ConnectorDescriptor {
+  return descriptor({
+    config: options.config ?? {}, hosts: ['api.x.com', '*.x.com'],
+    streams: { items: streamDescriptor({ item: table({ id: 'string' }, ['id']) }, { syncModes: ['full'] }) },
+    ...options.extra,
+  });
+}
+
+/** 一个只有数据流 `items` 的连接器；`stream` 是生成器函数体（可用 ctx、input）。 */
+function streamConnector(stream: string, options: { config?: Record<string, ConfigField>; extra?: Partial<ConnectorDescriptor>; header?: string } = {}): string {
+  return rawConnector(itemsDescriptor(options), `streams: { items: defineStream('items', async function* (ctx, input) { ${stream} }) },`, options.header ?? '');
+}
+
+/** 带 `check` 的连接器：`body` 是 check 的函数体（可用 ctx）。 */
+function checkConnector(body: string): string {
+  return rawConnector(itemsDescriptor({ extra: { hosts: ['api.x.com'], check: true } }),
+    `streams: { items: defineStream('items', async function* () {}) }, check: defineCheck(async (ctx) => { ${body} }),`);
+}
+
+function rows(run: RunResult): Array<Record<string, unknown>> {
+  return run.calls.filter((entry) => entry.method === 'emit').flatMap((entry) => (entry.payload as GuestPullBatch).records.map((record) => record.row));
+}
+
+function httpResponse(status: number, body: unknown, headers: Record<string, string> = {}, url = 'https://api.x.com/'): EgressHttpResponse {
+  const text = typeof body === 'string' ? body : JSON.stringify(body);
+  return { status, url, headers: { 'content-type': typeof body === 'string' ? 'text/plain' : 'application/json', ...headers }, body: text, bodyEncoding: 'utf8' };
+}
+
+/** 依次返回给定的回复；值为 HostReject 时回错误。 */
+function sequence(...replies: Array<EgressHttpResponse | HostReject>): HostHandler {
+  let index = 0;
+  return () => {
+    const reply = replies[Math.min(index, replies.length - 1)];
+    index += 1;
+    if (reply instanceof HostReject) throw reply;
+    return reply;
+  };
+}
+
+const httpCalls = (run: RunResult) => run.calls.filter((entry) => entry.method === 'http').map((entry) => entry.payload as EgressHttpRequest);
+
+describe('ctx.secrets', () => {
+  test('普通字段是句柄；exposeToScript 字段经一次 secret.reveal 取明文并缓存', async () => {
+    const code = streamConnector(
+      `yield ctx.record('item', { key: ctx.secrets.appKey, secret: ctx.secrets.appSecret, again: ctx.secrets.appSecret, missing: ctx.secrets.other === undefined });`,
+      { config: { appKey: configField('secret'), appSecret: configField('secret', { exposeToScript: true }), other: configField('secret') } },
+    );
+    const run = await runGuest({
+      code, job: pullJob({ secretFields: ['appKey', 'appSecret'] }),
+      host: { 'secret.reveal': (payload) => ({ value: `plain-${(payload as { field: string }).field}` }) },
+    });
+    expectResult(run.outcome);
+    expect(rows(run)).toEqual([{ key: 'ontos:secret:appKey', secret: 'plain-appSecret', again: 'plain-appSecret', missing: true }]);
+    expect(run.calls.filter((entry) => entry.method === 'secret.reveal')).toEqual([{ method: 'secret.reveal', payload: { field: 'appSecret' } }]);
+  });
+
+  test('ctx.files 访问即抛 NOT_AVAILABLE', async () => {
+    const code = streamConnector(`let code; try { ctx.files; } catch (e) { code = e.code; } yield ctx.record('item', { code });`);
+    const run = await runGuest({ code, job: pullJob() });
+    expect(rows(run)).toEqual([{ code: 'NOT_AVAILABLE' }]);
+  });
+});
+
+describe('ctx.http', () => {
+  test('相对路径拼在 auth.baseUrl 上，query 值转成字符串，JSON 响应解析成对象', async () => {
+    const code = streamConnector(`
+      const res = await ctx.http.get('/v2/orders', { query: { page: 1, tags: ['a', 2], skip: undefined }, headers: { 'X-Trace': 'abc' }, auth: { baseUrl: 'https://api.x.com', headers: { 'app-token': 't1' } } });
+      const posted = await ctx.http.post('https://api.x.com/v2/orders', { body: { a: 1 } });
+      yield ctx.record('item', { data: res.data, text: res.text, status: res.status, postedType: typeof posted.data });`);
+    const run = await runGuest({
+      code, job: pullJob(),
+      host: { http: (payload) => ((payload as EgressHttpRequest).method === 'GET' ? httpResponse(200, { orders: [1, 2] }) : httpResponse(201, 'created')) },
+    });
+    expectResult(run.outcome);
+    const [get, post] = httpCalls(run);
+    expect(get).toEqual({
+      method: 'GET', url: 'https://api.x.com/v2/orders', headers: { 'app-token': 't1', 'x-trace': 'abc' },
+      query: { page: '1', tags: ['a', '2'] }, body: null, bodyEncoding: 'utf8',
+    });
+    expect(post).toMatchObject({ method: 'POST', body: '{"a":1}', headers: { 'content-type': 'application/json' } });
+    expect(rows(run)).toEqual([{ data: { orders: [1, 2] }, text: '{"orders":[1,2]}', status: 200, postedType: 'string' }]);
+  });
+
+  test('没有 baseUrl 时相对路径拼在 hosts 里第一个确定的主机上', async () => {
+    const code = streamConnector(`await ctx.http.get('orders'); yield ctx.record('item', {});`);
+    const run = await runGuest({ code, job: pullJob(), host: { http: () => httpResponse(200, {}) } });
+    expectResult(run.outcome);
+    expect(httpCalls(run)[0]?.url).toBe('https://api.x.com/orders');
+  });
+
+  test('网关限流（retryAfterMs: 50）等待后重发', async () => {
+    const code = streamConnector(`const res = await ctx.http.get('https://api.x.com/a'); yield ctx.record('item', { status: res.status });`);
+    const limited = new HostReject({ code: 'EGRESS_RATE_LIMITED', message: 'slow down', retryAfterMs: 50 });
+    const started = Date.now();
+    const run = await runGuest({ code, job: pullJob(), host: { http: sequence(limited, limited, httpResponse(200, {})) } });
+    expectResult(run.outcome);
+    expect(httpCalls(run)).toHaveLength(3);
+    expect(Date.now() - started).toBeGreaterThanOrEqual(90);
+  });
+
+  test('网关限流超过 5 次重试后失败', async () => {
+    const code = streamConnector(`await ctx.http.get('https://api.x.com/a'); yield ctx.record('item', {});`);
+    const limited = new HostReject({ code: 'EGRESS_RATE_LIMITED', message: 'slow down', retryAfterMs: 5 });
+    const run = await runGuest({ code, job: pullJob(), host: { http: sequence(limited) } });
+    const failure = expectFailure(run.outcome);
+    expect(failure.code).toBe('TRANSIENT_ERROR');
+    expect(failure.message).toContain('rate limited after 5 retries');
+    expect(httpCalls(run)).toHaveLength(6);
+  });
+
+  test('上游 429 按 Retry-After 秒数等待后重发', async () => {
+    const code = streamConnector(`const res = await ctx.http.get('https://api.x.com/a'); yield ctx.record('item', { status: res.status });`);
+    const started = Date.now();
+    const run = await runGuest({ code, job: pullJob(), host: { http: sequence(httpResponse(429, 'busy', { 'retry-after': '1' }), httpResponse(200, {})) } });
+    expect(rows(run)).toEqual([{ status: 200 }]);
+    expect(Date.now() - started).toBeGreaterThanOrEqual(950);
+  });
+
+  test('上游 502/503/504 指数退避重试 3 次后抛 TransientError', async () => {
+    const code = streamConnector(`await ctx.http.get('https://api.x.com/a'); yield ctx.record('item', {});`);
+    const started = Date.now();
+    const run = await runGuest({ code, job: pullJob(), host: { http: sequence(httpResponse(502, 'bad'), httpResponse(503, 'bad'), httpResponse(504, 'bad'), httpResponse(502, 'bad')) } });
+    const elapsed = Date.now() - started;
+    const failure = expectFailure(run.outcome);
+    expect(failure.code).toBe('TRANSIENT_ERROR');
+    expect(failure.message).toContain('returned 502 after 3 retries');
+    expect(httpCalls(run)).toHaveLength(4);
+    // 200 + 400 + 800
+    expect(elapsed).toBeGreaterThanOrEqual(1350);
+  });
+
+  test('POST / PATCH 遇 502 与网关超时缺省不重试；PUT / DELETE 照常重试', async () => {
+    for (const method of ['post', 'patch']) {
+      for (const failureReply of [httpResponse(502, 'bad'), new HostReject({ code: 'EGRESS_TIMEOUT', message: 'timed out' })]) {
+        const code = streamConnector(`await ctx.http.${method}('https://api.x.com/a', { body: { n: 1 } }); yield ctx.record('item', {});`);
+        const run = await runGuest({ code, job: pullJob(), host: { http: sequence(failureReply, httpResponse(200, {})) } });
+        const failure = expectFailure(run.outcome);
+        expect(failure.code).toBe('TRANSIENT_ERROR');
+        expect(failure.message).toContain('after 0 retries');
+        expect(httpCalls(run)).toHaveLength(1);
+      }
+    }
+    for (const method of ['put', 'delete']) {
+      const code = streamConnector(`const res = await ctx.http.${method}('https://api.x.com/a'); yield ctx.record('item', { status: res.status });`);
+      const run = await runGuest({ code, job: pullJob(), host: { http: sequence(httpResponse(503, 'bad'), httpResponse(200, {})) } });
+      expect(rows(run)).toEqual([{ status: 200 }]);
+      expect(httpCalls(run)).toHaveLength(2);
+    }
+  });
+
+  test('retry: true 让 POST 也重试；retry: false 让 GET 也不重试；限流与 429 不受 retry 影响', async () => {
+    const post = streamConnector(`const res = await ctx.http.post('https://api.x.com/a', { body: {}, retry: true }); yield ctx.record('item', { status: res.status });`);
+    const postRun = await runGuest({ code: post, job: pullJob(), host: { http: sequence(httpResponse(502, 'bad'), httpResponse(200, {})) } });
+    expect(rows(postRun)).toEqual([{ status: 200 }]);
+    expect(httpCalls(postRun)).toHaveLength(2);
+
+    const get = streamConnector(`await ctx.http.get('https://api.x.com/a', { retry: false }); yield ctx.record('item', {});`);
+    const getRun = await runGuest({ code: get, job: pullJob(), host: { http: sequence(httpResponse(504, 'bad'), httpResponse(200, {})) } });
+    expect(expectFailure(getRun.outcome).code).toBe('TRANSIENT_ERROR');
+    expect(httpCalls(getRun)).toHaveLength(1);
+
+    const limitedPost = streamConnector(`const res = await ctx.http.post('https://api.x.com/a', { body: {}, retry: false }); yield ctx.record('item', { status: res.status });`);
+    const limited = new HostReject({ code: 'EGRESS_RATE_LIMITED', message: 'slow down', retryAfterMs: 5 });
+    const limitedRun = await runGuest({ code: limitedPost, job: pullJob(), host: { http: sequence(limited, httpResponse(429, 'busy', { 'retry-after': '0' }), httpResponse(200, {})) } });
+    expect(rows(limitedRun)).toEqual([{ status: 200 }]);
+    expect(httpCalls(limitedRun)).toHaveLength(3);
+  });
+
+  test('网关超时同样退避重试，恢复后照常返回', async () => {
+    const code = streamConnector(`const res = await ctx.http.get('https://api.x.com/a'); yield ctx.record('item', { status: res.status });`);
+    const timeout = new HostReject({ code: 'EGRESS_TIMEOUT', message: 'timed out' });
+    const run = await runGuest({ code, job: pullJob(), host: { http: sequence(timeout, httpResponse(200, {})) } });
+    expect(rows(run)).toEqual([{ status: 200 }]);
+    expect(httpCalls(run)).toHaveLength(2);
+  });
+
+  test('上游 401 不重试，抛 AuthError；其他宿主错误按 code 失败', async () => {
+    const code = streamConnector(`await ctx.http.get('https://api.x.com/a'); yield ctx.record('item', {});`);
+    const run = await runGuest({ code, job: pullJob(), host: { http: sequence(httpResponse(401, 'no')) } });
+    expect(expectFailure(run.outcome).code).toBe('AUTH_ERROR');
+    expect(httpCalls(run)).toHaveLength(1);
+
+    const denied = await runGuest({ code, job: pullJob(), host: { http: sequence(new HostReject({ code: 'EGRESS_HOST_DENIED', message: 'host evil.com is not allowed', status: 403 })) } });
+    expect(expectFailure(denied.outcome)).toMatchObject({ code: 'FATAL_ERROR', message: 'EGRESS_HOST_DENIED: host evil.com is not allowed' });
+  });
+
+  test('raw: true 不按状态码抛错、不解析 JSON', async () => {
+    const code = streamConnector(`const res = await ctx.http.get('https://api.x.com/a', { raw: true }); yield ctx.record('item', { status: res.status, data: res.data });`);
+    const run = await runGuest({ code, job: pullJob(), host: { http: sequence(httpResponse(404, { error: 'x' })) } });
+    expect(rows(run)).toEqual([{ status: 404, data: '{"error":"x"}' }]);
+  });
+});
+
+describe('ctx.paginate', () => {
+  test('page：共 3 页时依次产出 3 页，maxOf 取该页最大值', async () => {
+    const code = streamConnector(`
+      for await (const page of ctx.paginate.page({
+        firstPage: 1,
+        request: (n) => ctx.http.get('https://api.x.com/p', { query: { page: n } }),
+        rows: (res) => res.data.rows,
+        totalPages: (res) => res.data.total,
+      })) yield ctx.record('item', { ids: page.rows.map((r) => r.id), max: page.maxOf((r) => r.at) });`);
+    const pages: Record<string, unknown> = {
+      1: { rows: [{ id: 1, at: '2026-01-02' }, { id: 2, at: '2026-01-05' }], total: 3 },
+      2: { rows: [{ id: 3, at: '2026-02-01' }], total: 3 },
+      3: { rows: [{ id: 4, at: '2026-03-09' }, { id: 5, at: '2026-03-01' }], total: 3 },
+    };
+    const run = await runGuest({ code, job: pullJob(), host: { http: (payload) => httpResponse(200, pages[String((payload as EgressHttpRequest).query.page)]) } });
+    expect(rows(run)).toEqual([{ ids: [1, 2], max: '2026-01-05' }, { ids: [3], max: '2026-02-01' }, { ids: [4, 5], max: '2026-03-09' }]);
+    expect(httpCalls(run)).toHaveLength(3);
+  });
+
+  test('cursor / offset / link 各给 2 页数据，没有下一页时结束', async () => {
+    const code = streamConnector(`
+      const out = { cursor: [], offset: [], link: [] };
+      for await (const page of ctx.paginate.cursor({
+        request: (cursor) => ctx.http.get('https://api.x.com/c', { query: { cursor } }),
+        rows: (res) => res.data.items, nextCursor: (res) => res.data.next,
+      })) out.cursor.push(page.rows);
+      for await (const page of ctx.paginate.offset({
+        limit: 2, request: (offset, limit) => ctx.http.get('https://api.x.com/o', { query: { offset, limit } }), rows: (res) => res.data.items,
+      })) out.offset.push(page.rows);
+      for await (const page of ctx.paginate.link({ url: 'https://api.x.com/l?page=1', rows: (res) => res.data.items })) out.link.push(page.rows);
+      yield ctx.record('item', out);`);
+    const http: HostHandler = (payload) => {
+      const request = payload as EgressHttpRequest;
+      if (request.url.startsWith('https://api.x.com/c')) {
+        return request.query.cursor === undefined ? httpResponse(200, { items: [1, 2], next: 'n2' }) : httpResponse(200, { items: [3], next: null });
+      }
+      if (request.url.startsWith('https://api.x.com/o')) {
+        return request.query.offset === '0' ? httpResponse(200, { items: ['a', 'b'] }) : httpResponse(200, { items: ['c'] });
+      }
+      return request.url.endsWith('page=1')
+        ? httpResponse(200, { items: ['x'] }, { link: '<https://api.x.com/l?page=2>; rel="next", <https://api.x.com/l?page=1>; rel="first"' }, request.url)
+        : httpResponse(200, { items: ['y'] }, { link: '<https://api.x.com/l?page=1>; rel="first"' }, request.url);
+    };
+    const run = await runGuest({ code, job: pullJob(), host: { http } });
+    expect(rows(run)).toEqual([{ cursor: [[1, 2], [3]], offset: [['a', 'b'], ['c']], link: [['x'], ['y']] }]);
+    expect(httpCalls(run).map((request) => request.url)).toEqual([
+      'https://api.x.com/c', 'https://api.x.com/c', 'https://api.x.com/o', 'https://api.x.com/o', 'https://api.x.com/l?page=1', 'https://api.x.com/l?page=2',
+    ]);
+  });
+
+  test('keyset：按键翻页直到返回空', async () => {
+    const code = streamConnector(`
+      const pages = [];
+      for await (const page of ctx.paginate.keyset({
+        query: (last) => ctx.db.query('select id from t where id > $1 order by id limit 2', [last ?? 0]),
+        key: (row) => row.id,
+      })) pages.push(page.rows.map((r) => r.id));
+      yield ctx.record('item', { pages });`, { extra: { db: { engine: 'postgresql' } } });
+    const data = [1, 2, 3, 4, 5];
+    const run = await runGuest({
+      code, job: pullJob(),
+      host: {
+        'db.query': (payload) => {
+          const after = (payload as { params: number[] }).params[0] ?? 0;
+          return { cursorId: null, fields: [{ name: 'id', dataTypeId: 23 }], rows: data.filter((id) => id > after).slice(0, 2).map((id) => ({ id })), done: true };
+        },
+      },
+    });
+    expect(rows(run)).toEqual([{ pages: [[1, 2], [3, 4], [5]] }]);
+    expect(run.calls.filter((entry) => entry.method === 'db.query').map((entry) => entry.payload)).toEqual([0, 2, 4, 5].map((last) => ({ sql: 'select id from t where id > $1 order by id limit 2', params: [last] })));
+  });
+});
+
+describe('ctx.db', () => {
+  const db = { 'db.query': () => ({ cursorId: 'c1', fields: [{ name: 'id', dataTypeId: 23 }], rows: Array.from({ length: 1000 }, (_, i) => ({ id: i + 11 })), done: false }) };
+
+  test('游标分批取完全部行', async () => {
+    const code = streamConnector(`
+      let count = 0; let last;
+      for await (const row of ctx.db.query('select * from t where id > $1 order by id', [10])) { count += 1; last = row.id; }
+      yield ctx.record('item', { count, last });`, { extra: { db: { engine: 'postgresql' } } });
+    const run = await runGuest({ code, job: pullJob(), host: { ...db, 'db.next': () => ({ rows: [{ id: 1011 }, { id: 1012 }], done: true }) } });
+    expect(rows(run)).toEqual([{ count: 1002, last: 1012 }]);
+    expect(run.calls.filter((entry) => entry.method.startsWith('db.'))).toEqual([
+      { method: 'db.query', payload: { sql: 'select * from t where id > $1 order by id', params: [10] } },
+      { method: 'db.next', payload: { cursorId: 'c1' } },
+    ]);
+  });
+
+  test('中途 break 时发 db.close', async () => {
+    const code = streamConnector(`
+      for await (const row of ctx.db.query('select * from t', [new Date('2026-01-01T00:00:00Z'), 10n, undefined])) { if (row.id > 12) break; }
+      yield ctx.record('item', {});`, { extra: { db: { engine: 'postgresql' } } });
+    const run = await runGuest({ code, job: pullJob(), host: db });
+    expectResult(run.outcome);
+    expect(run.calls.filter((entry) => entry.method.startsWith('db.'))).toEqual([
+      { method: 'db.query', payload: { sql: 'select * from t', params: ['2026-01-01T00:00:00.000Z', '10', null] } },
+      { method: 'db.close', payload: { cursorId: 'c1' } },
+    ]);
+  });
+});
+
+describe('ctx.map / cache / crypto / time', () => {
+  test('ctx.map 的并发不超过描述的 rateLimit.concurrency', async () => {
+    const code = streamConnector(`
+      const items = Array.from({ length: 20 }, (_, i) => i);
+      const out = await ctx.map(items, async (i) => (await ctx.http.get('https://api.x.com/i', { query: { i } })).data.i * 2, { concurrency: 8 });
+      yield ctx.record('item', { out });`, { extra: { rateLimit: { perSecond: 100, concurrency: 4 } } });
+    let inFlight = 0;
+    let peak = 0;
+    const run = await runGuest({
+      code, job: pullJob(),
+      host: {
+        http: async (payload) => {
+          inFlight += 1;
+          peak = Math.max(peak, inFlight);
+          await Bun.sleep(5);
+          inFlight -= 1;
+          return httpResponse(200, { i: Number((payload as EgressHttpRequest).query.i) });
+        },
+      },
+    });
+    expect(rows(run)).toEqual([{ out: Array.from({ length: 20 }, (_, i) => i * 2) }]);
+    expect(peak).toBe(4);
+  });
+
+  test('作业带生效限流（连接覆盖更小）时 ctx.map 按它收紧；更大时仍按描述', async () => {
+    const code = streamConnector(`
+      const items = Array.from({ length: 12 }, (_, i) => i);
+      const out = await ctx.map(items, async (i) => (await ctx.http.get('https://api.x.com/i', { query: { i } })).data.i, { concurrency: 8 });
+      yield ctx.record('item', { n: out.length });`, { extra: { rateLimit: { perSecond: 100, concurrency: 4 } } });
+    for (const [rateLimit, expected] of [[{ perSecond: 1, concurrency: 2 }, 2], [{ perSecond: 100, concurrency: 16 }, 4], [undefined, 4]] as const) {
+      let inFlight = 0;
+      let peak = 0;
+      const run = await runGuest({
+        code, job: pullJob(rateLimit ? { rateLimit } : {}),
+        host: {
+          http: async (payload) => {
+            inFlight += 1;
+            peak = Math.max(peak, inFlight);
+            await Bun.sleep(5);
+            inFlight -= 1;
+            return httpResponse(200, { i: Number((payload as EgressHttpRequest).query.i) });
+          },
+        },
+      });
+      expect(rows(run)).toEqual([{ n: 12 }]);
+      expect(peak).toBe(expected);
+    }
+  });
+
+  test('cache.getOrSet 未命中时调 fn 并 set，命中时读缓存', async () => {
+    const code = streamConnector(`
+      let calls = 0;
+      const fn = async () => { calls += 1; return 'token-' + calls; };
+      const first = await ctx.cache.getOrSet('session', 3000, fn);
+      const second = await ctx.cache.getOrSet('session', 3000, fn);
+      yield ctx.record('item', { first, second, calls });`);
+    const store = new Map<string, string>();
+    const run = await runGuest({
+      code, job: pullJob(),
+      host: {
+        'cache.get': (payload) => {
+          const value = store.get((payload as { key: string }).key);
+          return value === undefined ? null : { value, expiresAt: new Date(Date.now() + 60_000).toISOString() };
+        },
+        'cache.set': (payload) => {
+          const { key, value } = payload as { key: string; value: string };
+          store.set(key, value);
+          return null;
+        },
+      },
+    });
+    expect(rows(run)).toEqual([{ first: 'token-1', second: 'token-1', calls: 1 }]);
+    expect(run.calls.filter((entry) => entry.method.startsWith('cache.')).map((entry) => entry.method)).toEqual(['cache.get', 'cache.set', 'cache.get']);
+    expect(run.calls.find((entry) => entry.method === 'cache.set')?.payload).toEqual({ key: 'session', value: 'token-1', ttlSeconds: 3000 });
+  });
+
+  test('crypto：hmac / hash 走宿主，base64 在 guest 里按 UTF-8 编解码', async () => {
+    const code = streamConnector(`
+      const signature = await ctx.crypto.hmac('sha256', ctx.secrets.appSecret, 'data');
+      const digest = await ctx.crypto.hash('md5', 'abc', 'base64');
+      const encoded = ctx.crypto.base64Encode('金蝶 ok ✓');
+      yield ctx.record('item', { signature, digest, encoded, decoded: ctx.crypto.base64Decode(encoded) });`, { config: { appSecret: configField('secret') } });
+    const run = await runGuest({ code, job: pullJob({ secretFields: ['appSecret'] }), host: { crypto: (payload) => ({ value: `digest:${(payload as { op: string }).op}` }) } });
+    expect(rows(run)).toEqual([{ signature: 'digest:hmac', digest: 'digest:hash', encoded: Buffer.from('金蝶 ok ✓').toString('base64'), decoded: '金蝶 ok ✓' }]);
+    expect(run.calls.filter((entry) => entry.method === 'crypto').map((entry) => entry.payload)).toEqual([
+      { op: 'hmac', algorithm: 'sha256', key: 'ontos:secret:appSecret', data: 'data', encoding: 'hex' },
+      { op: 'hash', algorithm: 'md5', data: 'abc', encoding: 'base64' },
+    ]);
+  });
+
+  test('time.toUtc 按时区换算本地时间', async () => {
+    const code = streamConnector(`
+      yield ctx.record('item', {
+        shanghai: ctx.time.toUtc('2026-10-25 08:00:00', 'Asia/Shanghai'),
+        newYorkDst: ctx.time.toUtc('2026-07-01T12:30:00', 'America/New_York'),
+        formatted: ctx.time.toUtc('25/10/2026 08:00', 'Asia/Shanghai', 'DD/MM/YYYY HH:mm'),
+        zoned: ctx.time.toUtc('2026-10-25T08:00:00+08:00', 'UTC'),
+        now: typeof ctx.time.now(),
+      });`);
+    const run = await runGuest({ code, job: pullJob() });
+    expect(rows(run)).toEqual([{
+      shanghai: '2026-10-25T00:00:00.000Z', newYorkDst: '2026-07-01T16:30:00.000Z', formatted: '2026-10-25T00:00:00.000Z',
+      zoned: '2026-10-25T00:00:00.000Z', now: 'string',
+    }]);
+  });
+});
+
+describe('ctx.signal / ctx.log', () => {
+  test('宿主发 cancel 后 signal.aborted 为 true，onAbort 回调被调用', async () => {
+    const code = checkConnector(`
+    let called = false;
+    ctx.signal.onAbort(() => { called = true; });
+    const before = ctx.signal.aborted;
+    try { await ctx.http.get('https://api.x.com/slow'); } catch (e) { ctx.log.info(JSON.stringify({ before, after: ctx.signal.aborted, called, code: e.code })); }`);
+    const run = await runGuest({ code, job: checkJob(), host: { http: (_payload, host) => { host.cancel(); return new Promise(() => undefined); } } });
+    const failure = expectFailure(run.outcome);
+    expect(failure.code).toBe('CANCELED');
+    expect(JSON.parse(failure.logs[0]?.message ?? '{}')).toEqual({ before: false, after: true, called: true, code: 'CANCELED' });
+  });
+
+  test('ctx.log 一次运行最多保留 1000 条，单条超过 4096 字符截断', async () => {
+    const code = checkConnector(`
+    ctx.log.warn('x'.repeat(5000));
+    for (let i = 0; i < 1000; i += 1) ctx.log.info('line ' + i, { i });`);
+    const result = expectResult((await runGuest({ code, job: checkJob() })).outcome);
+    expect(result.logs).toHaveLength(1000);
+    expect(result.logs[0]).toMatchObject({ level: 'warn' });
+    expect(result.logs[0]?.message).toHaveLength(4096);
+    expect(result.logs[1]?.message).toBe('line 0 {"i":0}');
+    expect(result.logs[999]?.message).toBe('line 998 {"i":998}');
+  });
+});

package/test/runtime/helpers.ts

@@ -0,0 +1,157 @@
+/**
+ * 运行时测试的假宿主：在测试进程里直接建 guest 会话（vm 上下文），按方法回应 `call`。
+ * 每条子进程消息都先过一遍 `parseChildMessage`，顺带验证消息符合协议。
+ */
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import type { BunPlugin, Loader } from 'bun';
+import {
+  createGuestSession, GUEST_ENTRY_PATH, parseChildMessage, type ChildMessage, type GuestJob, type HostCallError, type HostMethod,
+} from '../../src/runtime';
+
+const LOADERS: Readonly<Record<string, Loader>> = { ts: 'ts', mts: 'ts', cts: 'ts', tsx: 'tsx', js: 'js', mjs: 'js', cjs: 'js', jsx: 'jsx' };
+
+/** Bun 1.3：当前进程已 import 过的源文件再交给 `Bun.build` 会报「Unexpected reading file」，经插件自己读文件绕开。 */
+const readSourcePlugin: BunPlugin = {
+  name: 'sdk-test-read-source',
+  setup(build) {
+    build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, async (args) => {
+      const extension = args.path.slice(args.path.lastIndexOf('.') + 1);
+      return { contents: await Bun.file(args.path).text(), loader: LOADERS[extension] ?? 'ts' };
+    });
+  },
+};
+
+async function build(entry: string, external: string[] = []): Promise<string> {
+  const result = await Bun.build({ entrypoints: [entry], format: 'cjs', target: 'browser', minify: false, external, plugins: [readSourcePlugin] });
+  const output = result.outputs[0];
+  if (!result.success || !output) throw new Error(`bundle failed: ${result.logs.map((log) => log.message).join('; ')}`);
+  return output.text();
+}
+
+let guestBundle: Promise<string> | undefined;
+
+/** 与 Phase 2 的 `bundleTrustedEntry` 参数一致：cjs、browser、不压缩。 */
+export function bundleGuest(): Promise<string> {
+  guestBundle ??= build(GUEST_ENTRY_PATH);
+  return guestBundle;
+}
+
+/** 把 TS 连接器源码打成 CJS，SDK 为 external（与平台打包一致）。 */
+export async function bundleConnector(source: string): Promise<string> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'sdk-runtime-'));
+  try {
+    const entry = path.join(dir, 'index.ts');
+    await writeFile(entry, source);
+    return await build(entry, ['@deepexi/datasense-connector']);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+export class HostReject extends Error {
+  readonly error: HostCallError;
+
+  constructor(error: HostCallError) {
+    super(error.message);
+    this.error = error;
+  }
+}
+
+export type HostHandler = (payload: unknown, session: FakeHost) => unknown;
+
+export interface FakeHost {
+  calls: Array<{ method: HostMethod; payload: unknown }>;
+  messages: ChildMessage[];
+  cancel(): void;
+}
+
+export interface RunOptions {
+  code: string;
+  job: GuestJob;
+  expect?: { name: string; version: string };
+  host?: Partial<Record<HostMethod, HostHandler>>;
+  /** 每条消息之后调用（例如在某次调用之后发 cancel）。 */
+  onMessage?(message: ChildMessage, host: FakeHost): void;
+  timeoutMs?: number;
+}
+
+export type Outcome = Extract<ChildMessage, { type: 'result' | 'failure' }>;
+
+export interface RunResult extends FakeHost {
+  outcome: Outcome;
+}
+
+export const DEFAULT_EXPECT = { name: 'demo', version: '1.0.0' };
+
+export async function runGuest(options: RunOptions): Promise<RunResult> {
+  const guest = await bundleGuest();
+  const job = options.job;
+  return new Promise<RunResult>((resolve, reject) => {
+    const host: FakeHost = {
+      calls: [],
+      messages: [],
+      cancel: () => session.handle(JSON.stringify({ type: 'cancel' })),
+    };
+    const timer = setTimeout(() => reject(new Error(`guest did not finish; messages: ${JSON.stringify(host.messages)}`)), options.timeoutMs ?? 10_000);
+    const reply = (id: number, handler: HostHandler | undefined, payload: unknown) => {
+      Promise.resolve()
+        .then(() => (handler ? handler(payload, host) : null))
+        .then(
+          (value) => session.handle(JSON.stringify({ type: 'reply', id, ok: true, value: value ?? null })),
+          (error: unknown) => {
+            const failure = error instanceof HostReject ? error.error : { code: 'HOST_TEST_ERROR', message: String(error) };
+            session.handle(JSON.stringify({ type: 'reply', id, ok: false, error: failure }));
+          },
+        );
+    };
+    const session = createGuestSession((json) => {
+      const message = parseChildMessage(JSON.parse(json), job);
+      if (!message) {
+        clearTimeout(timer);
+        reject(new Error(`malformed child message: ${json}`));
+        return;
+      }
+      host.messages.push(message);
+      if (message.type === 'call') {
+        host.calls.push({ method: message.method, payload: message.payload });
+        reply(message.id, options.host?.[message.method], message.payload);
+      }
+      options.onMessage?.(message, host);
+      if (message.type === 'result' || message.type === 'failure') {
+        clearTimeout(timer);
+        resolve({ ...host, outcome: message });
+      }
+    });
+    session.handle(JSON.stringify({ type: 'execute', guest, code: options.code, expect: options.expect ?? DEFAULT_EXPECT, job }));
+  });
+}
+
+export const checkJob = (config: Record<string, unknown> = {}, secretFields: string[] = []): GuestJob => ({ kind: 'check', config, secretFields });
+
+export const suggestJob = (stream: string, table: string, config: Record<string, unknown> = {}): GuestJob => ({ kind: 'suggest', config, secretFields: [], stream, table });
+
+export const pullJob = (overrides: Partial<Extract<GuestJob, { kind: 'pull' }>> = {}): GuestJob => ({
+  kind: 'pull', config: {}, secretFields: [], stream: 'items', mode: 'full', state: null, streamConfig: {}, tables: ['item'], ...overrides,
+});
+
+export const pushJob = (requests: Array<{ requestId: string; push?: string; body: string }>, config: Record<string, unknown> = {}): GuestJob => ({
+  kind: 'push', config, secretFields: [],
+  requests: requests.map((request) => ({
+    requestId: request.requestId, push: request.push ?? 'default', receivedAt: '2026-10-25T00:00:00.000Z',
+    headers: { 'content-type': 'application/json' }, body: request.body,
+  })),
+});
+
+export { rawConnector } from '../fixtures/descriptor';
+
+export function expectFailure(outcome: Outcome): Extract<ChildMessage, { type: 'failure' }> {
+  if (outcome.type !== 'failure') throw new Error(`expected failure, got ${JSON.stringify(outcome)}`);
+  return outcome;
+}
+
+export function expectResult(outcome: Outcome): Extract<ChildMessage, { type: 'result' }>['result'] {
+  if (outcome.type !== 'result') throw new Error(`expected result, got ${JSON.stringify(outcome)}`);
+  return outcome.result;
+}