Skip to content
Merged
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
Original file line number Diff line number Diff line change
@@ -1,98 +1,129 @@
# Nexus serialization context

This sample calls a synchronous and an asynchronous Nexus operation through each of
two endpoints. Each endpoint routes to its own handler worker, which registers both
`SyncEchoService` and `AsyncEchoService`. The caller's `NexusCodec` uses
`NexusSerializationContext` to select the `PayloadCodec` registered for each endpoint.
The sample uses these keys:

- Key A: compresses with zlib, then encrypts synchronous and asynchronous payloads for `nexus-serialization-compressed-encrypted`.
- Key B: encrypts synchronous and asynchronous payloads for `nexus-serialization-encrypted`.
- Key C: encrypts the caller workflow's input and final result.

The caller configures a codec for each endpoint and a separate codec for its own
workflow input and result. Each handler worker uses the fixed key for its endpoint.

The caller schedules all four operations before waiting for their results, so each
result must be decoded using the context of its own endpoint. The caller's
`NexusCodec` uses Key C for its own workflow payloads, which have no Nexus endpoint.

For both Nexus endpoints, the outer encrypted payload stores the endpoint name in
`nexus-endpoint-name` metadata alongside `binary/nexus-aes-gcm` and a sample key ID
(`key-a` or `key-b`). A Codec Server can use the endpoint name to select the matching
key and decompression chain without SDK context.

For the compressed endpoint, the outer payload's decoded metadata looks like:
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. `CompressedEncryptedHandlerWorker` compresses and then
encrypts Nexus payloads. `EncryptedHandlerWorker` 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 | Endpoint | Encryption key | Nexus payload encoding |
|---|---|---|---|
| `CompressedEncryptedHandlerWorker` | `nexus-serialization-compressed-encrypted-1` | `COMPRESSED_ENCRYPTED_KEY_1` | zlib, then AES-GCM |
| `CompressedEncryptedHandlerWorker` | `nexus-serialization-compressed-encrypted-2` | `COMPRESSED_ENCRYPTED_KEY_2` | zlib, then AES-GCM |
| `EncryptedHandlerWorker` | `nexus-serialization-encrypted-1` | `ENCRYPTED_KEY_1` | AES-GCM |
| `EncryptedHandlerWorker` | `nexus-serialization-encrypted-2` | `ENCRYPTED_KEY_2` | AES-GCM |

These four endpoint keys are distinct 128-bit AES keys. Compression runs before encryption;
decoding decrypts before decompressing. AES-GCM authenticates the ciphertext.
The AES-GCM and zlib codecs are implemented in this sample; Nexus supplies the endpoint
context used to select them.

Each worker configures `NexusCodec` with an endpoint-to-codec map and a default codec
for ordinary workflow payloads. The caller uses a separate `CALLER_WORKFLOW_KEY` for
its own input and final result, keeping those payloads independent of the keys shared
with Nexus handlers. Each handler reuses its key 1 for backing workflow inputs.

| Ordinary workflow payload | Encryption key |
|---|---|
| Caller workflow input and final result | `CALLER_WORKFLOW_KEY` |
| Compressed/encrypted handler workflow inputs | `COMPRESSED_ENCRYPTED_KEY_1` |
| Encrypted handler workflow inputs | `ENCRYPTED_KEY_1` |

These workflow payloads use AES-GCM without compression or endpoint metadata.
An async Nexus result uses the key and compression chain selected by its endpoint,
even when that differs from the backing workflow's input encryption.

