11# Nexus serialization context
22
3- This sample calls a synchronous and an asynchronous Nexus operation through each of
4- two endpoints. Each endpoint routes to its own handler worker, which registers both
5- ` SyncEchoService ` and ` AsyncEchoService ` . The caller's ` NexusCodec ` uses
6- ` NexusSerializationContext ` to select the ` PayloadCodec ` registered for each endpoint.
7- The sample uses these keys:
8-
9- - Key A: compresses with zlib, then encrypts synchronous and asynchronous payloads for ` nexus-serialization-compressed-encrypted ` .
10- - Key B: encrypts synchronous and asynchronous payloads for ` nexus-serialization-encrypted ` .
11- - Key C: encrypts the caller workflow's input and final result.
12-
13- The caller configures a codec for each endpoint and a separate codec for its own
14- workflow input and result. Each handler worker uses the fixed key for its endpoint.
15-
16- The caller schedules all four operations before waiting for their results, so each
17- result must be decoded using the context of its own endpoint. The caller's
18- ` NexusCodec ` uses Key C for its own workflow payloads, which have no Nexus endpoint.
19-
20- For both Nexus endpoints, the outer encrypted payload stores the endpoint name in
21- ` nexus-endpoint-name ` metadata alongside ` binary/nexus-aes-gcm ` and a sample key ID
22- (` key-a ` or ` key-b ` ). A Codec Server can use the endpoint name to select the matching
23- key and decompression chain without SDK context.
24-
25- For the compressed endpoint, the outer payload's decoded metadata looks like:
3+ This sample uses ` NexusSerializationContext ` to select an encryption key for each Nexus
4+ endpoint. The caller invokes synchronous and workflow-backed asynchronous operations
5+ through four endpoints. Handler A (` CompressedEncryptedHandlerWorker ` ) compresses and
6+ then encrypts Nexus payloads. Handler B (` EncryptedHandlerWorker ` ) encrypts without
7+ compression. Each handler selects between its own key 1 and key 2 using
8+ the endpoint in the Nexus context.
9+
10+ | Endpoint | Encryption key | Nexus payload encoding |
11+ | ---| ---| ---|
12+ | ` handler-a-1 ` | ` HANDLER_A_KEY_1 ` | zlib, then AES-GCM |
13+ | ` handler-b-1 ` | ` HANDLER_B_KEY_1 ` | AES-GCM |
14+ | ` handler-a-2 ` | ` HANDLER_A_KEY_2 ` | zlib, then AES-GCM |
15+ | ` handler-b-2 ` | ` HANDLER_B_KEY_2 ` | AES-GCM |
16+
17+ These are four distinct 128-bit AES keys. Compression runs before encryption;
18+ decoding decrypts before decompressing. AES-GCM authenticates the ciphertext.
19+ The AES-GCM and zlib codecs are implemented in this sample; Nexus supplies the endpoint
20+ context used to select them.
21+
22+ Each worker configures ` NexusCodec ` with an endpoint-to-codec map and a default codec
23+ for ordinary workflow payloads. The sample reuses key 1 for workflow payloads
24+ to keep the example to four keys:
25+
26+ | Ordinary workflow payload | Encryption key |
27+ | ---| ---|
28+ | Caller workflow input and final result | ` HANDLER_A_KEY_1 ` |
29+ | Handler A backing workflow inputs | ` HANDLER_A_KEY_1 ` |
30+ | Handler B backing workflow inputs | ` HANDLER_B_KEY_1 ` |
31+
32+ These workflow payloads use AES-GCM without compression or endpoint metadata.
33+ An async Nexus result uses the key and compression chain selected by its endpoint,
34+ even when that differs from the backing workflow's input encryption.
35+
36+ For synchronous operations, the SDK supplies Nexus context when decoding inputs and
37+ encoding results. When an asynchronous handler starts ` EchoWorkflow ` , the SDK includes
38+ the Nexus endpoint, service, and operation in the workflow-start request. The server
39+ stores these fields in the ` WorkflowExecutionStarted ` history event. The worker SDK
40+ restores the Nexus context from that event when encoding the workflow's result, so
41+ ` NexusCodec ` can select the endpoint's codec and key from the worker's local configuration.
42+ The workflow's input still uses ordinary workflow context; this sample's default codec
43+ encrypts it with that handler's key 1.
44+
45+ The caller starts all eight operations before waiting for their results. Each operation
46+ keeps its own endpoint context, even when operations for different keys are in flight.
47+ No custom interceptor or workflow-header propagation is required.
48+
49+ The outer encrypted payload includes ` encoding ` , ` encryption-key-id ` , and, for Nexus
50+ payloads, ` nexus-endpoint-name ` metadata. For example:
2651
2752``` text
2853encoding: binary/nexus-aes-gcm
29- encryption-key-id: key-a
30- nexus-endpoint-name: nexus-serialization-compressed-encrypted
54+ encryption-key-id: handler-a-1
55+ nexus-endpoint-name: handler-a-1
3156```
3257
33- The asynchronous results have ` encryption-key-id: key-a ` or ` key-b ` and their respective
34- endpoint names in the outer payload metadata.
35- The caller workflow's input and final result use ` encryption-key-id: key-c ` ; they do not
36- have endpoint metadata. The starter uses the same converter as the caller worker, so it
37- can decode the final result before printing it.
38-
39- For synchronous operations, the SDK supplies ` NexusSerializationContext ` when decoding
40- inputs and encoding results. For asynchronous operations backed by ` EchoWorkflow ` , the
41- handler's SDK sends the context when starting the workflow, and the server stores it.
42- The workflow worker receives that context and uses it to encode the workflow's result
43- for the Nexus caller. Other workflow payloads keep their normal workflow context.
44-
45- The sample's ` AesGcmCodec.withContext ` reads the endpoint directly from this context
46- and includes it in the encrypted result's metadata. No custom interceptor or workflow
47- header propagation is needed. The SDK-side codec chooses the key; the server carries
48- the context without access to encryption keys.
58+ A Codec Server can use that metadata to select the key and decompression chain without
59+ SDK context. Ordinary workflow payloads have a key ID but no endpoint metadata or compression.
4960
5061The hard-coded keys are only for this local example. For production encryption,
5162use a secure key store, as in the
@@ -55,73 +66,71 @@ use a secure key store, as in the
5566
5667Use a Temporal Server that supports Nexus serialization-context propagation for
5768workflow-backed asynchronous operations. For local development, download
58- [ Temporal CLI ` v1.9.3-nexus-serialization-context ` ] ( https://github.com/temporalio/cli/releases/tag/v1.9.3-nexus-serialization-context )
59- and add its ` temporal ` binary to your ` PATH ` . Its dev server includes this support.
69+ [ Temporal CLI ` v1.9.3-nexus-serialization-context ` ] ( https://github.com/temporalio/cli/releases/tag/v1.9.3-nexus-serialization-context ) .
70+ Keep this prerelease binary separate from your stable CLI. The commands below use
71+ ` ./temporal ` to run the downloaded binary from the repository root.
6072
6173## Run locally
6274
75+ The caller and both handlers share the ` nexus-serialization ` namespace. Each worker
76+ polls its own task queue; both endpoints for a handler target that handler's queue.
77+
6378Start the dev server:
6479
6580``` bash
66- temporal server start-dev
81+ ./ temporal server start-dev --namespace nexus-serialization
6782```
6883
69- In another terminal, create the namespaces and endpoints :
84+ Create two endpoints for each handler worker :
7085
7186``` bash
72- temporal operator namespace create --namespace nexus-serialization-caller
73- temporal operator namespace create --namespace nexus-serialization-key-a-handler
74- temporal operator namespace create --namespace nexus-serialization-key-b-handler
75- temporal operator nexus endpoint create \
76- --name nexus-serialization-compressed-encrypted \
77- --target-namespace nexus-serialization-key-a-handler \
78- --target-task-queue nexus-serialization-key-a-handler
79- temporal operator nexus endpoint create \
80- --name nexus-serialization-encrypted \
81- --target-namespace nexus-serialization-key-b-handler \
82- --target-task-queue nexus-serialization-key-b-handler
87+ ./temporal operator nexus endpoint create \
88+ --name handler-a-1 \
89+ --target-namespace nexus-serialization \
90+ --target-task-queue nexus-serialization-handler-a
91+ ./temporal operator nexus endpoint create \
92+ --name handler-a-2 \
93+ --target-namespace nexus-serialization \
94+ --target-task-queue nexus-serialization-handler-a
95+ ./temporal operator nexus endpoint create \
96+ --name handler-b-1 \
97+ --target-namespace nexus-serialization \
98+ --target-task-queue nexus-serialization-handler-b
99+ ./temporal operator nexus endpoint create \
100+ --name handler-b-2 \
101+ --target-namespace nexus-serialization \
102+ --target-task-queue nexus-serialization-handler-b
83103```
84104
85105Run each of the following in its own terminal from the repository root:
86106
87107``` bash
88108./gradlew -q :core:execute -PmainClass=io.temporal.samples.nexusserializationcontext.handler.CompressedEncryptedHandlerWorker \
89- --args=" -namespace nexus-serialization-key-a-handler "
109+ --args=" -namespace nexus-serialization"
90110```
91111
92112``` bash
93113./gradlew -q :core:execute -PmainClass=io.temporal.samples.nexusserializationcontext.handler.EncryptedHandlerWorker \
94- --args=" -namespace nexus-serialization-key-b-handler "
114+ --args=" -namespace nexus-serialization"
95115```
96116
97117``` bash
98118./gradlew -q :core:execute -PmainClass=io.temporal.samples.nexusserializationcontext.caller.CallerWorker \
99- --args=" -namespace nexus-serialization-caller "
119+ --args=" -namespace nexus-serialization"
100120```
101121
102122``` bash
103123./gradlew -q :core:execute -PmainClass=io.temporal.samples.nexusserializationcontext.caller.CallerStarter \
104- --args=" -namespace nexus-serialization-caller "
124+ --args=" -namespace nexus-serialization"
105125```
106126
107- The starter will print:
108-
109- ``` text
110- Compressed and encrypted endpoint sync result: Hello from Nexus
111- Encrypted endpoint sync result: Hello from Nexus
112- Compressed and encrypted endpoint async result: Hello from Nexus
113- Encrypted endpoint async result: Hello from Nexus
114- ```
127+ The starter prints a sync result and an async result for each endpoint. All eight
128+ results should be ` Hello from Nexus ` .
115129
116130## Test
117131
118- Run the codec tests and integration test :
132+ Run the codec tests:
119133
120134``` bash
121- ./gradlew :core:test --tests ' io.temporal.samples.nexusserializationcontext.* '
135+ ./gradlew :core:test --tests ' io.temporal.samples.nexusserializationcontext.codec.NexusCodecTest '
122136```
123-
124- The integration test downloads and starts the dev-server version listed above,
125- runs synchronous and workflow-backed asynchronous calls through both endpoints,
126- and checks the recorded Nexus context and encrypted async-result metadata in
127- workflow history. It stops the server and workers when finished.
0 commit comments