@republicroad/zen-udf 0.2.0

package/src/decision-runtime.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, test } from 'vitest';
+
+import { DecisionRuntime } from './engine.ts';
+import { getExecContext, runWithExecContext } from './exec-context.ts';
+import './reference.ts';
+import { UdfRegistry } from './register.ts';
+
+// 缺省构造回落 globalUdfRegistry：装载参考域
+
+const graph = {
+  id: 'tenant-graph',
+  nodes: [
+    { id: 'in', type: 'inputNode', name: 'Request' },
+    { id: 'out', type: 'outputNode', name: 'Response' },
+  ],
+  edges: [],
+};
+
+/** 带 customNode 的图：expr 调用 probe_udf 并把结果写到 out 字段 */
+const customGraph = (id: string) => ({
+  id,
+  nodes: [
+    { id: 'in', type: 'inputNode', name: 'Request' },
+    {
+      id: 'c1',
+      type: 'customNode',
+      name: 'custom',
+      content: {
+        kind: 'UDF',
+        config: { expressions: [{ id: 'e1', key: 'out', value: 'probe_udf;;x' }] },
+      },
+    },
+    { id: 'out', type: 'outputNode', name: 'Response' },
+  ],
+  edges: [
+    { id: 'ed1', sourceId: 'in', targetId: 'c1', type: 'edge' },
+    { id: 'ed2', sourceId: 'c1', targetId: 'out', type: 'edge' },
+  ],
+});
+
+describe('DecisionRuntime 租户上下文强制（U2）', () => {
+  test('无租户上下文时 evaluate 拒绝执行（fail closed）', async () => {
+    const runtime = new DecisionRuntime({});
+    await runWithExecContext({ tenantId: 'setup' }, () => {
+      runtime.createDecisionWithCacheKey('k', structuredClone(graph));
+      return Promise.resolve();
+    });
+
+    await expect(runtime.evaluateAsync('k', { x: 1 })).rejects.toThrow('missing exec context tenantId');
+    await expect(runWithExecContext({ userId: 'u1' }, () => runtime.evaluateAsync('k', { x: 1 }))).rejects.toThrow(
+      'missing exec context tenantId',
+    );
+  });
+
+  test('携带 tenantId 时正常执行', async () => {
+    const runtime = new DecisionRuntime({});
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', structuredClone(graph));
+      return Promise.resolve();
+    });
+
+    const result = await runWithExecContext({ tenantId: 't-1', userId: 'u1' }, () =>
+      runtime.evaluateAsync('k', { x: 1 }),
+    );
+    expect(result.result).toBeDefined();
+  });
+
+  test('tenantExempt 豁免单租户部署', async () => {
+    const runtime = new DecisionRuntime({});
+    await runWithExecContext({ tenantExempt: true }, () => {
+      runtime.createDecisionWithCacheKey('k', structuredClone(graph));
+      return Promise.resolve();
+    });
+
+    const result = await runWithExecContext({ tenantExempt: true }, () => runtime.evaluateAsync('k', { x: 1 }));
+    expect(result.result).toBeDefined();
+  });
+
+  test('tenantId 经 AsyncLocalStorage 贯穿并发链路', async () => {
+    const probe = async (): Promise<string | undefined> => {
+      await new Promise((resolve) => setTimeout(resolve, Math.random() * 10));
+      return getExecContext()?.tenantId;
+    };
+    const results = await Promise.all([
+      runWithExecContext({ tenantId: 't-a' }, probe),
+      runWithExecContext({ tenantId: 't-b' }, probe),
+      runWithExecContext({ tenantId: 't-c' }, probe),
+    ]);
+    expect(results).toEqual(['t-a', 't-b', 't-c']);
+  });
+});
+
+describe('DecisionRuntime 实例注入（U3）', () => {
+  const makeRegistry = (tag: string): UdfRegistry => {
+    const registry = new UdfRegistry();
+    registry.registerFunction(function probe_udf(kwargs: Record<string, unknown>) {
+      return { tag, x: kwargs?.x ?? null };
+    }, 'probe');
+    return registry;
+  };
+
+  test('两个运行时实例同名 UDF 各自解析，互不串扰', async () => {
+    const ra = new DecisionRuntime({ registry: makeRegistry('A') });
+    const rb = new DecisionRuntime({ registry: makeRegistry('B') });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      ra.createDecisionWithCacheKey('k', customGraph('ga'));
+      rb.createDecisionWithCacheKey('k', customGraph('gb'));
+      return Promise.resolve();
+    });
+
+    const [a, b] = await Promise.all([
+      runWithExecContext({ tenantId: 't-1' }, () => ra.evaluateAsync('k', { x: 1 })),
+      runWithExecContext({ tenantId: 't-1' }, () => rb.evaluateAsync('k', { x: 2 })),
+    ]);
+    expect((a.result as { out: { tag: string } }).out.tag).toBe('A');
+    expect((b.result as { out: { tag: string } }).out.tag).toBe('B');
+  });
+
+  test('空注册表的运行时对未知 UDF 返回结构化错误而非抛出', async () => {
+    const runtime = new DecisionRuntime({ registry: new UdfRegistry() });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', customGraph('g-empty'));
+      return Promise.resolve();
+    });
+
+    const result = await runWithExecContext({ tenantId: 't-1' }, () => runtime.evaluateAsync('k', { x: 1 }));
+    const serialized = JSON.stringify(result);
+    expect(serialized).toContain('udf probe_udf not found');
+  });
+
+  test('缺省构造回落 globalUdfRegistry（reference 装载后 http 可用）', () => {
+    const runtime = new DecisionRuntime();
+    expect(runtime.udfFunctionSchemaTools().length).toBeGreaterThan(0);
+  });
+
+  test('ExecContext 经输入保留键贯穿 TSFN 边界，UDF 内可读（ALS 重建立）', async () => {
+    const registry = new UdfRegistry();
+    registry.registerFunction(function probe_udf() {
+      return { tenantInUdf: getExecContext()?.tenantId ?? null, userInUdf: getExecContext()?.userId ?? null };
+    }, 'probe');
+    const runtime = new DecisionRuntime({ registry });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', customGraph('g-als'));
+      return Promise.resolve();
+    });
+
+    const result = await runWithExecContext({ tenantId: 't-1', userId: 'u-9' }, () =>
+      runtime.evaluateAsync('k', { x: 1 }),
+    );
+    const out = (result.result as { out?: { tenantInUdf?: string; userInUdf?: string } }).out;
+    expect(out?.tenantInUdf).toBe('t-1');
+    expect(out?.userInUdf).toBe('u-9');
+  });
+});

