@republicroad/zen-udf 0.2.0

package/src/execution-spec.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, test } from 'vitest';
+
+import { DecisionRuntime } from './engine.ts';
+import { runWithExecContext } from './exec-context.ts';
+import { InMemoryConcurrencyLimiter, NoopConcurrencyLimiter } from './limiter.ts';
+import { UdfRegistry } from './register.ts';
+
+/** 带 customNode 的图：expr 调用 target_udf，结果写 out 字段 */
+const graph = (id: string, expr = 'target_udf;;p1;;p2;;p3') => ({
+  id,
+  nodes: [
+    { id: 'in', type: 'inputNode', name: 'Request' },
+    {
+      id: 'c1',
+      type: 'customNode',
+      name: 'custom',
+      content: {
+        kind: 'UDF',
+        config: { expressions: [{ id: 'e1', key: 'out', value: expr }] },
+      },
+    },
+    { id: 'out', type: 'outputNode', name: 'Response' },
+  ],
+  edges: [
+    { id: 'ed1', sourceId: 'in', targetId: 'c1', type: 'edge' },
+    { id: 'ed2', sourceId: 'c1', targetId: 'out', type: 'edge' },
+  ],
+});
+
+const makeRegistry = (fn: (kwargs: Record<string, unknown>) => unknown): UdfRegistry => {
+  const registry = new UdfRegistry();
+  registry.registerFunction(
+    fn,
+    'target',
+    {
+      description: 'target udf',
+      parametersSchema: {
+        properties: {
+          p1: { type: 'string', title: 'P1' },
+          p2: { type: 'integer', title: 'P2' },
+          p3: { type: 'string', title: 'P3', default: '' },
+          timeout: { type: 'integer', title: 'Timeout', default: 0 },
+        },
+      },
+    },
+    'target_udf',
+  );
+  return registry;
+};
+
+const evalGraph = async (runtime: DecisionRuntime, input: unknown) =>
+  runWithExecContext({ tenantId: 't-1' }, () => runtime.evaluateAsync('k', input));
+
+describe('执行规范 §6.1 参数校验', () => {
+  test('必填位置参数缺失 → INVALID_PARAM 结构化错误', async () => {
+    const registry = makeRegistry((kwargs) => ({ echo: kwargs?.p1 ?? null }));
+    const runtime = new DecisionRuntime({ registry });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', graph('g'));
+      return Promise.resolve();
+    });
+
+    // p2 为必填（无默认值），表达式传 null
+    const result = await evalGraph(runtime, { p1: 'a', p2: null, p3: 'c' });
+    const out = (result.result as { out?: { error?: { code?: string; issues?: string[] } } }).out;
+    expect(out?.error?.code).toBe('INVALID_PARAM');
+    expect(JSON.stringify(out?.error?.issues)).toContain('p2 is required');
+  });
+
+  test('有默认值的参数缺失不报错（funcBindParams 回退）', async () => {
+    const registry = makeRegistry((kwargs) => ({ got: kwargs?.p1 ?? null, timeout: kwargs?.timeout ?? null }));
+    const runtime = new DecisionRuntime({ registry });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', graph('g'));
+      return Promise.resolve();
+    });
+
+    const result = await evalGraph(runtime, { p1: 'a', p2: 2, p3: 'c' });
+    const out = (result.result as { out?: { got?: string } }).out;
+    expect(out?.got).toBe('a');
+  });
+});
+
+describe('执行规范 §6.2 超时约定', () => {
+  test('kwargs.timeout 超时返回 UDF_TIMEOUT 结构化错误', async () => {
+    const registry = makeRegistry(async (kwargs) => {
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      return { done: true, input: kwargs?.p1 ?? null };
+    });
+    // timeout 声明为 schema 最后一个参数（默认 0 = 不限时），表达式第 4 位传入
+    const runtime = new DecisionRuntime({ registry });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', graph('g-timeout', 'target_udf;;p1;;p2;;p3;;timeout'));
+      return Promise.resolve();
+    });
+
+    const result = await evalGraph(runtime, { p1: 'a', p2: 1, p3: 'b', timeout: 80 });
+    const out = (result.result as { out?: { error?: { code?: string; message?: string } } }).out;
+    expect(out?.error?.code).toBe('UDF_TIMEOUT');
+  });
+
+  test('未超时则正常返回', async () => {
+    const registry = makeRegistry(async (kwargs) => {
+      await new Promise((resolve) => setTimeout(resolve, 30));
+      return { done: true, input: kwargs?.p1 ?? null };
+    });
+    const runtime = new DecisionRuntime({ registry });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', graph('g-ok', 'target_udf;;p1;;p2;;p3;;timeout'));
+      return Promise.resolve();
+    });
+
+    const result = await evalGraph(runtime, { p1: 'ok', p2: 1, p3: 'b', timeout: 1000 });
+    const out = (result.result as { out?: { done?: boolean; input?: string } }).out;
+    expect(out?.done).toBe(true);
+    expect(out?.input).toBe('ok');
+  });
+});
+
+describe('执行规范 §6.3 并发闸', () => {
+  test('InMemoryConcurrencyLimiter 串行化同租户调用', async () => {
+    let active = 0;
+    let peak = 0;
+    const registry = new UdfRegistry();
+    registry.registerFunction(async function target_udf() {
+      active += 1;
+      peak = Math.max(peak, active);
+      await new Promise((resolve) => setTimeout(resolve, 60));
+      active -= 1;
+      return { ok: true };
+    }, 'target');
+
+    const limiter = new InMemoryConcurrencyLimiter(1);
+    const runtime = new DecisionRuntime({ registry, limiter });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', graph('g'));
+      return Promise.resolve();
+    });
+
+    const [a, b] = await Promise.all([
+      runWithExecContext({ tenantId: 't-1' }, () => runtime.evaluateAsync('k', { p1: 'a', p2: 1, p3: 'c' })),
+      runWithExecContext({ tenantId: 't-1' }, () => runtime.evaluateAsync('k', { p1: 'b', p2: 2, p3: 'c' })),
+    ]);
+    expect(peak).toBe(1);
+    expect((a.result as { out?: { ok?: boolean } }).out?.ok).toBe(true);
+    expect((b.result as { out?: { ok?: boolean } }).out?.ok).toBe(true);
+  });
+
+  test('NoopConcurrencyLimiter 不限制并发', async () => {
+    let active = 0;
+    let peak = 0;
+    const registry = new UdfRegistry();
+    registry.registerFunction(async function target_udf() {
+      active += 1;
+      peak = Math.max(peak, active);
+      await new Promise((resolve) => setTimeout(resolve, 60));
+      active -= 1;
+      return { ok: true };
+    }, 'target');
+
+    const runtime = new DecisionRuntime({ registry, limiter: new NoopConcurrencyLimiter() });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', graph('g'));
+      return Promise.resolve();
+    });
+
+    await Promise.all([
+      runWithExecContext({ tenantId: 't-1' }, () => runtime.evaluateAsync('k', { p1: 'a', p2: 1, p3: 'c' })),
+      runWithExecContext({ tenantId: 't-1' }, () => runtime.evaluateAsync('k', { p1: 'b', p2: 2, p3: 'c' })),
+    ]);
+    expect(peak).toBe(2);
+  });
+});

