Cleanup

Author: bergundy

packages/client/src/internal.ts

@@ -2,6 +2,8 @@ import { temporal } from '@temporalio/proto';
 
 // A key used internally to pass "hidden options to the WorkflowClient.start() call.
 export const InternalWorkflowStartOptionsKey = Symbol.for('__temporal_client_internal_workflow_start_options');
+
+// Hidden internal workflow start options, used by the temporal nexus helpers.
 export interface InternalWorkflowStartOptions {
   requestId?: string;
   /**

packages/client/src/workflow-client.ts

@@ -1278,7 +1278,6 @@ export class WorkflowClient extends BaseClient {
     const { identity, namespace } = this.options;
     const internalOptions = (opts as any)[InternalWorkflowStartOptionsKey] as InternalWorkflowStartOptions | undefined;
 
-    console.log(internalOptions);
     return {
       namespace,
       identity,

packages/nexus/src/context.ts

@@ -7,6 +7,7 @@ import { InternalWorkflowStartOptionsKey, InternalWorkflowStartOptions } from '@
 import { generateWorkflowRunOperationToken, loadWorkflowRunOperationToken } from './token';
 import { convertNexusLinkToWorkflowEventLink, convertWorkflowEventLinkToNexusLink } from './link-converter';
 
+// Context used internally in the SDK to propagate information from the worker to the Temporal Nexus helpers.
 export interface HandlerContext extends BaseHandlerContext {
   log: Logger;
   client: Client;
@@ -44,18 +45,27 @@ export const log: Logger = {
 // TODO: also support getting a metrics handler.
 
 /**
- * Returns a client to be used in a Nexus Operation's context, this Client is powered by the same Connection that the
- * worker was created with.
+ * Returns a client to be used in a Nexus Operation's context, this Client is powered by the same NativeConnection that
+ * the worker was created with.
  */
 export function getClient(): Client {
   return getHandlerContext<HandlerContext>().client;
 }
 
+/**
+ * A handle to a running workflow that is returned by the {@link startWorkflow} helper.
+ * This handle should be returned by {@link WorkflowRunOperationHandler} implementations.
+ */
 export interface WorkflowHandle<_T> {
   readonly workflowId: string;
   readonly runId: string;
 }
 
+/**
+ * Starts a workflow run for a {@link WorkflowRunOperationHandler}, linking the execution chain to a Nexus Operation
+ * (subsequent runs started from continue-as-new and retries). Automatically propagates the callback, request ID, and
+ * back and forward links from the Nexus options to the Workflow.
+ */
 export async function startWorkflow<T extends Workflow>(
   workflowTypeOrFunc: string | T,
   workflowOptions: WorkflowStartOptions<T>,
@@ -87,7 +97,7 @@ export async function startWorkflow<T extends Workflow>(
     internalOptions.completionCallbacks = [
       {
         nexus: { url: nexusOptions.callbackURL, header: nexusOptions.callbackHeaders },
-        links, // pass in links here as well, the server dedupes them.
+        links, // pass in links here as well for older servers, newer servers dedupe them.
       },
     ];
   }
@@ -103,11 +113,17 @@ export async function startWorkflow<T extends Workflow>(
   return { workflowId: handle.workflowId, runId: handle.firstExecutionRunId };
 }
 
+/**
+ * A handler function for the {@link WorkflowRunOperation} constructor.
+ */
 export type WorkflowRunOperationHandler<I, O> = (
   input: I,
   options: nexus.StartOperationOptions
 ) => Promise<WorkflowHandle<O>>;
 
+/**
+ * A Nexus Operation implementation that is backed by a Workflow run.
+ */
 export class WorkflowRunOperation<I, O> implements nexus.OperationHandler<I, O> {
   constructor(readonly handler: WorkflowRunOperationHandler<I, O>) {}
 

packages/test/src/test-nexus-handler.ts

@@ -47,9 +47,10 @@ test.before(async (t) => {
       extraArgs: [
         '--http-port',
         `${t.context.httpPort}`,
-        // SDK tests use arbitrary callback URLs, permit that on the server
+        // SDK tests use arbitrary callback URLs, permit that on the server.
         '--dynamic-config-value',
         'component.callbacks.allowedAddresses=[{"Pattern":"*","AllowInsecure":true}]',
+        // TODO: remove this config when it becomes the default on the server.
         '--dynamic-config-value',
         'history.enableRequestIdRefLinks=true',
       ],
@@ -638,7 +639,6 @@ test('WorkflowRunOperation attaches callback, link, and request ID', async (t) =
   };
   const nexusLink = convertWorkflowEventLinkToNexusLink(workflowLink);
 
-  // TODO: callback, link
   await w.runUntil(async () => {
     const backlinks = [];
     for (const requestId of [requestId1, requestId2]) {