Cross-Namespace Nexus Demo

This repository is a small public Temporal Python application that proves a Nexus call from a Workflow in one Temporal Cloud namespace to a handler in a second namespace. It is both a reusable example and the application payload for the tmprl-demo.cloud registry operator's Nexus rollout canary.

The design follows Temporal's hello_nexus sample, but adds the runtime contract needed for a containerized, environment-driven, WorkerDeployment-gated deployment.

Architecture

One image supports two roles selected by WORKER_ROLE:

• caller connects to the primary namespace, participates in Worker Versioning, and registers NexusE2ECanaryWorkflow.
• handler connects to an additional namespace and registers a workflow-backed Nexus service operation on nexus-handler.

The caller Workflow generates a replay-safe nonce and sends it through the configured Nexus Endpoint. The handler starts NexusCanaryHandlerWorkflow in the handler namespace and returns the nonce, a known response, and the namespace observed by that Workflow. The caller fails unless all values match.

When NexusE2ECanaryWorkflow is configured as a WorkerDeployment rollout gate, the target caller version cannot become current until the handler worker, cross-namespace endpoint routing, caller allowlist, and asynchronous Nexus callback path all work.

Configuration

Both roles read the standard environment injected by the demo registry:

Variable	Required	Meaning
WORKER_ROLE	yes	caller or handler
TEMPORAL_ADDRESS	yes	Temporal gRPC address
TEMPORAL_NAMESPACE	yes	Namespace for this worker
TEMPORAL_API_KEY	Cloud	API key for the namespace
TEMPORAL_TLS	no	Boolean; defaults to true when an API key is present
TEMPORAL_TASK_QUEUE	yes	Task queue polled by this role
NEXUS_ENDPOINT	caller	Account-wide Nexus Endpoint name
TEMPORAL_DEPLOYMENT_NAME	caller	Worker Deployment name
TEMPORAL_WORKER_BUILD_ID	caller	Worker Deployment build ID

The rollout gate input is a JSON object with this shape:

{
  "endpoint": "operator-canary-nexus-<unique-suffix>",
  "expectedResponse": "nexus-e2e-ok",
  "scheduleToStartSeconds": 300,
  "scheduleToCloseSeconds": 600,
  "timeoutSeconds": 600
}

timeoutSeconds is accepted because the registry operator uses it when sizing its wait for the nested WorkerDeployment rollout. The Nexus call itself uses the schedule-to-start and schedule-to-close values.

Development

uv sync --extra dev
uv run pytest
uv run ruff check .

Build the same image used by both roles:

docker build -t demo-nexus-cross-namespace .

The platform owns creation of the two Cloud namespaces, their credentials, and the Nexus Endpoint. For local manual use, create equivalent caller and handler namespaces plus an endpoint targeting the handler task queue before starting the two worker roles.