package/src/index.ts

@@ -0,0 +1,43 @@
+// 参考函数域装载：import 本包根即向 globalUdfRegistry 注册 contrib 参考域
+// （与 0.1.x 行为一致）。需要空注册表（实例隔离）时传 `new UdfRegistry()`，
+// 并按需用 loadReferenceInto 装载参考域。
+import './reference.ts';
+
+export { DecisionRuntime, type DecisionRuntimeOptions, type UdfTrace } from './engine.ts';
+export {
+  DecisionCache,
+  type CacheMetricsSnapshot,
+  type DecisionCacheEntry,
+  type DecisionCacheOptions,
+} from './decision-cache.ts';
+export { getExecContext, runWithExecContext, type ExecContext } from './exec-context.ts';
+export { InMemoryConcurrencyLimiter, NoopConcurrencyLimiter, type ConcurrencyLimiter } from './limiter.ts';
+export { registerRoster, listRosters, getRoster, deleteRoster, queryRoster, type Roster } from './roster.ts';
+export {
+  UdfRegistry,
+  globalUdfRegistry,
+  registerUdf,
+  createExtRegister,
+  createUdfRegistry,
+  validatePack,
+  type UdfPack,
+  type CreateUdfRegistryOptions,
+  type ContribToolDef,
+  type ContribDef,
+  type UdfSchema,
+  type UdfSchemaParameter,
+  type JsonSchema,
+  type JsonSchemaProperty,
+  type CustomFunctionTool,
+  type CustomNodeNamespace,
+} from './register.ts';
+export { loadReferenceInto, referenceDomains } from './reference.ts';
+export { configureHttpUdf, type EgressGuard, type SecretResolver } from './contrib/http.ts';
+export {
+  setRateStore,
+  getRateStore,
+  InMemoryRateStore,
+  type RateStore,
+  type RateCommonResult,
+  type GroupDistinctCommonResult,
+} from './contrib/rate-window.ts';

