Skip to content

Commit fbf43c2

Browse files
committed
Demonstrate per-endpoint key selection in Nexus handlers
Serve two endpoints per handler with distinct keys in one namespace. Keep sync and async calls explicit, simplify the sample codec tests, and remove the dev-server integration test.
1 parent 94eb2f0 commit fbf43c2

11 files changed

Lines changed: 284 additions & 463 deletions

File tree

‎core/src/main/java/io/temporal/samples/nexusserializationcontext/README.md‎

Lines changed: 84 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,62 @@
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
2853
encoding: 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

5061
The hard-coded keys are only for this local example. For production encryption,
5162
use a secure key store, as in the
@@ -55,73 +66,71 @@ use a secure key store, as in the
5566

5667
Use a Temporal Server that supports Nexus serialization-context propagation for
5768
workflow-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+
6378
Start 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

85105
Run 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.
Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,21 @@
11
package io.temporal.samples.nexusserializationcontext;
22

33
public final class SampleConfig {
4-
public static final String COMPRESSED_ENCRYPTED_ENDPOINT =
5-
"nexus-serialization-compressed-encrypted";
6-
public static final String ENCRYPTED_ENDPOINT = "nexus-serialization-encrypted";
4+
public static final String HANDLER_A_1_ENDPOINT = "handler-a-1";
5+
public static final String HANDLER_B_1_ENDPOINT = "handler-b-1";
6+
public static final String HANDLER_A_2_ENDPOINT = "handler-a-2";
7+
public static final String HANDLER_B_2_ENDPOINT = "handler-b-2";
78
public static final String ENDPOINT_METADATA_KEY = "nexus-endpoint-name";
8-
public static final String KEY_A_ID = "key-a";
9-
public static final String KEY_B_ID = "key-b";
10-
public static final String KEY_C_ID = "key-c";
9+
public static final String HANDLER_A_KEY_1_ID = "handler-a-1";
10+
public static final String HANDLER_B_KEY_1_ID = "handler-b-1";
11+
public static final String HANDLER_A_KEY_2_ID = "handler-a-2";
12+
public static final String HANDLER_B_KEY_2_ID = "handler-b-2";
1113

12-
// Hard-coded keys are only for this local sample.
13-
public static final String KEY_A_VALUE = "sample-key-A-123";
14-
public static final String KEY_B_VALUE = "sample-key-B-123";
15-
public static final String KEY_C_VALUE = "sample-key-C-123";
14+
// Four distinct, hard-coded keys for this local sample only.
15+
public static final String HANDLER_A_KEY_1 = "handler-a-key-01";
16+
public static final String HANDLER_B_KEY_1 = "handler-b-key-01";
17+
public static final String HANDLER_A_KEY_2 = "handler-a-key-02";
18+
public static final String HANDLER_B_KEY_2 = "handler-b-key-02";
1619

1720
private SampleConfig() {}
1821
}

‎core/src/main/java/io/temporal/samples/nexusserializationcontext/caller/CallerStarter.java‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
import io.temporal.client.WorkflowClientOptions;
55
import io.temporal.client.WorkflowOptions;
66
import io.temporal.samples.nexus.options.ClientOptions;
7+
import io.temporal.samples.nexusserializationcontext.SampleConfig;
78

89
public class CallerStarter {
910
public static void main(String[] args) {
@@ -18,12 +19,20 @@ public static void main(String[] args) {
1819

1920
EndpointResults results = workflow.echoThroughEndpoints("Hello from Nexus");
2021
System.out.println(
21-
"Compressed and encrypted endpoint sync result: "
22-
+ results.compressedEncryptedSyncResult());
23-
System.out.println("Encrypted endpoint sync result: " + results.encryptedSyncResult());
22+
SampleConfig.HANDLER_A_1_ENDPOINT + " sync result: " + results.handlerA1SyncResult());
2423
System.out.println(
25-
"Compressed and encrypted endpoint async result: "
26-
+ results.compressedEncryptedAsyncResult());
27-
System.out.println("Encrypted endpoint async result: " + results.encryptedAsyncResult());
24+
SampleConfig.HANDLER_A_1_ENDPOINT + " async result: " + results.handlerA1AsyncResult());
25+
System.out.println(
26+
SampleConfig.HANDLER_B_1_ENDPOINT + " sync result: " + results.handlerB1SyncResult());
27+
System.out.println(
28+
SampleConfig.HANDLER_B_1_ENDPOINT + " async result: " + results.handlerB1AsyncResult());
29+
System.out.println(
30+
SampleConfig.HANDLER_A_2_ENDPOINT + " sync result: " + results.handlerA2SyncResult());
31+
System.out.println(
32+
SampleConfig.HANDLER_A_2_ENDPOINT + " async result: " + results.handlerA2AsyncResult());
33+
System.out.println(
34+
SampleConfig.HANDLER_B_2_ENDPOINT + " sync result: " + results.handlerB2SyncResult());
35+
System.out.println(
36+
SampleConfig.HANDLER_B_2_ENDPOINT + " async result: " + results.handlerB2AsyncResult());
2837
}
2938
}

