Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ jobs:
langsmith
mutex
nestjs-exchange-rates
nexus-serialization-context
nexus-standalone-activity
nexus-standalone-operations
sleep-for-days
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions nexus-serialization-context/.eslintignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
node_modules
lib
.eslintrc.js
48 changes: 48 additions & 0 deletions nexus-serialization-context/.eslintrc.js
Original file line number Diff line number Diff line change
@@ -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}`]),
],
},
},
],
};
3 changes: 3 additions & 0 deletions nexus-serialization-context/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
lib
node_modules
/temporal
2 changes: 2 additions & 0 deletions nexus-serialization-context/.prettierrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
printWidth: 120
singleQuote: true
187 changes: 187 additions & 0 deletions nexus-serialization-context/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,187 @@
# 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 |

Each endpoint uses a different 128-bit AES key. The codec uses Node.js for
AES-GCM encryption and zlib compression.

`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.

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 |
| -------------------------------------------- | ------------------------ |
| 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.

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
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
```

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.

## Prerequisites

Use Node.js 22 or newer, [pnpm](https://pnpm.io/installation), and Temporal TypeScript
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
[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
```

### 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:

```text
Started workflow: nexus-serialization-<workflow UUID>
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 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 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.
51 changes: 51 additions & 0 deletions nexus-serialization-context/package.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
4 changes: 4 additions & 0 deletions nexus-serialization-context/src/api.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
import * as nexus from 'nexus-rpc';

export const syncEchoService = nexus.service('SyncEchoService', { echo: nexus.operation<string, string>() });
export const asyncEchoService = nexus.service('AsyncEchoService', { echoAsync: nexus.operation<string, string>() });
24 changes: 24 additions & 0 deletions nexus-serialization-context/src/caller/worker.ts
Original file line number Diff line number Diff line change
@@ -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);
});
31 changes: 31 additions & 0 deletions nexus-serialization-context/src/caller/workflows.ts
Original file line number Diff line number Diff line change
@@ -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<EndpointResults> {
// 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() },
]),
),
);
}
Loading
Loading