package/src/limiter.ts

@@ -0,0 +1,70 @@
+/**
+ * 并发闸端口（执行规范 §6.3）：per-tenant UDF 并发上限，防单租户打满
+ * evaluate worker 线程池。机制在本仓（内存参考实现 + 接口契约），真实语义
+ * （分布式/Redis 化配额）由宿主（verdict）实现注入。
+ */
+export interface ConcurrencyLimiter {
+  /** 获取 key（通常是 tenantId）的一个槽位；返回释放函数，必须调用恰好一次。实现须 FIFO 公平 */
+  acquire(key: string): Promise<() => void>;
+}
+
+interface SlotState {
+  active: number;
+  /** 等待队列（FIFO）：resolve 后调用方获得槽位 */
+  queue: Array<() => void>;
+}
+
+/** 进程内信号量参考实现：每 key 最多 maxPerKey 个并发，FIFO 排队 */
+export class InMemoryConcurrencyLimiter implements ConcurrencyLimiter {
+  private readonly slots = new Map<string, SlotState>();
+
+  constructor(private readonly maxPerKey = 5) {
+    this.maxPerKey = Math.max(1, maxPerKey);
+  }
+
+  async acquire(key: string): Promise<() => void> {
+    let state = this.slots.get(key);
+    if (!state) {
+      state = { active: 0, queue: [] };
+      this.slots.set(key, state);
+    }
+
+    if (state.active < this.maxPerKey) {
+      state.active += 1;
+      return this.releaseOf(key);
+    }
+
+    return new Promise((resolve) => {
+      state!.queue.push(() => resolve(this.releaseOf(key)));
+    });
+  }
+
+  private releaseOf(key: string): () => void {
+    return () => {
+      const state = this.slots.get(key);
+      if (!state) return;
+      const next = state.queue.shift();
+      if (next) {
+        // 槽位直接移交队首（active 数不变）
+        next();
+      } else {
+        state.active -= 1;
+        if (state.active === 0 && state.queue.length === 0) {
+          this.slots.delete(key);
+        }
+      }
+    };
+  }
+
+  /** 观测：某 key 当前活跃并发数（测试/指标用） */
+  activeOf(key: string): number {
+    return this.slots.get(key)?.active ?? 0;
+  }
+}
+
+/** 空实现：不限并发（DecisionRuntime 缺省，零开销） */
+export class NoopConcurrencyLimiter implements ConcurrencyLimiter {
+  async acquire(_key: string): Promise<() => void> {
+    return () => {};
+  }
+}

package/src/reference.ts

