Changes from reviewing

Evanthx · Evanthx · commit 2c57d9658d33 · 2026-04-14T16:53:06.000-07:00
diff --git a/src/NexusMessaging/CallerPattern/Caller/CallerWorkflow.workflow.cs b/src/NexusMessaging/CallerPattern/Caller/CallerWorkflow.workflow.cs
@@ -1,7 +1,7 @@
-namespace TemporalioSamples.NexusMessaging.Callerpattern.Caller;
+namespace TemporalioSamples.NexusMessaging.CallerPattern.Caller;
 
 using Temporalio.Workflows;
-using TemporalioSamples.NexusMessaging.Callerpattern;
+using TemporalioSamples.NexusMessaging.CallerPattern;
 using TemporalioSamples.NexusMessaging.Common;
 
 [Workflow]
diff --git a/src/NexusMessaging/CallerPattern/Handler/GreetingWorkflow.workflow.cs b/src/NexusMessaging/CallerPattern/Handler/GreetingWorkflow.workflow.cs
@@ -1,8 +1,8 @@
-namespace TemporalioSamples.NexusMessaging.Callerpattern.Handler;
+namespace TemporalioSamples.NexusMessaging.CallerPattern.Handler;
 
 using Temporalio.Exceptions;
 using Temporalio.Workflows;
-using TemporalioSamples.NexusMessaging.Callerpattern;
+using TemporalioSamples.NexusMessaging.CallerPattern;
 using TemporalioSamples.NexusMessaging.Common;
 
 [Workflow]
diff --git a/src/NexusMessaging/CallerPattern/Handler/NexusGreetingService.cs b/src/NexusMessaging/CallerPattern/Handler/NexusGreetingService.cs
@@ -1,23 +1,33 @@
-namespace TemporalioSamples.NexusMessaging.Callerpattern.Handler;
+namespace TemporalioSamples.NexusMessaging.CallerPattern.Handler;
 
 using NexusRpc.Handlers;
 using Temporalio.Nexus;
-using TemporalioSamples.NexusMessaging.Callerpattern;
+using TemporalioSamples.NexusMessaging.CallerPattern;
 using TemporalioSamples.NexusMessaging.Common;
 
+// Entity pattern: the handler worker pre-starts a GreetingWorkflow per user at boot time.
+// This service routes each Nexus operation to that existing workflow by deriving the
+// workflow ID from the caller-supplied UserId.
 [NexusServiceHandler(typeof(INexusGreetingService))]
 public class NexusGreetingService
 {
+    // OperationHandler.Sync means the result is returned inline to the Nexus caller
+    // (as opposed to WorkflowRunOperationHandler, which returns an async operation token).
+    // The lambda may still be async internally.
+
+    // Query: read-only, no state mutation — uses workflow query
     [NexusOperationHandler]
     public IOperationHandler<INexusGreetingService.GetLanguagesInput, INexusGreetingService.GetLanguagesOutput> GetLanguages() =>
         OperationHandler.Sync<INexusGreetingService.GetLanguagesInput, INexusGreetingService.GetLanguagesOutput>(
             async (ctx, input) =>
             {
+                // Access the Temporal client from the Nexus operation context
                 var client = NexusOperationExecutionContext.Current.TemporalClient;
                 var handle = client.GetWorkflowHandle<GreetingWorkflow>(WorkflowIdForUser(input.UserId));
                 return await handle.QueryAsync(wf => wf.QueryLanguages(input.IncludeUnsupported));
             });
 
+    // Query: read-only — returns the workflow's current language
     [NexusOperationHandler]
     public IOperationHandler<INexusGreetingService.GetLanguageInput, Language> GetLanguage() =>
         OperationHandler.Sync<INexusGreetingService.GetLanguageInput, Language>(
@@ -28,6 +38,7 @@ public class NexusGreetingService
                 return await handle.QueryAsync(wf => wf.QueryLanguage());
             });
 