For synchronous operations, the SDK supplies Nexus context when decoding inputs and
encoding results. When an asynchronous handler starts `EchoWorkflow`, the SDK includes
the Nexus endpoint, service, and operation in the workflow-start request. The server
stores these fields in the `WorkflowExecutionStarted` history event. The worker SDK
restores the Nexus context from that event when encoding the workflow's result, so
`NexusCodec` can select the endpoint's codec and key from the worker's local configuration.
The workflow's input still uses ordinary workflow context; this sample's default codec
encrypts it with that handler's 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.
No custom interceptor or workflow-header propagation is required.

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: key-a
nexus-endpoint-name: nexus-serialization-compressed-encrypted
encryption-key-id: compressed-encrypted-1
nexus-endpoint-name: nexus-serialization-compressed-encrypted-1
```

The asynchronous results have `encryption-key-id: key-a` or `key-b` and their respective
endpoint names in the outer payload metadata.
The caller workflow's input and final result use `encryption-key-id: key-c`; they do not
have endpoint metadata. The starter uses the same converter as the caller worker, so it
can decode the final result before printing it.

`NexusSerializationContext` works end to end for synchronous Nexus operations.
For an asynchronous operation, the handler's final result is serialized as a workflow
result and does not receive `NexusSerializationContext`. We plan to add
`NexusSerializationContext` support for asynchronous operation results in the Java SDK.
Until then, the sample's `NexusEndpointInterceptor` captures the endpoint when the
handler starts the backing `EchoWorkflow`. `NexusEndpointContextPropagator` saves it in
the workflow headers and restores it on the workflow thread. Each handler's codec uses
its fixed key to encrypt the workflow result and includes the propagated endpoint name
in the outer payload metadata. This propagation is needed for the endpoint metadata;
the handler already knows which key to use. When the result reaches the caller, the SDK
supplies `NexusSerializationContext` to decode it.

This endpoint propagation covers asynchronous operations backed by workflows. If the
endpoint is not propagated, the result remains encrypted with the handler's fixed key
but lacks the endpoint name in its metadata.
A Codec Server can use that metadata to select the key and decompression chain without
SDK context. Ordinary workflow payloads have a key ID but no endpoint metadata or compression.

The hard-coded keys are only for this local example. For production encryption,
use a secure key store, as in the
[AWS Encryption SDK sample](../keymanagementencryption/awsencryptionsdk/README.md).

Requires Java SDK 1.40.0 or later and Temporal Server 1.30.0 or later with Nexus enabled
so the handler can read the endpoint name.
## Prerequisites

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).
Keep this prerelease binary separate from your stable CLI. The commands below use
`./temporal` to run the downloaded binary from the repository root.

## Run locally

Start a Temporal dev server:
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:

```bash
temporal server start-dev
./temporal server start-dev \
--namespace nexus-serialization-caller \
--namespace nexus-serialization-compressed-encrypted-handler \
--namespace nexus-serialization-encrypted-handler
```

In another terminal, create the namespaces and endpoints:
Create two endpoints for each handler worker:

```bash
temporal operator namespace create --namespace nexus-serialization-caller
temporal operator namespace create --namespace nexus-serialization-key-a-handler
temporal operator namespace create --namespace nexus-serialization-key-b-handler
temporal operator nexus endpoint create \
--name nexus-serialization-compressed-encrypted \
--target-namespace nexus-serialization-key-a-handler \
--target-task-queue nexus-serialization-key-a-handler
temporal operator nexus endpoint create \
--name nexus-serialization-encrypted \
--target-namespace nexus-serialization-key-b-handler \
--target-task-queue nexus-serialization-key-b-handler
./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 of the following in its own terminal from the repository root:

```bash
./gradlew -q :core:execute -PmainClass=io.temporal.samples.nexusserializationcontext.handler.CompressedEncryptedHandlerWorker \
--args="-namespace nexus-serialization-key-a-handler"
--args="-namespace nexus-serialization-compressed-encrypted-handler"
```

```bash
./gradlew -q :core:execute -PmainClass=io.temporal.samples.nexusserializationcontext.handler.EncryptedHandlerWorker \
--args="-namespace nexus-serialization-key-b-handler"
--args="-namespace nexus-serialization-encrypted-handler"
```

```bash
Expand All @@ -105,11 +136,13 @@ Run each of the following in its own terminal from the repository root:
--args="-namespace nexus-serialization-caller"
```

The starter will print:
The starter prints a sync result and an async result for each endpoint. All eight
results should be `Hello from Nexus`.