@@ -0,0 +1,34 @@
+// 参考函数域装载（builtin: 'reference' 的实现核心）。
+// import 本模块即向 globalUdfRegistry 注册全部 contrib 工具（各 contrib 模块的
+// 模块级 defineContrib 副作用）；需要装载到独立实例（多租户/多运行时隔离）时，
+// 调用 loadReferenceInto(registry)。业务 UDF 包（verdict 侧）不应依赖本模块。
+import cryptoTools from './contrib/crypto.ts';
+import customListQueryTools from './contrib/custom-list-query.ts';
+import debugTools from './contrib/debug.ts';
+import debuguiTools from './contrib/debugui.ts';
+import httpTools from './contrib/http.ts';
+import ipLocationTools from './contrib/ip-location.ts';
+import rateWindowTools from './contrib/rate-window.ts';
+import rosterTools from './contrib/roster.ts';
+import { type ContribToolDef, type UdfRegistry, globalUdfRegistry } from './register.ts';
+
+/** 参考域清单：[namespace, tools]——namespace 与 contrib 文件名约定一致 */
+export const referenceDomains: Array<[string, ContribToolDef[]]> = [
+  ['crypto', cryptoTools],
+  ['custom-list-query', customListQueryTools],
+  ['debug', debugTools],
+  ['debugui', debuguiTools],
+  ['http', httpTools],
+  ['ip-location', ipLocationTools],
+  ['rate-window', rateWindowTools],
+  ['roster', rosterTools],
+];
+
+/** 将参考函数域注册到任意注册表（实例隔离场景用；global 的注册由 import 副作用完成） */
+export const loadReferenceInto = (registry: UdfRegistry): void => {
+  for (const [namespace, tools] of referenceDomains) {
+    registry.registerTools(tools, namespace);
+  }
+};
+
+export { globalUdfRegistry };

package/src/register.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'vitest';
+
+import { UdfRegistry } from './register.ts';
+
+describe('UdfRegistry namespace collision（U3 起跨名硬失败）', () => {
+  test('函数名与自身 namespace 同名放行（遗留契约：namespace 优先）', () => {
+    const manager = new UdfRegistry();
+    expect(() => manager.registerFunction(() => null, 'roster', undefined, 'roster')).not.toThrow();
+    expect(manager.udfFunctionSchema('roster')?.namespace).toBe('roster');
+  });
+
+  test('函数名与现有 namespace 同名时抛错', () => {
+    const manager = new UdfRegistry();
+    manager.registerFunction(() => null, 'counter', undefined, 'rate_1h');
+    expect(() => manager.registerFunction(() => null, 'debug', undefined, 'counter')).toThrow(/'counter'/);
+  });
+
+  test('namespace 与现有函数同名时抛错', () => {
+    const manager = new UdfRegistry();
+    manager.registerFunction(() => null, 'debug', undefined, 'roster');
+    expect(() => manager.registerFunction(() => null, 'roster', undefined, 'query_list')).toThrow(/namespace 'roster'/);
+  });
+
+  test('force 逃生口可显式接管撞名', () => {
+    const manager = new UdfRegistry();
+    manager.registerFunction(() => null, 'counter', undefined, 'rate_1h');
+    expect(() => manager.registerFunction(() => null, 'debug', undefined, 'counter', { force: true })).not.toThrow();
+    expect(manager.udfFunctionSchema('counter')).toBeDefined();
+  });
+
+  test('无碰撞时正常注册', () => {
+    const manager = new UdfRegistry();
+    expect(() => manager.registerFunction(() => null, 'debug', undefined, 'inout')).not.toThrow();
+  });
+
+  test('registerTools 批量注册到指定 namespace', () => {
+    const manager = new UdfRegistry();
+    manager.registerTools(
+      [
+        {
+          name: 'tool_a',
+          description: 'a',
+          parametersSchema: { properties: {}, title: 'tool_a', type: 'object' },
+          returnsSchema: { type: 'null' },
+          fn: () => 1,
+        },
+        {
+          name: 'tool_b',
+          description: 'b',
+          parametersSchema: { properties: {}, title: 'tool_b', type: 'object' },
+          returnsSchema: { type: 'null' },
+          fn: () => 2,
+        },
+      ],
+      'pack-ns',
+    );
+    expect(manager.udfFunctionSchema('tool_a')?.namespace).toBe('pack-ns');
+    expect(manager.udfFunctionSchema('tool_b')?.namespace).toBe('pack-ns');
+  });
+});