+    // Update: mutates state and returns the previous value — uses workflow update
     [NexusOperationHandler]
     public IOperationHandler<INexusGreetingService.SetLanguageInput, Language> SetLanguage() =>
         OperationHandler.Sync<INexusGreetingService.SetLanguageInput, Language>(
@@ -38,6 +49,7 @@ public class NexusGreetingService
                 return await handle.ExecuteUpdateAsync(wf => wf.SetLanguageAsync(input.Language));
             });
 
+    // Signal: fire-and-forget, no return value needed — uses workflow signal
     [NexusOperationHandler]
     public IOperationHandler<INexusGreetingService.ApproveInput, NoValue> Approve() =>
         OperationHandler.Sync<INexusGreetingService.ApproveInput, NoValue>(
diff --git a/src/NexusMessaging/CallerPattern/INexusGreetingService.cs b/src/NexusMessaging/CallerPattern/INexusGreetingService.cs
@@ -1,12 +1,12 @@
-namespace TemporalioSamples.NexusMessaging.Callerpattern;
+namespace TemporalioSamples.NexusMessaging.CallerPattern;
 
 using NexusRpc;
 using TemporalioSamples.NexusMessaging.Common;
 
 [NexusService]
 public interface INexusGreetingService
 {
-    public static readonly string EndpointName = "nexus-messaging-nexus-endpoint";
+    static readonly string EndpointName = "nexus-messaging-nexus-endpoint";
 
     [NexusOperation]
     GetLanguagesOutput GetLanguages(GetLanguagesInput input);
diff --git a/src/NexusMessaging/CallerPattern/README.md b/src/NexusMessaging/CallerPattern/README.md
@@ -0,0 +1,51 @@
+## Entity pattern
+
+The handler worker starts a `GreetingWorkflow` for a user ID at boot time.
+`NexusGreetingService` routes every Nexus operation to that existing workflow by deriving
+the workflow ID from the caller-supplied `UserId` (see the `WorkflowIdForUser` call).
+The caller passes a `UserId`, not a workflow ID -- the handler is responsible for the
+ID mapping.
+
+The caller workflow:
+1. Queries for supported languages (`GetLanguages` -- backed by a workflow query)
+2. Queries the current language (`GetLanguage` -- backed by a workflow query)
+3. Changes the language to Chinese (`SetLanguage` -- backed by a workflow update that calls an activity)
+4. Approves the workflow (`Approve` -- backed by a workflow signal)
+
+### Running
+
+Start a Temporal server:
+
+```bash
+temporal server start-dev
+```
+
+Create the namespaces and Nexus endpoint:
+
+```bash
+temporal operator namespace create --namespace nexus-messaging-handler-namespace
+temporal operator namespace create --namespace nexus-messaging-caller-namespace
+
+temporal operator nexus endpoint create \
+  --name nexus-messaging-nexus-endpoint \
+  --target-namespace nexus-messaging-handler-namespace \
+  --target-task-queue nexus-messaging-handler-sample
+```
+
+In one terminal, start the handler worker:
+
+```bash
+dotnet run --project src/NexusMessaging -- handler-worker
+```
+
+In a second terminal, start the caller worker:
+
+```bash
+dotnet run --project src/NexusMessaging -- caller-worker
+```
+
+In a third terminal, start the caller workflow:
+
+```bash
+dotnet run --project src/NexusMessaging -- caller-workflow
+```
diff --git a/src/NexusMessaging/Common/GreetingActivities.cs b/src/NexusMessaging/Common/GreetingActivities.cs
diff --git a/src/NexusMessaging/Common/Language.cs b/src/NexusMessaging/Common/Language.cs
diff --git a/src/NexusMessaging/OnDemandPattern/Caller/CallerRemoteWorkflow.workflow.cs b/src/NexusMessaging/OnDemandPattern/Caller/CallerRemoteWorkflow.workflow.cs
@@ -1,8 +1,8 @@
-namespace TemporalioSamples.NexusMessaging.Ondemandpattern.Caller;
+namespace TemporalioSamples.NexusMessaging.OnDemandPattern.Caller;
 
 using Temporalio.Workflows;
 using TemporalioSamples.NexusMessaging.Common;
-using TemporalioSamples.NexusMessaging.Ondemandpattern;
+using TemporalioSamples.NexusMessaging.OnDemandPattern;
 
 [Workflow]
 public class CallerRemoteWorkflow
diff --git a/src/NexusMessaging/OnDemandPattern/Handler/GreetingWorkflow.workflow.cs b/src/NexusMessaging/OnDemandPattern/Handler/GreetingWorkflow.workflow.cs
@@ -1,9 +1,9 @@
-namespace TemporalioSamples.NexusMessaging.Ondemandpattern.Handler;
+namespace TemporalioSamples.NexusMessaging.OnDemandPattern.Handler;
 
 using Temporalio.Exceptions;
 using Temporalio.Workflows;
 using TemporalioSamples.NexusMessaging.Common;
-using TemporalioSamples.NexusMessaging.Ondemandpattern;
+using TemporalioSamples.NexusMessaging.OnDemandPattern;
 
 [Workflow]
 public class GreetingWorkflow
@@ -19,7 +19,7 @@ public class GreetingWorkflow
     private string approvedBy = string.Empty;
 
     [WorkflowRun]
-    public async Task<string> RunAsync(string workflowId)
+    public async Task<string> RunAsync(string userId)
     {
         // Wait for approve signal and all handlers to finish
         await Workflow.WaitConditionAsync(() => approved && Workflow.AllHandlersFinished);
diff --git a/src/NexusMessaging/OnDemandPattern/Handler/NexusRemoteGreetingService.cs b/src/NexusMessaging/OnDemandPattern/Handler/NexusRemoteGreetingService.cs
@@ -1,31 +1,44 @@
-namespace TemporalioSamples.NexusMessaging.Ondemandpattern.Handler;
+namespace TemporalioSamples.NexusMessaging.OnDemandPattern.Handler;
 
 using NexusRpc.Handlers;
 using Temporalio.Nexus;
 using TemporalioSamples.NexusMessaging.Common;
-using TemporalioSamples.NexusMessaging.Ondemandpattern;
+using TemporalioSamples.NexusMessaging.OnDemandPattern;
 
+// On-demand pattern: no workflow is pre-started. The caller creates workflow instances
+// through Nexus operations. Each operation includes a UserId so the handler can derive
+// the target workflow ID.
 [NexusServiceHandler(typeof(INexusRemoteGreetingService))]
 public class NexusRemoteGreetingService
 {
+    // WorkflowRunOperationHandler starts a backing workflow and returns its handle to the
+    // Nexus infrastructure. The caller receives an async operation token and can poll for
+    // the workflow result later via GetResultAsync.
     [NexusOperationHandler]
     public IOperationHandler<INexusRemoteGreetingService.RunFromRemoteInput, string> RunFromRemote() =>
         WorkflowRunOperationHandler.FromHandleFactory(
             (WorkflowRunOperationContext context, INexusRemoteGreetingService.RunFromRemoteInput input) =>
                 context.StartWorkflowAsync(
-                    (GreetingWorkflow wf) => wf.RunAsync(GetWorkflowId(input.UserId)),
+                    (GreetingWorkflow wf) => wf.RunAsync(input.UserId),
                     new() { Id = GetWorkflowId(input.UserId) }));
 
+    // OperationHandler.Sync means the result is returned inline to the Nexus caller
+    // (as opposed to WorkflowRunOperationHandler, which returns an async operation token).
+    // The lambda may still be async internally.
+
+    // Query: read-only, no state mutation — uses workflow query
     [NexusOperationHandler]
     public IOperationHandler<INexusRemoteGreetingService.GetLanguagesInput, INexusRemoteGreetingService.GetLanguagesOutput> GetLanguages() =>
         OperationHandler.Sync<INexusRemoteGreetingService.GetLanguagesInput, INexusRemoteGreetingService.GetLanguagesOutput>(
             async (ctx, input) =>
             {
+                // Access the Temporal client from the Nexus operation context
                 var client = NexusOperationExecutionContext.Current.TemporalClient;
                 var handle = client.GetWorkflowHandle<GreetingWorkflow>(GetWorkflowId(input.UserId));
                 return await handle.QueryAsync(wf => wf.QueryLanguages(input.IncludeUnsupported));
             });
 
+    // Query: read-only — returns the workflow's current language
     [NexusOperationHandler]
     public IOperationHandler<INexusRemoteGreetingService.GetLanguageInput, Language> GetLanguage() =>
         OperationHandler.Sync<INexusRemoteGreetingService.GetLanguageInput, Language>(
@@ -36,6 +49,7 @@ public class NexusRemoteGreetingService
                 return await handle.QueryAsync(wf => wf.QueryLanguage());
             });
 
+    // Update: mutates state and returns the previous value — uses workflow update
     [NexusOperationHandler]
     public IOperationHandler<INexusRemoteGreetingService.SetLanguageInput, Language> SetLanguage() =>
         OperationHandler.Sync<INexusRemoteGreetingService.SetLanguageInput, Language>(
@@ -46,6 +60,7 @@ public class NexusRemoteGreetingService
                 return await handle.ExecuteUpdateAsync(wf => wf.SetLanguageAsync(input.Language));
             });
 
+    // Signal: fire-and-forget, no return value needed — uses workflow signal
     [NexusOperationHandler]
     public IOperationHandler<INexusRemoteGreetingService.ApproveInput, NoValue> Approve() =>
         OperationHandler.Sync<INexusRemoteGreetingService.ApproveInput, NoValue>(
diff --git a/src/NexusMessaging/OnDemandPattern/INexusRemoteGreetingService.cs b/src/NexusMessaging/OnDemandPattern/INexusRemoteGreetingService.cs
@@ -1,12 +1,12 @@
-namespace TemporalioSamples.NexusMessaging.Ondemandpattern;
+namespace TemporalioSamples.NexusMessaging.OnDemandPattern;
 
 using NexusRpc;
 using TemporalioSamples.NexusMessaging.Common;
 
 [NexusService]
 public interface INexusRemoteGreetingService
 {
-    public static readonly string EndpointName = "nexus-messaging-nexus-endpoint";
+    static readonly string EndpointName = "nexus-messaging-nexus-endpoint";
 
     [NexusOperation]
     string RunFromRemote(RunFromRemoteInput input);
diff --git a/src/NexusMessaging/OnDemandPattern/README.md b/src/NexusMessaging/OnDemandPattern/README.md
@@ -0,0 +1,50 @@
+## On-demand pattern
+
+No workflow is pre-started. The caller creates and controls workflow instances through Nexus
+operations. `NexusRemoteGreetingService` adds a `RunFromRemote` operation that starts a new
+`GreetingWorkflow`, and every other operation includes a `UserId` so the handler can derive
+the target workflow ID.
+
+The caller workflow:
+1. Starts two remote `GreetingWorkflow` instances via `RunFromRemote` (backed by `WorkflowRunOperationHandler`)
+2. Workflow one: queries supported languages, changes to Spanish, and approves
+3. Workflow two: queries the current language, changes to French, and approves
+4. Waits for each to complete and returns their results
+
+### Running
+
+Start a Temporal server:
+
+```bash
+temporal server start-dev
+```
+
+Create the namespaces and Nexus endpoint:
+
+```bash
+temporal operator namespace create --namespace nexus-messaging-handler-namespace
+temporal operator namespace create --namespace nexus-messaging-caller-namespace
+
+temporal operator nexus endpoint create \
+  --name nexus-messaging-nexus-endpoint \
+  --target-namespace nexus-messaging-handler-namespace \
+  --target-task-queue nexus-messaging-handler-sample
+```
+
+In one terminal, start the handler worker:
+
+```bash
+dotnet run --project src/NexusMessaging -- remote-handler-worker
+```
+
+In a second terminal, start the caller worker:
+
+```bash
+dotnet run --project src/NexusMessaging -- remote-caller-worker
+```
+
+In a third terminal, start the caller workflow:
+
+```bash
+dotnet run --project src/NexusMessaging -- remote-caller-workflow
+```
diff --git a/src/NexusMessaging/Program.cs b/src/NexusMessaging/Program.cs
@@ -2,15 +2,13 @@
 using Temporalio.Client;
 using Temporalio.Common.EnvConfig;
 using Temporalio.Worker;
-using TemporalioSamples.NexusMessaging.Callerpattern;
-using TemporalioSamples.NexusMessaging.Callerpattern.Caller;
-using TemporalioSamples.NexusMessaging.Callerpattern.Handler;
+using TemporalioSamples.NexusMessaging.CallerPattern.Caller;
+using TemporalioSamples.NexusMessaging.CallerPattern.Handler;
 using TemporalioSamples.NexusMessaging.Common;
-using TemporalioSamples.NexusMessaging.Ondemandpattern;
-using TemporalioSamples.NexusMessaging.Ondemandpattern.Caller;
-using CallerGreetingWorkflow = TemporalioSamples.NexusMessaging.Callerpattern.Handler.GreetingWorkflow;
-using OndemandGreetingWorkflow = TemporalioSamples.NexusMessaging.Ondemandpattern.Handler.GreetingWorkflow;
-using OndemandNexusService = TemporalioSamples.NexusMessaging.Ondemandpattern.Handler.NexusRemoteGreetingService;
+using TemporalioSamples.NexusMessaging.OnDemandPattern.Caller;
+using CallerGreetingWorkflow = TemporalioSamples.NexusMessaging.CallerPattern.Handler.GreetingWorkflow;
+using OnDemandGreetingWorkflow = TemporalioSamples.NexusMessaging.OnDemandPattern.Handler.GreetingWorkflow;
+using OnDemandNexusService = TemporalioSamples.NexusMessaging.OnDemandPattern.Handler.NexusRemoteGreetingService;
 
 using var loggerFactory = LoggerFactory.Create(builder =>
     builder.
@@ -28,8 +26,8 @@
 
 const string HandlerNamespace = "nexus-messaging-handler-namespace";
 const string CallerNamespace = "nexus-messaging-caller-namespace";
-const string HandlerTaskQueue = "nexus-messaging-handler-task-queue";
-const string CallerTaskQueue = "nexus-messaging-caller-task-queue";
+const string HandlerTaskQueue = "nexus-messaging-handler-sample";
+const string CallerTaskQueue = "nexus-messaging-caller-sample";
 
 Task<TemporalClient> ConnectClientAsync(string temporalNamespace)
 {
@@ -115,8 +113,8 @@ async Task RunRemoteHandlerWorkerAsync()
     using var worker = new TemporalWorker(
         await ConnectClientAsync(HandlerNamespace),
         new TemporalWorkerOptions(HandlerTaskQueue).
-            AddNexusService(new OndemandNexusService()).
-            AddWorkflow<OndemandGreetingWorkflow>().
+            AddNexusService(new OnDemandNexusService()).
+            AddWorkflow<OnDemandGreetingWorkflow>().
             AddAllActivities(new GreetingActivities()));
     try
     {
diff --git a/src/NexusMessaging/README.md b/src/NexusMessaging/README.md
diff --git a/tests/NexusMessaging/CallerPatternTests.cs b/tests/NexusMessaging/CallerPatternTests.cs
diff --git a/tests/NexusMessaging/OnDemandPatternTests.cs b/tests/NexusMessaging/OnDemandPatternTests.cs
