@volter/twin-temporal 0.1.0

package/src/temporal-conformance.ts

@@ -0,0 +1,52 @@
+// Conformance: the twin's wire, probed as a client finds it — a real socket, HTTP/2, gRPC framing —
+// against a fresh World root. Dev-only (cli.ts imports it lazily).
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { liveTemporalExecute } from './temporal-connector.ts';
+import { createTemporalTwinServer } from './temporal-server.ts';
+import { GrpcError } from './temporal-grpc.ts';
+import { OPERATOR_SERVICE, WORKFLOW_SERVICE, HEALTH_SERVICE } from './temporal-proto.ts';
+
+export type TemporalConformanceReport = { ok: boolean; checksRun: number; failures: string[] };
+
+export async function checkTemporalConformance(options: { root?: string } = {}): Promise<TemporalConformanceReport> {
+  const root = options.root ?? mkdtempSync(join(tmpdir(), 'temporal-conformance-'));
+  const server = await createTemporalTwinServer({ root });
+  const failures: string[] = [];
+  let checksRun = 0;
+  const check = async (name: string, probe: () => Promise<boolean>): Promise<void> => {
+    checksRun += 1;
+    try {
+      if (!(await probe())) failures.push(name);
+    } catch (error) {
+      failures.push(`${name}: ${(error as Error).message}`);
+    }
+  };
+  const call = liveTemporalExecute({ address: `127.0.0.1:${server.port}`, tls: false, budgetOptions: { root } });
+  const refusal = async (service: string, method: string, request: Record<string, unknown>): Promise<number | undefined> => {
+    try {
+      await call(service, method, request);
+      return undefined;
+    } catch (error) {
+      return error instanceof GrpcError ? error.code : -1;
+    }
+  };
+  try {
+    await check('GetSystemInfo answers a server version over h2c', async () => /^\d+\.\d+\.\d+$/.test(String((await call(WORKFLOW_SERVICE, 'GetSystemInfo', {})).serverVersion)));
+    await check('the default namespace exists', async () => ((await call(WORKFLOW_SERVICE, 'DescribeNamespace', { namespace: 'default' })).namespaceInfo as { name?: string } | undefined)?.name === 'default');
+    await check('an unknown namespace is NOT_FOUND', async () => (await refusal(WORKFLOW_SERVICE, 'DescribeNamespace', { namespace: 'nope' })) === 5);
+    await check('an RPC the twin does not serve is UNIMPLEMENTED', async () => (await refusal(WORKFLOW_SERVICE, 'ListSchedules', { namespace: 'default' })) === 12);
+    await check('an OperatorService RPC the twin does not serve is UNIMPLEMENTED', async () => (await refusal(OPERATOR_SERVICE, 'ListClusters', {})) === 12);
+    await check('a start answers a run id, and a second start of the id is ALREADY_EXISTS', async () => {
+      const start = { namespace: 'default', workflowId: 'conformance', workflowType: { name: 'wf' }, taskQueue: { name: 'q' } };
+      const first = await call(WORKFLOW_SERVICE, 'StartWorkflowExecution', { ...start, requestId: 'a' });
+      return /^[0-9a-f-]{36}$/.test(String(first.runId)) && (await refusal(WORKFLOW_SERVICE, 'StartWorkflowExecution', { ...start, requestId: 'b' })) === 6;
+    });
+    await check('health Check answers SERVING', async () => (await call(HEALTH_SERVICE, 'Check', {})).status === 'SERVING');
+  } finally {
+    await server.stop();
+    if (!options.root) rmSync(root, { recursive: true, force: true });
+  }
+  return { ok: failures.length === 0, checksRun, failures };
+}

package/src/temporal-connector.ts

