Skip to content
Open
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
197 changes: 197 additions & 0 deletions nexus-serialization-context/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,197 @@
# 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. 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.

## 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.
For this example, each handler reuses its endpoint-1 key for backing workflow inputs.

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

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

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:

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

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

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

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:

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

```shell
pnpm start.compressed
```

```shell
pnpm start.encrypted
```

```shell
pnpm start.caller
```

Start the caller workflow in another terminal:

```shell
pnpm workflow
```

### Output

Expected output:

```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);
});
34 changes: 34 additions & 0 deletions nexus-serialization-context/src/caller/workflows.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
import { createNexusServiceClient, log } from '@temporalio/workflow';
import { syncEchoService, asyncEchoService } from '../api';
import { ENDPOINTS, EndpointResults } from '../shared';

export async function callerWorkflow(message: string): Promise<EndpointResults> {
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 });
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,
})),
);
const results = Object.fromEntries(
await Promise.all(
started.map(async ({ endpoint, sync, async }) => [
endpoint,
{ sync: await sync.result(), async: await async.result() },
]),
),
);
log.info('Received sync and async replies', { endpointCount: started.length });
return results;
}
Loading
Loading