package/src/engine-cache-semantics.test.ts

@@ -0,0 +1,87 @@
+import { ZenEngine } from '@gorules/zen-engine';
+import { describe, expect, test } from 'vitest';
+
+/**
+ * zen-engine 2.0.2 缓存语义哨兵（源码核对 + 探针实证，设计见 docs/design/zen-udf-multi-tenant.md）：
+ * - 函数 loader 无引擎级缓存：engine.evaluate(key)/getDecision(key) 每次回调 loader 并重新解析
+ * - createDecision 返回的 ZenDecision 可复用：解析一次、evaluate N 次
+ * - customNode 不影响上述语义；customHandler 每次 evaluate 回调
+ * 多租户缓存架构（宿主自管 Map<key, ZenDecision>）建立在这些语义之上；
+ * 升级 zen-engine 后本测试若失败，说明缓存行为变化，需重新评估缓存设计。
+ */
+const graph = {
+  id: 'g',
+  nodes: [
+    { id: 'in', type: 'inputNode', name: 'Request' },
+    { id: 'out', type: 'outputNode', name: 'Response' },
+  ],
+  edges: [],
+};
+
+describe('zen-engine 缓存语义（2.0.2 实证）', () => {
+  test('函数 loader：evaluate(key) 每次回调 loader（引擎不缓存）', async () => {
+    let loads = 0;
+    const engine = new ZenEngine({
+      loader: async () => {
+        loads += 1;
+        return Buffer.from(JSON.stringify(graph));
+      },
+    });
+    await engine.evaluate('k', { a: 1 });
+    await engine.evaluate('k', { a: 2 });
+    expect(loads).toBe(2);
+  });
+
+  test('函数 loader：getDecision(key) 每次回调 loader', async () => {
+    let loads = 0;
+    const engine = new ZenEngine({
+      loader: async () => {
+        loads += 1;
+        return Buffer.from(JSON.stringify(graph));
+      },
+    });
+    await engine.getDecision('k');
+    await engine.getDecision('k');
+    expect(loads).toBe(2);
+  });
+
+  test('createDecision 实例可复用：解析一次 evaluate 多次', async () => {
+    const engine = new ZenEngine({});
+    const decision = engine.createDecision(structuredClone(graph));
+    const first = await decision.evaluate({ x: 1 });
+    const second = await decision.evaluate({ x: 2 });
+    expect(first.result).toBeDefined();
+    expect(second.result).toBeDefined();
+  });
+
+  test('customNode：缓存决策复用不受影响，handler 每次 evaluate 回调', async () => {
+    let handlerCalls = 0;
+    const engine = new ZenEngine({
+      customHandler: async () => {
+        handlerCalls += 1;
+        return { output: { handled: true } };
+      },
+    });
+    const customGraph = {
+      id: 'gc',
+      nodes: [
+        { id: 'in', type: 'inputNode', name: 'Request' },
+        {
+          id: 'c1',
+          type: 'customNode',
+          name: 'custom',
+          content: { kind: 'UDF', config: { expressions: [{ id: 'e1', key: 'r', value: 'some_udf;;x' }] } },
+        },
+        { id: 'out', type: 'outputNode', name: 'Response' },
+      ],
+      edges: [
+        { id: 'e1', sourceId: 'in', targetId: 'c1', type: 'edge' },
+        { id: 'e2', sourceId: 'c1', targetId: 'out', type: 'edge' },
+      ],
+    };
+    const decision = engine.createDecision(customGraph);
+    await decision.evaluate({ x: 1 });
+    await decision.evaluate({ x: 2 });
+    expect(handlerCalls).toBe(2);
+  });
+});