nexus-operations

name: nexus-operations description: Temporal Nexus implementation guidance for cross-namespace durable communication. Use when user asks about "nexus", "nexus operation", "nexus service", "nexus endpoint", "cross-namespace communication", "nexus caller", "nexus handler", "NexusClient", "ExecuteOperation", "WorkflowRunOperation", or "multi-namespace". Covers Go SDK (GA), with TypeScript/Python/Java in references. Do NOT use for architecture decisions about whether to adopt Nexus — use nexus-decision-guide instead. version: 1.0.0

Nexus Operations

Cross-namespace durable communication using Temporal Nexus (GA).

Overview

Nexus enables workflows in separate namespaces to call each other through typed service contracts with Temporal's full durable execution guarantees.

Architecture:

┌──────────────────┐   Nexus Endpoint   ┌──────────────────┐
│  Caller Namespace │──────────────────>│ Handler Namespace │
│  ┌──────────────┐│   (routes to       │┌────────────────┐│
│  │Caller Workflow││   target NS +     ││Handler Worker   ││
│  │  NexusClient  ││   task queue)     ││ NexusService    ││
│  └──────────────┘│                    │└────────────────┘│
└──────────────────┘                    └──────────────────┘

When to Use Nexus

Use Nexus when:

• Teams maintain separate namespaces and need to call each other's workflows
• You need durable execution guarantees across namespace boundaries
• You want clean, typed service contracts between teams/services
• You need both synchronous (< 10s) and asynchronous (long-running) cross-namespace calls

Don't use Nexus when:

• All workflows live in one namespace — use child workflows instead
• You need simple fire-and-forget notifications — use signals
• You need quick external API calls from workflows — use activities
• You need synchronous state mutation on a running workflow — use updates
• The added complexity (endpoints, handler workers, service contracts) isn't justified by the isolation benefits

Choosing the Right Pattern

SDK Support

Key Concepts

Nexus Endpoint: A cluster-level routing resource that maps a name to a target namespace + task queue. Decouples callers from handler location. Created via CLI or Terraform.

Nexus Service: A named collection of Nexus Operations. Defines the microservice contract. Registered on handler workers.

Nexus Operation: An arbitrary-duration operation — either:

• Synchronous: RPC-style, completes immediately (< 10s), handler returns result directly
• Asynchronous: Starts a workflow as the backing operation, returns an operation token for tracking

Nexus Machinery: Temporal's built-in infrastructure providing at-least-once execution, automatic retries, circuit breaking, and rate limiting for Nexus calls.

Endpoint Setup

Prerequisites: caller and handler namespaces must exist.

# Create namespaces (if not already present)
temporal operator namespace create --namespace handler-ns
temporal operator namespace create --namespace caller-ns

# Create Nexus endpoint
temporal operator nexus endpoint create \
  --name my-endpoint \
  --target-namespace handler-ns \
  --target-task-queue handler-tq

# List endpoints
temporal operator nexus endpoint list

# Describe endpoint
temporal operator nexus endpoint describe --name my-endpoint

# Update endpoint
temporal operator nexus endpoint update \
  --name my-endpoint \
  --target-task-queue new-handler-tq

# Delete endpoint
temporal operator nexus endpoint delete --name my-endpoint

Handler Implementation (Go SDK)

Synchronous Operation

For requests completing in < 10 seconds:

import (
    "context"
    "github.com/nexus-rpc/sdk-go/nexus"
)

// Synchronous operation — returns result directly
var EchoOp = nexus.NewSyncOperation("echo",
    func(ctx context.Context, input EchoInput, opts nexus.StartOperationOptions) (EchoOutput, error) {
        return EchoOutput{Message: input.Message}, nil
    })

Asynchronous (Workflow-Backed) Operation

For long-running processes:

import (
    "context"
    "go.temporal.io/sdk/client"
    temporalnexus "go.temporal.io/sdk/temporalnexus"
)

// Async operation — starts a workflow, returns when workflow completes
var ProcessOrderOp = temporalnexus.NewWorkflowRunOperation("process-order",
    ProcessOrderWorkflow,
    func(ctx context.Context, input OrderInput, opts nexus.StartOperationOptions) (client.StartWorkflowOptions, error) {
        return client.StartWorkflowOptions{
            // Use RequestID as workflow ID to deduplicate retries
            ID: opts.RequestID,
        }, nil
    })

Service Definition and Worker Registration

import (
    "github.com/nexus-rpc/sdk-go/nexus"
    "go.temporal.io/sdk/worker"
)

// Create and register service
func registerNexusService(w worker.Worker) {
    service := nexus.NewService("order-service")
    service.Register(EchoOp)
    service.Register(ProcessOrderOp)
    w.RegisterNexusService(service)
}

Other SDK Implementations

For TypeScript (experimental), Python (public preview), and Java (GA) handler and caller examples, see references/nexus-multi-sdk.md.

Caller Workflow Patterns (Go SDK)

func CallerWorkflow(ctx workflow.Context, input CallerInput) (*CallerOutput, error) {
    // Create Nexus client — endpoint name + service name
    nexusClient := workflow.NewNexusClient("my-endpoint", "order-service")

    // Execute operation (blocks until result)
    future := nexusClient.ExecuteOperation(ctx, ProcessOrderOp, OrderInput{
        ID: input.OrderID,
    }, workflow.NexusOperationOptions{
        ScheduleToCloseTimeout: 10 * time.Minute,
    })

    var result OrderOutput
    if err := future.Get(ctx, &result); err != nil {
        return nil, fmt.Errorf("nexus operation failed: %w", err)
    }

    return &CallerOutput{OrderResult: result}, nil
}

Error Handling

Error Types

Handling Errors in Callers (Go)

var result OrderOutput
if err := future.Get(ctx, &result); err != nil {
    var nexusErr *temporal.NexusOperationFailure
    if errors.As(err, &nexusErr) {
        // Application-level failure from handler
        logger.Error("Nexus operation failed", "error", nexusErr)
        return nil, err
    }
    // Other errors (timeout, cancellation)
    return nil, err
}

Returning Errors from Handlers (Go)

var ProcessOp = nexus.NewSyncOperation("process",
    func(ctx context.Context, input Input, opts nexus.StartOperationOptions) (Output, error) {
        if input.ID == "" {
            // Return application error — caller gets NexusOperationFailure
            return Output{}, nexus.HandlerErrorf(nexus.HandlerErrorTypeBadRequest, "ID is required")
        }
        return Output{Result: "ok"}, nil
    })

Event History

Nexus-specific events in caller workflow history:

Best Practices

• Use sync operations for < 10s requests — simpler, lower overhead
• Use async (workflow-backed) for long-running work — gets full workflow durability
• Deduplicate with RequestID — use opts.RequestID as workflow ID in async handlers to safely handle retries
• Implement idempotent handlers — Nexus provides at-least-once semantics, so handlers may be called more than once
• Always set scheduleToCloseTimeout on caller side — without it, operations may hang indefinitely
• Treat Nexus service contracts as stable APIs — they're microservice boundaries; version them carefully
• Use separate namespaces for caller and handler to get true isolation benefits
• Don't use Nexus within a single namespace — child workflows are simpler and equally durable

Additional Resources

Reference Files

For detailed patterns, consult:

• references/nexus-patterns.md - Advanced Nexus usage patterns
• references/nexus-multi-sdk.md - Multi-SDK implementation examples