temporalio/temporal

Nexus

Active contributors: alex, david, yichaoyang

Purpose

Nexus is Temporal's framework for composing services across namespaces and clusters. A workflow in namespace A can invoke a Nexus operation hosted by namespace B (or a non-Temporal HTTP service), and the result is delivered durably back to the caller. The full design document is at docs/architecture/nexus.md (~21KB).

What's involved

Inbound HTTP/gRPC at the Frontend.
State machines in History (HSM today, migrating to CHASM) tracking pending operations.
Outbound delivery via the History shard's outbound queue.
Endpoints — registered targets that map a Nexus service name to a worker task queue or HTTP URL.

Source map

Surface	File / package
Public proto	`temporal.api.nexus.v1.*` (in [`go.temporal.io/api`])
Frontend HTTP handlers	`service/frontend/nexus_handler.go` and siblings
Nexus endpoint client	`service/frontend/nexus_endpoint_client.go` and `service/matching/nexus_endpoint_client.go`
Nexus library helpers	`common/nexus/`
HSM components (today)	`components/nexusoperations/`
CHASM library (migration target)	`chasm/lib/nexusoperation/`
Outbound queue executor	`service/history/outbound_queue_active_task_executor.go`
Persistence	`nexus_endpoints` table; manager in `common/persistence/nexus_endpoint_manager.go`

How it works

sequenceDiagram
    participant Caller as Workflow A (namespace 1)
    participant FE as Frontend
    participant H as History (caller shard)
    participant Outbound as Outbound queue
    participant Target as Nexus target<br/>(namespace 2 / HTTP service)

    Caller->>FE: ScheduleNexusOperation command
    FE->>H: handler
    H->>H: append events,<br/>create HSM/CHASM node,<br/>schedule outbound task
    Outbound->>Target: HTTP/gRPC dispatch
    Target-->>FE: completion via Nexus inbound
    FE->>H: deliver completion to operation
    H->>Caller: Workflow Task with completion

A pending operation is tracked as a state machine inside the caller's workflow execution. The caller's shard owns the outbound delivery and retries on failure; the target's response (sync or async) feeds back through the Frontend's Nexus inbound handlers.

Endpoints

A Nexus endpoint is a registered routing target. Endpoint records live in the nexus_endpoints table (see common/persistence/nexus_endpoint_manager.go) and are managed via OperatorService RPCs. Endpoints are global; the cache is in common/nexus/.

Migration to CHASM

Nexus operations are mid-migration from HSM to CHASM:

HSM (current): components/nexusoperations/ — registered with the HSM library inside the workflow execution row.
CHASM (target): chasm/lib/nexusoperation/ — first-class CHASM Library with its own Engine entry points.

The two coexist behind feature flags; new behaviours are added to the CHASM side first.

Entry points for modification

Adding a Nexus operation type: if it's a generic HTTP target, no server change required — register the endpoint via the Operator API. Server-only operations (Nexus → workflow start) live in components/nexusoperations/ or chasm/lib/nexusoperation/.
Changing inbound auth: service/frontend/nexus_handler.go.
Changing outbound delivery (retry, headers): service/history/outbound_queue_active_task_executor.go.

Built by Factory AutoWiki from public repository content. It is a generated preview for codebase exploration, not source-maintained documentation.