@@ -0,0 +1,118 @@
+// The connector: pull a real Temporal frontend's namespace configuration into the World, over an
+// INJECTED unary-call function (the real network exists only inside liveTemporalExecute).
+//
+// What a pull observes is what a World needs to stand in for a real cluster before any app runs:
+// its namespaces (DescribeNamespaceResponse, the vendor's shape) and each namespace's custom search
+// attributes (an app's starts are refused over an attribute the namespace does not define). A real
+// cluster's workflow runs are NOT pulled: a run's state is its history, written by the workers that
+// execute it, and a copied history without those workers is a run nothing can advance.
+//
+// Push refuses by name. A World's local runs cannot be performed on a real cluster — a start or a
+// signal could be resent, but everything after it (workflow and activity tasks) is the work of
+// workers, which a deploy does not move.
+import { assertBudgetGuardIntact, observeResource, worldNow, type PushOutcome, type RemoteExecute, type TwinAction } from '@volter/world-core';
+import { TemporalBudget, temporalCallWeight, type TemporalBudgetOptions } from './temporal-budget.ts';
+import http2 from 'node:http2';
+import { decodeMessage, encodeMessage, serviceMethods, OPERATOR_SERVICE, WORKFLOW_SERVICE } from './temporal-proto.ts';
+import { GrpcError, grpcFrame, splitGrpcFrames } from './temporal-grpc.ts';
+
+type Obj = Record<string, unknown>;
+
+/** One unary call on a Temporal frontend: (service, method, request) → response, in the engine's plain form. */
+export type TemporalExecute = (service: string, method: string, request: Obj) => Promise<Obj>;
+
+/** THE CHOKE POINT — the one place this pack reaches a real Temporal frontend. `address` is host:port
+ *  (TEMPORAL_ADDRESS); `apiKey` (TEMPORAL_API_KEY) is sent as a bearer token, and a key implies TLS,
+ *  as the SDKs do. Every call is charged to the rate budget BEFORE it connects (a refused budget
+ *  throws and nothing is sent) and settled after, even when the call fails; a stand-in budget whose
+ *  guard methods are not the kernel's is refused rather than trusted. */
+export function liveTemporalExecute(options: { address?: string; apiKey?: string; tls?: boolean; namespace?: string; budget?: TemporalBudget; budgetOptions?: TemporalBudgetOptions } = {}): TemporalExecute {
+  const address = options.address ?? process.env.TEMPORAL_ADDRESS;
+  if (!address) throw new Error('liveTemporalExecute: TEMPORAL_ADDRESS is not set (host:port of a Temporal frontend)');
+  const apiKey = options.apiKey ?? process.env.TEMPORAL_API_KEY;
+  const tls = options.tls ?? Boolean(apiKey);
+  if (options.budget !== undefined && options.budget !== null) assertBudgetGuardIntact(options.budget, TemporalBudget, 'liveTemporalExecute');
+  const budget = options.budget instanceof TemporalBudget ? options.budget : new TemporalBudget({ token: address, ...(options.budgetOptions ?? {}) });
+  return async (service, method, request) => {
+    const weight = temporalCallWeight(service, method);
+    const reservation = budget.checkBudget(weight);
+    try {
+      return await unaryCall(address, tls, apiKey, options.namespace, service, method, request);
+    } finally {
+      budget.recordCall(weight, {}, { reservation });
+    }
+  };
+}
+
+function unaryCall(address: string, tls: boolean, apiKey: string | undefined, namespace: string | undefined, service: string, method: string, request: Obj): Promise<Obj> {
+  const options = { namespace };
+  return new Promise((resolve, reject) => {
+    const table = serviceMethods(service).get(method);
+    if (!table) { reject(new Error(`liveTemporalExecute: ${service}/${method} is not in the vendored API`)); return; }
+    const session = http2.connect(`${tls ? 'https' : 'http'}://${address}`);
+    session.on('error', (error) => { session.destroy(); reject(error); });
+    const stream = session.request({
+      ':method': 'POST', ':path': `/${service}/${method}`, 'content-type': 'application/grpc', te: 'trailers',
+      ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
+      ...(options.namespace ? { 'temporal-namespace': options.namespace } : {}),
+    });
+    const chunks: Buffer[] = [];
+    let status = '';
+    let message = '';
+    stream.on('response', (headers) => { status = String(headers['grpc-status'] ?? status); message = String(headers['grpc-message'] ?? message); });
+    stream.on('trailers', (trailers) => { status = String(trailers['grpc-status'] ?? status); message = String(trailers['grpc-message'] ?? message); });
+    stream.on('data', (chunk: Buffer) => chunks.push(chunk));
+    stream.on('error', (error) => { session.destroy(); reject(error); });
+    stream.on('end', () => {
+      session.close();
+      if (status !== '0') {
+        let text = message;
+        try { text = decodeURIComponent(message); } catch { /* a grpc-message that is not percent-encoding is shown as sent */ }
+        reject(new GrpcError(Number(status || 2), text));
+        return;
+      }
+      try {
+        const [frame] = splitGrpcFrames(new Uint8Array(Buffer.concat(chunks)));
+        resolve(frame ? decodeMessage(table.responseType, frame.message) : {});
+      } catch (error) { reject(error); }
+    });
+    stream.end(Buffer.from(grpcFrame(encodeMessage(table.requestType, request))));
+  });
+}
+
+
+/** Pull a real frontend's namespaces and their custom search attributes into the tree. */
+export async function syncTemporalFromReal(execute: TemporalExecute, options: { root?: string; occurredAt?: string } = {}): Promise<{ pulled: number }> {
+  const at = options.occurredAt ?? worldNow();
+  const scope = { ...(options.root !== undefined ? { root: options.root } : {}), at };
+  // read everything first: a call that fails part way leaves the tree as it was
+  const namespaces: Obj[] = [];
+  let pageToken: unknown;
+  do {
+    const listing = await execute(WORKFLOW_SERVICE, 'ListNamespaces', { pageSize: 100, ...(pageToken ? { nextPageToken: pageToken } : {}) });
+    namespaces.push(...((listing.namespaces ?? []) as Obj[]));
+    pageToken = listing.nextPageToken;
+  } while (pageToken);
+  const observed: Array<{ name: string; fields: Obj }> = [];
+  for (const described of namespaces) {
+    const name = String((described.namespaceInfo as Obj | undefined)?.name ?? '');
+    if (!name) throw new Error('temporal: a listed namespace has no name — refusing to fold a partial pull');
+    const attributes = await execute(OPERATOR_SERVICE, 'ListSearchAttributes', { namespace: name });
+    // the namespace's custom search attributes ride its subject as bookkeeping, as the engine keeps them
+    observed.push({ name, fields: { ...described, _searchAttributes: (attributes.customAttributes ?? {}) as Record<string, string> } });
+  }
+  for (const { name, fields } of observed) observeResource('temporal', { type: 'namespace', id: name, fields }, scope);
+  return { pulled: observed.length };
+}
+
+/** The real-system half of the state system (head.ts): performing one landed entry against a real
+ *  cluster. Refused, by name, for every entry — see the header; a real head over this twin stops its
+ *  deploy at the first entry with this reason rather than pretending the entry landed. */
+export async function performTemporalAction(_execute: RemoteExecute, action: TwinAction): Promise<PushOutcome> {
+  throw new Error(`temporal: performing ${action.operation} on a real Temporal cluster is not supported — a run's history is written by the workers that execute it, which a deploy does not move`);
+}
+
+/** Deploying a World's local runs to a real cluster is refused, by name (see the header). */
+export async function pushPendingTemporalActions(): Promise<never> {
+  throw new Error('temporal: pushing local workflow runs to a real Temporal cluster is not supported — a run\'s history is written by the workers that execute it, which a deploy does not move');
+}