From bffd2f533d799c666124c893d52482413f120296 Mon Sep 17 00:00:00 2001 From: Phil Prasek Date: Sun, 1 Mar 2026 01:11:39 -0800 Subject: [PATCH 1/2] nexus docs update Signed-off-by: Phil Prasek --- docs/cloud/get-started/namespaces.mdx | 4 +- docs/cloud/nexus/index.mdx | 48 +-- docs/cloud/nexus/latency-availability.mdx | 38 +-- docs/cloud/nexus/limits.mdx | 42 +-- docs/cloud/nexus/observability.mdx | 22 +- docs/cloud/nexus/pricing.mdx | 16 +- docs/cloud/nexus/security.mdx | 51 +-- docs/develop/dotnet/temporal-nexus.mdx | 51 ++- docs/develop/go/temporal-nexus.mdx | 29 +- docs/develop/java/temporal-nexus.mdx | 34 +- docs/develop/plugins-guide.mdx | 2 +- docs/develop/python/temporal-nexus.mdx | 19 +- docs/develop/typescript/temporal-nexus.mdx | 33 +- docs/encyclopedia/nexus-endpoints.mdx | 31 +- docs/encyclopedia/nexus-error-handling.mdx | 33 +- .../nexus-execution-debugging.mdx | 48 +-- docs/encyclopedia/nexus-metrics.mdx | 1 + docs/encyclopedia/nexus-operations.mdx | 291 +++++++----------- docs/encyclopedia/nexus-patterns.mdx | 73 +++++ docs/encyclopedia/nexus-registry.mdx | 70 ++--- docs/encyclopedia/nexus-security.mdx | 73 +++-- docs/encyclopedia/nexus-services.mdx | 52 +--- docs/encyclopedia/nexus-use-cases.mdx | 76 ----- docs/encyclopedia/nexus.mdx | 106 ++++--- .../temporal-nexus.mdx | 148 +++------ docs/glossary.md | 3 +- .../self-hosted-guide/temporal-nexus.mdx | 36 +-- sidebars.js | 8 +- static/diagrams/nexusadoptiondark.svg | 164 ++++++++++ static/diagrams/nexusadoptionlight.svg | 164 ++++++++++ 30 files changed, 937 insertions(+), 829 deletions(-) create mode 100644 docs/encyclopedia/nexus-patterns.mdx delete mode 100644 docs/encyclopedia/nexus-use-cases.mdx create mode 100644 static/diagrams/nexusadoptiondark.svg create mode 100644 static/diagrams/nexusadoptionlight.svg diff --git a/docs/cloud/get-started/namespaces.mdx b/docs/cloud/get-started/namespaces.mdx index 537aabec9a..42ae532069 100644 --- a/docs/cloud/get-started/namespaces.mdx +++ b/docs/cloud/get-started/namespaces.mdx @@ -264,8 +264,8 @@ Namespace configuration requires some consideration. Following are some general - Environments such as production and development usually have requirements for isolation. We recommend that each environment has its own Namespace. - Namespaces should be used to reduce the "blast radius" for mission-critical applications. -- Workflows that need to communicate with each other should (for now) be in the same Namespace. -- If you need to share Namespaces across team or domain boundaries, be sure to ensure the uniqueness of Workflow Ids. +- Use [Nexus](/nexus) to communicate across team, domain, and Namespace boundaries with a clean service contract instead of sharing Temporal primitives directly. + Nexus enables each team to have their own Namespace for improved security, troubleshooting, and fault isolation while sharing capabilities through Nexus Endpoints. ### Examples diff --git a/docs/cloud/nexus/index.mdx b/docs/cloud/nexus/index.mdx index 9225092f64..ea5320a088 100644 --- a/docs/cloud/nexus/index.mdx +++ b/docs/cloud/nexus/index.mdx @@ -2,7 +2,7 @@ id: index slug: /cloud/nexus title: Nexus -description: Discover Temporal Nexus, a powerful feature for connecting durable executions across team, namespace, region, and cloud boundaries. Nexus also enables each team to have their own namespace for improved security, troubleshooting, and blast radius isolation. +description: Temporal Cloud adds global Nexus Registry, built-in access controls, audit logging, and multi-region connectivity on top of core Nexus. sidebar_label: Temporal Nexus keywords: - Temporal Nexus @@ -32,48 +32,20 @@ Learn why you should use Nexus in the [evaluation guide](/evaluate/nexus). ::: -[Temporal Nexus](/nexus) allows you to connect Temporal Applications across (and within) isolated Namespaces. -This provides all the benefits of Durable Execution across team and application boundaries with improved modularity, security, debugging, and fault isolation. -Nexus supports cross-team, cross-domain, cross-namespace, multi-region, and multi-cloud use cases. +Temporal Cloud builds on the [core Nexus experience](/nexus) with: + +- **Global [Nexus Registry](/nexus/registry)** - Scoped to your entire Account across all Namespaces. Workers in any Namespace can host Nexus Services for others to use. +- **Built-in [access controls](/nexus/registry#configure-runtime-access-controls)** - Restrict which caller Namespaces can use a Nexus Endpoint at runtime. +- **[Audit logging](/cloud/audit-logs)** - Stream Nexus Registry actions (create, update, delete Endpoints) to your audit log integration. +- **Multi-region connectivity** - Nexus requests route across Namespaces within and across AWS and GCP using a global mTLS-secured Envoy mesh. Compatible with [Multi-region Namespaces](/cloud/multi-region) as Endpoint targets. +- **[Terraform support](/cloud/terraform-provider#manage-temporal-cloud-nexus-endpoints-with-terraform)** - Manage Nexus Endpoints with the Temporal Cloud Terraform provider. -Temporal Cloud support is built on top of the [core Nexus experience](/nexus) and adds a global Nexus Registry within an Account, enhanced security, and multi-region connectivity within and across AWS and GCP. - -:::tip RELATED - -- [Evaluate](/evaluate/nexus) why you should use Nexus and learn more about [Nexus use cases](/evaluate/nexus#use-cases). -- [Learn Nexus concepts](/nexus) in the Encyclopedia. - -::: - -## Global Nexus Registry - -The Nexus Registry in Temporal Cloud is scoped to an Account. -Workers in any Namespace can host Nexus Services for others to use within an Account. - -## Built-in access controls - -Temporal Cloud has built-in Endpoint access controls to restrict which callers can use a Nexus Endpoint. - -## Audit logging - -Temporal Cloud supports audit log streaming for Nexus Registry actions to create, update, or delete Endpoints. - -## Multi-region connectivity - -Nexus requests in Temporal Cloud are routed across Namespaces, within and across AWS and GCP, using a global mTLS-secured Envoy mesh. -Built-in Nexus Machinery provides reliable at-least-once execution and Workflow policy can deduplicate requests for exactly-once execution, even across multi-region boundaries. - -## Terraform support - -The [Terraform provider for Temporal Cloud](/cloud/terraform-provider#manage-temporal-cloud-nexus-endpoints-with-terraform) supports managing Nexus Endpoints. - ## Learn more -- [Evaluate](/evaluate/nexus) why you should use Nexus and watch the [Nexus keynote and demo](https://youtu.be/qqc2vsv1mrU?feature=shared&t=2082). -- [Learn key Nexus concepts](/nexus) and how Nexus works in the [Nexus deep dive talk](https://www.youtube.com/watch?v=izR9dQ_eIe4&t=934s) -- Explore [additional resources](/evaluate/nexus#learn-more) to learn more about Nexus. +- [Evaluate Nexus](/evaluate/nexus) | [Keynote and demo](https://youtu.be/qqc2vsv1mrU?feature=shared&t=2082) +- [How Nexus works](/nexus) | [Deep dive talk](https://www.youtube.com/watch?v=izR9dQ_eIe4&t=934s) diff --git a/docs/cloud/nexus/latency-availability.mdx b/docs/cloud/nexus/latency-availability.mdx index 3a4ffee8ac..929ed7d50d 100644 --- a/docs/cloud/nexus/latency-availability.mdx +++ b/docs/cloud/nexus/latency-availability.mdx @@ -20,8 +20,6 @@ keywords: - service level agreement --- -import { CaptionedImage } from '@site/src/components'; - :::tip SUPPORT, STABILITY, and DEPENDENCY INFO Temporal Nexus is now [Generally Available](/evaluate/development-production-features/release-stages#general-availability). @@ -29,36 +27,8 @@ Learn why you should use Nexus in the [evaluation guide](/evaluate/nexus). ::: -Nexus requests (commands, polling) have the same latency SLOs and error rate SLAs as other Worker requests in both the caller and handler Namespaces. - -## Latency metrics - -Nexus supports various [latency metrics](/nexus/metrics). - -## Worker to Temporal Cloud interactions - -Nexus interactions between a Worker and Temporal Cloud use the Worker's Namespace gRPC endpoint. -Nexus-related Worker interactions with Temporal Cloud have the same [latency SLOs](/cloud/service-availability#latency) and [availability SLAs](/cloud/sla) as other calls to a Namespaces's gRPC endpoint. - - - -This applies to the following Nexus-related interactions between a Worker and Temporal Cloud: - -- Caller Namespace - - RespondWorkflowTaskCompleted \- schedule a Nexus Operation. -- Handler Namespace - - PollNexusTaskQueue \- get a [Nexus Task](/tasks#nexus-task) to process, for example to start a Nexus Operation. - - RespondNexusTaskCompleted \- report the Nexus Task was successful. - - RespondNexusTaskFailed \- report the Nexus Task failed. - -## Nexus connectivity across Namespaces - -Nexus connectivity in Temporal Cloud is provided by a global mTLS secured Envoy mesh. -The cross-namespace latency between the caller's Nexus Machinery and the handler's Nexus Machinery varies based on the locality of the caller and handler Namespaces, which may be placed in different regions. +Nexus latency and availability in Temporal Cloud: -Communication between Namespaces in the same region will have lower latency. -Communication across different regions will have higher latency. -Consult the cross-region latency tables for your cloud provider(s) to estimate the latency for Nexus communication across Namespaces in Temporal Cloud. +- **SLOs and SLAs** - Nexus requests have the same [latency SLOs](/cloud/service-availability#latency) and [availability SLAs](/cloud/sla) as other Worker requests in both caller and handler Namespaces. +- **[Nexus metrics](/nexus/metrics)** - SDK and Cloud latency metrics for monitoring Nexus performance. +- **Cross-Namespace connectivity** - Traffic routes through a global mTLS-secured Envoy mesh. Same-region Namespaces have low latency; cross-region latency varies by provider. See [secure connectivity](/nexus/security#secure-connectivity). diff --git a/docs/cloud/nexus/limits.mdx b/docs/cloud/nexus/limits.mdx index 1da47bda8d..b569dadca6 100644 --- a/docs/cloud/nexus/limits.mdx +++ b/docs/cloud/nexus/limits.mdx @@ -25,37 +25,11 @@ Learn why you should use Nexus in the [evaluation guide](/evaluate/nexus). ::: -Temporal Cloud has default limits for several aspects of Nexus. -Many of these defaults are configurable, so if you need them changed please open a support ticket. - -## Rate Limiting - -Nexus requests (commands, polling) are counted as part of the overall [Namespace rate limit](/cloud/limits#requests-per-second) in both the caller and handler Namespaces. - -## Operational Limits - -Nexus has operational limits for thing like the maximum number of Nexus Endpoints and the maximum request handler timeout. - -### Max Nexus Endpoints - -By default, each account is provisioned with a max of 100 Nexus Endpoints. -You can request further increases beyond the initial 100 Endpoint limit by opening a support ticket. - -### Workflow Max Nexus Operations - -A single Workflow Execution can have a maximum of 30 in-flight Nexus Operations. - -See the Nexus Encyclopedia entry for [additional details](/workflow-execution/limits#workflow-execution-nexus-operation-limits). - -### Nexus Request Handler Timeout - -Nexus Operation handlers have less than 10 seconds to process a single Nexus start or cancel request. -Handlers should observe the context deadline and ensure they do not exceed it. -This includes fully processing a synchronous Nexus operation and starting an asynchronous Nexus operation, for example one that starts a Workflow. -If a handler doesn’t respond within a context deadline, a context deadline exceeded error will be tracked in the caller Workflow’s pending Nexus operations, and the Nexus Machinery will retry the Nexus request with an exponential backoff policy. - -### Nexus Operation Maximum Duration - -Each Nexus Operation has a maximum ScheduleToClose duration of 60 days, which is most applicable to asynchronous Nexus Operations that are completed with an asynchronous callback using a separate Nexus request from the handler back to the caller Namespace. -The 60 day maximum is a limit we will look to increase at some point in the future. -While the caller of a Nexus Operation can configure the ScheduleToClose duration to be shorter than 60 days, the maximum duration can not be extended beyond 60 days and will be capped by the server to 60 days. +Nexus limits are documented in [Temporal Cloud limits](/cloud/limits): + +- [Nexus rate limits](/cloud/limits#nexus-rate-limits) - Nexus requests count toward the Namespace RPS limit. +- [Nexus Endpoint limits](/cloud/limits#nexus-endpoints-limits) - 100 Endpoints per Account (default). +- [Per-Workflow Nexus Operation limits](/cloud/limits#per-workflow-nexus-operation-limits) - 30 in-flight Operations per Workflow. +- [Nexus Operation request timeout](/cloud/limits#nexus-operation-request-timeout) - Less than 10 seconds for a handler to process a start or cancel request. +- [Nexus Operation duration limits](/cloud/limits#nexus-operation-duration-limits) - 60-day maximum ScheduleToClose duration. +- [Per-Workflow callback limits](/cloud/limits#per-workflow-callback-limits) - Governs how many Nexus callers can attach to a handler Workflow. diff --git a/docs/cloud/nexus/observability.mdx b/docs/cloud/nexus/observability.mdx index f6582a068d..7344a60bb7 100644 --- a/docs/cloud/nexus/observability.mdx +++ b/docs/cloud/nexus/observability.mdx @@ -1,7 +1,7 @@ --- id: observability slug: /cloud/nexus/observability -title: Obserability - Temporal Nexus +title: Observability - Temporal Nexus description: Learn about integrated observability in Temporal Nexus including cloud metrics and audit log streaming. sidebar_label: Observability tags: @@ -25,20 +25,8 @@ should use Nexus in the [evaluation guide](/evaluate/nexus). ::: -Nexus provides metrics and audit log streaming, in addition to integrated -[execution debugging](/nexus/execution-debugging). +Nexus observability in Temporal Cloud: -## Metrics - -Nexus provides the following metrics: - -- [SDK metrics](/nexus/metrics#sdk-metrics) \- emitted by a Worker. -- [Cloud metrics](/nexus/metrics#cloud-metrics) \- emitted by Temporal Cloud. - -## Audit Logging - -The following Nexus control plane actions are sent to the [Audit Logging](/cloud/audit-logs) integrations: - -- Create Nexus Endpoint: `CreateNexusEndpoint` -- Update Nexus Endpoint: `UpdateNexusEndpoint` -- Delete Nexus Endpoint: `DeleteNexusEndpoint` +- **[Nexus metrics](/nexus/metrics)** - [SDK metrics](/nexus/metrics#sdk-metrics) emitted by Workers and [Cloud metrics](/nexus/metrics#cloud-metrics) emitted by Temporal Cloud. +- **[Execution debugging](/nexus/execution-debugging)** - Bi-directional linking, pending Operations, pending callbacks, and tracing across Namespaces. +- **[Audit logging](/cloud/audit-logs)** - `CreateNexusEndpoint`, `UpdateNexusEndpoint`, and `DeleteNexusEndpoint` actions streamed to your audit log integration. diff --git a/docs/cloud/nexus/pricing.mdx b/docs/cloud/nexus/pricing.mdx index 1e128b1bdb..1366962d89 100644 --- a/docs/cloud/nexus/pricing.mdx +++ b/docs/cloud/nexus/pricing.mdx @@ -20,18 +20,12 @@ Learn why you should use Nexus in the [evaluation guide](/evaluate/nexus). ::: -The pricing for [Temporal Nexus](/evaluate/nexus) is: +Nexus pricing: - **One Action to start or cancel a Nexus Operation** in the caller Namespace. - The underlying Temporal primitives such as Workflows, Activities, Signals created by a Nexus Operation handler (directly or indirectly) result in the normal Actions for those primitives. - This includes retries for underlying Temporal primitives like Activities. -- **No Action results for handling or retrying the Nexus Operation itself**. - However, while the retry of the Nexus Operation incurs no charge, any billable action initiated by the handler (such as an Activity) will be charged if it fails and is subsequently retried. + Underlying primitives (Workflows, Activities, Signals) created by the handler result in normal Actions, including retries. +- **No Action for handling or retrying the Nexus Operation itself**. + However, billable actions initiated by the handler (such as Activities) are charged if they fail and retry. -See [Pricing](/cloud/pricing) for additional details. +See [Pricing](/cloud/pricing) for details. -## Learn more - -- [Evaluate](/evaluate/nexus) why you should use Nexus and watch the [Nexus keynote and demo](https://youtu.be/qqc2vsv1mrU?feature=shared&t=2082). -- Learn how Nexus works in the [Nexus deep dive talk](https://www.youtube.com/watch?v=izR9dQ_eIe4) and [Encyclopedia](/nexus). -- [Additional resources](/evaluate/nexus#learn-more) to learn more about Nexus. diff --git a/docs/cloud/nexus/security.mdx b/docs/cloud/nexus/security.mdx index 9e8fd67ed5..cfab97c6e3 100644 --- a/docs/cloud/nexus/security.mdx +++ b/docs/cloud/nexus/security.mdx @@ -14,8 +14,6 @@ keywords: - access control --- -import { CaptionedImage } from '@site/src/components'; - :::tip SUPPORT, STABILITY, and DEPENDENCY INFO Temporal Nexus is now [Generally Available](/evaluate/development-production-features/release-stages#general-availability). @@ -23,48 +21,9 @@ Learn why you should use Nexus in the [evaluation guide](/evaluate/nexus). ::: -Temporal Cloud has built-in Nexus security. -It provides secure Nexus connectivity across Namespaces with an mTLS secured Envoy mesh. -Workers authenticate to their Namespace with mTLS client certificates or API keys, as allowed by their Namespace. -Encryption for Nexus payloads is also supported, for example using shared symmetric keys and compatible Data Converters. - -## Registry roles and permissions - -Nexus Endpoints are Account-scoped resources, similar to a Namespace. -The following roles and permissions are required to manage and view Nexus Endpoints in the Nexus Registry: - -- Viewing and browsing the full list of Nexus Endpoints in an Account: - - Read-only role (or higher) -- Managing a Nexus Endpoint (create, update, delete): - - Developer role (or higher) and Namespace Admin permission on the Endpoint’s target Namespace - -## Runtime access controls - -The Nexus Registry allows setting Endpoint access policy on each Endpoint. -This currently includes an allow list of caller Namespaces that can use the Endpoint at runtime. -Endpoint access control policies are enforced at runtime: - -1. Caller's Worker authenticates with their Namespace as they do today with mTLS certificates or API keys. - This establishes the caller's identity and caller Namespace. -2. Caller Workflow executes a Nexus Operation on a Nexus Endpoint. -3. Endpoint access control policy is enforced, checking if the caller Namespace is in the Endpoint allow list. - -See [Runtime Access Controls](/nexus/security#runtime-access-controls) and [Configuring Runtime Access Controls](/nexus/registry#configure-runtime-access-controls) for additional details. - -## Secure connectivity - -Nexus Endpoints are only privately accessible from within a Temporal Cloud and mTLS is used for all Nexus communication, including across cloud cells and regions. -Workers authenticate to their Namespaces through mTLS or an API key as allowed by their Namespace configuration. - - - -See [Nexus Secure Connectivity](/nexus/security#secure-connectivity) for additional details. - -## Payload encryption - -For payload encryption, the DataConverter works the same for a Nexus Operation as it does for other payloads sent between a Worker and Temporal Cloud. +Nexus security in Temporal Cloud: -See [Nexus Payload Encryption & Data Converter](/nexus/security#payload-encryption-data-converter) for additional details. +- **[Runtime access controls](/nexus/security#runtime-access-controls)** - Endpoint allowlists restrict which caller Namespaces can use an Endpoint. See [configuring access controls](/nexus/registry#configure-runtime-access-controls). +- **[Secure connectivity](/nexus/security#secure-connectivity)** - mTLS for all Nexus communication across cells and regions. Endpoints are only accessible within a Temporal Cloud Account. +- **[Payload encryption](/nexus/security#payload-encryption-data-converter)** - Same Data Converter as Workflows and Activities, with three approaches for cross-Namespace encryption. +- **[Registry roles and permissions](/nexus/registry#roles-and-permissions)** - Controls who can view, create, edit, and delete Endpoints. diff --git a/docs/develop/dotnet/temporal-nexus.mdx b/docs/develop/dotnet/temporal-nexus.mdx index f0ea419372..0c6ddc0a0c 100644 --- a/docs/develop/dotnet/temporal-nexus.mdx +++ b/docs/develop/dotnet/temporal-nexus.mdx @@ -65,11 +65,11 @@ The Temporal Web UI should now be accessible at [http://localhost:8233](http://l Before setting up Nexus endpoints, create separate Namespaces for the caller and handler. ``` -temporal operator namespace create --namespace my-target-namespace -temporal operator namespace create --namespace my-caller-namespace +temporal operator namespace create --namespace nexus-simple-handler-namespace +temporal operator namespace create --namespace nexus-simple-caller-namespace ``` -`my-target-namespace` will contain the Nexus Operation handler, and we will use a Workflow in `my-caller-namespace` to call that Operation handler. +`nexus-simple-handler-namespace` will contain the Nexus Operation handler, and we will use a Workflow in `nexus-simple-caller-namespace` to call that Operation handler. We use different namespaces to demonstrate cross-Namespace Nexus calls. ## Create a Nexus Endpoint to route requests from caller to handler {#create-nexus-endpoint} @@ -78,9 +78,9 @@ After establishing caller and handler Namespaces, the next step is to create a N ``` temporal operator nexus endpoint create \ - --name my-nexus-endpoint-name \ - --target-namespace my-target-namespace \ - --target-task-queue my-handler-task-queue + --name nexus-simple-endpoint \ + --target-namespace nexus-simple-handler-namespace \ + --target-task-queue nexus-simple-handler-sample ``` You can also use the Web UI to create the Namespaces and Nexus endpoint. @@ -134,7 +134,8 @@ public interface IHelloService Nexus Operation handlers are typically defined in the same Worker as the underlying Temporal primitives they abstract. Operation handlers can decide if a given Nexus Operation will be synchronous or asynchronous. -They can execute arbitrary code, and invoke underlying Temporal primitives such as a Workflow, Query, Signal, or Update. +They can invoke underlying Temporal primitives such as a Query, Signal, or Update using the Temporal SDK Client, or run other reliable code. +Handlers should be reliable since the [circuit breaker](/nexus/operations#circuit-breaking) trips after 5 consecutive retryable errors, blocking all Operations from the caller to that Endpoint. The `Temporalio.Nexus` namespace has utilities to help create Nexus Operations: @@ -147,8 +148,8 @@ This example starts with a sync Operation handler example using the `OperationHa ### Develop a Synchronous Nexus Operation handler The `OperationHandler.Sync` method is for exposing simple RPC handlers. -Its handler function can access an SDK client that can be used for signaling, querying, and listing Workflows. -However, implementations are free to make arbitrary calls to other services or databases, or perform computations such as this one: +Use `NexusOperationExecutionContext.Current.TemporalClient` to get the Temporal Client for signaling, querying, and listing Workflows. +Implementations can also make other calls, but handlers should be reliable to avoid tripping the [circuit breaker](/nexus/operations#circuit-breaking). [NexusSimple/Handler/HelloService.cs](https://github.com/temporalio/samples-dotnet/blob/main/src/NexusSimple/Handler/HelloService.cs) ```csharp @@ -167,6 +168,30 @@ public class HelloService } ``` +### Use the Temporal Client for Signals, Queries, and Updates + +A common pattern is to use the Temporal Client from within a sync handler to Signal, Query, or Update a Workflow. +You can also use Signal-With-Start or Update-With-Start to atomically start a Workflow and send it a Signal or Update. +All calls must complete within the [Nexus request timeout](/cloud/limits#nexus-operation-request-timeout). Updates should be short-lived to stay within this deadline. + +Use `NexusOperationExecutionContext.Current.TemporalClient` to get the Client that the Worker was initialized with: + +```csharp +[NexusOperationHandler] +public IOperationHandler SignalWorkflow() => + OperationHandler.Sync( + async (ctx, input) => + { + var client = NexusOperationExecutionContext.Current.TemporalClient; + var handle = client.GetWorkflowHandle(input.WorkflowId); + // Signal a Workflow + await handle.SignalAsync("MySignal", new[] { input.Value }); + // Query a Workflow + var result = await handle.QueryAsync("MyQuery"); + return new(result); + }); +``` + ### Develop an Asynchronous Nexus Operation handler to start a Workflow Use the `WorkflowRunOperationHandler.FromHandleFactory` method, which is the easiest way to expose a Workflow as an operation. @@ -444,10 +469,10 @@ To create a Nexus Endpoint you must have a Developer account role or higher, and ``` tcld nexus endpoint create \ - --name \ - --target-task-queue my-handler-task-queue \ - --target-namespace \ - --allow-namespace \ + --name nexus-simple-endpoint \ + --target-task-queue nexus-simple-handler-sample \ + --target-namespace \ + --allow-namespace \ --description-file endpoint_description.md ``` diff --git a/docs/develop/go/temporal-nexus.mdx b/docs/develop/go/temporal-nexus.mdx index b388ea6602..a28874e8f5 100644 --- a/docs/develop/go/temporal-nexus.mdx +++ b/docs/develop/go/temporal-nexus.mdx @@ -120,7 +120,8 @@ type EchoOutput EchoInput Nexus Operation handlers are typically defined in the same Worker as the underlying Temporal primitives they abstract. Operation handlers can decide if a given Nexus Operation will be synchronous or asynchronous. -They can execute arbitrary code, and invoke underlying Temporal primitives such as a Workflow, Query, Signal, or Update. +They can invoke underlying Temporal primitives such as a Query, Signal, or Update using the Temporal SDK Client, or run other reliable code. +Handlers should be reliable since the [circuit breaker](/nexus/operations#circuit-breaking) trips after 5 consecutive retryable errors, blocking all Operations from the caller to that Endpoint. The `temporalnexus` package has builders to create Nexus Operations and other helpers for authoring Operation handlers: @@ -133,8 +134,8 @@ This tutorial starts with a sync Operation handler example using the `nexus.NewS ### Develop a Synchronous Nexus Operation handler The `nexus.NewSyncOperation` builder function is for exposing simple RPC handlers. -Typically to use SDK client, which is obtained via `temporalnexus.GetClient(ctx)`, for signaling, querying, and listing Workflows. -However, implementations are free to make arbitrary calls to other services or databases, or perform computations such as this one: +Use `temporalnexus.GetClient(ctx)` to get the Temporal Client for signaling, querying, and listing Workflows. +Implementations can also make other calls, but handlers should be reliable to avoid tripping the [circuit breaker](/nexus/operations#circuit-breaking). [nexus/handler/app.go](https://github.com/temporalio/samples-go/blob/main/nexus/handler/app.go) @@ -165,6 +166,28 @@ var EchoOperation = nexus.NewSyncOperation(service.EchoOperationName, func(ctx c ``` +### Use the Temporal Client for Signals, Queries, and Updates + +A common pattern is to use the Temporal Client from within a sync handler to Signal, Query, or Update a Workflow. +You can also use Signal-With-Start or Update-With-Start to atomically start a Workflow and send it a Signal or Update. +All calls must complete within the [Nexus request timeout](/cloud/limits#nexus-operation-request-timeout). Updates should be short-lived to stay within this deadline. + +Use `temporalnexus.GetClient(ctx)` to get the Client that the Worker was initialized with: + +```go +var MyOperation = nexus.NewSyncOperation("my-operation", func(ctx context.Context, input MyInput, options nexus.StartOperationOptions) (MyOutput, error) { + c, err := temporalnexus.GetClient(ctx) + if err != nil { + return MyOutput{}, nexus.HandlerErrorf(nexus.HandlerErrorTypeInternal, "failed to get client: %v", err) + } + // Signal a Workflow + err = c.SignalWorkflow(ctx, input.WorkflowID, "", "my-signal", input.Value) + // Query a Workflow + val, err := c.QueryWorkflow(ctx, input.WorkflowID, "", "my-query") + // ... +}) +``` + ### Develop an Asynchronous Nexus Operation handler to start a Workflow Use the `NewWorkflowRunOperation` constructor, which is the easiest way to expose a Workflow as an operation. diff --git a/docs/develop/java/temporal-nexus.mdx b/docs/develop/java/temporal-nexus.mdx index 3d883cdd95..e1878bab57 100644 --- a/docs/develop/java/temporal-nexus.mdx +++ b/docs/develop/java/temporal-nexus.mdx @@ -185,7 +185,8 @@ public interface NexusService { Nexus Operation handlers are typically defined in the same Worker as the underlying Temporal primitives they abstract. Operation handlers can decide if a given Nexus Operation will be synchronous or asynchronous. -They can execute arbitrary code, and invoke underlying Temporal primitives such as a Workflow, Query, Signal, or Update. +They can invoke underlying Temporal primitives such as a Query, Signal, or Update using the Temporal SDK Client, or run other reliable code. +Handlers should be reliable since the [circuit breaker](/nexus/operations#circuit-breaking) trips after 5 consecutive retryable errors, blocking all Operations from the caller to that Endpoint. The `io.temporal.nexus.*` packages have utilities to help create Nexus Operations: @@ -198,8 +199,8 @@ This example starts with a sync Operation handler example using the `OperationHa ### Develop a Synchronous Nexus Operation handler The `OperationHandler.sync` method is for exposing simple RPC handlers. -Its handler function can access an SDK client that can be used for signaling, querying, and listing Workflows. -However, implementations are free to make arbitrary calls to other services or databases, or perform computations such as this one: +Use `Nexus.getOperationContext().getWorkflowClient(ctx)` to get the Temporal Client for signaling, querying, and listing Workflows. +Implementations can also make other calls, but handlers should be reliable to avoid tripping the [circuit breaker](/nexus/operations#circuit-breaking). {/* SNIPSTART samples-java-nexus-handler {"selectedLines": ["1-16", "43"]} */} [core/src/main/java/io/temporal/samples/nexus/handler/NexusServiceImpl.java](https://github.com/temporalio/samples-java/blob/nexus-snip-sync/core/src/main/java/io/temporal/samples/nexus/handler/NexusServiceImpl.java) @@ -225,6 +226,31 @@ public class NexusServiceImpl { ``` {/* SNIPEND */} +### Use the Temporal Client for Signals, Queries, and Updates + +A common pattern is to use the Temporal Client from within a sync handler to Signal, Query, or Update a Workflow. +You can also use Signal-With-Start or Update-With-Start to atomically start a Workflow and send it a Signal or Update. +All calls must complete within the [Nexus request timeout](/cloud/limits#nexus-operation-request-timeout). Updates should be short-lived to stay within this deadline. + +Use `Nexus.getOperationContext().getWorkflowClient(ctx)` to get the Client that the Worker was initialized with: + +```java +@OperationImpl +public OperationHandler signalWorkflow() { + return OperationHandler.sync( + (ctx, details, input) -> { + WorkflowClient client = Nexus.getOperationContext().getWorkflowClient(ctx); + // Signal a Workflow + client.newWorkflowStub(MyWorkflow.class, input.getWorkflowId()) + .mySignal(input.getValue()); + // Query a Workflow + String result = client.newWorkflowStub(MyWorkflow.class, input.getWorkflowId()) + .myQuery(); + return new SignalOutput(result); + }); +} +``` + ### Develop an Asynchronous Nexus Operation handler to start a Workflow Use the `WorkflowRunOperation.fromWorkflowMethod` method, which is the easiest way to expose a Workflow as an operation. @@ -590,7 +616,7 @@ See the [Nexus cancelation sample](https://github.com/temporalio/samples-java/tr ## Make Nexus calls across Namespaces in Temporal Cloud {#nexus-calls-across-namespaces-temporal-cloud} This section assumes you are already familiar with [how connect a Worker to Temporal Cloud](https://docs.temporal.io/develop/java/core-application#run-a-temporal-cloud-worker). -The same [source code](https://github.com/temporalio/samples-go/tree/main/nexus) is used in this section, but the `tcld` CLI will be used to create Namespaces and the Nexus Endpoint, and mTLS client certificates will be used to securely connect the caller and handler Workers to their respective Temporal Cloud Namespaces. +The same [source code](https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/nexus) is used in this section, but the `tcld` CLI will be used to create Namespaces and the Nexus Endpoint, and mTLS client certificates will be used to securely connect the caller and handler Workers to their respective Temporal Cloud Namespaces. ### Install the latest `tcld` CLI and generate certificates diff --git a/docs/develop/plugins-guide.mdx b/docs/develop/plugins-guide.mdx index 0f51224a81..1f79e31668 100644 --- a/docs/develop/plugins-guide.mdx +++ b/docs/develop/plugins-guide.mdx @@ -152,7 +152,7 @@ async with Worker( ### Built-in Nexus Operations -Nexus calls are used from Workflows similar to Activities and you can check out some common [Nexus Use Cases](/nexus/use-cases). Like Activities, Nexus Call arguments and return values must be serializable. +Nexus calls are used from Workflows similar to Activities and you can learn more about [Temporal Nexus](/nexus). Like Activities, Nexus Call arguments and return values must be serializable. Here's an example of how to register Nexus handlers in Workflows with Python: diff --git a/docs/develop/python/temporal-nexus.mdx b/docs/develop/python/temporal-nexus.mdx index 289c2b852f..d774c6e4fa 100644 --- a/docs/develop/python/temporal-nexus.mdx +++ b/docs/develop/python/temporal-nexus.mdx @@ -129,7 +129,8 @@ class MyNexusService: Nexus Operation handlers are typically defined in the same Worker as the underlying Temporal primitives they abstract. Operation handlers can decide if a given Nexus Operation will be synchronous or asynchronous. -They can execute arbitrary code, and invoke underlying Temporal primitives such as a Workflow, Query, Signal, or Update. +They can invoke underlying Temporal primitives such as a Query, Signal, or Update using the Temporal SDK Client, or run other reliable code. +Handlers should be reliable since the [circuit breaker](/nexus/operations#circuit-breaking) trips after 5 consecutive retryable errors, blocking all Operations from the caller to that Endpoint. The `nexusrpc.handler` and `temporalio.nexus` modules have utilities to help create Nexus Operations: @@ -156,12 +157,18 @@ class MyNexusServiceHandler: A synchronous operation handler must return quickly (less than `10s`). -In addition to performing simple CPU-bound computations such as the one above, implementations are free to make arbitrary calls to other services or databases. -The handler function can access an SDK client that can be used to execute Signals, Updates, or Queries against a Workflow, or to do other client operations such as listing Workflows. -The [nexus_sync_operations](https://github.com/temporalio/samples-python/blob/main/nexus_sync_operations) sample shows how to create a Nexus Service uses synchronous operations to send Updates and Queries: +Implementations can also make other calls, but handlers should be reliable to avoid tripping the [circuit breaker](/nexus/operations#circuit-breaking). -[nexus_sync_operations/handler/service_handler.py](https://github.com/temporalio/samples-python/blob/main/nexus_sync_operations/handler/service_handler.py) +### Use the Temporal Client for Signals, Queries, and Updates + +A common pattern is to use the Temporal Client from within a sync handler to Signal, Query, or Update a Workflow. +You can also use Signal-With-Start or Update-With-Start to atomically start a Workflow and send it a Signal or Update. +All calls must complete within the [Nexus request timeout](/cloud/limits#nexus-operation-request-timeout). Updates should be short-lived to stay within this deadline. +Use `nexus.client()` to get the Client that the Worker was initialized with. +The [nexus_sync_operations](https://github.com/temporalio/samples-python/blob/main/nexus_sync_operations) sample shows how to create a Nexus Service that uses synchronous operations to send Updates and Queries: + +[nexus_sync_operations/handler/service_handler.py](https://github.com/temporalio/samples-python/blob/main/nexus_sync_operations/handler/service_handler.py) ```python from temporalio import nexus @@ -295,7 +302,7 @@ class CallerWorkflow: ) # Alternatively, you can use start_operation to obtain the operation handle and # then `await` the handle to obtain the result. - sync_operation_handle = await self.nexus_client.start_operation( + sync_operation_handle = await nexus_client.start_operation( MyNexusService.my_sync_operation, MyInput(name), ) diff --git a/docs/develop/typescript/temporal-nexus.mdx b/docs/develop/typescript/temporal-nexus.mdx index ec264e4a09..950be0bb40 100644 --- a/docs/develop/typescript/temporal-nexus.mdx +++ b/docs/develop/typescript/temporal-nexus.mdx @@ -147,7 +147,8 @@ A Nexus Service handler is defined using the `nexus-rpc`'s [`serviceHandler`](ht Nexus Service handlers are typically defined in the same Worker as the underlying Temporal primitives they abstract. A Service handler must provide Operation handlers for each Operation declared by the Service. {/* Added */} Operation handlers can decide if a given Nexus Operation will be synchronous or asynchronous. -They can execute arbitrary code, and invoke underlying Temporal primitives such as a Workflow, Query, Signal, or Update. +They can invoke underlying Temporal primitives such as a Query, Signal, or Update using the Temporal SDK Client, or run other reliable code. +Handlers should be reliable since the [circuit breaker](/nexus/operations#circuit-breaking) trips after 5 consecutive retryable errors, blocking all Operations from the caller to that Endpoint. The `@temporalio/nexus` package provides utilities to help create Nexus Operations that interracts with a Temporal namespace: {/* Extended */} @@ -158,8 +159,8 @@ The `@temporalio/nexus` package provides utilities to help create Nexus Operatio ### Develop a Synchronous Nexus Operation handler Simple RPC handlers can be implemented as synchronous Nexus Operation handlers, which is defined in TypeScript as a simple async function. {/* sync operation vs async func is very confusing in this context */} -The handler function can obtain a Temporal Client, using `getClient()`, which can be used for signaling, querying, and listing Workflows. -However, implementations are free to make arbitrary calls to other services or databases, or perform computations such as this one: +Use `getClient()` from `@temporalio/nexus` to get the Temporal Client for signaling, querying, and listing Workflows. +Implementations can also make other calls, but handlers should be reliable to avoid tripping the [circuit breaker](/nexus/operations#circuit-breaking). [nexus-hello/src/service/handler.ts](https://github.com/temporalio/samples-typescript/blob/main/nexus-hello/src/service/handler.ts) @@ -186,6 +187,30 @@ export const helloServiceHandler = nexus.serviceHandler(helloService, { ``` +### Use the Temporal Client for Signals, Queries, and Updates + +A common pattern is to use the Temporal Client from within a sync handler to Signal, Query, or Update a Workflow. +You can also use Signal-With-Start or Update-With-Start to atomically start a Workflow and send it a Signal or Update. +All calls must complete within the [Nexus request timeout](/cloud/limits#nexus-operation-request-timeout). Updates should be short-lived to stay within this deadline. + +Use `getClient()` from `@temporalio/nexus` to get the Client connected to the same Namespace as the Worker: + +```ts +import { getClient } from '@temporalio/nexus'; + +export const myServiceHandler = nexus.serviceHandler(myService, { + signalWorkflow: async (ctx, input: SignalInput): Promise => { + const client = getClient(); + const handle = client.workflow.getHandle(input.workflowId); + // Signal a Workflow + await handle.signal('mySignal', input.value); + // Query a Workflow + const result = await handle.query('myQuery'); + return { result }; + }, +}); +``` + ### Develop an Asynchronous Nexus Operation handler to start a Workflow Use `@temporalio/nexus`'s `WorkflowRunOperationHandler` helper class to easily expose a Temporal Workflow as a Nexus Operation. @@ -272,7 +297,7 @@ You will need to provide the Nexus Endpoint name, which you registered previousl import * as wf from "@temporalio/workflow"; import { helloService, LanguageCode } from "../service/api"; -const HELLO_SERVICE_ENDPOINT = "hello-service-endpoint-name"; +const HELLO_SERVICE_ENDPOINT = "my-nexus-endpoint-name"; export async function helloCallerWorkflow(name: string, language: LanguageCode): Promise { const nexusClient = wf.createNexusClient({ diff --git a/docs/encyclopedia/nexus-endpoints.mdx b/docs/encyclopedia/nexus-endpoints.mdx index ac9a497f00..573ee1415f 100644 --- a/docs/encyclopedia/nexus-endpoints.mdx +++ b/docs/encyclopedia/nexus-endpoints.mdx @@ -1,7 +1,7 @@ --- id: nexus-endpoints title: Nexus endpoints -sidebar_label: Nexus endpoints +sidebar_label: Nexus Endpoints description: Nexus Endpoints are reverse proxies that connect Nexus callers and handlers forwarding Nexus requests to an upstream target Namespace and Task Queue that a Worker is polling. toc_max_heading_level: 4 slug: /nexus/endpoints @@ -22,30 +22,23 @@ Temporal Nexus is now [Generally Available](/evaluate/development-production-fea ::: -A [Temporal Nexus Endpoint](/glossary#nexus-endpoint) is a reverse proxy that can route Nexus requests from a caller Workflow to an upstream target Namespace and Task Queue. -A [Nexus Service](/nexus/services) runs in a Worker that is polling the Endpoint's target Task Queue. +A [Nexus Endpoint](/glossary#nexus-endpoint) is a fully managed reverse proxy for [Nexus Services](/nexus/services). +It routes requests from a caller Workflow to a target Namespace and Task Queue. +Callers only need to know the Endpoint name - the target Namespace, Task Queue, and internal implementation are encapsulated. -An Endpoint decouples the caller and handler, so the caller only needs to know the Endpoint name. -The Endpoint encapsulates the upstream target Namespace and Task Queue from the caller. -A Worker handles Nexus requests by registering one or more [Nexus Services](/nexus/services) and polling the Endpoint's target Task Queue. +Workers handle Nexus requests by registering one or more Services and polling the Endpoint's target Task Queue. +Multiple Endpoints can target different Task Queues in the same Namespace. - - -Multiple Nexus Endpoints can target different Task Queues in the same target Namespace. +The Endpoint description field supports markdown for documenting available Operations, contact information, or schema links. ## Reverse proxy for Nexus Services, not a general purpose L7 proxy -A [Temporal Nexus Endpoint](/glossary#nexus-endpoint) is a reverse proxy for [Nexus Services](/nexus/services). -It is not a general purpose L7 reverse proxy like NGINX which can route arbitrary HTTP requests to different upstream targets. -A Nexus Endpoint currently supports routing Nexus requests to a single upstream target. -The Temporal Nexus [EndpointSpec](https://github.com/temporalio/api/blob/2a5b3951e71565e28628edea1b3d88d69ed26607/temporal/api/nexus/v1/message.proto#L170) has two [Endpoint target types](https://github.com/temporalio/api/blob/2a5b3951e71565e28628edea1b3d88d69ed26607/temporal/api/nexus/v1/message.proto#L185): +A Nexus Endpoint is not a general-purpose L7 proxy. It routes Nexus requests to a single upstream target. +The [EndpointSpec](https://github.com/temporalio/api/blob/2a5b3951e71565e28628edea1b3d88d69ed26607/temporal/api/nexus/v1/message.proto#L170) supports two [target types](https://github.com/temporalio/api/blob/2a5b3951e71565e28628edea1b3d88d69ed26607/temporal/api/nexus/v1/message.proto#L185): -- Worker: route Nexus requests to a target Namespace and Task Queue. -- External (experimental): route Nexus requests to an external target [Nexus RPC endpoint](https://github.com/nexus-rpc/api/blob/main/SPEC.md) with experimental support in `temporal operator nexus create endpoint` for `--target-url` which may be used with the Nexus Registry in a self-hosted Temporal Service. +- **Worker**: Route to a target Namespace and Task Queue. +- **External** (experimental): Route to an external [Nexus RPC endpoint](https://github.com/nexus-rpc/api/blob/main/SPEC.md) using `--target-url` in `temporal operator nexus create endpoint` (self-hosted only). ## Deploying a Nexus Endpoint -Adding a Nexus Endpoint to the [Nexus Registry](/nexus/registry) deploys the Endpoint in the Temporal Service, so it is available at runtime to serve Nexus requests. +Adding an Endpoint to the [Nexus Registry](/nexus/registry) deploys it immediately. The Endpoint is available at runtime as soon as it's registered. diff --git a/docs/encyclopedia/nexus-error-handling.mdx b/docs/encyclopedia/nexus-error-handling.mdx index 433ca60820..fe90648f81 100644 --- a/docs/encyclopedia/nexus-error-handling.mdx +++ b/docs/encyclopedia/nexus-error-handling.mdx @@ -21,47 +21,34 @@ Temporal Nexus is now [Generally Available](/evaluate/development-production-fea ::: -Nexus Operations can return an error for a caller Workflow to handle. -If an asynchronous Nexus Operation starts a Workflow that returns an error, it will be propagated back to the caller Workflow. +Nexus Operations can return errors for a caller Workflow to handle. +Errors from an asynchronous Operation's underlying Workflow propagate back to the caller. ## Errors in Nexus handlers -In Temporal, a user-defined Nexus handler is primarily responsible for starting a Nexus Operation. -Nexus handlers run in a Temporal Worker and use Temporal SDK builder functions like New-Sync-Operation or New-Workflow-Run-Operation to start an Operation. Nexus handlers may return [different error types](/references/failures#nexus-errors). -Nexus Operations can end up in [completed](/references/events#nexusoperationcompleted), [failed](/references/events#nexusoperationfailed), [canceled](/references/events#nexusoperationcanceled), and [timed out](/references/events#nexusoperationtimedout) states. - -The Nexus Machinery breaks up the [Nexus Operation lifecycle](/nexus/operations#operation-lifecycle) into one or more [Nexus Tasks](/tasks#nexus-task) that a Nexus handler is responsible for processing. -It creates a Nexus Task to start an Operation and may create additional Nexus Tasks, for example to cancel a long-running [asynchronous Operation](/nexus/operations#asynchronous-operation-lifecycle). - -By default, Nexus handler errors are considered retryable, unless specified below: +By default, handler errors are retryable unless they are: - [Application Failures](/references/failures#nexus-errors) marked as non-retryable. -- [Unsuccessful Operation errors](/references/failures#nexus-errors) that can resolve an operation as either failed or canceled. +- [Unsuccessful Operation errors](/references/failures#nexus-errors) that resolve an Operation as failed or canceled. - [Non-retryable Nexus errors](/references/failures#non-retryable-nexus-errors). -For example, if an unknown error is returned from a Nexus handler it will be classified as a retryable error. +When the caller's Nexus Machinery receives an error: -When an error is received by the caller's Nexus Machinery: - -- If a [non-retryable error](/references/failures#non-retryable-nexus-errors) is returned, the caller Workflow will have a [NexusOperationFailed](/references/events#nexusoperationfailed) event added to its Workflow History. -- If a [retryable error](/references/failures#retryable-nexus-errors) is returned, the Nexus Machinery will automatically retry the [Nexus Task](/tasks#nexus-task), as discussed in [automatic retries](/nexus/operations#automatic-retries). - These errors are visible to the caller Workflow as part of integrated execution debugging in [Pending Operations](/nexus/execution-debugging/#pending-operations). +- **Non-retryable** - A [NexusOperationFailed](/references/events#nexusoperationfailed) event is added to the caller's Workflow History. +- **Retryable** - The Nexus Machinery [automatically retries](/nexus/operations#automatic-retries). These errors surface in [Pending Operations](/nexus/execution-debugging/#pending-operations). :::tip -To avoid infinite [automatic retries](/nexus/operations#automatic-retries) and improve semantics, custom Nexus handlers should return a [specific Nexus error type](/references/failures#nexus-errors). - +Return a [specific Nexus error type](/references/failures#nexus-errors) to avoid infinite retries. See [errors in Nexus Operations](/references/failures#errors-in-nexus-operations) for additional details. ::: ## Nexus error handling in caller Workflows -A Nexus Operation Failure is delivered to the Workflow Execution when a Nexus Operation fails. -It contains information about the failure and the Nexus Operation Execution; for example, the Nexus Operation name and -Nexus Operation token. -The reason for the failure is in the message and in the underlying cause is typically an Application Error or a Canceled Error. +When a Nexus Operation fails, the caller receives a Nexus Operation Failure containing the Operation name, token, and failure reason. +The underlying cause is typically an Application Error or Canceled Error. :::tip RESOURCES diff --git a/docs/encyclopedia/nexus-execution-debugging.mdx b/docs/encyclopedia/nexus-execution-debugging.mdx index f5f06bb331..8bc13ead25 100644 --- a/docs/encyclopedia/nexus-execution-debugging.mdx +++ b/docs/encyclopedia/nexus-execution-debugging.mdx @@ -21,21 +21,13 @@ Temporal Nexus is now [Generally Available](/evaluate/development-production-fea ::: -Nexus supports end-to-end execution debugging that may span: -- Caller Workflows -- One or more Nexus Operations executed within and across Namespaces -- Underlying Temporal primitives, like a Workflow, created by a Nexus Operation handler - -This includes [multi-level Nexus calls](/nexus#multi-level-calls), for example: - -- Workflow A → Nexus Operation 1 → Workflow B → Nexus Operation 2 → Workflow C +Nexus supports end-to-end execution debugging across caller Workflows, Nexus Operations, and handler Workflows - even across [multi-level calls](/nexus#multi-level-calls) spanning multiple Namespaces. ## Bi-directional linking -Bi-directional links enable navigation of an end-to-end execution across Namespace boundaries in the Temporal UI. -They are automatically added by the Temporal SDK for builder functions like New-Workflow-Run-Operation. -Links are auto-wired from a specific Nexus Operation event in the caller's Workflow history to a specific event in the handler's Workflow history. +Bidirectional links connect Nexus Operation events in the caller's Workflow History to corresponding events in the handler's Workflow History. +They are automatically wired by SDK builder functions like New-Workflow-Run-Operation, enabling click-through navigation across Namespaces, regions, and clouds in the Temporal UI. -Bi-directional links enable navigating across Namespace boundaries: - -- Forward through the Nexus Operation execution: - - From a Nexus Operation event in the caller's Workflow history. - - To the underlying event in the handler's Workflow. -- Backwards through the Nexus Operation execution: - - From the underlying event in the handler's Workflow. - - To a Nexus Operation event in the caller's Workflow history. +- **Forward**: From a caller's Nexus Operation event to the handler's Workflow. +- **Backward**: From the handler's Workflow back to the caller's Nexus Operation event. ## Pending Operations -Similar to pending Activities, pending Nexus Operations are displayed in the Workflow details page and using: `temporal workflow describe`. +Pending Nexus Operations are displayed in the Workflow details page and with `temporal workflow describe`, similar to pending Activities. -For example, from the Temporal UI: +From the UI: -For example, from the `temporal` CLI: +From the CLI: ``` temporal workflow describe @@ -83,15 +69,15 @@ Pending Nexus Operations: 1 LastAttemptFailure {"message":"handler error (INTERNAL): internal error","applicationFailureInfo":{}} ``` -Retryable Nexus errors [returned from a Nexus handler](/nexus/error-handling#errors-in-nexus-handlers) will surface as part of the Pending Operation in a caller Workflow. -Non-retryable errors will result in the Nexus Operation reaching a final state in the caller Workflow, with a [Failed](/references/events#nexusoperationfailed), [TimedOut](/references/events#nexusoperationtimedout) or [Canceled](/references/events#nexusoperationcanceled) event. +[Retryable errors](/nexus/error-handling#errors-in-nexus-handlers) surface in the Pending Operation. +Non-retryable errors resolve the Operation with a [Failed](/references/events#nexusoperationfailed), [TimedOut](/references/events#nexusoperationtimedout), or [Canceled](/references/events#nexusoperationcanceled) event. ## Pending Callbacks -Nexus callbacks are sent from the handler's Namespace to the caller's Namespace to complete an asynchronous Nexus Operation. -These show up in the UI and using: `temporal workflow describe`. +Nexus completion callbacks are sent from the handler's Namespace to the caller's Namespace for asynchronous Operations. +These appear in the UI and with `temporal workflow describe`. -For example, from the Temporal UI: +From the UI: -For example, from the `temporal` CLI: +From the CLI: ``` temporal workflow describe @@ -115,10 +101,8 @@ Callbacks: 1 ## Tracing -Temporal integrates with tracing libraries like [OpenTelemetry](https://opentelemetry.io/) and [OpenTracing](https://opentracing.io/). -Tracing allows you to visualize the call graph of a Workflow, including its Activities, Nexus Operations, and Child Workflows. -You can enable tracing by installing an interceptor on the Temporal Client or Worker in the supported SDKs. -See the samples linked below to enable tracing for the SDKs: +Temporal integrates with [OpenTelemetry](https://opentelemetry.io/) and [OpenTracing](https://opentracing.io/) to visualize call graphs across Activities, Nexus Operations, and Child Workflows. +Enable tracing by installing an interceptor on the Client or Worker: - [Go SDK](https://github.com/temporalio/samples-go/tree/main/opentelemetry) - [Java SDK](https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/tracing) diff --git a/docs/encyclopedia/nexus-metrics.mdx b/docs/encyclopedia/nexus-metrics.mdx index debf55c4fe..510fa743d7 100644 --- a/docs/encyclopedia/nexus-metrics.mdx +++ b/docs/encyclopedia/nexus-metrics.mdx @@ -23,6 +23,7 @@ Temporal Nexus is now [Generally Available](/evaluate/development-production-fea ::: + Nexus provides SDK metrics, Cloud metrics, and OSS Cluster metrics in addition to integrated [execution debugging](/nexus/execution-debugging). ## SDK Metrics diff --git a/docs/encyclopedia/nexus-operations.mdx b/docs/encyclopedia/nexus-operations.mdx index 4254432c3d..b753fd3f36 100644 --- a/docs/encyclopedia/nexus-operations.mdx +++ b/docs/encyclopedia/nexus-operations.mdx @@ -1,7 +1,7 @@ --- id: nexus-operations title: Nexus operations -sidebar_label: Nexus operations +sidebar_label: Nexus Operations description: Learn about the Nexus Operation lifecycle, execution semantics, and automatic retries for reliable execution. toc_max_heading_level: 4 slug: /nexus/operations @@ -33,67 +33,61 @@ Temporal Nexus is now [Generally Available](/evaluate/development-production-fea ::: -[Nexus Operations](/glossary#nexus-operation) are arbitrary-duration operations that may be synchronous or asynchronous, short-lived or long-lived, and are used to connect Temporal Applications within and across Namespaces, clusters, regions, and clouds. +[Nexus Operations](/glossary#nexus-operation) can be synchronous or asynchronous. Unlike a traditional RPC, an asynchronous Nexus Operation has an operation token that can be used to re-attach to a long-running Operation backed by a Workflow. +An Operation's lifecycle spans scheduling, reliable delivery with retries, handler execution, and result or callback completion. -Unlike a traditional RPC, an asynchronous Nexus Operation has an operation token that can be used to re-attach to a long-lived Nexus Operation, for example, one backed by a Temporal Workflow. -Nexus Operations support a uniform interface to get the status of an operation or its result, receive a completion callback, or cancel the operation – all of which are fully integrated into the Temporal Platform. +## SDK support {#sdk-support} -## SDK support +:::tip SDK GUIDES -The Temporal SDK provides an integrated Temporal experience to build, run, and use Nexus Operations. +- [Go](/develop/go/nexus) | + [Java](/develop/java/nexus) | + [Python](/develop/python/nexus) | + [TypeScript](/develop/typescript/nexus) | + [.NET](/develop/dotnet/nexus) -:::tip RESOURCES +::: -- [Go SDK - Nexus quick start and code sample](/develop/go/nexus) -- [Java SDK - Nexus quick start and code sample](/develop/java/nexus) - ::: +**Caller side:** A caller Workflow executes a Nexus Operation through a [Nexus Endpoint](/nexus/endpoints) using the Temporal SDK. -Caller Workflows use the Temporal SDK to execute Nexus Operations. +**Handler side:** [Nexus Services](/nexus/services) and their Operations are registered with a Worker that polls the Endpoint's target Task Queue. Operations are defined using SDK builder functions: -Nexus Operation handlers are created with Temporal SDK builder functions such as: +- **New-Workflow-Run-Operation** - Start a Workflow as an asynchronous Operation. +- **New-Sync-Operation** - Run a synchronous Operation: invoke a Query, Signal, or Update, or execute other reliable code using the Temporal SDK Client. -- New-Workflow-Run-Operation - - Start a Workflow as an asynchronous Operation. -- New-Sync-Operation - - Invoke an underlying Query or Signal as a synchronous Operation. - - Invoke an Update as a synchronous Operation. - - Execute arbitrary code as a synchronous Operation. ## Nexus Operation lifecycle {#operation-lifecycle} -When you execute a Nexus Operation from a caller Workflow using the Temporal SDK, a command is sent to Temporal to schedule the Nexus Operation which is atomically handed off to the Nexus Machinery. -The [Nexus Machinery](/glossary#nexus-machinery) uses state-machine-based invocation and completion callbacks to ensure [at-least-once](#at-least-once-execution-semantics-and-idempotency) execution of a Nexus Operation and reliable delivery of the result. +When a caller Workflow executes a Nexus Operation, the command is atomically handed off to the [Nexus Machinery](/glossary#nexus-machinery). +The Machinery ensures [at-least-once](#at-least-once-execution-semantics-and-idempotency) execution with [automatic retries](#automatic-retries) and reliable result delivery. -The Nexus Machinery is responsible for making the Nexus RPC calls on behalf of the caller Workflow, with [automatic-retries](#automatic-retries). -This means you don't have to use Nexus RPC directly, only the Temporal SDK along with the Temporal Service. - ### Synchronous Operation lifecycle -Nexus supports synchronous Operations that take less than 10 seconds to execute, as measured from the caller's Nexus Machinery. +Synchronous Operations must complete within the [10-second handler deadline](/cloud/limits#nexus-operation-request-timeout), as measured from the caller's Nexus Machinery. -The lifecycle for a synchronous Nexus Operation, for example to Signal or Query a Workflow: +Lifecycle for a synchronous Operation (for example, to Signal, Query, or Update a Workflow, or run other reliable code): -1. Caller Workflow executes a Nexus Operation using the Temporal SDK. -1. Caller Worker issues a [ScheduleNexusOperation](/references/commands#schedulenexusoperation) command to its Namespace gRPC endpoint. -1. Caller Namespace records a [NexusOperationScheduled](/references/events#nexusoperationscheduled) event in the caller's Workflow History. -1. Caller Nexus Machinery makes a Nexus call to start a Nexus Operation. -1. Handler Nexus Machinery receives the Nexus request and sync matches to a handler Worker. -1. Handler Worker gets a [Nexus Task](/tasks#nexus-task) to start a Nexus Operation, by polling the Nexus Endpoint's target Task Queue. -1. Handler processes the Nexus Task, using the Temporal SDK **New-Sync-Operation**. -1. Handler responds to its Namespace gRPC endpoint with the Operation result. -1. Caller Namespace records the result in the caller's Workflow history as a Nexus event, for example [Completed](/references/events#nexusoperationcompleted) or [Failed](/references/events#nexusoperationfailed). -1. Caller Worker polls for a Workflow Task on its Workflow Task Queue. -1. Caller Workflow gets the Operation result, using the Temporal SDK. +1. Caller Workflow executes a Nexus Operation. +1. Caller Worker issues a [ScheduleNexusOperation](/references/commands#schedulenexusoperation) command. +1. Caller Namespace records a [NexusOperationScheduled](/references/events#nexusoperationscheduled) event. +1. Caller Nexus Machinery sends the start request. +1. Handler Nexus Machinery sync-matches the request to a handler Worker. +1. Handler Worker receives a [Nexus Task](/tasks#nexus-task) by polling the Endpoint's target Task Queue. +1. Handler processes the task using **New-Sync-Operation**. +1. Handler responds with the Operation result. +1. Caller Namespace records a [Completed](/references/events#nexusoperationcompleted) or [Failed](/references/events#nexusoperationfailed) event. +1. Caller Worker polls for a Workflow Task. +1. Caller Workflow receives the result. -The lifecycle of an asynchronous Nexus Operation, with differences between the synchronous lifecycle in bold: - -1. Caller Workflow executes a Nexus Operation using the Temporal SDK. -1. Caller Worker issues a [ScheduleNexusOperation](/references/commands#schedulenexusoperation) command to its Namespace gRPC endpoint. -1. Caller Namespace records a [NexusOperationScheduled](/references/events#nexusoperationscheduled) event in the caller Workflow's History. -1. Caller Nexus Machinery makes a Nexus RPC to start a Nexus Operation. -1. Handler Nexus Machinery receives the Nexus request and sync matches to a handler Worker. -1. Handler Worker gets a [Nexus Task](/tasks#nexus-task) to start a Nexus Operation, by polling the Nexus Endpoint's target Task Queue. -1. Handler processes the Nexus Task, using the Temporal SDK **New-Workflow-Run-Operation**. -1. Handler responds to its Namespace gRPC endpoint with the **start Operation response**. -1. Caller Namespace records the response in the caller's Workflow history as a Nexus event, for example **[NexusOperationStarted](/references/events#nexusoperationstarted)**. -1. **Handler Workflow completes and the [Nexus Completion Callback](/glossary#nexus-async-completion-callback) is delivered to the caller's Nexus Machinery.** -1. Caller Namespace records the result in the caller's Workflow history as a Nexus event, for example [Completed](/references/events#nexusoperationcompleted) or [Failed](/references/events#nexusoperationfailed). -1. Caller Worker polls for a Workflow Task on its Workflow Task Queue. -1. Caller Workflow gets the Operation result, using the Temporal SDK. +1. Caller Workflow executes a Nexus Operation. +1. Caller Worker issues a [ScheduleNexusOperation](/references/commands#schedulenexusoperation) command. +1. Caller Namespace records a [NexusOperationScheduled](/references/events#nexusoperationscheduled) event. +1. Caller Nexus Machinery sends the start request. +1. Handler Nexus Machinery sync-matches the request to a handler Worker. +1. Handler Worker receives a [Nexus Task](/tasks#nexus-task) by polling the Endpoint's target Task Queue. +1. Handler processes the task using **New-Workflow-Run-Operation**. +1. Handler responds with the **start Operation response**. +1. Caller Namespace records a **[NexusOperationStarted](/references/events#nexusoperationstarted)** event. +1. **Handler Workflow completes and a [Nexus Completion Callback](/glossary#nexus-async-completion-callback) is delivered to the caller's Nexus Machinery.** +1. Caller Namespace records a [Completed](/references/events#nexusoperationcompleted) or [Failed](/references/events#nexusoperationfailed) event. +1. Caller Worker polls for a Workflow Task. +1. Caller Workflow receives the result. -### Executing arbitrary code from a synchronous Nexus Operation handler {#executing-arbitrary-code-from-a-sync-handler} +### Executing code from a synchronous handler {#executing-arbitrary-code-from-a-sync-handler} + +Synchronous handlers can execute code directly but must complete within the [handler deadline](/cloud/limits#nexus-operation-request-timeout). +Use the Temporal SDK Client to invoke Signals, Queries, Updates, or other reliable code. + +:::caution -Synchronous Nexus Operation handlers can execute arbitrary code, but unlike Activities they should be short-lived. -As mentioned above, a synchronous Nexus Operation handler has less than 10 seconds to process a Nexus start Operation request and should stay within the remaining request deadline budget for the Nexus request. -For example, this may be done by looking at the Request-Timeout header or hooking into cancelation that is triggered when the timeout is exceeded. +Use [async Operations](#asynchronous-operation-lifecycle) for long-running work. +Repeated sync handler failures can trip the [circuit breaker](#circuit-breaking), blocking all Operations from that caller to the Endpoint. + +::: -For example, when you execute a Nexus Operation in a caller Workflow the following Namespace gRPC calls are made: - -1. **RespondWorkflowTaskCompleted** ([ScheduleNexusOperation command](/references/commands#schedulenexusoperation)) is used by the caller Worker to schedule a Nexus Operation, which atomically hands off execution to the caller's Nexus Machinery. -1. **PollNexusTaskQueue** is used by the handler Worker to receive a [Nexus Task](/tasks#nexus-task) to process, for example to start a Nexus Operation. -1. **RespondNexusTaskCompleted** or **RespondNexusTaskFailed** is used by the handler Worker to return the Nexus Task result. - When asked to start a Nexus Operation, the Nexus handler decides if the Operation will be synchronous or asynchronous. - 1. This is typically a static decision based on the [Temporal SDK builder function used](#sdk-support). - 1. [Asynchronous Nexus Operations](#asynchronous-operation-lifecycle), created with the New-Workflow-Run-Operation SDK helper, will return a Nexus Operation token, that can be used to perform additional actions like canceling an Operation. - 1. [Synchronous Nexus Operations](#synchronous-operation-lifecycle), created with the New-Sync-Operation SDK helper, will return the Operation result directly. - 1. The caller's Nexus Machinery receives the result and records a NexusOperation event in the caller's Workflow History. -1. **PollWorkflowTaskQueue** is used by the caller Worker to receive a Workflow Task with the Nexus Operation event which may be - [Started](/references/events#nexusoperationstarted), - [Completed](/references/events#nexusoperationcompleted), - [Failed](/references/events#nexusoperationfailed), - [Canceled](/references/events#nexusoperationcanceled), or - [TimedOut](/references/events#nexusoperationtimedout). +At a high level, when a caller Workflow executes a Nexus Operation: -## Automatic retries {#automatic-retries} +1. The caller Worker schedules the Operation with a [ScheduleNexusOperation command](/references/commands#schedulenexusoperation), atomically handing off execution to the caller's Nexus Machinery. +2. The handler Worker receives a [Nexus Task](/tasks#nexus-task) by polling the Endpoint's target Task Queue. +3. The handler processes the task and returns the result (synchronous) or an Operation token (asynchronous). +4. The caller's Nexus Machinery records a NexusOperation event ([Started](/references/events#nexusoperationstarted), [Completed](/references/events#nexusoperationcompleted), [Failed](/references/events#nexusoperationfailed), [Canceled](/references/events#nexusoperationcanceled), or [TimedOut](/references/events#nexusoperationtimedout)) in the caller's Workflow History. -Once the caller Workflow schedules an Operation with the caller's Temporal Service, the caller's Nexus Machinery keeps trying to start the Operation. -If a [retryable Nexus error](/references/failures#nexus-errors) is returned the Nexus Machinery will retry until the Nexus Operation's Start-to-Close-Timeout is exceeded. +## Automatic retries {#automatic-retries} -For example, if a Nexus handler returns a [retryable error](/references/failures#nexus-errors), or an [upstream timeout](https://github.com/nexus-rpc/api/blob/main/SPEC.md#predefined-handler-errors) is encountered by the caller, the Nexus request will be retried up to the [default Retry Policy's](https://github.com/temporalio/temporal/blob/de7c8879e103be666a7b067cc1b247f0ac63c25c/components/nexusoperations/config.go#L111) max attempts and expiration interval. +Once an Operation is scheduled, the caller's Nexus Machinery retries on [retryable errors](/references/failures#nexus-errors) or [upstream timeouts](https://github.com/nexus-rpc/api/blob/main/SPEC.md#predefined-handler-errors) until the Operation's Schedule-to-Close timeout is exceeded. +Retries follow the [default Retry Policy](https://github.com/temporalio/temporal/blob/de7c8879e103be666a7b067cc1b247f0ac63c25c/components/nexusoperations/config.go#L111). :::note -This differs from how Activities and Workflows handle errors and retries: - -- [Errors in Activities](/references/failures#errors-in-activities) -- [Non-retryable errors](/references/failures#non-retryable) - +This differs from Activity and Workflow error handling. +See [errors in Activities](/references/failures#errors-in-activities) and [non-retryable errors](/references/failures#non-retryable). ::: -See [errors in Nexus handlers](/nexus/error-handling#errors-in-nexus-handlers) to control the retry behavior by returning a [non-retryable Nexus error](/references/failures#non-retryable-nexus-errors). +To control retry behavior, return a [non-retryable Nexus error](/references/failures#non-retryable-nexus-errors). +See [errors in Nexus handlers](/nexus/error-handling#errors-in-nexus-handlers). ## Circuit breaking {#circuit-breaking} -Circuit breaking handles deployment issues, such as remote service faults, that take time to recover. -The circuit-breaker pattern improves application stability and resilience by detecting repeated errors and enforcing a "timeout" to allow external resources to recover. -Nexus implements the circuit-breaker pattern for each pair of caller Namespaces and target Nexus Endpoints. - -This pair is called a "destination pair" and consists of one Namespace and one Endpoint. -The circuit breaker for each pair is unique to those two elements. -It will trip and reset independently from all other Nexus destination pairs. +Nexus implements circuit breaking per caller-Namespace/Endpoint pair ("destination pair"). +Each destination pair trips and resets independently. +By default, the circuit breaker activates after 5 consecutive [retryable errors](/references/failures#nexus-errors). -Here's an example of how the circuit breaker functionality works. -Say that all Nexus Workers associated with a Nexus Endpoint are unavailable for some reasons. -Five consecutive requests fail due to request timeouts. -By default, the circuit breaker activates after five consecutive Nexus requests fail due to [retryable errors](/references/failures#nexus-errors). - -After a circuit breaker trips, it enters the _open_ state. -In this state, the caller's Nexus Machinery fails early and stops sending requests to the target Nexus Endpoint. -After 60 seconds in the _open_ state, the circuit breaker transitions to the _half-open_ state, allowing a single trailblazing request from the Client. -If the request is successful, the circuit breaker returns to the _closed_ state, its default operational state. -Once the circuit breaker closes, all requests are allowed through. -If it fails, the circuit breaker returns to the _half-open_ state for another 60 seconds. +After tripping, the circuit breaker enters the _open_ state and stops sending requests. +After 60 seconds, it transitions to _half-open_, allowing a single probe request. +If the probe succeeds, the circuit breaker returns to _closed_ (normal operation). +If it fails, the circuit breaker returns to _open_ for another 60 seconds. -The circuit breaker state is surfaced in a caller Workflow's [Pending Nexus Operations](/nexus/execution-debugging#pending-operations) and in the handler's Workflow [Pending Nexus Callbacks](/nexus/execution-debugging#pending-callbacks). -You can check the circuit breaker state using the UI, the Temporal CLI, or the `DescribeWorkflowExecution` API. - -When the circuit breaker for a destination pair is tripped (i.e., the circuit breaker is _open_), the [Pending Nexus Operation](/nexus/execution-debugging#pending-operations) for a [Nexus Operation Scheduled](/references/events#nexusoperationscheduled) event surfaces a State of Blocked along with a BlockedReason. +Circuit breaker state surfaces in [Pending Nexus Operations](/nexus/execution-debugging#pending-operations) and [Pending Callbacks](/nexus/execution-debugging#pending-callbacks). +Check it in the UI, CLI, or `DescribeWorkflowExecution` API. -Here's how that looks in the Web UI: +When open, pending Operations show a `Blocked` state with a `BlockedReason`: -In the preceding screen shot, the open circuit breaker has made 1 attempt. -For a given destination pair, differing Nexus Operations may contribute to tripping the circuit breaker count. -When the circuit breaker is open, a given Nexus Operation may have no attempts or fewer than 5 attempts. +Different Operations within the same destination pair contribute to the trip count. +A given Operation may have fewer than 5 attempts when the circuit breaker opens. -To check from the command line, issue: +From the CLI: ```sh temporal workflow describe -w my-workflow-id ``` -Here's how that looks: - ```sh -Execution Info: - WorkflowId my-workflow-id - ... - -Pending Activities: 0 -Pending Child Workflows: 0 Pending Nexus Operations: 1 Endpoint my-nexus-endpoint Service nexus-playground Operation sync-op-ok - OperationToken State Blocked Attempt 1 - ScheduleToCloseTimeout 1d 0h 0m 0s - LastAttemptCompleteTime 56 seconds ago - LastAttemptFailure {"message":"handler error (UPSTREAM_TIMEOUT): upstream timeout","cause":{"message":"upstream timeout","applicationFailureInfo":{"type":"NexusFailure"}},"applicationFailureInfo":{"type":"NexusHandlerError"}} + LastAttemptFailure {"message":"handler error (UPSTREAM_TIMEOUT): upstream timeout",...} BlockedReason The circuit breaker is open. ``` -Here's what a [Nexus Operation Cancel Request](/references/events#nexusoperationcancelrequested) surfaces for a CancelationState of Blocked and a CancelationBlockedReason: - -```sh -Execution Info: - WorkflowId my-workflow-id - ... - -Pending Activities: 0 -Pending Child Workflows: 0 -Pending Nexus Operations: 1 - - Endpoint my-nexus-endpoint - Service nexus-playground - Operation async-op-workflow-wait-for-cancel - OperationToken eyJ2IjowLCJ0IjoxLCJucyI6Im5zIiwid2lkIjoidyJ - State Started - Attempt 1 - ScheduleToCloseTimeout 1d 0h 0m 0s - LastAttemptCompleteTime 51 seconds ago - CancelationState Blocked - CancelationAttempt 5 - CancelationRequestedTime 37 seconds ago - CancelationLastAttemptCompleteTime 27 seconds ago - CancelationLastAttemptFailure {"message":"handler error (UPSTREAM_TIMEOUT): upstream timeout","cause":{"message":"upstream timeout","applicationFailureInfo":{"type":"NexusFailure"}},"applicationFailureInfo":{"type":"NexusHandlerError"}} - CancelationBlockedReason The circuit breaker is open. -``` +Cancellation requests surface the same pattern with `CancelationState: Blocked` and `CancelationBlockedReason`. ## Execution semantics {#execution-semantics} ### At-least-once execution semantics and idempotency -The Nexus Machinery provides reliable execution with at-least-once execution semantics for a Nexus Operation, until the caller's Schedule-to-Close-Timeout is exceeded, at which time the overall Nexus Operation times out. +Nexus provides at-least-once execution up to the Schedule-to-Close timeout. +The Machinery retries on handler timeouts or retryable errors, so a handler may be invoked multiple times for the same Operation. -The Nexus Machinery breaks up the [Nexus Operation lifecycle](/nexus/operations#operation-lifecycle) into one or more [Nexus Tasks](/tasks#nexus-task) that a Nexus handler is responsible for processing. -If a Nexus handler times out or returns a non-retryable Nexus error, then the Nexus Machinery will retry the Nexus request to provide at-least-once execution. -This means it's possible for your Nexus handler to be invoked multiple times for a given Nexus Operation. +Nexus Operation handlers should be idempotent, similar to Activities. +Not strictly required in all cases, but highly recommended. -To deal with at-least-once execution, the Nexus Operation handler should be idempotent, like Activities should be idempotent. -It's not required in all cases, but highly recommended in general. +### Exactly-once execution semantics -### Exactly-once execution semantics through an underlying WorkflowIDReusePolicy - -To deduplicate work and get exactly-once execution semantics, a Nexus Operation can start a Workflow with a WorkflowIDReusePolicy of RejectDuplicates which only allows one Workflow Execution per Workflow ID within a Namespace for the Retention Period. +To upgrade to exactly-once, back your Operation with a Workflow that uses a WorkflowIDReusePolicy of RejectDuplicates. +This allows only one Workflow Execution per Workflow ID within a Namespace for the Retention Period. ## Cancelation -The request to cancel a caller Workflow is automatically propagated to all pending Nexus Operations, and in turn any underlying handler Workflows. - -If an underlying handler Workflow is canceled, the Nexus Operation will report a [Canceled Failure](/references/failures#cancelled-failure) to the caller's Workflow Execution. +Cancelling a caller Workflow automatically propagates to all pending Nexus Operations and their underlying handler Workflows. +A canceled handler Workflow reports a [Canceled Failure](/references/failures#cancelled-failure) to the caller. ## Termination -If the caller Workflow is Terminated, all pending Nexus Operations are abandoned. -If possible, consider [cancellation](#cancelation) instead. +Terminating a caller Workflow abandons all pending Nexus Operations. +Prefer [cancellation](#cancelation) when possible. ## Versioning {#versioning} -Task Routing is the simplest way to version your service code. - -If you have a new backward-incompatible Nexus Operation Handler, for example due to a wire-level incompatible breaking change, start by using a different Service and Task Queue. -The version may be part of the service name, for example `prod.payments.v2`. -Callers can then migrate to the new version in their normal deployment schedule. +Task Routing is the simplest way to version Nexus service code. +For backward-incompatible changes, use a different Service name and Task Queue (for example, `prod.payments.v2`). +Callers migrate to the new version on their own deployment schedule. ## Attaching multiple Nexus callers to a handler Workflow {#attaching-multiple-nexus-callers} :::tip SUPPORT, STABILITY, and DEPENDENCY INFO -Using a [Conflict-Policy of Use-Existing](/workflow-execution/workflowid-runid#workflow-id-conflict-policy) with the [New-Workflow-Run-Operation](/nexus/operations#sdk-support) SDK helper is currently a [Public Preview](/evaluate/development-production-features/release-stages#public-preview) feature. - -::: - -:::tip CLOUD LIMITS - -In [Cloud](https://docs.temporal.io/cloud/limits#per-workflow-callback-limits), this is limited to 32, and in self-hosted Temporal, it can be configured with the [Callback limit](/workflow-execution/limits#workflow-execution-callback-limits) +Using a [Conflict-Policy of Use-Existing](/workflow-execution/workflowid-runid#workflow-id-conflict-policy) with [New-Workflow-Run-Operation](/nexus/operations#sdk-support) is in [Public Preview](/evaluate/development-production-features/release-stages#public-preview). ::: -Nexus Operations that start a Workflow with the [New-Workflow-Run-Operation](/nexus/operations#sdk-support) SDK helper will automatically attach a completion Callback on the handler Workflow, so the Nexus caller receives the result. -Additional Nexus callers may attach to the same handler Workflow if the Nexus handler uses a [Conflict-Policy of Use-Existing](/workflow-execution/workflowid-runid#workflow-id-conflict-policy). +Operations started with [New-Workflow-Run-Operation](/nexus/operations#sdk-support) automatically attach a completion Callback to the handler Workflow. +Additional callers can attach to the same handler Workflow using a [Conflict-Policy of Use-Existing](/workflow-execution/workflowid-runid#workflow-id-conflict-policy). -A single handler Workflow Execution has a [Callback limit](/workflow-execution/limits#workflow-execution-callback-limits) that governs how many Nexus callers can be attached. -Nexus callers that exceed the limit will receive an error. +Each handler Workflow has a [Callback limit](/workflow-execution/limits#workflow-execution-callback-limits) ([32 in Cloud](https://docs.temporal.io/cloud/limits#per-workflow-callback-limits), configurable in self-hosted). +Callers that exceed the limit receive an error. -When a handler Workflow uses [Continue-As-New](/workflow-execution/continue-as-new) the existing Nexus completion Callbacks will be copied to the new Workflow Execution -and the previous Workflow Execution's completion Callbacks will be left in the Standby state indefinitely. +When a handler Workflow uses [Continue-As-New](/workflow-execution/continue-as-new), existing completion Callbacks are copied to the new Execution. +The previous Execution's Callbacks remain in `Standby` state indefinitely. diff --git a/docs/encyclopedia/nexus-patterns.mdx b/docs/encyclopedia/nexus-patterns.mdx new file mode 100644 index 0000000000..88a156f8bf --- /dev/null +++ b/docs/encyclopedia/nexus-patterns.mdx @@ -0,0 +1,73 @@ +--- +id: nexus-patterns +title: Nexus Patterns +sidebar_label: Nexus patterns +description: Common patterns for building Nexus Services including the collocated pattern and the router-queue pattern for flexible deployment topologies. +slug: /nexus/patterns +keywords: + - nexus patterns + - collocated pattern + - router queue pattern + - nexus task queue routing + - nexus deployment topology + - nexus worker architecture + - temporal nexus +tags: + - Nexus + - Concepts +--- + +:::tip SUPPORT, STABILITY, and DEPENDENCY INFO + +Temporal Nexus is now [Generally Available](/evaluate/development-production-features/release-stages#general-availability) for [Temporal Cloud](/cloud/nexus) and [self-hosted deployments](/production-deployment/self-hosted-guide/nexus). + +::: + +Common patterns for building and deploying [Nexus Services](/nexus/services). + +## Collocated pattern (default) {#collocated-pattern} + +The **collocated pattern** runs Nexus Operation handlers in the same Worker and on the same Task Queue as the Workflows they abstract. +This is the default and simplest deployment topology. + +The Nexus Endpoint's target Task Queue points to the same Task Queue used by the underlying Workflows. +The same Worker process registers both Nexus Services and Workflow types, so everything runs together. + +### Why start here + +- **Simplest setup:** One Worker, one Task Queue, one deployment. No extra infrastructure. +- **Eager Workflow Start:** When the handler starts a Workflow in the same Worker process, [Eager Workflow Start](/develop/worker-performance#eager-workflow-start) can reserve a slot and execute the first Workflow Task locally without an extra round trip to the Temporal Service - while still recording durable state. If the process crashes, the Workflow resumes on another Worker. +- **Clean facade:** Operations act as a stable contract. You can change the underlying implementation (Signal today, Workflow tomorrow) without impacting callers. + +### When to use this pattern + +- Getting started with Nexus. +- The handler team owns both the Nexus Service and the underlying Workflows. +- No need to scale Nexus routing separately from Workflow execution. + +### When to move on + +When you need separate scaling, different IAM permissions per Worker fleet, or want to add Nexus to existing Workers without modifying them, see the [router-queue pattern](#router-queue-pattern). + +## Router-queue pattern + +The **router-queue pattern** separates Nexus routing from Workflow execution: a dedicated Nexus Worker on a "router" Task Queue routes Operations to Workflows on different Task Queues in the same Namespace. + +### When to use this pattern + +- **Separate scaling:** Scale Nexus routing independently from Workflow execution. +- **Dedicated routing layer:** A single Nexus Worker routes requests to multiple Workflow types on different Task Queues. +- **Different IAM permissions:** Worker fleets behind different Task Queues may have different IAM permissions to different underlying resources. +- **Avoid modifying existing Workers:** Add a router Worker to a Namespace without changing any existing Workers or Workflows. + +### How it works + +1. Register a Nexus Worker that polls a dedicated "router" Task Queue. +2. Configure the Nexus Endpoint's target Task Queue to point to this router Task Queue. +3. In each Nexus Operation handler, specify a different target Task Queue in the Workflow start options. +4. Existing Workers continue to poll their own Task Queues and execute the Workflows started by the router. + +### Production usage + +Used in production by organizations running self-service platforms where a central gateway routes requests to domain-specific Namespaces and Task Queues. +The router Worker is lightweight - it only handles routing logic. diff --git a/docs/encyclopedia/nexus-registry.mdx b/docs/encyclopedia/nexus-registry.mdx index afe8c8c233..7db5f1b3be 100644 --- a/docs/encyclopedia/nexus-registry.mdx +++ b/docs/encyclopedia/nexus-registry.mdx @@ -27,28 +27,15 @@ Temporal Nexus is now [Generally Available](/evaluate/development-production-fea ::: -The [Nexus Registry](/glossary#nexus-registry) is used to view and manage [Nexus Endpoints](/nexus/endpoints). -Adding a Nexus Endpoint to the Nexus Registry deploys the Endpoint, so it is available at runtime to serve Nexus requests. +The [Nexus Registry](/glossary#nexus-registry) manages [Nexus Endpoints](/nexus/endpoints). +Adding an Endpoint to the Registry deploys it for immediate runtime use. +Endpoint names must be unique within the Registry. +In Temporal Cloud, the Registry is global across your entire Account, spanning all Namespaces. +In self-hosted deployments, it is scoped to a Cluster. - - -:::info - -The Nexus Registry is scoped to an Account in Temporal Cloud and scoped to a Cluster for self-hosted deployments. - -::: - -Developers can advertise available Endpoints and Services, so others can find them for use in their caller Workflows. -Endpoint names must be unique within the Nexus Registry. +## View and manage Nexus Endpoints -## View and Manage Nexus Endpoints - -Nexus Endpoints may be managed using the Temporal UI, CLI, Cloud Terraform provider, or [Cloud Ops API](/ops). +Manage Endpoints using the Temporal UI, CLI, Terraform provider, or [Cloud Ops API](/ops). :::tip RESOURCES @@ -59,14 +46,14 @@ Nexus Endpoints may be managed using the Temporal UI, CLI, Cloud Terraform provi ### Search for a Nexus Endpoint -You can search the Nexus Registry for Endpoint name or an Endpoint's target Namespace to quickly find an Endpoint of interest. +Search by Endpoint name or target Namespace. -The Endpoint details page shows the target Namespace and target Task Queue along with the endpoint description rendered as markdown. +The details page shows the target Namespace, Task Queue, and description rendered as markdown. -The Access Policy allows specifying the caller Namespaces that can use Nexus Services on an Endpoint at runtime. - -No callers are allowed by default, even if the caller is in the same Namespace as the Endpoint target. - -See [Runtime Access Controls](/nexus/security#runtime-access-controls) for more information. +See [Runtime Access Controls](/nexus/security#runtime-access-controls) for details. ## Roles and permissions @@ -117,19 +108,16 @@ Temporal Cloud has built-in Nexus security. For self-hosted deployments you can ::: -In Temporal Cloud, access to the Nexus Registry is controlled with the following roles and permissions: +In Temporal Cloud: -- View, list, and search Nexus Endpoints: - - Read-only role (or higher) in an Account -- Manage a Nexus Endpoint (create, edit, delete) requires **both**: - - Developer role (or higher) in an Account - - Namespace Admin permission on the Endpoint's target Namespace +- **View/search Endpoints**: Read-only role (or higher) in the Account. +- **Manage Endpoints** (create, edit, delete): Developer role (or higher) **and** Namespace Admin on the target Namespace. - See [Nexus Security in Temporal Cloud](/cloud/nexus/security) for more information. +See [Nexus security in Temporal Cloud](/cloud/nexus/security). ## Terraform and Ops API support -Nexus Endpoint provisioning and lifecycle management may be automated with Terraform or the Ops API. +Automate Endpoint provisioning and lifecycle management with Terraform or the Ops API. :::tip RESOURCES diff --git a/docs/encyclopedia/nexus-security.mdx b/docs/encyclopedia/nexus-security.mdx index 3e07048805..8aff638849 100644 --- a/docs/encyclopedia/nexus-security.mdx +++ b/docs/encyclopedia/nexus-security.mdx @@ -25,28 +25,23 @@ Temporal Nexus is now [Generally Available](/evaluate/development-production-fea ::: -Nexus supports restricting access to Nexus Endpoints. -Temporal Cloud has built-in Endpoint access controls and provides secure Nexus connectivity across Namespaces. -For self-hosted deployments you can implement custom Authorizers. +Temporal Cloud provides built-in Endpoint access controls and secure connectivity across Namespaces. +Self-hosted deployments can implement [custom Authorizers](/self-hosted-guide/security#authorizer-plugin). ## Runtime access controls {#runtime-access-controls} -In Temporal Cloud, access to a Nexus Endpoint at runtime is controlled by the Endpoint's access control policy (allowlist of caller Namespaces) for each Endpoint in the Nexus Registry. +In Temporal Cloud, each Endpoint has an access control policy: an allowlist of caller Namespaces. -Workers in each Namespace may authenticate with Temporal Cloud as they do now with mTLS certificates or API key as allowed by the caller Namespace. -Once a Worker has authenticated it can send Nexus Operation commands to Temporal Cloud using a Temporal SDK to start a Nexus Operation in a different Namespace. -For example, in the Temporal Go SDK a caller Workflow would use `nexusClient.ExecuteOperation` to issue a command to start a Nexus Operation. +Workers authenticate with their Namespace using mTLS or API key. +When a caller Workflow executes a Nexus Operation, Temporal Cloud verifies the caller's Namespace is in the Endpoint's allowlist before routing the request to the handler. +Temporal Cloud acts as a trusted broker across Namespace boundaries. -To process a `ScheduleNexusOperation` command from a caller Workflow, Temporal Cloud obtains the handler Namespace and Task Queue for the handler endpoint, and restricts access by verifying that the caller's Namespace is in the endpoint's allowlist. - -In this way, Temporal Cloud acts as a trusted broker across Namespace boundaries, and relies on authenticated workers in each Namespace. - -See [Configure Runtime Access Controls](/nexus/registry#configure-runtime-access-controls) for additional information. +See [Configure runtime access controls](/nexus/registry#configure-runtime-access-controls). ## Secure connectivity {#secure-connectivity} @@ -58,32 +53,50 @@ Self-hosted deployments rely on the Temporal Cluster being secure. ::: -In Temporal Cloud multiple security provisions are in place to ensure it can act as a trusted broker across Namespace boundaries: +Temporal Cloud secures all Nexus communication: -- Workers authenticate to their Namespaces via mTLS or an API key as allowed by their Namespace configuration. -- mTLS is used for all Nexus communication, including across cloud cells and regions, to: - - Start or Cancel a Nexus Operation. - - Callback on completion of an asynchronous Nexus Operation. -- Nexus Endpoints are only privately accessible from within a Temporal Cloud account. - - Accessible from within a caller Workflow using the Temporal SDK. - - Not externally accessible for arbitrary clients yet. +- Workers authenticate to their Namespace using mTLS or API key. +- mTLS encrypts all cross-Namespace Nexus traffic (start, cancel, and completion callbacks) across cells and regions. +- Endpoints are only accessible from within a Temporal Cloud Account through the Temporal SDK - not externally accessible. ## Payload encryption and Data Converter {#payload-encryption-data-converter} -The Data Converter works the same for a Nexus Operation as it does for other payloads sent between a Worker and Temporal Cloud. -The caller and handler Workers must have compatible Data Converters as operation inputs and results are passed between the two. +Nexus uses the same Data Converter as Workflows and Activities - JSON, Proto, and binary payloads are all supported. +If you use a Codec for encryption, it also encrypts Nexus payloads. + +Caller and handler Workers must have compatible Data Converters. +Payloads are encrypted by the sender (caller encrypts input, handler encrypts result). + +Three common approaches for cross-Namespace payload encryption: + +### Option 1: Same encryption key {#same-encryption-key} + +Both Namespaces share the same encryption key. +Simplest approach - no additional configuration needed. + +### Option 2: Pass KMS key ID in payload metadata {#kms-key-id-metadata} -If encryption keys are used to encrypt payloads, they must be available in both the caller and handler. For example, -the caller and handler can use a shared symmetric key stored in your KMS. +Each Namespace uses its own encryption key, with the KMS key ID passed in Temporal payload metadata. +The receiver reads the key ID from metadata and decrypts using KMS IAM permissions. -Please let us know if you need per-Service payload encryption or better handling for asymmetric encryption keys. +Works bi-directionally: caller encrypts input with the caller's key, handler decrypts using the key ID from metadata, then encrypts the result with the handler's key. +The Codec Server needs KMS decrypt permissions for all relevant keys. + +See the [encryption sample](https://github.com/temporalio/samples-go/blob/main/encryption/data_converter.go) and the [reference-app-orders-go data converter](https://github.com/temporalio/reference-app-orders-go/blob/main/app/temporalutil/data_converter.go). + +### Option 3: Wrapper types for endpoint-specific encryption keys {#endpoint-specific-keys} + +Use wrapper types (for example, `EndpointValue`) so the Data Converter selects an Endpoint-specific encryption key. +This encrypts only Nexus traffic with a dedicated key, without sharing Namespace keys across teams. + +See the [draft endpoint-based encryption sample](https://github.com/temporalio/samples-go/compare/main...bergundy:samples-go:nexus-encryption-by-endpoint). + +### Choosing an approach + +Options 1 and 2, where both sides share the same key or flow the KMS key ID in payload metadata, work with the standard Data Converter. +Option 3 is more advanced and is intended for teams that don't want to share their Namespace encryption keys with other teams. ## Nexus Registry security {#managing-nexus-endpoints} See [Nexus Registry Roles and Permissions](/nexus/registry#roles-and-permissions). -## Learn more - -- [Evaluate](/evaluate/nexus) why you should use Nexus and watch the [Nexus keynote and demo](https://youtu.be/qqc2vsv1mrU?feature=shared&t=2082). -- Learn how Nexus works in the [Nexus deep dive talk](https://www.youtube.com/watch?v=izR9dQ_eIe4&t=934s). -- Explore [additional resources](/evaluate/nexus#learn-more) to learn more about Nexus. diff --git a/docs/encyclopedia/nexus-services.mdx b/docs/encyclopedia/nexus-services.mdx index be07ffa8bf..2d07d9ac08 100644 --- a/docs/encyclopedia/nexus-services.mdx +++ b/docs/encyclopedia/nexus-services.mdx @@ -1,7 +1,7 @@ --- id: nexus-services title: Nexus services -sidebar_label: Nexus services +sidebar_label: Nexus Services description: Nexus Services are named collections of arbitrary-duration Nexus Operations that provide a microservice contract suitable for sharing across team boundaries. toc_max_heading_level: 4 slug: /nexus/services @@ -25,49 +25,11 @@ Temporal Nexus is now [Generally Available](/evaluate/development-production-fea ::: -[Nexus Services](/glossary#nexus-service) are named collections of arbitrary-duration [Nexus Operations](/nexus/operations) that provide a contract suitable for sharing across team boundaries. +[Nexus Services](/glossary#nexus-service) are named collections of [Nexus Operations](/nexus/operations) that provide a contract for sharing across team boundaries. +A [Nexus Endpoint](/nexus/endpoints) exposes Services for callers to use. - +Services are registered in a Worker that polls the Endpoint's target Task Queue. +Multiple Services can run in the same Worker. +Services typically run alongside the Workflows they abstract, or in a dedicated router Worker using the [router-queue pattern](/nexus/patterns#router-queue-pattern). -A [Nexus Endpoint](/nexus/endpoints) exposes Nexus Services for others to use. -Services are handled in a Temporal Worker that is polling an Endpoint's target Namespace and Task Queue. -Multiple Nexus Services may be run in the same Worker polling the same Endpoint target Namespace and Task Queue. - -For example, a Nexus Service is often registered in the same Worker as the underlying Workflows they abstract: - -```go -func main() { - c, err := client.Dial(client.Options{}) - if err != nil { - log.Fatalln("Unable to create client", err) - } - defer c.Close() - - w := worker.New(c, taskQueue, worker.Options{}) - service := nexus.NewService(service.HelloServiceName) - err = service.Register(handler.EchoOperation, handler.HelloOperation) - if err != nil { - log.Fatalln("Unable to register operations", err) - } - w.RegisterNexusService(service) - w.RegisterWorkflow(handler.HelloHandlerWorkflow) - - err = w.Run(worker.InterruptCh()) - if err != nil { - log.Fatalln("Unable to start worker", err) - } -} -``` - -The Nexus Service name is used when invoking a Nexus Operation from a caller workflow. - -:::tip RESOURCES - -- [Go SDK - build and use Nexus Services](/develop/go/nexus#develop-nexus-service-operation-handlers). -- [Java SDK - build and use Nexus Services](/develop/java/nexus#develop-nexus-service-operation-handlers). - ::: +Callers reference a Service by name when executing a Nexus Operation. diff --git a/docs/encyclopedia/nexus-use-cases.mdx b/docs/encyclopedia/nexus-use-cases.mdx deleted file mode 100644 index 5480c33669..0000000000 --- a/docs/encyclopedia/nexus-use-cases.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -id: nexus-use-cases -slug: /nexus/use-cases -title: Common use cases for Temporal Nexus -description: Common use cases for Temporal Nexus -sidebar_label: Nexus use cases -tags: - - Nexus -keywords: - - nexus - - nexus use cases - - nemporal nexus onboarding - - setting up Nexus Endpoints - - temporal cloud - - nexus setup - ---- - -:::tip SUPPORT, STABILITY, and DEPENDENCY INFO - -Temporal Nexus is now [Generally Available](/evaluate/development-production-features/release-stages#general-availability) for [Temporal Cloud](/cloud/nexus) and [self-hosted deployments](/production-deployment/self-hosted-guide/nexus). - -::: - -[Temporal Nexus](/evaluate/nexus) enables the following use cases: - -- **Cross-team, cross-domain, and cross-namespace** \- - connect Temporal Applications within and across Namespaces. -- **Share a subset of a Temporal Application** \- - abstract and share a subset of an Temporal Application as a Nexus Service. -- **Modular design for growth** \- - modular application design that can evolve as you grow. -- **Smaller failure domains** \- - each team to have their own Namespace for improved security, troubleshooting, and fault isolation. -- **Multi-region** \- - Nexus requests in Temporal Cloud are routed across a global mTLS-secured Envoy mesh. - -:::tip RELATED - -- [Evaluate](/evaluate/nexus) why you should use Nexus and learn more about [Nexus use cases](/evaluate/nexus#use-cases). - -::: - -## Share Workflows Across Namespaces - -Nexus is purpose-built to connect Temporal Applications within and across Namespaces. -It addresses the limitations of Child Workflows, Activity Wrappers, and bespoke APIs that target a remote Namespace. -Nexus has a streamlined Temporal developer experience, reliable execution, and integrated observability. - -Without Nexus, when a caller Workflow invokes another Workflow directly the caller must know: - -- target Workflow's Namespace and Task Queue. -- target Workflow Retry Policy and Timeouts. -- target Workflow options including [Workflow-Id-Reuse-Policy](/workflow-execution/workflowid-runid#workflow-id-reuse-policy) and [Workflow-Id-Conflict-Policy](/workflow-execution/workflowid-runid#workflow-id-conflict-policy). -- target Workflow ID uniqueness constraints, so it doesn't conflict with other Workflow types in the handler Namespace. - -This creates a high degree of coupling between the caller and handler, by exposing internal implementation details to the caller. -This adds friction for the caller, who shouldn't need to know this level of detail. -It's more difficult to refactor or migrate handler Workflows to different Namespace or Task Queue. -In short, Workflow to Workflow is a leaky abstraction. - -Nexus addresses this by providing a cleaner service contract between the caller and handler. -Nexus is suitable for abstracting and sharing Workflows across team, domain, and Namespace boundaries. -Nexus requests in Temporal Cloud are routed across a global mTLS-secured Envoy mesh, so they're also suitable for multi-region use cases. - -Enable calls across Namespaces by: - -1. Creating a [Nexus Endpoint](/nexus/endpoints) in the [Nexus Registry](/nexus/registry) that: - 1. Targets the handler Namespace. - 2. Allows the caller Namespace. -2. Creating a [Nexus Service](/nexus/services) in a Worker within a handler Namespace. - 1. Abstract Workflows with Nexus Operations [using Temporal SDK builder functions for Nexus Operations](/nexus/operations#sdk-support). - 2. Register the Nexus Service with the Worker. - 3. Ensure the Worker is polling the Endpoint's Task Queue. -3. Calling the Nexus Service from a Workflow in a different Namespace. - 1. Execute a Nexus Operation from a caller Workflow [using the Temporal SDK](/nexus/operations#sdk-support). diff --git a/docs/encyclopedia/nexus.mdx b/docs/encyclopedia/nexus.mdx index 032dacb8ba..7e3c26be49 100644 --- a/docs/encyclopedia/nexus.mdx +++ b/docs/encyclopedia/nexus.mdx @@ -2,7 +2,7 @@ id: nexus title: Temporal Nexus sidebar_label: Temporal Nexus -description: Temporal Nexus is a feature of the Temporal platform designed to connect durable executions across team, namespace, region, and cloud boundaries. It promotes a more modular architecture for sharing a subset of your team's capabilities via well-defined microservice contracts for other teams to use, that abstract underlying Temporal primitives, like Workflows, or execute arbitrary code. +description: Temporal Nexus connects Temporal Applications across isolated Namespaces with clean service contracts, built-in durability, observability, and security. toc_max_heading_level: 4 slug: /nexus keywords: @@ -22,79 +22,101 @@ Temporal Nexus is now [Generally Available](/evaluate/development-production-fea ::: -[Temporal Nexus](/evaluate/nexus) allows you to reliably connect Temporal Applications. -It promotes a more modular architecture for sharing a subset of your team's capabilities with well-defined microservice contracts for other teams to use. -Nexus was designed with Durable Execution in mind and enables each team to have their own Namespace for improved modularity, security, debugging, and fault isolation. +:::info NEW TO NEXUS? -## Connect Temporal Applications +This page explains what Nexus is and how it works. To evaluate whether Nexus fits your use case, see the [evaluation guide](/evaluate/nexus). -[Nexus Services](/nexus/services) are exposed from a [Nexus Endpoint](/nexus/endpoints) created in the [Nexus Registry](/nexus/registry). -Adding a Nexus Endpoint to the Nexus Registry deploys the Endpoint, so it is available at runtime to serve Nexus requests. -The Nexus Registry is scoped to an Account in Temporal Cloud and scoped to a Cluster for self-hosted deployments. +::: + +## What is Nexus? + +Nexus connects Temporal Applications across (and within) isolated Namespaces. +Each team gets their own Namespace for security and fault isolation, while exposing a clean service contract for others to use through a [Nexus Endpoint](/nexus/endpoints). + +Designed for Durable Execution, Nexus combines a familiar SDK programming model with reliable execution, built-in observability, and multi-region connectivity in Temporal Cloud. + +Nexus is peer-to-peer, not hierarchical. +Caller and handler Workflows are siblings that communicate across Namespace boundaries. -A Nexus Endpoint is a reverse proxy that decouples the caller from the handler and routes requests to upstream targets. It currently supports routing to a single target Namespace and Task Queue. -Nexus Services and [Nexus Operations](/nexus/operations) are often registered in the same Worker as the underlying Temporal primitives they abstract. +## How Nexus works + +### Services and Operations -Nexus connectivity across Namespaces is provided by the Temporal Service. -Temporal Cloud supports Nexus connectivity [within and across regions](/cloud/nexus#multi-region-connectivity) and has [built-in access controls](/cloud/nexus#built-in-access-controls). -Self-hosted Nexus connectivity is supported within a single Cluster and [custom Authorizers](/self-hosted-guide/security#authorizer-plugin) may be used for access control. +A [Nexus Service](/nexus/services) is a named collection of [Nexus Operations](/nexus/operations) that a team exposes. +Operations abstract the underlying implementation - callers don't need to know whether an Operation starts a Workflow, sends a Signal, runs a Query, or executes other reliable code. -## Build and use Nexus Services +The [Operation lifecycle](/nexus/operations#operation-lifecycle) supports two modes: -Nexus has a familiar programming model to build and use Nexus Services using the Temporal SDK. -The [Nexus Operation lifecycle](/nexus/operations#operation-lifecycle) supports both [synchronous](/nexus/operations#synchronous-operation-lifecycle) and [asynchronous](/nexus/operations#asynchronous-operation-lifecycle) Operations. -It is suitable for low-latency and long-running use cases. -Nexus Operations can be implemented with Temporal primitives, like Workflows, or [execute arbitrary code](/nexus/operations#executing-arbitrary-code-from-a-sync-handler). +- **Asynchronous** - Starts a Workflow (same or different Task Queue, with optional [Eager Start](/develop/worker-performance#eager-workflow-start)). Can run up to [60 days](/cloud/limits#nexus-operation-duration-limits). +- **Synchronous** - Completes within the [10-second handler deadline](/cloud/limits#nexus-operation-request-timeout). Use for Signals, Queries, Updates, or other reliable low-latency calls using the [Temporal SDK Client](/nexus/operations#executing-arbitrary-code-from-a-sync-handler). -:::tip RESOURCES +Services and Operations are built with the Temporal SDK and typically [collocated](/nexus/patterns#collocated-pattern) in the same Worker as the Temporal primitives they abstract, or in a dedicated router Worker using the [router-queue pattern](/nexus/patterns#router-queue-pattern). -- [Go SDK - Nexus quick start and code sample](/develop/go/nexus) -- [Java SDK - Nexus quick start and code sample](/develop/java/nexus) -- [Python SDK - Nexus quick start and code sample](/develop/python/nexus) -- [TypeScript SDK - Nexus quick start and code sample](/develop/typescript/nexus) -- [.NET SDK - Nexus quick start and code sample](/develop/dotnet/nexus) +:::tip SDK GUIDES - ::: +- [Go](/develop/go/nexus) | + [Java](/develop/java/nexus) | + [Python](/develop/python/nexus) | + [TypeScript](/develop/typescript/nexus) | + [.NET](/develop/dotnet/nexus) -## Queue-based Worker architecture +::: + +### Endpoints and Registry + +A [Nexus Endpoint](/nexus/endpoints) is a reverse proxy that decouples callers from handlers. +Callers reference an Endpoint by name. The Endpoint routes requests to a target Namespace and Task Queue. +Callers never need to know the handler's Namespace, Task Queue, or internal implementation. -Nexus uses the Temporal queue-based Worker architecture and built-in Nexus Machinery to ensure reliable execution of Nexus Operations. -If a Nexus Service is down, a caller Workflow can continue to schedule Nexus Operations and they will be processed when the service is up. +Endpoints are managed in the [Nexus Registry](/nexus/registry) using the UI, CLI, or Cloud Ops API. -Nexus handler Workers poll the Endpoint's target Namespace and Task Queue for [Nexus Tasks](/tasks#nexus-task) to process. -Workers authenticate to their Namespace's gRPC endpoint with supported methods including mTLS client certificates or API Keys in Temporal Cloud. +### Queue-based Worker architecture + +Nexus uses the same queue-based Worker architecture as the rest of Temporal. +Handler Workers poll the Endpoint's target Task Queue for [Nexus Tasks](/tasks#nexus-task). +If a Nexus Service is down, caller Workflows continue to schedule Operations - they process when the service is back up. +No bespoke service deployments needed. Load balancing is automatic. -See [system interactions](/nexus/operations/#system-interactions) for additional detail. +See [system interactions](/nexus/operations#system-interactions) for the full request flow. + +### Built-in Nexus Machinery + +When a caller Workflow executes a Nexus Operation, the [Nexus Machinery](/glossary#nexus-machinery) handles delivery with [at-least-once](/nexus/operations#execution-semantics) execution: -## Built-in Nexus Machinery +- Automatic retries with exponential backoff +- Rate limiting and concurrency limiting +- [Circuit breaking](/nexus/operations#circuit-breaking) (trips after 5 consecutive retryable errors) +- Automatic load balancing -The built-in [Nexus Machinery](/glossary#nexus-machinery) uses state-machine-based invocation and completion callbacks. -It guarantees [at-least-once](/nexus/operations#execution-semantics) execution, with automatic retries, circuit breaking, rate limiting, and load balancing. +The Machinery uses [Nexus RPC](/glossary#nexus-rpc) on the wire - a protocol supporting arbitrary-duration Operations. +You interact only with the Temporal SDK, not Nexus RPC directly. -The Nexus Machinery uses [Nexus RPC](/glossary#nexus-rpc) on the wire, a protocol designed with Durable Execution in mind, to support arbitrary-duration Operations that extend beyond a traditional RPC. +### Multi-level calls -For example, when you execute a Nexus Operation in a caller Workflow, a command is sent to Temporal to schedule the Operation, and the Nexus Machinery is responsible for making the Nexus RPC calls on your behalf. -This means you don't have to use Nexus RPC directly, only the Temporal SDK along with the Temporal Service. +Nexus calls chain across teams and Namespaces: -## Multi-level calls +- Workflow A -> Nexus Op 1 -> Workflow B -> Nexus Op 2 -> Workflow C -Nexus supports multi-level Nexus calls, for example: +## Operational reference -- Workflow A → Nexus Operation 1 → Workflow B → Nexus Operation 2 → Workflow C +- [Nexus security](/nexus/security) - Access controls, secure connectivity, and payload encryption. +- [Nexus execution debugging](/nexus/execution-debugging) - Bi-directional linking, pending Operations, and tracing. +- [Nexus error handling](/nexus/error-handling) - Error types and how they surface in caller Workflows. +- [Nexus metrics](/nexus/metrics) - SDK, Cloud, and OSS cluster metrics. ## Public Preview features diff --git a/docs/evaluate/development-production-features/temporal-nexus.mdx b/docs/evaluate/development-production-features/temporal-nexus.mdx index 9261274fe5..a9e251a2eb 100644 --- a/docs/evaluate/development-production-features/temporal-nexus.mdx +++ b/docs/evaluate/development-production-features/temporal-nexus.mdx @@ -40,120 +40,74 @@ Temporal Nexus is now [Generally Available](/evaluate/development-production-fea ::: -## Connect Temporal Applications +Nexus connects Temporal Applications across (and within) isolated Namespaces with built-in durability, observability, and security. +Each team gets their own Namespace for improved security and fault isolation, while sharing capabilities through clean service contracts. +Watch the [Nexus overview](https://www.youtube.com/watch?v=tJ1OwSFokOg&t=117s) for a walkthrough. -Nexus allows you to connect Temporal Applications across (and within) isolated Namespaces. -This provides all the benefits of Durable Execution across team and application boundaries with improved modularity, security, debugging, and fault isolation. -Nexus supports cross-team, cross-domain, cross-namespace, multi-region, and multi-cloud use cases. +## Who's using Nexus? -## Why use Nexus? +Companies using Nexus include: -Unlike other forms of inter-service communication, Nexus combines a familiar programming model with the resiliency of the Temporal Platform and its queue-based Worker architecture. +- **Duolingo** - Self-service infrastructure ([Case study](https://temporal.io/resources/case-studies/duolingo-temporal-nexus) | [Webinar](https://www.youtube.com/watch?v=tJ1OwSFokOg&t=524s)) +- **Netflix** - Infrastructure orchestration ([Replay talk](https://www.youtube.com/watch?v=izR9dQ_eIe4&t=470s) | [Webinar](https://www.youtube.com/watch?v=At1FfqGQiu0&t=1295s)) +- **Miro** - Cross-region data migration ([Replay talk](https://youtu.be/YLmFR-IAC3M?feature=shared&t=1488)) + +## Benefits + +Connect Temporal Applications across teams, domains, regions, and clouds with: + +- **Stronger security posture** - Built-in access controls for a specific service contract instead of broad Namespace access. Easier audits and safer cross-team collaboration. +- **Higher reliability** - Durable, atomic handoffs remove lost requests and hand-rolled retry and deduplication logic. +- **Reduced engineering overhead** - Less code, custom retry, deduplication, and refactoring work. Teams ship features faster. +- **Scalable platform patterns** - Enables platform-level orchestration (cross-region, cross-team) without centralizing ownership. +- **New workflows and integrations** - Frees teams to add more Workflows once Nexus is adopted, especially shared services or cross-team use cases. + +## Why separate Namespaces? + +As teams and workloads grow, separate Namespaces provide: + +- **Security** - Sensitive data (PCI, PII) stays in a restricted Namespace with its own encryption key and access controls. +- **Fault isolation** - Misbehaving Workers in one Namespace don't trigger rate limits or affect other teams. +- **Compliance** - Data residency requirements may mandate isolated regions or Namespaces. +- **Ownership** - Each team controls their own Namespace, Workers, and deployment lifecycle. + +Before Nexus, connecting Namespaces required workarounds: + +- **Child Workflows** - Leaky abstraction. Caller must know target Namespace, Task Queue, and Workflow policy options. Same-Namespace only in Temporal Cloud. +- **Activity wrappers** - Require an mTLS client per target, grant full Namespace write access, no integrated observability, error-prone boilerplate for async results. +- **Bespoke gateways** - Not durable, poor cross-service debugging, another service to manage and patch. + +Nexus replaces all of these with a clean service contract between caller and handler, less code, and first-class observability. + + +## Should I use Nexus? Use the following decision tree to help determine if Nexus is right for your use case: -### Benefits - -- **Integrated Temporal experience** \- with improved security, observability, and reliability. -- **Microservice contracts** \- suitable for sharing across teams or domains. -- **Abstract and share underlying Temporal primitives** \- like Workflows, Signals, or Updates. -- **At-least-once execution guarantees** \- with support for exactly-once execution using Workflow policy. -- **Improved security and blast-radius isolation** \- with separate Namespaces for each team or domain. -- **Modular design** \- for streamlined multi-team development. -- **Custom handlers** \- that execute arbitrary code. -- **No error-prone boilerplate code** \- with Temporal SDK support to build and use Nexus Services. -- **Same queue-based Worker architecture** \- so no bespoke service deployments are needed. - -### Use cases - -- **Cross-team, cross-domain, and cross-namespace** \- - Nexus is purpose-built to connect Temporal Applications within and across Namespaces. - It addresses the limitations of Child Workflows, Activity Wrappers, and bespoke APIs that target a remote Namespace; such as leaking implementation details, second-class observability, overly-permissive security, and error-prone boilerplate code. - Nexus has a streamlined Temporal developer experience, reliable execution, and integrated observability. - -- **Share a subset of a Temporal Application** \- - Abstract and share a subset of an Application as a Nexus Service. - Nexus Operations can span any length of execution, be synchronous or asynchronous, and be implemented with Temporal primitives, like Workflows, Signals, or Updates. - Expose Services on a Nexus Endpoint for others to use and secure them with access control policies. - Nexus Endpoints decouple callers from handlers, so teams can operate more autonomously. - -- **Modular design for growth** \- - Temporal Nexus enables a modular application design that can evolve as you grow. - Start with Nexus Services in a monolithic Namespace and move Services to separate Namespaces with small configuration changes. - -- **Smaller failure domains** \- When teams operate in the same monolithic Namespace, everything is available to everyone, and mis-behaving Workers can trigger rate limits that affect all teams operating in that monolithic Namespace. - Nexus enables each team to have their own Namespace for improved security, troubleshooting, and fault isolation. - -- **Multi-region** \- - Nexus requests in Temporal Cloud are routed across a global mTLS-secured Envoy mesh within and across AWS and GCP. - Built-in Nexus Machinery provides reliable at-least-once execution and Workflow policy can deduplicate requests for exactly-once execution, even across multi-region boundaries. - -### Key features - -- **Familiar developer experience** \- - Temporal SDKs provide an integrated way to build and use Nexus Services. - - Use Nexus Services from a caller Workflow. - - Run Nexus Service handlers in a Worker, often the same Worker as underlying Temporal primitives. - - Implement long-running asynchronous Nexus Operations as Workflows. - - Handle low-latency synchronous Nexus Operations with Temporal primitives or arbitrary code. - - Execute Operations with at-least-once semantics by default, and exactly-once semantics using Workflow ID reuse policies. - -- **Nexus Endpoints with a queue-based Worker architecture** \- Nexus Endpoints are a reverse proxy for Nexus Services. - - Connect callers and handlers through Nexus Endpoints, for looser coupling. - - Manage Endpoints in the Nexus Registry using the UI, CLI, or Cloud Ops API. - - Use a Nexus Endpoint by name, which routes requests to an upstream target Namespace and Task Queue. - - Handle Nexus requests in a Nexus Worker by polling an Endpoint's target Task Queue, with automatic load balancing. - - Streamline operations by running Nexus Services in existing queue-based Workers. - -- **Built-in Nexus Machinery** \- - Execution guarantees are provided with built-in Nexus Machinery. - - Execute Nexus Operations with reliable state-machine-based invocation and completion callbacks. - - Guarantee atomic handoff from Workflow Event History to Nexus Operation state machines. - - Ensure reliable execution with automatic retries, rate limiting, concurrency limiting, and circuit breaking. - -- **Integrated observability** \- - Execution debugging and observability is integrated into the Temporal Platform. - - View Nexus Operation lifecycle and error info in Workflow Event History. - - Debug across Namespaces with bi-directional linking. - - Generate metrics, traces, and logs. - -- **Improved blast radius isolation** \- - Separate Namespaces isolate underlying Workers and sensitive Workflow state. - - Limit direct access to a Namespace, while exposing Nexus Endpoints for others to use. - - Isolate misbehaving Workers that affect rate limits for all Workers in a Namespace. - - Avoid leaking Workflow implementation details to external callers. - -- **Enhanced security and connectivity** \- - Temporal Cloud provides integrated Nexus access controls and multi-region routing. - - Connect Applications across Namespaces in an Account with Temporal's private mTLS-secured Envoy mesh. - - Multi-region connectivity within and across AWS and GCP. - - Restrict which callers can use a Nexus Endpoint, with built-in Endpoint access controls. - - Stream audit logs including Nexus Registry actions to create, update, or delete Endpoints. - -## Learn more - -To connect with the Nexus community, join the [#nexus](https://temporalio.slack.com/archives/C07LQN0JK9B) channel in [Temporal Slack](https://t.mp/slack). +## Get started {#learn-more} + +Join the [#nexus](https://temporalio.slack.com/archives/C07LQN0JK9B) channel in [Temporal Slack](https://t.mp/slack) to connect with the Nexus community. - - - - - - - + + + + + + + diff --git a/docs/glossary.md b/docs/glossary.md index d508e0d126..44be275fb3 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -386,8 +386,7 @@ A Nexus Async Completion Callback is the completion callback for an asynchronous A Nexus Endpoint is a reverse proxy that can serve one or more Nexus Services. It routes Nexus requests to a target Namespace and Task Queue, that a Nexus Worker is polling. This allows service providers to present a clean service contract and hide the underlying implementation, which may consist of many internal Workflows. Multiple Nexus Endpoints -can target the same Namespace, and over time a Nexus Endpoint will be able to span multiple Namespaces with service -routing rules. +can target the same Namespace. diff --git a/docs/production-deployment/self-hosted-guide/temporal-nexus.mdx b/docs/production-deployment/self-hosted-guide/temporal-nexus.mdx index 9d4b23f935..0130c9ec2b 100644 --- a/docs/production-deployment/self-hosted-guide/temporal-nexus.mdx +++ b/docs/production-deployment/self-hosted-guide/temporal-nexus.mdx @@ -20,8 +20,7 @@ Learn why you should use Nexus in the [evaluation guide](/evaluate/nexus). ::: -[Temporal Nexus](/nexus) allows you to reliably connect Temporal Applications. -It was designed with Durable Execution in mind and enables each team to have their own Namespace for improved modularity, security, debugging, and fault isolation. +[Temporal Nexus](/nexus) connects Temporal Applications across Namespaces with built-in durability, security, and fault isolation. + + + + + + + + + + + + + + + Does your use case span team, domain, + namespace, region, or cloud boundaries? + + + + + Yes + + + + No + + + + + Use a single namespace with + Workflows and Activities. + + + + + + + + + + Do you need separate namespaces for + security, fault isolation, or modularity? + + + + + Yes + + + + No + + + + + + + + + Is Nexus SDK support available + for your language? + + + + + Yes + + + + No + + + + + Do you plan to split into separate + namespaces later? + + + + + Yes + + + + No + + + + + + + + ✓ Use Nexus + + + + + Is cross-namespace a future + goal, not urgent now? + + + + + Yes + + + + No + + + + + ✓ Use Nexus in a single namespace + for separation of concerns and + easier future migration. + + + + + + Need cleaner contracts than + Child Workflows provide? + + + + + Yes + + + + No + + + + + + + + + ✓ Build in isolated namespaces now. + Use Nexus to connect them later. + + + + + + Use Child Workflows in a single namespace. + Migration to Nexus is straightforward later. + + + + + + + Question + + Use Nexus + + Alternative path + + \ No newline at end of file diff --git a/static/diagrams/nexusadoptionlight.svg b/static/diagrams/nexusadoptionlight.svg new file mode 100644 index 0000000000..59e2e46967 --- /dev/null +++ b/static/diagrams/nexusadoptionlight.svg @@ -0,0 +1,164 @@ + + + + + + + + + + + + + + + + Does your use case span team, domain, + namespace, region, or cloud boundaries? + + + + + Yes + + + + No + + + + + Use a single namespace with + Workflows and Activities. + + + + + + + + + + Do you need separate namespaces for + security, fault isolation, or modularity? + + + + + Yes + + + + No + + + + + + + + + Is Nexus SDK support available + for your language? + + + + + Yes + + + + No + + + + + Do you plan to split into separate + namespaces later? + + + + + Yes + + + + No + + + + + + + + ✓ Use Nexus + + + + + Is cross-namespace a future + goal, not urgent now? + + + + + Yes + + + + No + + + + + ✓ Use Nexus in a single namespace + for separation of concerns and + easier future migration. + + + + + + Need cleaner contracts than + Child Workflows provide? + + + + + Yes + + + + No + + + + + + + + + ✓ Build in isolated namespaces now. + Use Nexus to connect them later. + + + + + + Use Child Workflows in a single namespace. + Migration to Nexus is straightforward later. + + + + + + + Question + + Use Nexus + + Alternative path + + \ No newline at end of file From 2d4bce5bd8f961b39042b0f3c23bc96ff7a61cbe Mon Sep 17 00:00:00 2001 From: Phil Prasek Date: Sun, 1 Mar 2026 11:47:21 -0800 Subject: [PATCH 2/2] update SDK guides description of Signal-With-Start Signed-off-by: Phil Prasek --- docs/develop/dotnet/temporal-nexus.mdx | 2 +- docs/develop/go/temporal-nexus.mdx | 2 +- docs/develop/java/temporal-nexus.mdx | 2 +- docs/develop/python/temporal-nexus.mdx | 2 +- docs/develop/typescript/temporal-nexus.mdx | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/develop/dotnet/temporal-nexus.mdx b/docs/develop/dotnet/temporal-nexus.mdx index 0c6ddc0a0c..aca5dd534c 100644 --- a/docs/develop/dotnet/temporal-nexus.mdx +++ b/docs/develop/dotnet/temporal-nexus.mdx @@ -171,7 +171,7 @@ public class HelloService ### Use the Temporal Client for Signals, Queries, and Updates A common pattern is to use the Temporal Client from within a sync handler to Signal, Query, or Update a Workflow. -You can also use Signal-With-Start or Update-With-Start to atomically start a Workflow and send it a Signal or Update. +You can also use Signal-With-Start or Update-With-Start to ensure the Workflow is started and send it a Signal or Update. All calls must complete within the [Nexus request timeout](/cloud/limits#nexus-operation-request-timeout). Updates should be short-lived to stay within this deadline. Use `NexusOperationExecutionContext.Current.TemporalClient` to get the Client that the Worker was initialized with: diff --git a/docs/develop/go/temporal-nexus.mdx b/docs/develop/go/temporal-nexus.mdx index a28874e8f5..c2112cf4d9 100644 --- a/docs/develop/go/temporal-nexus.mdx +++ b/docs/develop/go/temporal-nexus.mdx @@ -169,7 +169,7 @@ var EchoOperation = nexus.NewSyncOperation(service.EchoOperationName, func(ctx c ### Use the Temporal Client for Signals, Queries, and Updates A common pattern is to use the Temporal Client from within a sync handler to Signal, Query, or Update a Workflow. -You can also use Signal-With-Start or Update-With-Start to atomically start a Workflow and send it a Signal or Update. +You can also use Signal-With-Start or Update-With-Start to ensure the Workflow is started and send it a Signal or Update. All calls must complete within the [Nexus request timeout](/cloud/limits#nexus-operation-request-timeout). Updates should be short-lived to stay within this deadline. Use `temporalnexus.GetClient(ctx)` to get the Client that the Worker was initialized with: diff --git a/docs/develop/java/temporal-nexus.mdx b/docs/develop/java/temporal-nexus.mdx index e1878bab57..566b46f6cd 100644 --- a/docs/develop/java/temporal-nexus.mdx +++ b/docs/develop/java/temporal-nexus.mdx @@ -229,7 +229,7 @@ public class NexusServiceImpl { ### Use the Temporal Client for Signals, Queries, and Updates A common pattern is to use the Temporal Client from within a sync handler to Signal, Query, or Update a Workflow. -You can also use Signal-With-Start or Update-With-Start to atomically start a Workflow and send it a Signal or Update. +You can also use Signal-With-Start or Update-With-Start to ensure the Workflow is started and send it a Signal or Update. All calls must complete within the [Nexus request timeout](/cloud/limits#nexus-operation-request-timeout). Updates should be short-lived to stay within this deadline. Use `Nexus.getOperationContext().getWorkflowClient(ctx)` to get the Client that the Worker was initialized with: diff --git a/docs/develop/python/temporal-nexus.mdx b/docs/develop/python/temporal-nexus.mdx index d774c6e4fa..b61fe8c964 100644 --- a/docs/develop/python/temporal-nexus.mdx +++ b/docs/develop/python/temporal-nexus.mdx @@ -162,7 +162,7 @@ Implementations can also make other calls, but handlers should be reliable to av ### Use the Temporal Client for Signals, Queries, and Updates A common pattern is to use the Temporal Client from within a sync handler to Signal, Query, or Update a Workflow. -You can also use Signal-With-Start or Update-With-Start to atomically start a Workflow and send it a Signal or Update. +You can also use Signal-With-Start or Update-With-Start to ensure the Workflow is started and send it a Signal or Update. All calls must complete within the [Nexus request timeout](/cloud/limits#nexus-operation-request-timeout). Updates should be short-lived to stay within this deadline. Use `nexus.client()` to get the Client that the Worker was initialized with. diff --git a/docs/develop/typescript/temporal-nexus.mdx b/docs/develop/typescript/temporal-nexus.mdx index 950be0bb40..97cb449265 100644 --- a/docs/develop/typescript/temporal-nexus.mdx +++ b/docs/develop/typescript/temporal-nexus.mdx @@ -190,7 +190,7 @@ export const helloServiceHandler = nexus.serviceHandler(helloService, { ### Use the Temporal Client for Signals, Queries, and Updates A common pattern is to use the Temporal Client from within a sync handler to Signal, Query, or Update a Workflow. -You can also use Signal-With-Start or Update-With-Start to atomically start a Workflow and send it a Signal or Update. +You can also use Signal-With-Start or Update-With-Start to ensure the Workflow is started and send it a Signal or Update. All calls must complete within the [Nexus request timeout](/cloud/limits#nexus-operation-request-timeout). Updates should be short-lived to stay within this deadline. Use `getClient()` from `@temporalio/nexus` to get the Client connected to the same Namespace as the Worker: