Sample code for Nexus messaging (#457)

* Added Nexus messaging sample code

* Changes from code review

* Fixes for lint

* Update nexus-messaging/callerpattern/README.md

Co-authored-by: Andrew Yuan <andrew.yuan@temporal.io>

* Update nexus-messaging/callerpattern/README.md

Co-authored-by: Andrew Yuan <andrew.yuan@temporal.io>

* Update nexus-messaging/callerpattern/README.md

Co-authored-by: Andrew Yuan <andrew.yuan@temporal.io>

* Changes from code reviews

---------

Co-authored-by: Andrew Yuan <andrew.yuan@temporal.io>

Author: Evanthx

README.md

@@ -213,10 +213,16 @@ These samples demonstrate some common control flow patterns using Temporal's Go
 
 - [**Nexus Context Propagation**](./nexus-context-propagation): Demonstrates how to propagate context through client calls, workflows, and Nexus headers.
 
+
+
 ### Scenario based examples
 
 - [**Safe Message Handler**](./safe_message_handler): This demonstrates how to safely handle concurrent update and signal requests.
 
+- [**Nexus Messaging**](./nexus-messaging): Demonstrates how send signal, update and query messages through Nexus.
+  This contains two samples, one sending messages to an existing workflow and a second that creates a workflow through Nexus
+  and sends messages to it.
+
 - [**DSL Workflow**](./dsl): Demonstrates how to implement a
   DSL-based Workflow. This sample contains 2 yaml files that each define a custom "workflow" which instructs the
   Temporal Workflow. This is useful if you want to build in a "low code" layer.

nexus-messaging/README.md

@@ -0,0 +1,16 @@
+This sample shows how to expose a long-running Workflow's queries, updates, and signals as Nexus
+operations. There are two self-contained examples, each in its own directory:
+
+|                                | `callerpattern/`                     | `ondemandpattern/`                                           |
+|--------------------------------|--------------------------------------|--------------------------------------------------------------|
+| **Pattern**                    | Signal an existing Workflow          | Create and run Workflows on demand, and send signals to them |
+| **Who creates the Workflow?**  | The handler worker starts it on boot | The caller starts it via a Nexus operation                   |
+| **Who knows the Workflow ID?** | Only the handler                     | The caller chooses and passes it in every operation          |
+| **Nexus service**              | `NexusGreetingService`               | `NexusRemoteGreetingService`                                 |
+
+Each directory is fully self-contained for clarity. The
+`GreetingWorkflow`, `GreetingActivity`, and `Language` type are pretty much the same between the two -- only the
+Nexus service definition and its handler implementation differ. This highlights that the same Workflow can be
+exposed through Nexus in different ways depending on whether the caller needs lifecycle control.
+
+See each directory's README for running instructions.

nexus-messaging/callerpattern/README.md

@@ -0,0 +1,60 @@
+## Caller pattern
+
+The handler worker starts a `GreetingWorkflow` for a User ID.
+The Nexus handler holds that ID and routes every Nexus operation to it.
+The caller’s input doesn’t include the Workflow ID because it isn’t known. Instead, the caller provides the User ID, and the handler derives the Workflow ID from it (see `GetWorkflowID`).
+
+The handler worker uses the same `GetWorkflowID` call to generate a Workflow ID from a User ID when it launches the Workflow.
+
+The caller Workflow:
+1. Queries for supported languages (`getLanguages` -- backed by a query handler)
+2. Changes the language to Arabic (`setLanguage` -- backed by an update handler that calls an activity)
+3. Confirms the change via a second query (`getLanguage`)
+4. Approves the Workflow (`approve` -- backed by a signal handler)
+
+### Running
+
+Start a Temporal server:
+
+```bash
+temporal server start-dev
+```
+
+Create the namespaces and Nexus endpoint:
+
+```bash
+temporal operator namespace create --namespace my-target-namespace
+temporal operator namespace create --namespace my-caller-namespace
+
+temporal operator nexus endpoint create \
+  --name my-nexus-endpoint-name \
+  --target-namespace my-target-namespace \
+  --target-task-queue my-handler-task-queue
+```
+
+In one terminal, start the handler worker:
+
+```bash
+go run ./nexus-messaging/callerpattern/handler/worker/main.go
+```
+
+In a second terminal, start the caller worker:
+
+```bash
+go run ./nexus-messaging/callerpattern/caller/worker/main.go
+```
+
+In a third terminal, run the following command to start the example
+
+```bash
+go run ./nexus-messaging/callerpattern/caller/starter/main.go
+```
+
+Expected output:
+
+```
+[1] getLanguages returned 2 languages
+[2] setLanguage(Arabic) returned previous language: English
+[3] getLanguage returned: Arabic (confirmed Arabic)
+[4] approve sent successfully
+```

nexus-messaging/callerpattern/caller/starter/main.go

@@ -0,0 +1,42 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"time"
+
+	"go.temporal.io/sdk/client"
+
+	"github.com/temporalio/samples-go/nexus-messaging/callerpattern/caller"
+)
+
+func main() {
+	// Connect to the caller's namespace. For a non-local setup, provide additional
+	// client options such as HostPort and TLS credentials.
+	c, err := client.Dial(client.Options{Namespace: "my-caller-namespace"})
+	if err != nil {
+		log.Fatalln("Unable to create client", err)
+	}
+	defer c.Close()
+
+	ctx := context.Background()
+	workflowOptions := client.StartWorkflowOptions{
+		ID:        "nexus-messaging-caller-workflow-" + time.Now().Format("20060102150405"),
+		TaskQueue: caller.CallerTaskQueue,
+	}
+
+	wr, err := c.ExecuteWorkflow(ctx, workflowOptions, caller.CallerWorkflow, "default-user")
+	if err != nil {
+		log.Fatalln("Unable to execute workflow", err)
+	}
+	log.Println("Started workflow", "WorkflowID", wr.GetID(), "RunID", wr.GetRunID())
+
+	var result []string
+	if err := wr.Get(ctx, &result); err != nil {
+		log.Fatalln("Unable to get workflow result", err)
+	}
+	for i, entry := range result {
+		fmt.Printf("[%d] %s\n", i+1, entry)
+	}
+}

nexus-messaging/callerpattern/caller/worker/main.go

@@ -0,0 +1,28 @@
+package main
+
+import (
+	"log"
+
+	"go.temporal.io/sdk/client"
+	"go.temporal.io/sdk/worker"
+
+	"github.com/temporalio/samples-go/nexus-messaging/callerpattern/caller"
+)
+
+func main() {
+	// Connect to the caller's namespace. For a non-local setup, provide additional
+	// client options such as HostPort and TLS credentials.
+	c, err := client.Dial(client.Options{Namespace: "my-caller-namespace"})
+	if err != nil {
+		log.Fatalln("Unable to create client", err)
+	}
+	defer c.Close()
+
+	w := worker.New(c, caller.CallerTaskQueue, worker.Options{})
+	w.RegisterWorkflow(caller.CallerWorkflow)
+
+	err = w.Run(worker.InterruptCh())
+	if err != nil {
+		log.Fatalln("Unable to start worker", err)
+	}
+}

nexus-messaging/callerpattern/caller/workflows.go

@@ -0,0 +1,69 @@
+package caller
+
+import (
+	"fmt"
+
+	"go.temporal.io/sdk/workflow"
+
+	"github.com/temporalio/samples-go/nexus-messaging/callerpattern/service"
+)
+
+const (
+	CallerTaskQueue = "nexus-messaging-caller-task-queue"
+	endpointName    = "my-nexus-endpoint-name"
+)
+
+// CallerWorkflow calls the NexusGreetingService operations for a given userID
+// and returns a log of actions taken.
+func CallerWorkflow(ctx workflow.Context, userID string) ([]string, error) {
+	var log []string
+	c := workflow.NewNexusClient(endpointName, service.ServiceName)
+
+	// 1. Get supported languages.
+	fut := c.ExecuteOperation(ctx, service.GetLanguagesOperationName, service.GetLanguagesInput{
+		IncludeUnsupported: false,
+		UserID:             userID,
+	}, workflow.NexusOperationOptions{})
+	var langsOut service.GetLanguagesOutput
+	if err := fut.Get(ctx, &langsOut); err != nil {
+		return nil, fmt.Errorf("getLanguages failed: %w", err)
+	}
+	log = append(log, fmt.Sprintf("getLanguages returned %d languages", len(langsOut.Languages)))
+
+	// 2. Set language to Arabic.
+	fut = c.ExecuteOperation(ctx, service.SetLanguageOperationName, service.SetLanguageInput{
+		Language: service.Arabic,
+		UserID:   userID,
+	}, workflow.NexusOperationOptions{})
+	var prevLang service.Language
+	if err := fut.Get(ctx, &prevLang); err != nil {
+		return nil, fmt.Errorf("setLanguage failed: %w", err)
+	}
+	log = append(log, fmt.Sprintf("setLanguage(Arabic) returned previous language: %s", prevLang))
+
+	// 3. Get current language (assert it is Arabic).
+	fut = c.ExecuteOperation(ctx, service.GetLanguageOperationName, service.GetLanguageInput{
+		UserID: userID,
+	}, workflow.NexusOperationOptions{})
+	var currentLang service.Language
+	if err := fut.Get(ctx, &currentLang); err != nil {
+		return nil, fmt.Errorf("getLanguage failed: %w", err)
+	}
+	if currentLang != service.Arabic {
+		return nil, fmt.Errorf("expected Arabic, got %s", currentLang)
+	}
+	log = append(log, fmt.Sprintf("getLanguage returned: %s (confirmed Arabic)", currentLang))
+
+	// 4. Approve the workflow.
+	fut = c.ExecuteOperation(ctx, service.ApproveOperationName, service.ApproveInput{
+		Name:   "CallerWorkflow",
+		UserID: userID,
+	}, workflow.NexusOperationOptions{})
+	var approveOut service.ApproveOutput
+	if err := fut.Get(ctx, &approveOut); err != nil {
+		return nil, fmt.Errorf("approve failed: %w", err)
+	}
+	log = append(log, "approve sent successfully")
+
+	return log, nil
+}