```text
Compressed and encrypted endpoint sync result: Hello from Nexus
Encrypted endpoint sync result: Hello from Nexus
Compressed and encrypted endpoint async result: Hello from Nexus
Encrypted endpoint async result: Hello from Nexus
## Test

Run the codec tests:

```bash
./gradlew :core:test --tests 'io.temporal.samples.nexusserializationcontext.codec.NexusCodecTest'
```
Original file line number Diff line number Diff line change
@@ -1,18 +1,25 @@
package io.temporal.samples.nexusserializationcontext;

public final class SampleConfig {
public static final String COMPRESSED_ENCRYPTED_ENDPOINT =
"nexus-serialization-compressed-encrypted";
public static final String ENCRYPTED_ENDPOINT = "nexus-serialization-encrypted";
public static final String COMPRESSED_ENCRYPTED_1_ENDPOINT =
"nexus-serialization-compressed-encrypted-1";
public static final String ENCRYPTED_1_ENDPOINT = "nexus-serialization-encrypted-1";
public static final String COMPRESSED_ENCRYPTED_2_ENDPOINT =
"nexus-serialization-compressed-encrypted-2";
public static final String ENCRYPTED_2_ENDPOINT = "nexus-serialization-encrypted-2";
public static final String ENDPOINT_METADATA_KEY = "nexus-endpoint-name";
public static final String KEY_A_ID = "key-a";
public static final String KEY_B_ID = "key-b";
public static final String KEY_C_ID = "key-c";
public static final String COMPRESSED_ENCRYPTED_KEY_1_ID = "compressed-encrypted-1";
public static final String ENCRYPTED_KEY_1_ID = "encrypted-1";
public static final String COMPRESSED_ENCRYPTED_KEY_2_ID = "compressed-encrypted-2";
public static final String ENCRYPTED_KEY_2_ID = "encrypted-2";
public static final String CALLER_WORKFLOW_KEY_ID = "caller-workflow";

// Hard-coded keys are only for this local sample.
public static final String KEY_A_VALUE = "sample-key-A-123";
public static final String KEY_B_VALUE = "sample-key-B-123";
public static final String KEY_C_VALUE = "sample-key-C-123";
public static final String COMPRESSED_ENCRYPTED_KEY_1 = "handler-a-key-01";
public static final String ENCRYPTED_KEY_1 = "handler-b-key-01";
public static final String COMPRESSED_ENCRYPTED_KEY_2 = "handler-a-key-02";
public static final String ENCRYPTED_KEY_2 = "handler-b-key-02";
public static final String CALLER_WORKFLOW_KEY = "sample-key-C-123";

private SampleConfig() {}
}
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
import io.temporal.client.WorkflowClientOptions;
import io.temporal.client.WorkflowOptions;
import io.temporal.samples.nexus.options.ClientOptions;
import io.temporal.samples.nexusserializationcontext.SampleConfig;

public class CallerStarter {
public static void main(String[] args) {
Expand All @@ -18,12 +19,28 @@ public static void main(String[] args) {

EndpointResults results = workflow.echoThroughEndpoints("Hello from Nexus");
System.out.println(
"Compressed and encrypted endpoint sync result: "
+ results.compressedEncryptedSyncResult());
System.out.println("Encrypted endpoint sync result: " + results.encryptedSyncResult());
SampleConfig.COMPRESSED_ENCRYPTED_1_ENDPOINT
+ " sync result: "
+ results.compressedEncrypted1SyncResult());
System.out.println(
"Compressed and encrypted endpoint async result: "
+ results.compressedEncryptedAsyncResult());
System.out.println("Encrypted endpoint async result: " + results.encryptedAsyncResult());
SampleConfig.COMPRESSED_ENCRYPTED_1_ENDPOINT
+ " async result: "
+ results.compressedEncrypted1AsyncResult());
System.out.println(
SampleConfig.ENCRYPTED_1_ENDPOINT + " sync result: " + results.encrypted1SyncResult());
System.out.println(
SampleConfig.ENCRYPTED_1_ENDPOINT + " async result: " + results.encrypted1AsyncResult());
System.out.println(
SampleConfig.COMPRESSED_ENCRYPTED_2_ENDPOINT
+ " sync result: "
+ results.compressedEncrypted2SyncResult());
System.out.println(
SampleConfig.COMPRESSED_ENCRYPTED_2_ENDPOINT
+ " async result: "
+ results.compressedEncrypted2AsyncResult());
System.out.println(
SampleConfig.ENCRYPTED_2_ENDPOINT + " sync result: " + results.encrypted2SyncResult());
System.out.println(
SampleConfig.ENCRYPTED_2_ENDPOINT + " async result: " + results.encrypted2AsyncResult());
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -34,25 +34,42 @@ public static void main(String[] args) {
}

public static DataConverter dataConverter() {
SecretKey keyA =
new SecretKeySpec(SampleConfig.KEY_A_VALUE.getBytes(StandardCharsets.UTF_8), "AES");
SecretKey keyB =
new SecretKeySpec(SampleConfig.KEY_B_VALUE.getBytes(StandardCharsets.UTF_8), "AES");
SecretKey keyC =
new SecretKeySpec(SampleConfig.KEY_C_VALUE.getBytes(StandardCharsets.UTF_8), "AES");
SecretKey compressedEncryptedKey1 =
new SecretKeySpec(
SampleConfig.COMPRESSED_ENCRYPTED_KEY_1.getBytes(StandardCharsets.UTF_8), "AES");
SecretKey encryptedKey1 =
new SecretKeySpec(SampleConfig.ENCRYPTED_KEY_1.getBytes(StandardCharsets.UTF_8), "AES");
SecretKey compressedEncryptedKey2 =
new SecretKeySpec(
SampleConfig.COMPRESSED_ENCRYPTED_KEY_2.getBytes(StandardCharsets.UTF_8), "AES");
SecretKey encryptedKey2 =
new SecretKeySpec(SampleConfig.ENCRYPTED_KEY_2.getBytes(StandardCharsets.UTF_8), "AES");
SecretKey callerWorkflowKey =
new SecretKeySpec(SampleConfig.CALLER_WORKFLOW_KEY.getBytes(StandardCharsets.UTF_8), "AES");
PayloadCodec compressedEncryptedKey1Encryption =
new AesGcmCodec(SampleConfig.COMPRESSED_ENCRYPTED_KEY_1_ID, compressedEncryptedKey1);
PayloadCodec encryptedKey1Encryption =
new AesGcmCodec(SampleConfig.ENCRYPTED_KEY_1_ID, encryptedKey1);
PayloadCodec compressedEncryptedKey2Encryption =
new AesGcmCodec(SampleConfig.COMPRESSED_ENCRYPTED_KEY_2_ID, compressedEncryptedKey2);
PayloadCodec encryptedKey2Encryption =
new AesGcmCodec(SampleConfig.ENCRYPTED_KEY_2_ID, encryptedKey2);
// ChainCodec encodes last to first: compress, then encrypt.
PayloadCodec compressedEncrypted =
new ChainCodec(List.of(new AesGcmCodec(SampleConfig.KEY_A_ID, keyA), new ZlibCodec()));
PayloadCodec encrypted = new AesGcmCodec(SampleConfig.KEY_B_ID, keyB);
Map<String, PayloadCodec> nexusEndpointCodecs =
Map.of(
SampleConfig.COMPRESSED_ENCRYPTED_1_ENDPOINT,
new ChainCodec(List.of(compressedEncryptedKey1Encryption, new ZlibCodec())),
SampleConfig.ENCRYPTED_1_ENDPOINT,
encryptedKey1Encryption,
SampleConfig.COMPRESSED_ENCRYPTED_2_ENDPOINT,
new ChainCodec(List.of(compressedEncryptedKey2Encryption, new ZlibCodec())),
SampleConfig.ENCRYPTED_2_ENDPOINT,
encryptedKey2Encryption);
// Ordinary caller workflow payloads use a separate key from Nexus payloads.
PayloadCodec callerWorkflowEncryption =
new AesGcmCodec(SampleConfig.CALLER_WORKFLOW_KEY_ID, callerWorkflowKey);
return new CodecDataConverter(
DefaultDataConverter.newDefaultInstance(),
List.of(
new NexusCodec(
Map.of(
SampleConfig.COMPRESSED_ENCRYPTED_ENDPOINT,
compressedEncrypted,
SampleConfig.ENCRYPTED_ENDPOINT,
encrypted),
new AesGcmCodec(SampleConfig.KEY_C_ID, keyC))));
List.of(new NexusCodec(nexusEndpointCodecs, callerWorkflowEncryption)));
}
}
Loading
Loading