Skip to content

Latest commit

 

History

History
 
 

nexus_serialization_context

README.md

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 cryptography for AES-GCM and Python's zlib module for compression.

NexusCodec uses the endpoint from the Nexus context to select a codec. It uses a default codec for ordinary workflow payloads. Use NexusCodec as the payload_codec on a DataConverter, then pass that converter as data_converter to Client.connect for the caller and handler clients.

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. NexusCodec.with_context returns a copy so binding one operation does not change another. 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:

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 Python 3.11 or newer, uv, and Temporal Python SDK 1.36.0 or later. This is a separate uv project because the required SDK needs Python 3.11+, while the repository's other samples support Python 3.10.

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. Extract it and place the temporal executable in the repository root. 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:

cd nexus_serialization_context
uv sync
../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:

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

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

uv run worker.py compressed-encrypted
uv run worker.py encrypted
uv run worker.py caller

Start the caller workflow in another terminal:

uv run starter.py

Output

The starter prints the workflow and run IDs, followed by a sync result and an async result for each endpoint. Replacing the generated IDs, the output is:

Started workflow: ID=nexus-serialization-<workflow UUID> RunID=<run UUID>
nexus-serialization-compressed-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-1: 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.

To see what Temporal stored, open the printed workflow ID in the Temporal UI 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.

Test

Run the codec and workflow tests:

uv run poe test

The workflow test starts its own server and checks all eight results, the stored Nexus context, and the backing workflows' input and result encryption metadata.