‎core/src/main/java/io/temporal/samples/nexusserializationcontext/caller/CallerWorker.java‎

Lines changed: 29 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -34,25 +34,37 @@ public static void main(String[] args) {
3434
}
3535

3636
public static DataConverter dataConverter() {
37-
SecretKey keyA =
38-
new SecretKeySpec(SampleConfig.KEY_A_VALUE.getBytes(StandardCharsets.UTF_8), "AES");
39-
SecretKey keyB =
40-
new SecretKeySpec(SampleConfig.KEY_B_VALUE.getBytes(StandardCharsets.UTF_8), "AES");
41-
SecretKey keyC =
42-
new SecretKeySpec(SampleConfig.KEY_C_VALUE.getBytes(StandardCharsets.UTF_8), "AES");
37+
SecretKey handlerAKey1 =
38+
new SecretKeySpec(SampleConfig.HANDLER_A_KEY_1.getBytes(StandardCharsets.UTF_8), "AES");
39+
SecretKey handlerBKey1 =
40+
new SecretKeySpec(SampleConfig.HANDLER_B_KEY_1.getBytes(StandardCharsets.UTF_8), "AES");
41+
SecretKey handlerAKey2 =
42+
new SecretKeySpec(SampleConfig.HANDLER_A_KEY_2.getBytes(StandardCharsets.UTF_8), "AES");
43+
SecretKey handlerBKey2 =
44+
new SecretKeySpec(SampleConfig.HANDLER_B_KEY_2.getBytes(StandardCharsets.UTF_8), "AES");
45+
PayloadCodec handlerAKey1Encryption =
46+
new AesGcmCodec(SampleConfig.HANDLER_A_KEY_1_ID, handlerAKey1);
47+
PayloadCodec handlerBKey1Encryption =
48+
new AesGcmCodec(SampleConfig.HANDLER_B_KEY_1_ID, handlerBKey1);
49+
PayloadCodec handlerAKey2Encryption =
50+
new AesGcmCodec(SampleConfig.HANDLER_A_KEY_2_ID, handlerAKey2);
51+
PayloadCodec handlerBKey2Encryption =
52+
new AesGcmCodec(SampleConfig.HANDLER_B_KEY_2_ID, handlerBKey2);
4353
// ChainCodec encodes last to first: compress, then encrypt.
44-
PayloadCodec compressedEncrypted =
45-
new ChainCodec(List.of(new AesGcmCodec(SampleConfig.KEY_A_ID, keyA), new ZlibCodec()));
46-
PayloadCodec encrypted = new AesGcmCodec(SampleConfig.KEY_B_ID, keyB);
54+
Map<String, PayloadCodec> nexusEndpointCodecs =
55+
Map.of(
56+
SampleConfig.HANDLER_A_1_ENDPOINT,
57+
new ChainCodec(List.of(handlerAKey1Encryption, new ZlibCodec())),
58+
SampleConfig.HANDLER_B_1_ENDPOINT,
59+
handlerBKey1Encryption,
60+
SampleConfig.HANDLER_A_2_ENDPOINT,
61+
new ChainCodec(List.of(handlerAKey2Encryption, new ZlibCodec())),
62+
SampleConfig.HANDLER_B_2_ENDPOINT,
63+
handlerBKey2Encryption);
64+
// Reuse handler A's key 1 for the caller's workflow payloads.
65+
PayloadCodec callerWorkflowEncryption = handlerAKey1Encryption;
4766
return new CodecDataConverter(
4867
DefaultDataConverter.newDefaultInstance(),
49-
List.of(
50-
new NexusCodec(
51-
Map.of(
52-
SampleConfig.COMPRESSED_ENCRYPTED_ENDPOINT,
53-
compressedEncrypted,
54-
SampleConfig.ENCRYPTED_ENDPOINT,
55-
encrypted),
56-
new AesGcmCodec(SampleConfig.KEY_C_ID, keyC))));
68+
List.of(new NexusCodec(nexusEndpointCodecs, callerWorkflowEncryption)));
5769
}
5870
}

0 commit comments

Comments
 (0)