From 1112505f0283f25ece9f1a5ed9edb3fc4410c401 Mon Sep 17 00:00:00 2001 From: Joie Wu Date: Tue, 17 Nov 2026 13:12:57 -0800 Subject: [PATCH 1/9] Add Nexus serialization context sample --- README.md | 1 + nexus-serialization-context/.eslintignore | 3 + nexus-serialization-context/.eslintrc.js | 48 ++++ nexus-serialization-context/.gitignore | 3 + nexus-serialization-context/.prettierrc | 2 + nexus-serialization-context/README.md | 186 +++++++++++++ nexus-serialization-context/package.json | 51 ++++ nexus-serialization-context/src/api.ts | 4 + .../src/caller/worker.ts | 24 ++ .../src/caller/workflows.ts | 31 +++ nexus-serialization-context/src/codec.ts | 103 ++++++++ .../src/handler/handler.ts | 16 ++ .../src/handler/worker.ts | 29 ++ .../src/handler/workflows.ts | 3 + .../src/mocha/codec.test.ts | 171 ++++++++++++ .../src/mocha/workflows.test.ts | 191 ++++++++++++++ nexus-serialization-context/src/shared.ts | 11 + nexus-serialization-context/src/starter.ts | 29 ++ nexus-serialization-context/tsconfig.json | 14 + pnpm-lock.yaml | 247 ++++++++++++++++++ 20 files changed, 1167 insertions(+) create mode 100644 nexus-serialization-context/.eslintignore create mode 100644 nexus-serialization-context/.eslintrc.js create mode 100644 nexus-serialization-context/.gitignore create mode 100644 nexus-serialization-context/.prettierrc create mode 100644 nexus-serialization-context/README.md create mode 100644 nexus-serialization-context/package.json create mode 100644 nexus-serialization-context/src/api.ts create mode 100644 nexus-serialization-context/src/caller/worker.ts create mode 100644 nexus-serialization-context/src/caller/workflows.ts create mode 100644 nexus-serialization-context/src/codec.ts create mode 100644 nexus-serialization-context/src/handler/handler.ts create mode 100644 nexus-serialization-context/src/handler/worker.ts create mode 100644 nexus-serialization-context/src/handler/workflows.ts create mode 100644 nexus-serialization-context/src/mocha/codec.test.ts create mode 100644 nexus-serialization-context/src/mocha/workflows.test.ts create mode 100644 nexus-serialization-context/src/shared.ts create mode 100644 nexus-serialization-context/src/starter.ts create mode 100644 nexus-serialization-context/tsconfig.json diff --git a/README.md b/README.md index 5c63b4321..4e3a0713f 100644 --- a/README.md +++ b/README.md @@ -110,6 +110,7 @@ and you'll be given the list of sample options. #### Nexus APIs - [**Nexus Hello**](./nexus-hello): Demonstrates how to define a Nexus Service, implement the Operation handlers, and call the Operations from a Workflow. +- [**Nexus Serialization Context**](./nexus-serialization-context): Select endpoint-specific encryption and compression for synchronous and workflow-backed asynchronous Nexus Operations. - [**Nexus Cancellation**](./nexus-cancellation): Demonstrates how to cancel a Nexus Operation from a caller workflow using a CancellationScope - [**Nexus Messaging**](./nexus-messaging): Demonstrates how to send signal, update and query messages through Nexus. This contains two samples, one sending messages to an existing workflow and a second that creates a workflow through Nexus diff --git a/nexus-serialization-context/.eslintignore b/nexus-serialization-context/.eslintignore new file mode 100644 index 000000000..7bd99a41b --- /dev/null +++ b/nexus-serialization-context/.eslintignore @@ -0,0 +1,3 @@ +node_modules +lib +.eslintrc.js \ No newline at end of file diff --git a/nexus-serialization-context/.eslintrc.js b/nexus-serialization-context/.eslintrc.js new file mode 100644 index 000000000..58aae9b48 --- /dev/null +++ b/nexus-serialization-context/.eslintrc.js @@ -0,0 +1,48 @@ +const { builtinModules } = require('module'); + +const ALLOWED_NODE_BUILTINS = new Set(['assert']); + +module.exports = { + root: true, + parser: '@typescript-eslint/parser', + parserOptions: { + project: './tsconfig.json', + tsconfigRootDir: __dirname, + }, + plugins: ['@typescript-eslint'], + extends: [ + 'eslint:recommended', + 'plugin:@typescript-eslint/eslint-recommended', + 'plugin:@typescript-eslint/recommended', + 'prettier', + ], + rules: { + // recommended for safety + '@typescript-eslint/no-floating-promises': 'error', // forgetting to await Activities and Workflow APIs is bad + '@typescript-eslint/no-deprecated': 'warn', + + // code style preference + 'object-shorthand': ['error', 'always'], + + // relaxed rules, for convenience + '@typescript-eslint/no-unused-vars': [ + 'warn', + { + argsIgnorePattern: '^_', + varsIgnorePattern: '^_', + }, + ], + '@typescript-eslint/no-explicit-any': 'off', + }, + overrides: [ + { + files: ['src/**/workflows.ts', 'src/**/workflows-*.ts', 'src/**/workflows/*.ts'], + rules: { + 'no-restricted-imports': [ + 'error', + ...builtinModules.filter((m) => !ALLOWED_NODE_BUILTINS.has(m)).flatMap((m) => [m, `node:${m}`]), + ], + }, + }, + ], +}; diff --git a/nexus-serialization-context/.gitignore b/nexus-serialization-context/.gitignore new file mode 100644 index 000000000..28c94d49c --- /dev/null +++ b/nexus-serialization-context/.gitignore @@ -0,0 +1,3 @@ +lib +node_modules +/temporal diff --git a/nexus-serialization-context/.prettierrc b/nexus-serialization-context/.prettierrc new file mode 100644 index 000000000..965d50bff --- /dev/null +++ b/nexus-serialization-context/.prettierrc @@ -0,0 +1,2 @@ +printWidth: 120 +singleQuote: true diff --git a/nexus-serialization-context/README.md b/nexus-serialization-context/README.md new file mode 100644 index 000000000..686ebbdb8 --- /dev/null +++ b/nexus-serialization-context/README.md @@ -0,0 +1,186 @@ +# Nexus serialization context + +This sample uses `NexusSerializationContext` to select an encryption key for each Nexus +endpoint. The caller invokes synchronous and workflow-backed asynchronous operations +through four endpoints. The `compressed-encrypted` worker compresses and then encrypts +Nexus payloads. The `encrypted` worker encrypts without compression. Each handler selects +between its own key 1 and key 2 using the endpoint in the Nexus context. +The caller and each handler run in separate namespaces. + +| Handler worker | Endpoint | Key ID | Nexus payload encoding | +| -------------------- | -------------------------------------------- | ------------------------ | ---------------------- | +| Compressed/encrypted | `nexus-serialization-compressed-encrypted-1` | `compressed-encrypted-1` | zlib, then AES-GCM | +| Compressed/encrypted | `nexus-serialization-compressed-encrypted-2` | `compressed-encrypted-2` | zlib, then AES-GCM | +| Encrypted | `nexus-serialization-encrypted-1` | `encrypted-1` | AES-GCM | +| Encrypted | `nexus-serialization-encrypted-2` | `encrypted-2` | AES-GCM | + +These four endpoint keys are distinct 128-bit AES keys. Compression runs before encryption; +decoding decrypts before decompressing. AES-GCM authenticates the ciphertext. +The encryption codec uses Node.js's AES-GCM implementation and `zlib` module. +Nexus supplies the endpoint context used to select them. The context also identifies the +service and operation, so a codec can select keys using those fields as well. + +Each worker configures `NexusCodec` for its role. The codec keeps an endpoint-to-codec +map and a default for ordinary workflow payloads. The caller uses a separate key for its own input and +final result, keeping those payloads independent of the keys shared with Nexus handlers. +Each handler reuses its key 1 for backing workflow inputs. + +| Ordinary workflow payload | Default key ID | +| -------------------------------------------- | ------------------------ | +| Caller workflow input and final result | `caller-workflow` | +| Compressed/encrypted handler workflow inputs | `compressed-encrypted-1` | +| Encrypted handler workflow inputs | `encrypted-1` | + +These workflow payloads use AES-GCM without compression or endpoint metadata. +An async Nexus result uses the key and compression selected by its endpoint, +even when that differs from the backing workflow's input encryption. + +For synchronous operations, the SDK supplies Nexus context when decoding inputs and +encoding results. When an asynchronous handler starts `EchoWorkflow`, the SDK includes +the Nexus endpoint, service, and operation in the workflow-start request. The server +stores these fields in the `WorkflowExecutionStarted` history event. The worker SDK +restores the Nexus context from that event when encoding the workflow's result, so +`NexusCodec` can select the endpoint's codec and key from the worker's local configuration. +The workflow's input still uses ordinary workflow context; the default codec encrypts +it with that handler's key 1. + +The caller starts all eight operations before waiting for their results. The SDK passes +`SerializationContext` directly to the codec's `encode` and `decode` methods. `NexusCodec` +keeps the endpoint selection local to each call and shares read-only configuration, +so operations for different endpoints do not change each other's encoding. +No custom interceptor or workflow-header propagation is required. + +A workflow execution produces one serialized result, shared by all Nexus operations +attached to it. Operations that need differently encrypted results therefore need +separate workflow executions. This sample starts a backing workflow for each async +operation, using its Nexus request ID as the workflow ID suffix. Retrying the same +request uses the same workflow ID. + +The outer encrypted payload includes `encoding`, `encryption-key-id`, and, for Nexus +payloads, `nexus-endpoint-name` metadata. For example: + +```text +encoding: binary/nexus-aes-gcm +encryption-key-id: compressed-encrypted-1 +nexus-endpoint-name: nexus-serialization-compressed-encrypted-1 +``` + +These labels identify the key and endpoint; they do not contain the key material. +Ordinary workflow payloads have a key ID but no endpoint metadata or compression. + +The AES-GCM codec and hard-coded keys are for this example. Use an established encryption +implementation and secure key storage for production. + +## Prerequisites + +Use Node.js 22 or newer, [pnpm](https://pnpm.io/installation), and Temporal TypeScript +SDK 1.26.0 or later. This SDK version supports native Nexus context propagation to +workflow-backed asynchronous results. + +Use a Temporal Server that supports Nexus serialization-context propagation for +workflow-backed asynchronous operations. For local development, download +[Temporal CLI `v1.9.3-nexus-serialization-context`](https://github.com/temporalio/cli/releases/tag/v1.9.3-nexus-serialization-context). +Extract it and place the `temporal` executable in this sample directory. The commands +below use `./temporal` to run this build separately from your installed CLI. + +## Run locally + +From the repository root, enter the sample directory and install its dependencies: + +```shell +cd nexus-serialization-context +pnpm install +./temporal --version +``` + +The CLI should report `1.9.3-nexus-serialization-context`. Run the remaining commands +from `nexus-serialization-context`, including commands in new terminals. + +The caller and each handler use separate namespaces. Each worker polls a task queue +with the same name as its namespace. Both endpoints for a handler target that handler's +namespace and task queue. + +| Worker | Namespace and task queue | +| ---------------------------- | -------------------------------------------------- | +| Caller | `nexus-serialization-caller` | +| Compressed/encrypted handler | `nexus-serialization-compressed-encrypted-handler` | +| Encrypted handler | `nexus-serialization-encrypted-handler` | + +Start the dev server in its own terminal and leave it running: + +```shell +./temporal server start-dev \ + --namespace nexus-serialization-caller \ + --namespace nexus-serialization-compressed-encrypted-handler \ + --namespace nexus-serialization-encrypted-handler +``` + +In another terminal, create two endpoints for each handler worker: + +```shell +./temporal operator nexus endpoint create \ + --name nexus-serialization-compressed-encrypted-1 \ + --target-namespace nexus-serialization-compressed-encrypted-handler \ + --target-task-queue nexus-serialization-compressed-encrypted-handler +./temporal operator nexus endpoint create \ + --name nexus-serialization-compressed-encrypted-2 \ + --target-namespace nexus-serialization-compressed-encrypted-handler \ + --target-task-queue nexus-serialization-compressed-encrypted-handler +./temporal operator nexus endpoint create \ + --name nexus-serialization-encrypted-1 \ + --target-namespace nexus-serialization-encrypted-handler \ + --target-task-queue nexus-serialization-encrypted-handler +./temporal operator nexus endpoint create \ + --name nexus-serialization-encrypted-2 \ + --target-namespace nexus-serialization-encrypted-handler \ + --target-task-queue nexus-serialization-encrypted-handler +``` + +Run each worker in its own terminal and leave all three running alongside the server: + +```shell +pnpm start.compressed +``` + +```shell +pnpm start.encrypted +``` + +```shell +pnpm start.caller +``` + +Start the caller workflow in another terminal: + +```shell +pnpm workflow +``` + +The starter prints the workflow ID, followed by a sync result and an async result for +each endpoint. Replacing the generated ID, the output is: + +```text +Started workflow: nexus-serialization- +nexus-serialization-compressed-encrypted-1: sync="Hello from Nexus" async="Hello from Nexus" +nexus-serialization-encrypted-1: sync="Hello from Nexus" async="Hello from Nexus" +nexus-serialization-compressed-encrypted-2: sync="Hello from Nexus" async="Hello from Nexus" +nexus-serialization-encrypted-2: sync="Hello from Nexus" async="Hello from Nexus" +``` + +All eight results should be `Hello from Nexus`. The starter exits when they are available; +the workers and server keep running. The run creates five workflow executions: one caller +and four async backing workflows. The four sync operations return directly from their handlers. + +## Test + +Run the codec and workflow tests: + +```shell +pnpm test +pnpm lint +pnpm build +``` + +The workflow test starts an isolated server on private ports using the same CLI build +and checks the stored Nexus context and the backing workflows' input and result metadata. +Set `TEMPORAL_CLI_PATH` to use this CLI build from another location. diff --git a/nexus-serialization-context/package.json b/nexus-serialization-context/package.json new file mode 100644 index 000000000..10fc574c0 --- /dev/null +++ b/nexus-serialization-context/package.json @@ -0,0 +1,51 @@ +{ + "name": "nexus-serialization-context", + "version": "0.1.0", + "private": true, + "scripts": { + "build": "tsc --build", + "build.watch": "tsc --build --watch", + "format": "prettier --write .", + "format:check": "prettier --check .", + "lint": "eslint .", + "test": "mocha --exit --require ts-node/register --require source-map-support/register src/mocha/*.test.ts", + "start.caller": "ts-node src/caller/worker.ts", + "start.compressed": "ts-node src/handler/worker.ts compressed", + "start.encrypted": "ts-node src/handler/worker.ts encrypted", + "workflow": "ts-node src/starter.ts" + }, + "nodemonConfig": { + "execMap": { + "ts": "ts-node" + }, + "ext": "ts", + "watch": [ + "src" + ] + }, + "dependencies": { + "@temporalio/client": "^1.26.0", + "@temporalio/common": "^1.26.0", + "@temporalio/nexus": "^1.26.0", + "@temporalio/proto": "^1.26.0", + "@temporalio/worker": "^1.26.0", + "@temporalio/workflow": "^1.26.0", + "nexus-rpc": "^0.0.3" + }, + "devDependencies": { + "@temporalio/testing": "^1.26.0", + "@tsconfig/node22": "^22.0.0", + "@types/mocha": "10.x", + "@types/node": "^22.9.1", + "@typescript-eslint/eslint-plugin": "^8.72.1", + "@typescript-eslint/parser": "^8.72.1", + "eslint": "^8.57.1", + "eslint-config-prettier": "^9.1.0", + "mocha": "^12.0.3", + "nodemon": "^3.1.7", + "prettier": "^3.4.2", + "source-map-support": "^0.5.21", + "ts-node": "^10.9.2", + "typescript": "^6.0.3" + } +} diff --git a/nexus-serialization-context/src/api.ts b/nexus-serialization-context/src/api.ts new file mode 100644 index 000000000..fada78ea7 --- /dev/null +++ b/nexus-serialization-context/src/api.ts @@ -0,0 +1,4 @@ +import * as nexus from 'nexus-rpc'; + +export const syncEchoService = nexus.service('SyncEchoService', { echo: nexus.operation() }); +export const asyncEchoService = nexus.service('AsyncEchoService', { echoAsync: nexus.operation() }); diff --git a/nexus-serialization-context/src/caller/worker.ts b/nexus-serialization-context/src/caller/worker.ts new file mode 100644 index 000000000..112aeacef --- /dev/null +++ b/nexus-serialization-context/src/caller/worker.ts @@ -0,0 +1,24 @@ +import { NativeConnection, Worker } from '@temporalio/worker'; +import { NexusCodec } from '../codec'; +import { CALLER } from '../shared'; + +async function run() { + const connection = await NativeConnection.connect({ address: process.env.TEMPORAL_ADDRESS ?? 'localhost:7233' }); + try { + const worker = await Worker.create({ + connection, + namespace: CALLER, + taskQueue: CALLER, + workflowsPath: require.resolve('./workflows'), + dataConverter: { payloadCodecs: [new NexusCodec()] }, + }); + await worker.run(); + } finally { + await connection.close(); + } +} + +run().catch((err) => { + console.error(err); + process.exit(1); +}); diff --git a/nexus-serialization-context/src/caller/workflows.ts b/nexus-serialization-context/src/caller/workflows.ts new file mode 100644 index 000000000..36ef126b6 --- /dev/null +++ b/nexus-serialization-context/src/caller/workflows.ts @@ -0,0 +1,31 @@ +import { createNexusServiceClient } from '@temporalio/workflow'; +import { syncEchoService, asyncEchoService } from '../api'; +import { ENDPOINTS, EndpointResults } from '../shared'; + +export async function callerWorkflow(message: string): Promise { + // Schedule all eight operations before awaiting any result. + const operations = ENDPOINTS.map((endpoint) => { + const sync = createNexusServiceClient({ endpoint, service: syncEchoService }); + const async = createNexusServiceClient({ endpoint, service: asyncEchoService }); + return { + endpoint, + sync: sync.startOperation('echo', message, { scheduleToCloseTimeout: '30s' }), + async: async.startOperation('echoAsync', message, { scheduleToCloseTimeout: '30s' }), + }; + }); + const started = await Promise.all( + operations.map(async (operation) => ({ + endpoint: operation.endpoint, + sync: await operation.sync, + async: await operation.async, + })), + ); + return Object.fromEntries( + await Promise.all( + started.map(async ({ endpoint, sync, async }) => [ + endpoint, + { sync: await sync.result(), async: await async.result() }, + ]), + ), + ); +} diff --git a/nexus-serialization-context/src/codec.ts b/nexus-serialization-context/src/codec.ts new file mode 100644 index 000000000..902e84007 --- /dev/null +++ b/nexus-serialization-context/src/codec.ts @@ -0,0 +1,103 @@ +import { createCipheriv, createDecipheriv, createSecretKey, KeyObject, randomBytes } from 'crypto'; +import { deflateSync, inflateSync } from 'zlib'; +import { Payload, PayloadCodec, SerializationContext } from '@temporalio/common'; +import { temporal } from '@temporalio/proto'; + +const PayloadMessage = temporal.api.common.v1.Payload; + +interface EndpointCodec { + readonly keyId: string; + readonly key: KeyObject; + readonly compress: boolean; +} + +// Hard-coded 128-bit keys are demonstration values, separate from their public key IDs. +const endpointCodecs: ReadonlyMap = new Map([ + ['nexus-serialization-compressed-encrypted-1', endpointCodec('compressed-encrypted-1', 'handler-a-key-01', true)], + ['nexus-serialization-compressed-encrypted-2', endpointCodec('compressed-encrypted-2', 'handler-a-key-02', true)], + ['nexus-serialization-encrypted-1', endpointCodec('encrypted-1', 'handler-b-key-01', false)], + ['nexus-serialization-encrypted-2', endpointCodec('encrypted-2', 'handler-b-key-02', false)], +]); + +function endpointCodec(keyId: string, rawKey: string, compress: boolean): EndpointCodec { + return Object.freeze({ keyId, key: createSecretKey(Buffer.from(rawKey)), compress }); +} + +/** Selects an endpoint's encryption, with a default for ordinary workflow payloads. */ +export class NexusCodec implements PayloadCodec { + private readonly workflowCodec: EndpointCodec; + private readonly endpoints: ReadonlyMap; + + constructor(role: 'caller' | 'compressed' | 'encrypted' = 'caller') { + this.endpoints = new Map( + [...endpointCodecs].filter(([, codec]) => role === 'caller' || codec.compress === (role === 'compressed')), + ); + switch (role) { + case 'caller': + this.workflowCodec = endpointCodec('caller-workflow', 'sample-key-C-123', false); + break; + case 'compressed': + this.workflowCodec = endpointCodec('compressed-encrypted-1', 'handler-a-key-01', false); + break; + case 'encrypted': + this.workflowCodec = endpointCodec('encrypted-1', 'handler-b-key-01', false); + break; + } + } + + private select(context?: SerializationContext): EndpointCodec { + if (context?.type !== 'nexus') return this.workflowCodec; + const selected = this.endpoints.get(context.endpoint); + if (!selected) throw new Error(`Unknown Nexus endpoint: ${context.endpoint}`); + return selected; + } + + async encode(payloads: Payload[], context?: SerializationContext): Promise { + // Context stays local to this call so concurrent operations never mutate shared codec configuration. + const { keyId, key, compress } = this.select(context); + return payloads.map((payload) => { + if (compress) { + payload = { + metadata: { encoding: Buffer.from('binary/nexus-zlib') }, + data: deflateSync(PayloadMessage.encode(payload).finish()), + }; + } + const nonce = randomBytes(12); + const cipher = createCipheriv('aes-128-gcm', key, nonce); + return { + metadata: { + encoding: Buffer.from('binary/nexus-aes-gcm'), + 'encryption-key-id': Buffer.from(keyId), + ...(context?.type === 'nexus' ? { 'nexus-endpoint-name': Buffer.from(context.endpoint) } : {}), + }, + data: Buffer.concat([ + nonce, + cipher.update(PayloadMessage.encode(payload).finish()), + cipher.final(), + cipher.getAuthTag(), + ]), + }; + }); + } + + async decode(payloads: Payload[], context?: SerializationContext): Promise { + const { keyId, key, compress } = this.select(context); + return payloads.map((payload) => { + if (Buffer.from(payload.metadata?.encoding ?? []).toString() !== 'binary/nexus-aes-gcm') + throw new Error('Expected an AES-GCM payload'); + if (Buffer.from(payload.metadata?.['encryption-key-id'] ?? []).toString() !== keyId) + throw new Error('Unexpected encryption key ID'); + const data = Buffer.from(payload.data ?? []); + if (data.length < 28) throw new Error('AES-GCM payload is too short'); + const cipher = createDecipheriv('aes-128-gcm', key, data.subarray(0, 12)); + cipher.setAuthTag(data.subarray(-16)); + let inner = PayloadMessage.decode(Buffer.concat([cipher.update(data.subarray(12, -16)), cipher.final()])); + if (compress) { + if (Buffer.from(inner.metadata?.encoding ?? []).toString() !== 'binary/nexus-zlib') + throw new Error('Expected a Nexus zlib payload'); + inner = PayloadMessage.decode(inflateSync(inner.data)); + } + return inner; + }); + } +} diff --git a/nexus-serialization-context/src/handler/handler.ts b/nexus-serialization-context/src/handler/handler.ts new file mode 100644 index 000000000..a436e0601 --- /dev/null +++ b/nexus-serialization-context/src/handler/handler.ts @@ -0,0 +1,16 @@ +import * as nexus from 'nexus-rpc'; +import { WorkflowRunOperationHandler, startWorkflow } from '@temporalio/nexus'; +import { syncEchoService, asyncEchoService } from '../api'; +import { EchoWorkflow } from './workflows'; + +export const syncHandler = nexus.serviceHandler(syncEchoService, { echo: async (_ctx, message) => message }); + +export const asyncHandler = nexus.serviceHandler(asyncEchoService, { + echoAsync: new WorkflowRunOperationHandler(async (ctx, message: string) => + startWorkflow(ctx, EchoWorkflow, { + // Reuse the request ID for retries; independent operations get separate executions. + workflowId: `nexus-echo-${ctx.requestId}`, + args: [message], + }), + ), +}); diff --git a/nexus-serialization-context/src/handler/worker.ts b/nexus-serialization-context/src/handler/worker.ts new file mode 100644 index 000000000..d75a1f090 --- /dev/null +++ b/nexus-serialization-context/src/handler/worker.ts @@ -0,0 +1,29 @@ +import { NativeConnection, Worker } from '@temporalio/worker'; +import { NexusCodec } from '../codec'; +import { COMPRESSED_HANDLER, ENCRYPTED_HANDLER } from '../shared'; +import { syncHandler, asyncHandler } from './handler'; + +async function run() { + const role = process.argv[2]; + if (role !== 'compressed' && role !== 'encrypted') throw new Error('Choose compressed or encrypted'); + const namespace = role === 'compressed' ? COMPRESSED_HANDLER : ENCRYPTED_HANDLER; + const connection = await NativeConnection.connect({ address: process.env.TEMPORAL_ADDRESS ?? 'localhost:7233' }); + try { + const worker = await Worker.create({ + connection, + namespace, + taskQueue: namespace, + workflowsPath: require.resolve('./workflows'), + nexusServices: [syncHandler, asyncHandler], + dataConverter: { payloadCodecs: [new NexusCodec(role)] }, + }); + await worker.run(); + } finally { + await connection.close(); + } +} + +run().catch((err) => { + console.error(err); + process.exit(1); +}); diff --git a/nexus-serialization-context/src/handler/workflows.ts b/nexus-serialization-context/src/handler/workflows.ts new file mode 100644 index 000000000..63ee15759 --- /dev/null +++ b/nexus-serialization-context/src/handler/workflows.ts @@ -0,0 +1,3 @@ +export async function EchoWorkflow(message: string): Promise { + return message; +} diff --git a/nexus-serialization-context/src/mocha/codec.test.ts b/nexus-serialization-context/src/mocha/codec.test.ts new file mode 100644 index 000000000..3ff027213 --- /dev/null +++ b/nexus-serialization-context/src/mocha/codec.test.ts @@ -0,0 +1,171 @@ +import assert from 'assert'; +import { createDecipheriv } from 'crypto'; +import { inflateSync } from 'zlib'; +import { temporal } from '@temporalio/proto'; +import { describe, it } from 'mocha'; +import { defaultPayloadConverter, NexusSerializationContext } from '@temporalio/common'; +import { NexusCodec } from '../codec'; + +describe('Nexus codec', () => { + it('round trips caller requests and handler results through every endpoint', async () => { + for (const keyId of ['compressed-encrypted-1', 'compressed-encrypted-2', 'encrypted-1', 'encrypted-2']) { + const context: NexusSerializationContext = { + type: 'nexus', + endpoint: `nexus-serialization-${keyId}`, + service: 'SyncEchoService', + operation: 'echo', + }; + const caller = new NexusCodec(); + const handler = new NexusCodec(keyId.startsWith('compressed') ? 'compressed' : 'encrypted'); + const [request] = await caller.encode([defaultPayloadConverter.toPayload('hello')], context); + assert.deepStrictEqual(request.metadata, { + encoding: Buffer.from('binary/nexus-aes-gcm'), + 'encryption-key-id': Buffer.from(keyId), + 'nexus-endpoint-name': Buffer.from(context.endpoint), + }); + const [decoded] = await handler.decode([request], context); + assert.equal(defaultPayloadConverter.fromPayload(decoded), 'hello'); + const [result] = await handler.encode([defaultPayloadConverter.toPayload('reply')], context); + assert.deepStrictEqual(result.metadata, request.metadata); + const [reply] = await caller.decode([result], context); + assert.equal(defaultPayloadConverter.fromPayload(reply), 'reply'); + } + }); + it('compresses before encrypting with either key', async () => { + const codec = new NexusCodec(); + const payload = defaultPayloadConverter.toPayload('repeat me '.repeat(100)); + for (const number of [1, 2]) { + const context = (id: string): NexusSerializationContext => ({ + type: 'nexus', + endpoint: `nexus-serialization-${id}-${number}`, + service: 'SyncEchoService', + operation: 'echo', + }); + const [compressed] = await codec.encode([payload], context('compressed-encrypted')); + const [encrypted] = await codec.encode([payload], context('encrypted')); + assert.ok(compressed.data!.length < encrypted.data!.length); + const [decoded] = await codec.decode([compressed], context('compressed-encrypted')); + assert.equal(defaultPayloadConverter.fromPayload(decoded), 'repeat me '.repeat(100)); + } + }); + + it('uses the expected raw keys and inner protobuf format for Nexus and ordinary workflows', async () => { + for (const [role, endpoint, keyId, rawKey, compressed] of [ + ['caller', 'compressed-encrypted-1', 'compressed-encrypted-1', 'handler-a-key-01', true], + ['caller', 'compressed-encrypted-2', 'compressed-encrypted-2', 'handler-a-key-02', true], + ['caller', 'encrypted-1', 'encrypted-1', 'handler-b-key-01', false], + ['caller', 'encrypted-2', 'encrypted-2', 'handler-b-key-02', false], + ['caller', '', 'caller-workflow', 'sample-key-C-123', false], + ['compressed', '', 'compressed-encrypted-1', 'handler-a-key-01', false], + ['encrypted', '', 'encrypted-1', 'handler-b-key-01', false], + ] as const) { + const codec = new NexusCodec(role); + const context = endpoint + ? { + type: 'nexus' as const, + endpoint: `nexus-serialization-${endpoint}`, + service: 'AsyncEchoService', + operation: 'echoAsync', + } + : { type: 'workflow' as const, namespace: 'handler', workflowId: 'workflow-id' }; + for (const value of ['Hello from Nexus', { sync: 'Hello from Nexus', async: 'reply' }]) { + const [payload] = await codec.encode([defaultPayloadConverter.toPayload(value)], context); + assert.equal(Buffer.from(payload.metadata!['encryption-key-id']).toString(), keyId); + assert.deepStrictEqual( + payload.metadata!['nexus-endpoint-name'], + endpoint ? Buffer.from(`nexus-serialization-${endpoint}`) : undefined, + ); + const data = Buffer.from(payload.data!); + assert.ok(!data.includes(Buffer.from('Hello from Nexus'))); + const decipher = createDecipheriv('aes-128-gcm', Buffer.from(rawKey), data.subarray(0, 12)); + decipher.setAuthTag(data.subarray(-16)); + let inner = temporal.api.common.v1.Payload.decode( + Buffer.concat([decipher.update(data.subarray(12, -16)), decipher.final()]), + ); + if (compressed) { + assert.deepStrictEqual(inner.metadata, { encoding: Buffer.from('binary/nexus-zlib') }); + inner = temporal.api.common.v1.Payload.decode(inflateSync(inner.data)); + } + assert.deepStrictEqual(inner.metadata, { encoding: Buffer.from('json/plain') }); + assert.deepStrictEqual(defaultPayloadConverter.fromPayload(inner), value); + const [decoded] = await codec.decode([payload], context); + assert.deepStrictEqual(defaultPayloadConverter.fromPayload(decoded), value); + } + } + }); + + it('rejects unknown endpoints on both encode and decode', async () => { + const codec = new NexusCodec(); + const context: NexusSerializationContext = { + type: 'nexus', + endpoint: 'unknown', + service: 'SyncEchoService', + operation: 'echo', + }; + await assert.rejects( + codec.encode([defaultPayloadConverter.toPayload('hello')], context), + /Unknown Nexus endpoint: unknown/, + ); + await assert.rejects(codec.decode([], context), /Unknown Nexus endpoint: unknown/); + }); + + it('keeps overlapping endpoint calls separate and leaves ordinary workflow defaults unchanged', async () => { + const codec = new NexusCodec(); + const contexts: NexusSerializationContext[] = [1, 2].map((number) => ({ + type: 'nexus', + endpoint: `nexus-serialization-encrypted-${number}`, + service: 'SyncEchoService', + operation: 'echo', + })); + const payload = defaultPayloadConverter.toPayload('hello'); + const pending = contexts.map((context) => codec.encode([payload], context)); + const [ordinary] = await codec.encode([payload]); + const results = await Promise.all(pending); + for (const [index, [encoded]] of results.entries()) { + assert.equal(Buffer.from(encoded.metadata!['encryption-key-id']).toString(), `encrypted-${index + 1}`); + assert.equal(Buffer.from(encoded.metadata!['nexus-endpoint-name']).toString(), contexts[index].endpoint); + const [decoded] = await codec.decode([encoded], contexts[index]); + assert.equal(defaultPayloadConverter.fromPayload(decoded), 'hello'); + } + assert.equal(Buffer.from(ordinary.metadata!['encryption-key-id']).toString(), 'caller-workflow'); + assert.equal(ordinary.metadata!['nexus-endpoint-name'], undefined); + const [after] = await codec.encode([payload], { type: 'workflow', namespace: 'caller', workflowId: 'caller-id' }); + assert.deepStrictEqual(after.metadata, ordinary.metadata); + }); + + it('uses a fresh nonce and ciphertext for repeated values', async () => { + const codec = new NexusCodec(); + const context: NexusSerializationContext = { + type: 'nexus', + endpoint: 'nexus-serialization-encrypted-1', + service: 'SyncEchoService', + operation: 'echo', + }; + const input = defaultPayloadConverter.toPayload('hello'); + const [first] = await codec.encode([input], context); + const [second] = await codec.encode([input], context); + assert.notDeepStrictEqual(first.data!.subarray(0, 12), second.data!.subarray(0, 12)); + assert.notDeepStrictEqual(first.data, second.data); + for (const encrypted of [first, second]) { + const [decoded] = await codec.decode([encrypted], context); + assert.equal(defaultPayloadConverter.fromPayload(decoded), 'hello'); + } + }); + + it('rejects altered ciphertext, incomplete nonces, and truncated authentication tags', async () => { + const codec = new NexusCodec(); + const context: NexusSerializationContext = { + type: 'nexus', + endpoint: 'nexus-serialization-encrypted-1', + service: 'SyncEchoService', + operation: 'echo', + }; + const [payload] = await codec.encode([defaultPayloadConverter.toPayload('hello')], context); + const data = Buffer.from(payload.data!); + const altered = Buffer.from(data); + altered[12] ^= 1; + for (const damaged of [altered, data.subarray(0, 1), data.subarray(0, -1)]) { + await assert.rejects(codec.decode([{ ...payload, data: damaged }], context)); + } + }); +}); diff --git a/nexus-serialization-context/src/mocha/workflows.test.ts b/nexus-serialization-context/src/mocha/workflows.test.ts new file mode 100644 index 000000000..889f150d7 --- /dev/null +++ b/nexus-serialization-context/src/mocha/workflows.test.ts @@ -0,0 +1,191 @@ +import assert from 'assert'; +import path from 'path'; +import { createDecipheriv, randomUUID } from 'crypto'; +import { inflateSync } from 'zlib'; +import { Payload, defaultPayloadConverter } from '@temporalio/common'; +import { temporal } from '@temporalio/proto'; +import { after, before, describe, it } from 'mocha'; +import { Client } from '@temporalio/client'; +import { TestWorkflowEnvironment } from '@temporalio/testing'; +import { Worker } from '@temporalio/worker'; +import { NexusCodec } from '../codec'; +import { CALLER, COMPRESSED_HANDLER, ENCRYPTED_HANDLER, ENDPOINTS } from '../shared'; +import { callerWorkflow } from '../caller/workflows'; +import { syncHandler, asyncHandler } from '../handler/handler'; + +describe('Nexus serialization context workflows', function () { + this.timeout(60000); + let env: TestWorkflowEnvironment; + before(async () => { + env = await TestWorkflowEnvironment.createLocal({ + server: { + executable: { type: 'existing-path', path: process.env.TEMPORAL_CLI_PATH ?? path.resolve('temporal') }, + namespace: CALLER, + extraArgs: ['--namespace', COMPRESSED_HANDLER, '--namespace', ENCRYPTED_HANDLER], + }, + }); + for (const endpoint of ENDPOINTS) { + const namespace = endpoint.includes('compressed') ? COMPRESSED_HANDLER : ENCRYPTED_HANDLER; + await env.connection.operatorService.createNexusEndpoint({ + spec: { name: endpoint, target: { worker: { namespace, taskQueue: namespace } } }, + }); + } + }); + after(async () => { + await env?.teardown(); + }); + + it('runs eight operations in five workflows with native async result context', async () => { + const workers = await Promise.all([ + Worker.create({ + connection: env.nativeConnection, + namespace: CALLER, + taskQueue: CALLER, + workflowsPath: require.resolve('../caller/workflows'), + dataConverter: { payloadCodecs: [new NexusCodec()] }, + }), + ...( + [ + ['compressed', COMPRESSED_HANDLER], + ['encrypted', ENCRYPTED_HANDLER], + ] as const + ).map(([role, namespace]) => + Worker.create({ + connection: env.nativeConnection, + namespace, + taskQueue: namespace, + workflowsPath: require.resolve('../handler/workflows'), + nexusServices: [syncHandler, asyncHandler], + dataConverter: { payloadCodecs: [new NexusCodec(role)] }, + }), + ), + ]); + const client = new Client({ + connection: env.connection, + namespace: CALLER, + dataConverter: { payloadCodecs: [new NexusCodec()] }, + }); + await workers[0].runUntil(() => + workers[1].runUntil(() => + workers[2].runUntil(async () => { + const handle = await client.workflow.start(callerWorkflow, { + workflowId: `nexus-serialization-${randomUUID()}`, + taskQueue: CALLER, + args: ['Hello from Nexus'], + workflowExecutionTimeout: '30s', + }); + assert.deepStrictEqual( + await handle.result(), + Object.fromEntries( + ENDPOINTS.map((endpoint) => [endpoint, { sync: 'Hello from Nexus', async: 'Hello from Nexus' }]), + ), + ); + const history = await handle.fetchHistory(); + const scheduled = history.events!.flatMap((event) => + event.nexusOperationScheduledEventAttributes ? [event.nexusOperationScheduledEventAttributes] : [], + ); + assert.equal(scheduled.length, 8); + const completedEvents = history.events!.filter((event) => event.nexusOperationCompletedEventAttributes); + assert.equal(completedEvents.length, 8); + const lastScheduled = Math.max( + ...history + .events!.filter((event) => event.nexusOperationScheduledEventAttributes) + .map((event) => Number(event.eventId)), + ); + assert.ok(completedEvents.every((event) => Number(event.eventId) > lastScheduled)); + + assert.equal(history.events!.filter((event) => event.nexusOperationStartedEventAttributes).length, 4); + for (const operation of scheduled) { + assert.ok(ENDPOINTS.includes(operation.endpoint as (typeof ENDPOINTS)[number])); + assert.equal(operation.service, operation.operation === 'echo' ? 'SyncEchoService' : 'AsyncEchoService'); + assertEndpointPayload(operation.input!, operation.endpoint!); + } + const callerStarted = history.events![0].workflowExecutionStartedEventAttributes!; + const callerCompleted = history.events!.find( + (event) => event.workflowExecutionCompletedEventAttributes, + )!.workflowExecutionCompletedEventAttributes!; + for (const payload of [callerStarted.input!.payloads![0], callerCompleted.result!.payloads![0]]) { + assert.equal(payload.metadata!['nexus-endpoint-name'], undefined); + assert.equal(Buffer.from(payload.metadata!['encryption-key-id']).toString(), 'caller-workflow'); + decrypt(payload, 'sample-key-C-123', false); + } + const endpoints = new Set(); + const workflowIds = new Set(); + for (const namespace of [COMPRESSED_HANDLER, ENCRYPTED_HANDLER]) { + const handlerClient = new Client({ connection: env.connection, namespace }); + const executions = []; + for await (const execution of handlerClient.workflow.list()) executions.push(execution); + assert.equal(executions.length, 2); + for (const execution of executions) { + assert.ok(execution.workflowId.startsWith('nexus-echo-')); + workflowIds.add(execution.workflowId); + const backing = await handlerClient.workflow.getHandle(execution.workflowId).fetchHistory(); + const started = backing.events![0].workflowExecutionStartedEventAttributes!; + const context = started.propagatedNexusSerializationContext!; + assert.ok(context); + assert.equal(context.service, 'AsyncEchoService'); + assert.equal(context.operation, 'echoAsync'); + assert.ok(ENDPOINTS.includes(context.endpoint as (typeof ENDPOINTS)[number])); + endpoints.add(context.endpoint!); + const request = scheduled.find( + (operation) => operation.endpoint === context.endpoint && operation.operation === 'echoAsync', + ); + assert.ok(request?.requestId); + assert.equal(execution.workflowId, `nexus-echo-${request.requestId}`); + + const input = started.input!.payloads![0]; + const compressed = namespace === COMPRESSED_HANDLER; + assert.equal( + Buffer.from(input.metadata!['encryption-key-id']).toString(), + compressed ? 'compressed-encrypted-1' : 'encrypted-1', + ); + assert.equal(input.metadata!['nexus-endpoint-name'], undefined); + assert.equal( + decrypt(input, compressed ? 'handler-a-key-01' : 'handler-b-key-01', false), + 'Hello from Nexus', + ); + const completed = backing.events!.find( + (event) => event.workflowExecutionCompletedEventAttributes, + )!.workflowExecutionCompletedEventAttributes!; + assertEndpointPayload(completed.result!.payloads![0], context.endpoint!); + } + } + assert.deepStrictEqual(endpoints, new Set(ENDPOINTS)); + assert.equal(workflowIds.size, 4); + }), + ), + ); + }); +}); + +function decrypt(payload: Payload, key: string, compressed: boolean): unknown { + const data = Buffer.from(payload.data!); + const decipher = createDecipheriv('aes-128-gcm', Buffer.from(key), data.subarray(0, 12)); + decipher.setAuthTag(data.subarray(-16)); + let inner = temporal.api.common.v1.Payload.decode( + Buffer.concat([decipher.update(data.subarray(12, -16)), decipher.final()]), + ); + if (compressed) { + assert.deepStrictEqual(inner.metadata, { encoding: Buffer.from('binary/nexus-zlib') }); + inner = temporal.api.common.v1.Payload.decode(inflateSync(inner.data)); + } + assert.deepStrictEqual(inner.metadata, { encoding: Buffer.from('json/plain') }); + return defaultPayloadConverter.fromPayload(inner); +} + +function assertEndpointPayload(payload: Payload, endpoint: string): void { + const keyId = endpoint.replace('nexus-serialization-', ''); + assert.deepStrictEqual(payload.metadata, { + encoding: Buffer.from('binary/nexus-aes-gcm'), + 'encryption-key-id': Buffer.from(keyId), + 'nexus-endpoint-name': Buffer.from(endpoint), + }); + assert.equal( + decrypt( + payload, + `handler-${endpoint.includes('compressed') ? 'a' : 'b'}-key-0${endpoint.slice(-1)}`, + endpoint.includes('compressed'), + ), + 'Hello from Nexus', + ); +} diff --git a/nexus-serialization-context/src/shared.ts b/nexus-serialization-context/src/shared.ts new file mode 100644 index 000000000..2df230d45 --- /dev/null +++ b/nexus-serialization-context/src/shared.ts @@ -0,0 +1,11 @@ +export const CALLER = 'nexus-serialization-caller'; +export const COMPRESSED_HANDLER = 'nexus-serialization-compressed-encrypted-handler'; +export const ENCRYPTED_HANDLER = 'nexus-serialization-encrypted-handler'; +export const ENDPOINTS = [ + 'nexus-serialization-compressed-encrypted-1', + 'nexus-serialization-encrypted-1', + 'nexus-serialization-compressed-encrypted-2', + 'nexus-serialization-encrypted-2', +] as const; + +export type EndpointResults = Record; diff --git a/nexus-serialization-context/src/starter.ts b/nexus-serialization-context/src/starter.ts new file mode 100644 index 000000000..f6eea4fa1 --- /dev/null +++ b/nexus-serialization-context/src/starter.ts @@ -0,0 +1,29 @@ +import { randomUUID } from 'crypto'; +import { Client, Connection } from '@temporalio/client'; +import { NexusCodec } from './codec'; +import { CALLER, ENDPOINTS } from './shared'; +import { callerWorkflow } from './caller/workflows'; + +async function run() { + const connection = await Connection.connect({ address: process.env.TEMPORAL_ADDRESS ?? 'localhost:7233' }); + try { + const client = new Client({ connection, namespace: CALLER, dataConverter: { payloadCodecs: [new NexusCodec()] } }); + const handle = await client.workflow.start(callerWorkflow, { + workflowId: `nexus-serialization-${randomUUID()}`, + taskQueue: CALLER, + args: ['Hello from Nexus'], + }); + console.log(`Started workflow: ${handle.workflowId}`); + const results = await handle.result(); + for (const endpoint of ENDPOINTS) { + console.log(`${endpoint}: sync="${results[endpoint].sync}" async="${results[endpoint].async}"`); + } + } finally { + await connection.close(); + } +} + +run().catch((err) => { + console.error(err); + process.exit(1); +}); diff --git a/nexus-serialization-context/tsconfig.json b/nexus-serialization-context/tsconfig.json new file mode 100644 index 000000000..d6c0398af --- /dev/null +++ b/nexus-serialization-context/tsconfig.json @@ -0,0 +1,14 @@ +{ + "extends": "@tsconfig/node22/tsconfig.json", + "version": "6.0.3", + "compilerOptions": { + "types": ["node"], + "lib": ["es2021"], + "declaration": true, + "declarationMap": true, + "sourceMap": true, + "rootDir": "./src", + "outDir": "./lib" + }, + "include": ["src/**/*.ts"] +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 4b491114b..3cc503c2c 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -4382,6 +4382,73 @@ importers: specifier: ^6.0.3 version: 6.0.3 + nexus-serialization-context: + dependencies: + "@temporalio/client": + specifier: ^1.26.0 + version: 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/common": + specifier: ^1.26.0 + version: 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/nexus": + specifier: ^1.26.0 + version: 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/proto": + specifier: ^1.26.0 + version: 1.26.0 + "@temporalio/worker": + specifier: ^1.26.0 + version: 1.26.0(@swc/helpers@0.5.15)(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/workflow": + specifier: ^1.26.0 + version: 1.26.0(long@5.3.2)(protobufjs@8.8.1) + nexus-rpc: + specifier: ^0.0.3 + version: 0.0.3 + devDependencies: + "@temporalio/testing": + specifier: ^1.26.0 + version: 1.26.0(@swc/helpers@0.5.15)(long@5.3.2)(protobufjs@8.8.1) + "@tsconfig/node22": + specifier: ^22.0.0 + version: 22.0.5 + "@types/mocha": + specifier: 10.x + version: 10.0.10 + "@types/node": + specifier: ^22.9.1 + version: 22.12.0 + "@typescript-eslint/eslint-plugin": + specifier: ^8.72.1 + version: 8.72.1(@typescript-eslint/parser@8.72.1(eslint@8.57.1)(typescript@6.0.3))(eslint@8.57.1)(typescript@6.0.3) + "@typescript-eslint/parser": + specifier: ^8.72.1 + version: 8.72.1(eslint@8.57.1)(typescript@6.0.3) + eslint: + specifier: ^8.57.1 + version: 8.57.1 + eslint-config-prettier: + specifier: ^9.1.0 + version: 9.1.0(eslint@8.57.1) + mocha: + specifier: ^12.0.3 + version: 12.0.3(ts-node@10.9.2(@swc/core@1.10.11(@swc/helpers@0.5.15))(@types/node@22.12.0)(typescript@6.0.3)) + nodemon: + specifier: ^3.1.7 + version: 3.1.9 + prettier: + specifier: ^3.4.2 + version: 3.4.2 + source-map-support: + specifier: ^0.5.21 + version: 0.5.21 + ts-node: + specifier: ^10.9.2 + version: 10.9.2(@swc/core@1.10.11(@swc/helpers@0.5.15))(@types/node@22.12.0)(typescript@6.0.3) + typescript: + specifier: ^6.0.3 + version: 6.0.3 + packages: '@a2a-js/sdk@0.3.14': @@ -17769,6 +17836,76 @@ packages: engines: {node: '>= 12.17.0'} hasBin: true + "@temporalio/activity@1.26.0": + resolution: + integrity: sha512-j0/yL0PDasvbOuIH571c1rr1n+xsm0BnGX0dl/G+lpWRurxyojCCJmZG9FF472x8xUON6WWequ2qOGquw0gb8A== + engines: + node: ">= 20.3.0" + peerDependencies: + long: ^5.3.2 + protobufjs: ^8.7.1 + "@temporalio/client@1.26.0": + resolution: + integrity: sha512-01hNfP6m6bjlut/huL6oCJ8czAMXm3jWKriLnEoLmnh5RzU6AEuqzbw77dmNDF3lQiZaFeY++lCKjSig4IVd9A== + engines: + node: ">= 20.3.0" + peerDependencies: + long: ^5.3.2 + protobufjs: ^8.7.1 + "@temporalio/common@1.26.0": + resolution: + integrity: sha512-mHpfPAm6IThHUreLmH9iE7G0ekURbj6jDqJZuG8kfg2unMVx33fQ1cx05TkRuzG8U6IPjIMheyVDnVrBid/TBg== + engines: + node: ">= 20.3.0" + peerDependencies: + long: ^5.3.2 + protobufjs: ^8.7.1 + "@temporalio/core-bridge@1.26.0": + resolution: + integrity: sha512-O2vtTOtFkHyl4YQwmUZni63HGlTUxOVoiZNRTZezaygMXG3LJw0dMap4+qCMponkBOiV8Z6qkrGNnShslqYC5g== + engines: + node: ">= 20.3.0" + peerDependencies: + long: ^5.3.2 + protobufjs: ^8.7.1 + "@temporalio/nexus@1.26.0": + resolution: + integrity: sha512-Tj44f+H+hNQl3lgrLAduv17Nv3bcPXj4i1hN6wv3C+ZPjFbklD5sroN6gMHK6bzlEqGSR9s5UInjbfE4if8J9w== + engines: + node: ">= 20.3.0" + peerDependencies: + long: ^5.3.2 + protobufjs: ^8.7.1 + "@temporalio/proto@1.26.0": + resolution: + integrity: sha512-hrYoXs/b3W7u+PvuK6qB2Cvb/TZv1AxKJn9Rj4YCeQsemWknZ3a4+2FICRuGxwB6bR0qsoVFf5uKQOPtouyDCw== + engines: + node: ">= 20.3.0" + "@temporalio/testing@1.26.0": + resolution: + integrity: sha512-eClmpgDEl2xBj7wb2SdLsenAxlA8K42qhINDOnjctBA3NJbq2e85FkMRAe3f+vlzoao9HzT0A4hwcGapMYzeoA== + engines: + node: ">= 20.3.0" + peerDependencies: + long: ^5.3.2 + protobufjs: ^8.7.1 + "@temporalio/worker@1.26.0": + resolution: + integrity: sha512-X6xdDzBtPNBfP7wdl2PWaWov4wmMtzBLb6PAQYQmOmupPVBZSTajLUi9wP+Fz0s1sqFvUQamY02QaQ3TJysrRA== + engines: + node: ">= 20.3.0" + peerDependencies: + long: ^5.3.2 + protobufjs: ^8.7.1 + "@temporalio/workflow@1.26.0": + resolution: + integrity: sha512-wa5SYoxn4qNVOtNaP6D7QPzyifg8KX6rzTkmE9oIqAqF5uxPgCgv1BbIIRq8Iu7Z0AH/mkkUCGwhwirdcmQwhA== + engines: + node: ">= 20.3.0" + peerDependencies: + long: ^5.3.2 + protobufjs: ^8.7.1 + snapshots: '@a2a-js/sdk@0.3.14(@grpc/grpc-js@1.14.4)(express@5.2.1)': @@ -35365,3 +35502,113 @@ snapshots: zwitch@2.0.4: {} zx@8.8.5: {} + + "@temporalio/activity@1.26.0(long@5.3.2)(protobufjs@8.8.1)": + dependencies: + "@temporalio/client": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/common": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + long: 5.3.2 + protobufjs: 8.8.1 + "@temporalio/client@1.26.0(long@5.3.2)(protobufjs@8.8.1)": + dependencies: + "@grpc/grpc-js": 1.14.4 + "@temporalio/common": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/proto": 1.26.0 + long: 5.3.2 + nexus-rpc: 0.0.3 + protobufjs: 8.8.1 + uuid: 11.1.0 + "@temporalio/common@1.26.0(long@5.3.2)(protobufjs@8.8.1)": + dependencies: + "@temporalio/proto": 1.26.0 + long: 5.3.2 + ms: 3.0.0-canary.202508261828 + nexus-rpc: 0.0.3 + protobufjs: 8.8.1 + "@temporalio/core-bridge@1.26.0(long@5.3.2)(protobufjs@8.8.1)": + dependencies: + "@grpc/grpc-js": 1.14.4 + "@temporalio/common": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + long: 5.3.2 + protobufjs: 8.8.1 + "@temporalio/nexus@1.26.0(long@5.3.2)(protobufjs@8.8.1)": + dependencies: + "@temporalio/client": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/common": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/proto": 1.26.0 + long: 5.3.2 + nexus-rpc: 0.0.3 + protobufjs: 8.8.1 + "@temporalio/proto@1.26.0": + dependencies: + long: 5.3.2 + protobufjs: 8.8.1 + "@temporalio/testing@1.26.0(@swc/helpers@0.5.15)(long@5.3.2)(protobufjs@8.8.1)": + dependencies: + "@temporalio/activity": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/client": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/common": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/core-bridge": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/proto": 1.26.0 + "@temporalio/worker": 1.26.0(@swc/helpers@0.5.15)(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/workflow": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + long: 5.3.2 + protobufjs: 8.8.1 + transitivePeerDependencies: + - "@minify-html/node" + - "@swc/css" + - "@swc/helpers" + - "@swc/html" + - clean-css + - cssnano + - csso + - esbuild + - html-minifier-terser + - lightningcss + - postcss + - uglify-js + - webpack-cli + "@temporalio/worker@1.26.0(@swc/helpers@0.5.15)(long@5.3.2)(protobufjs@8.8.1)": + dependencies: + "@grpc/grpc-js": 1.14.4 + "@swc/core": 1.10.11(@swc/helpers@0.5.15) + "@temporalio/activity": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/client": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/common": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/core-bridge": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/nexus": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/proto": 1.26.0 + "@temporalio/workflow": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + heap-js: 2.6.0 + long: 5.3.2 + memfs: 4.17.0 + nexus-rpc: 0.0.3 + protobufjs: 8.8.1 + rxjs: 7.8.2 + source-map: 0.7.6 + source-map-loader: 5.0.0(webpack@5.108.4(@swc/core@1.10.11(@swc/helpers@0.5.15))) + supports-color: 8.1.1 + swc-loader: 0.2.6(@swc/core@1.10.11(@swc/helpers@0.5.15))(webpack@5.108.4(@swc/core@1.10.11(@swc/helpers@0.5.15))) + unionfs: 4.6.0 + webpack: 5.108.4(@swc/core@1.10.11(@swc/helpers@0.5.15)) + transitivePeerDependencies: + - "@minify-html/node" + - "@swc/css" + - "@swc/helpers" + - "@swc/html" + - clean-css + - cssnano + - csso + - esbuild + - html-minifier-terser + - lightningcss + - postcss + - uglify-js + - webpack-cli + "@temporalio/workflow@1.26.0(long@5.3.2)(protobufjs@8.8.1)": + dependencies: + "@temporalio/common": 1.26.0(long@5.3.2)(protobufjs@8.8.1) + "@temporalio/proto": 1.26.0 + long: 5.3.2 + nexus-rpc: 0.0.3 + protobufjs: 8.8.1 From e25c91a0459e89a3ebda0c910d9c6729b22c12c5 Mon Sep 17 00:00:00 2001 From: Joie Wu Date: Tue, 17 Nov 2026 13:14:12 -0800 Subject: [PATCH 2/9] Verify each Nexus endpoint receives both echo operations --- nexus-serialization-context/src/mocha/workflows.test.ts | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/nexus-serialization-context/src/mocha/workflows.test.ts b/nexus-serialization-context/src/mocha/workflows.test.ts index 889f150d7..e80316339 100644 --- a/nexus-serialization-context/src/mocha/workflows.test.ts +++ b/nexus-serialization-context/src/mocha/workflows.test.ts @@ -85,6 +85,14 @@ describe('Nexus serialization context workflows', function () { event.nexusOperationScheduledEventAttributes ? [event.nexusOperationScheduledEventAttributes] : [], ); assert.equal(scheduled.length, 8); + assert.deepStrictEqual( + scheduled.map((operation) => `${operation.endpoint}/${operation.service}/${operation.operation}`).sort(), + ENDPOINTS.flatMap((endpoint) => [ + `${endpoint}/SyncEchoService/echo`, + `${endpoint}/AsyncEchoService/echoAsync`, + ]).sort(), + ); + const completedEvents = history.events!.filter((event) => event.nexusOperationCompletedEventAttributes); assert.equal(completedEvents.length, 8); const lastScheduled = Math.max( From baa4cf96e76a69965c007f06401cde2828006e02 Mon Sep 17 00:00:00 2001 From: Joie Wu Date: Tue, 17 Nov 2026 13:18:01 -0800 Subject: [PATCH 3/9] Run Nexus serialization context tests in CI with pinned CLI --- .github/workflows/ci.yml | 1 + nexus-serialization-context/README.md | 7 ++++--- nexus-serialization-context/src/mocha/workflows.test.ts | 5 +++-- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1bffb457a..d23a49472 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -63,6 +63,7 @@ jobs: langsmith mutex nestjs-exchange-rates + nexus-serialization-context nexus-standalone-activity nexus-standalone-operations sleep-for-days diff --git a/nexus-serialization-context/README.md b/nexus-serialization-context/README.md index 686ebbdb8..57857100b 100644 --- a/nexus-serialization-context/README.md +++ b/nexus-serialization-context/README.md @@ -181,6 +181,7 @@ pnpm lint pnpm build ``` -The workflow test starts an isolated server on private ports using the same CLI build -and checks the stored Nexus context and the backing workflows' input and result metadata. -Set `TEMPORAL_CLI_PATH` to use this CLI build from another location. +The workflow test downloads and caches CLI `v1.9.3-nexus-serialization-context`, starts +an isolated server on private ports, and checks the stored Nexus context and the backing +workflows' input and result metadata. Set `TEMPORAL_CLI_PATH` to use an existing CLI +executable instead. diff --git a/nexus-serialization-context/src/mocha/workflows.test.ts b/nexus-serialization-context/src/mocha/workflows.test.ts index e80316339..128bd1376 100644 --- a/nexus-serialization-context/src/mocha/workflows.test.ts +++ b/nexus-serialization-context/src/mocha/workflows.test.ts @@ -1,5 +1,4 @@ import assert from 'assert'; -import path from 'path'; import { createDecipheriv, randomUUID } from 'crypto'; import { inflateSync } from 'zlib'; import { Payload, defaultPayloadConverter } from '@temporalio/common'; @@ -19,7 +18,9 @@ describe('Nexus serialization context workflows', function () { before(async () => { env = await TestWorkflowEnvironment.createLocal({ server: { - executable: { type: 'existing-path', path: process.env.TEMPORAL_CLI_PATH ?? path.resolve('temporal') }, + executable: process.env.TEMPORAL_CLI_PATH + ? { type: 'existing-path', path: process.env.TEMPORAL_CLI_PATH } + : { type: 'cached-download', version: 'v1.9.3-nexus-serialization-context' }, namespace: CALLER, extraArgs: ['--namespace', COMPRESSED_HANDLER, '--namespace', ENCRYPTED_HANDLER], }, From 8348175c22055880c7e9f5bac4b4ab11732c70e8 Mon Sep 17 00:00:00 2001 From: Joie Wu Date: Tue, 17 Nov 2026 15:47:24 -0800 Subject: [PATCH 4/9] Align Nexus serialization context README with Go --- nexus-serialization-context/README.md | 53 ++++++++++++++------------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/nexus-serialization-context/README.md b/nexus-serialization-context/README.md index 57857100b..c45d85478 100644 --- a/nexus-serialization-context/README.md +++ b/nexus-serialization-context/README.md @@ -20,10 +20,14 @@ The encryption codec uses Node.js's AES-GCM implementation and `zlib` module. Nexus supplies the endpoint context used to select them. The context also identifies the service and operation, so a codec can select keys using those fields as well. -Each worker configures `NexusCodec` for its role. The codec keeps an endpoint-to-codec -map and a default for ordinary workflow payloads. The caller uses a separate key for its own input and -final result, keeping those payloads independent of the keys shared with Nexus handlers. -Each handler reuses its key 1 for backing workflow inputs. +`NexusCodec` keeps an endpoint-to-codec map and a default for ordinary workflow +payloads. To use this pattern, add the codec to `dataConverter.payloadCodecs` in the +`Client` and `Worker` options for the caller and handlers. Both sides need matching +keys and encodings for each endpoint. + +The caller uses a separate key for its own input and final result, keeping those +payloads independent of the keys shared with Nexus handlers. Each handler reuses its +key 1 for backing workflow inputs. | Ordinary workflow payload | Default key ID | | -------------------------------------------- | ------------------------ | @@ -35,19 +39,15 @@ These workflow payloads use AES-GCM without compression or endpoint metadata. An async Nexus result uses the key and compression selected by its endpoint, even when that differs from the backing workflow's input encryption. -For synchronous operations, the SDK supplies Nexus context when decoding inputs and -encoding results. When an asynchronous handler starts `EchoWorkflow`, the SDK includes -the Nexus endpoint, service, and operation in the workflow-start request. The server -stores these fields in the `WorkflowExecutionStarted` history event. The worker SDK -restores the Nexus context from that event when encoding the workflow's result, so -`NexusCodec` can select the endpoint's codec and key from the worker's local configuration. -The workflow's input still uses ordinary workflow context; the default codec encrypts -it with that handler's key 1. - -The caller starts all eight operations before waiting for their results. The SDK passes -`SerializationContext` directly to the codec's `encode` and `decode` methods. `NexusCodec` -keeps the endpoint selection local to each call and shares read-only configuration, -so operations for different endpoints do not change each other's encoding. +The SDK supplies Nexus context when encoding and decoding operation requests and +results. For workflow-backed asynchronous operations, it preserves that context in +workflow history and restores it when encoding the result. A call through endpoint 2 +can therefore return a result encrypted with key 2, as the caller expects, even though +the backing workflow's input uses the handler's default key 1. + +The caller starts all eight operations before waiting for their results. Each operation +keeps its own endpoint context, even when operations for different keys are in flight. +The SDK passes context to each codec call, so endpoint selection stays local to that call. No custom interceptor or workflow-header propagation is required. A workflow execution produces one serialized result, shared by all Nexus operations @@ -74,8 +74,7 @@ implementation and secure key storage for production. ## Prerequisites Use Node.js 22 or newer, [pnpm](https://pnpm.io/installation), and Temporal TypeScript -SDK 1.26.0 or later. This SDK version supports native Nexus context propagation to -workflow-backed asynchronous results. +SDK 1.26.0 or later. Use a Temporal Server that supports Nexus serialization-context propagation for workflow-backed asynchronous operations. For local development, download @@ -156,6 +155,8 @@ Start the caller workflow in another terminal: pnpm workflow ``` +### Output + The starter prints the workflow ID, followed by a sync result and an async result for each endpoint. Replacing the generated ID, the output is: @@ -167,9 +168,10 @@ nexus-serialization-compressed-encrypted-2: sync="Hello from Nexus" async="Hello nexus-serialization-encrypted-2: sync="Hello from Nexus" async="Hello from Nexus" ``` -All eight results should be `Hello from Nexus`. The starter exits when they are available; -the workers and server keep running. The run creates five workflow executions: one caller -and four async backing workflows. The four sync operations return directly from their handlers. +All eight results should be `Hello from Nexus`. + +The run creates five workflow executions: one caller and four async backing workflows. +The four sync operations return directly from their handlers. ## Test @@ -181,7 +183,6 @@ pnpm lint pnpm build ``` -The workflow test downloads and caches CLI `v1.9.3-nexus-serialization-context`, starts -an isolated server on private ports, and checks the stored Nexus context and the backing -workflows' input and result metadata. Set `TEMPORAL_CLI_PATH` to use an existing CLI -executable instead. +The workflow test downloads the required CLI, starts its own server, and checks all eight +results, the stored Nexus context, and the backing workflows' input and result encryption +metadata. Set `TEMPORAL_CLI_PATH` to use an existing CLI executable instead. From 8bb7b36c4dcbbfe99eea7bd40c900eb4d22aee19 Mon Sep 17 00:00:00 2001 From: Joie Wu Date: Wed, 18 Nov 2026 11:32:28 -0800 Subject: [PATCH 5/9] Align Nexus serialization context wording with Go --- nexus-serialization-context/README.md | 29 +++++++++++++-------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/nexus-serialization-context/README.md b/nexus-serialization-context/README.md index c45d85478..2dd502715 100644 --- a/nexus-serialization-context/README.md +++ b/nexus-serialization-context/README.md @@ -14,20 +14,18 @@ The caller and each handler run in separate namespaces. | Encrypted | `nexus-serialization-encrypted-1` | `encrypted-1` | AES-GCM | | Encrypted | `nexus-serialization-encrypted-2` | `encrypted-2` | AES-GCM | -These four endpoint keys are distinct 128-bit AES keys. Compression runs before encryption; -decoding decrypts before decompressing. AES-GCM authenticates the ciphertext. -The encryption codec uses Node.js's AES-GCM implementation and `zlib` module. -Nexus supplies the endpoint context used to select them. The context also identifies the -service and operation, so a codec can select keys using those fields as well. +Each endpoint uses a different 128-bit AES key. The codec uses Node.js for +AES-GCM encryption and zlib compression. -`NexusCodec` keeps an endpoint-to-codec map and a default for ordinary workflow -payloads. To use this pattern, add the codec to `dataConverter.payloadCodecs` in the -`Client` and `Worker` options for the caller and handlers. Both sides need matching -keys and encodings for each endpoint. +`NexusCodec` uses the endpoint from the Nexus context to select encryption and compression +settings. It uses a default for ordinary workflow payloads. Add the codec to +`dataConverter.payloadCodecs` when creating the workers and the starter's client. -The caller uses a separate key for its own input and final result, keeping those -payloads independent of the keys shared with Nexus handlers. Each handler reuses its -key 1 for backing workflow inputs. +Because AES-GCM uses symmetric encryption, the caller and handler share a secret key +for each endpoint. This sample uses that key for both requests and results. + +The caller uses a separate key for its workflow input and final result. Each handler +reuses its key 1 for backing workflow inputs. | Ordinary workflow payload | Default key ID | | -------------------------------------------- | ------------------------ | @@ -65,11 +63,12 @@ encryption-key-id: compressed-encrypted-1 nexus-endpoint-name: nexus-serialization-compressed-encrypted-1 ``` -These labels identify the key and endpoint; they do not contain the key material. +The metadata identifies the key and endpoint. The key material stays in the codec +configuration. Ordinary workflow payloads have a key ID but no endpoint metadata or compression. -The AES-GCM codec and hard-coded keys are for this example. Use an established encryption -implementation and secure key storage for production. +The AES-GCM codec and hard-coded keys are for this example. For production, use an +established encryption implementation and secure key storage. ## Prerequisites From f3ef8028cebf3d8f9e73b3ef98d0ba4c6e850191 Mon Sep 17 00:00:00 2001 From: Joie Wu Date: Wed, 18 Nov 2026 12:40:04 -0800 Subject: [PATCH 6/9] Show where to find encrypted Nexus payloads --- nexus-serialization-context/README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/nexus-serialization-context/README.md b/nexus-serialization-context/README.md index 2dd502715..f7d6dbd4b 100644 --- a/nexus-serialization-context/README.md +++ b/nexus-serialization-context/README.md @@ -169,6 +169,12 @@ nexus-serialization-encrypted-2: sync="Hello from Nexus" async="Hello from Nexus All eight results should be `Hello from Nexus`. +To see what Temporal stored, open the printed workflow ID in the +[Temporal UI](http://localhost:8233) under the `nexus-serialization-caller` namespace. +In **History**, check **Input** on a **Nexus Operation Scheduled** event and **Result** +on its **Nexus Operation Completed** event. The payload data is encrypted and shown in +Base64. Look for `encryption-key-id` in the payload metadata to compare endpoints. + The run creates five workflow executions: one caller and four async backing workflows. The four sync operations return directly from their handlers. From 2ebf4697f2f8a6074bdfe9cafb8ca17d4e6eb316 Mon Sep 17 00:00:00 2001 From: Joie Wu Date: Wed, 18 Nov 2026 14:57:29 -0800 Subject: [PATCH 7/9] Revert "Show where to find encrypted Nexus payloads" This reverts commit f3ef8028cebf3d8f9e73b3ef98d0ba4c6e850191. --- nexus-serialization-context/README.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/nexus-serialization-context/README.md b/nexus-serialization-context/README.md index f7d6dbd4b..2dd502715 100644 --- a/nexus-serialization-context/README.md +++ b/nexus-serialization-context/README.md @@ -169,12 +169,6 @@ nexus-serialization-encrypted-2: sync="Hello from Nexus" async="Hello from Nexus All eight results should be `Hello from Nexus`. -To see what Temporal stored, open the printed workflow ID in the -[Temporal UI](http://localhost:8233) under the `nexus-serialization-caller` namespace. -In **History**, check **Input** on a **Nexus Operation Scheduled** event and **Result** -on its **Nexus Operation Completed** event. The payload data is encrypted and shown in -Base64. Look for `encryption-key-id` in the payload metadata to compare endpoints. - The run creates five workflow executions: one caller and four async backing workflows. The four sync operations return directly from their handlers. From d601105b92ed368ba8602da28d0215908e5016da Mon Sep 17 00:00:00 2001 From: Joie Wu Date: Thu, 19 Nov 2026 12:44:31 -0800 Subject: [PATCH 8/9] Accept plaintext in the Nexus serialization context sample Test plaintext and encrypted payloads in the same batch. Add caller and handler progress logging and document how to adapt the sample and its example key reuse. --- nexus-serialization-context/README.md | 76 ++++++++++--------- .../src/caller/workflows.ts | 7 +- nexus-serialization-context/src/codec.ts | 3 +- .../src/handler/handler.ts | 20 +++-- .../src/mocha/codec.test.ts | 3 +- 5 files changed, 63 insertions(+), 46 deletions(-) diff --git a/nexus-serialization-context/README.md b/nexus-serialization-context/README.md index 2dd502715..1bba8df62 100644 --- a/nexus-serialization-context/README.md +++ b/nexus-serialization-context/README.md @@ -14,45 +14,56 @@ The caller and each handler run in separate namespaces. | Encrypted | `nexus-serialization-encrypted-1` | `encrypted-1` | AES-GCM | | Encrypted | `nexus-serialization-encrypted-2` | `encrypted-2` | AES-GCM | -Each endpoint uses a different 128-bit AES key. The codec uses Node.js for -AES-GCM encryption and zlib compression. +Each endpoint uses a different 128-bit AES key. Compression runs before encryption, +and decoding decrypts before decompressing. AES-GCM authenticates the ciphertext. +The encryption codec uses Node.js's AES-GCM implementation and `zlib` module. +Nexus supplies the endpoint context used to select a codec. The context also identifies +the service and operation, which can be used to select keys. -`NexusCodec` uses the endpoint from the Nexus context to select encryption and compression -settings. It uses a default for ordinary workflow payloads. Add the codec to -`dataConverter.payloadCodecs` when creating the workers and the starter's client. +## Adapt this pattern + +`NexusCodec` maps endpoints to encryption settings and uses a default for ordinary +workflow payloads. Add it to `dataConverter.payloadCodecs` in the caller and handler +`Client` and `Worker` options. See [src/codec.ts](src/codec.ts) for the key maps and +[src/handler/worker.ts](src/handler/worker.ts) for worker setup. Because AES-GCM uses symmetric encryption, the caller and handler share a secret key for each endpoint. This sample uses that key for both requests and results. +Both sides also need the same payload format, including whether to compress. -The caller uses a separate key for its workflow input and final result. Each handler -reuses its key 1 for backing workflow inputs. +The caller uses a separate key for its workflow input and final result. +For this example, each handler reuses its endpoint-1 key for backing workflow inputs. +If your application already has a workflow codec, keep it as the default so it +can still read existing histories. -| Ordinary workflow payload | Default key ID | -| -------------------------------------------- | ------------------------ | -| Caller workflow input and final result | `caller-workflow` | -| Compressed/encrypted handler workflow inputs | `compressed-encrypted-1` | -| Encrypted handler workflow inputs | `encrypted-1` | +| Ordinary workflow payload | Default key ID | +| ------------------------------------------------------ | ------------------------ | +| Caller workflow input and final result | `caller-workflow` | +| Compressed/encrypted handler's backing workflow inputs | `compressed-encrypted-1` | +| Encrypted handler's backing workflow inputs | `encrypted-1` | These workflow payloads use AES-GCM without compression or endpoint metadata. -An async Nexus result uses the key and compression selected by its endpoint, -even when that differs from the backing workflow's input encryption. -The SDK supplies Nexus context when encoding and decoding operation requests and -results. For workflow-backed asynchronous operations, it preserves that context in -workflow history and restores it when encoding the result. A call through endpoint 2 -can therefore return a result encrypted with key 2, as the caller expects, even though -the backing workflow's input uses the handler's default key 1. +On decode, the AES-GCM codec passes other encodings through for ordinary decoding. +For AES-GCM payloads, it checks the key ID against the codec selected by context and +verifies the ciphertext before returning the decoded value. + +The SDK supplies Nexus context for operation requests and results. For workflow-backed +async operations, the server stores the context in workflow history and the SDK uses it +to select the result's key and compression. To see the two keys in one execution, call +`nexus-serialization-encrypted-2` and check the backing workflow's history. Its input +records `encrypted-1` and its result records `encrypted-2`. The caller starts all eight operations before waiting for their results. Each operation -keeps its own endpoint context, even when operations for different keys are in flight. +keeps its own endpoint context while calls using different keys run concurrently. The SDK passes context to each codec call, so endpoint selection stays local to that call. No custom interceptor or workflow-header propagation is required. -A workflow execution produces one serialized result, shared by all Nexus operations -attached to it. Operations that need differently encrypted results therefore need -separate workflow executions. This sample starts a backing workflow for each async -operation, using its Nexus request ID as the workflow ID suffix. Retrying the same -request uses the same workflow ID. +Each workflow execution has one serialized result, shared by all Nexus operations +attached to it. Operations that need results encrypted with different keys must use +separate workflow executions. This sample starts one backing workflow per async +operation, using the Nexus request ID as its workflow ID suffix. Retrying the same +request reuses that workflow ID. The outer encrypted payload includes `encoding`, `encryption-key-id`, and, for Nexus payloads, `nexus-endpoint-name` metadata. For example: @@ -65,7 +76,6 @@ nexus-endpoint-name: nexus-serialization-compressed-encrypted-1 The metadata identifies the key and endpoint. The key material stays in the codec configuration. -Ordinary workflow payloads have a key ID but no endpoint metadata or compression. The AES-GCM codec and hard-coded keys are for this example. For production, use an established encryption implementation and secure key storage. @@ -76,7 +86,7 @@ Use Node.js 22 or newer, [pnpm](https://pnpm.io/installation), and Temporal Type SDK 1.26.0 or later. Use a Temporal Server that supports Nexus serialization-context propagation for -workflow-backed asynchronous operations. For local development, download +workflow-backed asynchronous operations. For the local walkthrough, download the prerelease [Temporal CLI `v1.9.3-nexus-serialization-context`](https://github.com/temporalio/cli/releases/tag/v1.9.3-nexus-serialization-context). Extract it and place the `temporal` executable in this sample directory. The commands below use `./temporal` to run this build separately from your installed CLI. @@ -94,9 +104,8 @@ pnpm install The CLI should report `1.9.3-nexus-serialization-context`. Run the remaining commands from `nexus-serialization-context`, including commands in new terminals. -The caller and each handler use separate namespaces. Each worker polls a task queue -with the same name as its namespace. Both endpoints for a handler target that handler's -namespace and task queue. +Each worker polls a task queue with the same name as its namespace. Both endpoints +for a handler target that handler's namespace and task queue. | Worker | Namespace and task queue | | ---------------------------- | -------------------------------------------------- | @@ -104,7 +113,7 @@ namespace and task queue. | Compressed/encrypted handler | `nexus-serialization-compressed-encrypted-handler` | | Encrypted handler | `nexus-serialization-encrypted-handler` | -Start the dev server in its own terminal and leave it running: +Start the dev server in its own terminal: ```shell ./temporal server start-dev \ @@ -134,7 +143,7 @@ In another terminal, create two endpoints for each handler worker: --target-task-queue nexus-serialization-encrypted-handler ``` -Run each worker in its own terminal and leave all three running alongside the server: +Run each worker in its own terminal: ```shell pnpm start.compressed @@ -156,8 +165,7 @@ pnpm workflow ### Output -The starter prints the workflow ID, followed by a sync result and an async result for -each endpoint. Replacing the generated ID, the output is: +Expected output: ```text Started workflow: nexus-serialization- diff --git a/nexus-serialization-context/src/caller/workflows.ts b/nexus-serialization-context/src/caller/workflows.ts index 36ef126b6..f9c910975 100644 --- a/nexus-serialization-context/src/caller/workflows.ts +++ b/nexus-serialization-context/src/caller/workflows.ts @@ -1,8 +1,9 @@ -import { createNexusServiceClient } from '@temporalio/workflow'; +import { createNexusServiceClient, log } from '@temporalio/workflow'; import { syncEchoService, asyncEchoService } from '../api'; import { ENDPOINTS, EndpointResults } from '../shared'; export async function callerWorkflow(message: string): Promise { + log.info('Calling Nexus endpoints', { endpointCount: ENDPOINTS.length }); // Schedule all eight operations before awaiting any result. const operations = ENDPOINTS.map((endpoint) => { const sync = createNexusServiceClient({ endpoint, service: syncEchoService }); @@ -20,7 +21,7 @@ export async function callerWorkflow(message: string): Promise async: await operation.async, })), ); - return Object.fromEntries( + const results = Object.fromEntries( await Promise.all( started.map(async ({ endpoint, sync, async }) => [ endpoint, @@ -28,4 +29,6 @@ export async function callerWorkflow(message: string): Promise ]), ), ); + log.info('Received sync and async replies', { endpointCount: started.length }); + return results; } diff --git a/nexus-serialization-context/src/codec.ts b/nexus-serialization-context/src/codec.ts index 902e84007..842cd42fb 100644 --- a/nexus-serialization-context/src/codec.ts +++ b/nexus-serialization-context/src/codec.ts @@ -83,8 +83,7 @@ export class NexusCodec implements PayloadCodec { async decode(payloads: Payload[], context?: SerializationContext): Promise { const { keyId, key, compress } = this.select(context); return payloads.map((payload) => { - if (Buffer.from(payload.metadata?.encoding ?? []).toString() !== 'binary/nexus-aes-gcm') - throw new Error('Expected an AES-GCM payload'); + if (Buffer.from(payload.metadata?.encoding ?? []).toString() !== 'binary/nexus-aes-gcm') return payload; if (Buffer.from(payload.metadata?.['encryption-key-id'] ?? []).toString() !== keyId) throw new Error('Unexpected encryption key ID'); const data = Buffer.from(payload.data ?? []); diff --git a/nexus-serialization-context/src/handler/handler.ts b/nexus-serialization-context/src/handler/handler.ts index a436e0601..2953bc459 100644 --- a/nexus-serialization-context/src/handler/handler.ts +++ b/nexus-serialization-context/src/handler/handler.ts @@ -1,16 +1,22 @@ import * as nexus from 'nexus-rpc'; -import { WorkflowRunOperationHandler, startWorkflow } from '@temporalio/nexus'; +import { WorkflowRunOperationHandler, log, operationInfo, startWorkflow } from '@temporalio/nexus'; import { syncEchoService, asyncEchoService } from '../api'; import { EchoWorkflow } from './workflows'; -export const syncHandler = nexus.serviceHandler(syncEchoService, { echo: async (_ctx, message) => message }); +export const syncHandler = nexus.serviceHandler(syncEchoService, { + echo: async (_ctx, message) => { + log.info('Handling sync echo', { endpoint: operationInfo().endpoint }); + return message; + }, +}); export const asyncHandler = nexus.serviceHandler(asyncEchoService, { - echoAsync: new WorkflowRunOperationHandler(async (ctx, message: string) => - startWorkflow(ctx, EchoWorkflow, { - // Reuse the request ID for retries; independent operations get separate executions. + echoAsync: new WorkflowRunOperationHandler(async (ctx, message: string) => { + log.info('Starting async echo workflow', { endpoint: operationInfo().endpoint }); + return startWorkflow(ctx, EchoWorkflow, { + // Reuse the request ID for retries. Independent operations get separate executions. workflowId: `nexus-echo-${ctx.requestId}`, args: [message], - }), - ), + }); + }), }); diff --git a/nexus-serialization-context/src/mocha/codec.test.ts b/nexus-serialization-context/src/mocha/codec.test.ts index 3ff027213..b11790696 100644 --- a/nexus-serialization-context/src/mocha/codec.test.ts +++ b/nexus-serialization-context/src/mocha/codec.test.ts @@ -23,7 +23,8 @@ describe('Nexus codec', () => { 'encryption-key-id': Buffer.from(keyId), 'nexus-endpoint-name': Buffer.from(context.endpoint), }); - const [decoded] = await handler.decode([request], context); + const [plain, decoded] = await handler.decode([defaultPayloadConverter.toPayload('plain'), request], context); + assert.equal(defaultPayloadConverter.fromPayload(plain), 'plain'); assert.equal(defaultPayloadConverter.fromPayload(decoded), 'hello'); const [result] = await handler.encode([defaultPayloadConverter.toPayload('reply')], context); assert.deepStrictEqual(result.metadata, request.metadata); From 630aa23dac606ba18a678be641c9168613f47544 Mon Sep 17 00:00:00 2001 From: Joie Wu Date: Fri, 20 Nov 2026 13:34:55 -0800 Subject: [PATCH 9/9] Clarify Nexus codec endpoint selection and workflow fallback --- nexus-serialization-context/README.md | 6 ++++-- nexus-serialization-context/src/codec.ts | 15 ++++++++++++--- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/nexus-serialization-context/README.md b/nexus-serialization-context/README.md index 1bba8df62..611452e33 100644 --- a/nexus-serialization-context/README.md +++ b/nexus-serialization-context/README.md @@ -33,8 +33,10 @@ Both sides also need the same payload format, including whether to compress. The caller uses a separate key for its workflow input and final result. For this example, each handler reuses its endpoint-1 key for backing workflow inputs. -If your application already has a workflow codec, keep it as the default so it -can still read existing histories. + +When adapting this sample, use your existing codec for ordinary workflow payloads +so workers can still read existing histories. The sample selects the workflow default +where `select` returns `workflowCodec` in [src/codec.ts](src/codec.ts). | Ordinary workflow payload | Default key ID | | ------------------------------------------------------ | ------------------------ | diff --git a/nexus-serialization-context/src/codec.ts b/nexus-serialization-context/src/codec.ts index 842cd42fb..fe3c3b7cf 100644 --- a/nexus-serialization-context/src/codec.ts +++ b/nexus-serialization-context/src/codec.ts @@ -29,9 +29,18 @@ export class NexusCodec implements PayloadCodec { private readonly endpoints: ReadonlyMap; constructor(role: 'caller' | 'compressed' | 'encrypted' = 'caller') { - this.endpoints = new Map( - [...endpointCodecs].filter(([, codec]) => role === 'caller' || codec.compress === (role === 'compressed')), - ); + const endpoints = new Map(); + for (const [endpoint, settings] of endpointCodecs) { + if (role === 'caller') { + endpoints.set(endpoint, settings); + } else if (role === 'compressed' && settings.compress) { + endpoints.set(endpoint, settings); + } else if (role === 'encrypted' && !settings.compress) { + endpoints.set(endpoint, settings); + } + } + this.endpoints = endpoints; + switch (role) { case 'caller': this.workflowCodec = endpointCodec('caller-workflow', 'sample-key-C-123', false);