@temporalio/nexus 1.17.2 → 1.17.3

package/lib/context.d.ts

@@ -15,7 +15,6 @@ export interface HandlerContext {
     client: Client;
     namespace: string;
     taskQueue: string;
-    endpoint: string;
 }
 /**
  * Holds information about the current Nexus Operation Execution.
@@ -31,11 +30,6 @@ export interface OperationInfo {
      * Task Queue this Nexus Operation is executing on
      */
     readonly taskQueue: string;
-    /**
-     * Nexus Endpoint this Operation was routed through.
-     * Only available with server version 1.30.0 or later.
-     */
-    readonly endpoint: string;
 }
 /**
  * A logger for use in Nexus Handler scope.

package/lib/context.js

@@ -96,7 +96,6 @@ function operationInfo() {
     return {
         namespace: ctx.namespace,
         taskQueue: ctx.taskQueue,
-        endpoint: ctx.endpoint,
     };
 }
 //# sourceMappingURL=context.js.map

package/lib/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temporalio/nexus",
-  "version": "1.17.2",
+  "version": "1.17.3",
   "description": "Temporal.io SDK Nexus sub-package",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -17,15 +17,15 @@
     "concurrency": 1,
     "workerThreads": false
   },
-  "devDependencies": {
-    "ava": "^5.3.1"
-  },
   "dependencies": {
     "long": "^5.2.3",
     "nexus-rpc": "^0.0.2",
-    "@temporalio/client": "1.17.2",
-    "@temporalio/common": "1.17.2",
-    "@temporalio/proto": "1.17.2"
+    "@temporalio/proto": "1.17.3",
+    "@temporalio/common": "1.17.3",
+    "@temporalio/client": "1.17.3"
+  },
+  "devDependencies": {
+    "ava": "^5.3.1"
   },
   "bugs": {
     "url": "https://github.com/temporalio/sdk-typescript/issues"

package/src/context.ts

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
+import type * as nexus from 'nexus-rpc';
 import type { Logger, LogLevel, LogMetadata, MetricMeter } from '@temporalio/common';
 import type { Client } from '@temporalio/client';
 
@@ -57,6 +58,24 @@ export interface OperationInfo {
   readonly endpoint: string;
 }
 
+/**
+ * Context received by a {@link TemporalOperationHandler}'s start handler when a Nexus Operation is
+ * started.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface TemporalStartOperationContext extends nexus.StartOperationContext {}
+
+/**
+ * Context received by a {@link TemporalOperationHandler}'s cancel handler when a Nexus Operation is
+ * canceled.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface TemporalCancelOperationContext extends nexus.CancelOperationContext {}
+
 // Basic APIs //////////////////////////////////////////////////////////////////////////////////////
 
 /**

package/src/index.ts

@@ -11,10 +11,18 @@ export {
   metricMeter,
   operationInfo,
   type OperationInfo,
+  type TemporalCancelOperationContext,
+  type TemporalStartOperationContext,
 } from './context';
 
 export {
   startWorkflow,
+  type CancelWorkflowRunOptions,
+  type TemporalOperationHandlerOptions,
+  TemporalOperationHandler,
+  TemporalOperationResult,
+  type TemporalNexusClient,
+  type TemporalOperationStartHandler,
   WorkflowHandle,
   WorkflowRunOperationHandler,
   WorkflowRunOperationStartHandler,

package/src/link-converter.ts

@@ -3,7 +3,9 @@ import type { Link as NexusLink } from 'nexus-rpc';
 import { temporal } from '@temporalio/proto';
 
 const { EventType } = temporal.api.enums.v1;
+type TemporalLink = temporal.api.common.v1.ILink;
 type WorkflowEventLink = temporal.api.common.v1.Link.IWorkflowEvent;
+type NexusOperationLink = temporal.api.common.v1.Link.INexusOperation;
 type EventReference = temporal.api.common.v1.Link.WorkflowEvent.IEventReference;
 type RequestIdReference = temporal.api.common.v1.Link.WorkflowEvent.IRequestIdReference;
 
@@ -11,12 +13,46 @@ const LINK_EVENT_ID_PARAM = 'eventID';
 const LINK_EVENT_TYPE_PARAM = 'eventType';
 const LINK_REQUEST_ID_PARAM = 'requestID';
 const LINK_REFERENCE_TYPE_KEY = 'referenceType';
+const LINK_RUN_ID_KEY = 'runID';
 
 const EVENT_REFERENCE_TYPE = 'EventReference';
 const REQUEST_ID_REFERENCE_TYPE = 'RequestIdReference';
 
 // fullName isn't part of the generated typed unfortunately.
 const WORKFLOW_EVENT_TYPE: string = (temporal.api.common.v1.Link.WorkflowEvent as any).fullName.slice(1);
+const NEXUS_OPERATION_TYPE: string = (temporal.api.common.v1.Link.NexusOperation as any).fullName.slice(1);
+
+export function convertTemporalLinkToNexusLink(link: TemporalLink): NexusLink {
+  if (link.workflowEvent != null) {
+    return convertWorkflowEventLinkToNexusLink(link.workflowEvent);
+  }
+
+  if (link.nexusOperation != null) {
+    return convertNexusOperationLinkToNexusLink(link.nexusOperation);
+  }
+
+  throw new TypeError('Invalid Temporal link: unknown variant');
+}
+
+export function convertNexusLinkToTemporalLink(link: NexusLink): TemporalLink {
+  if (link.url.protocol !== 'temporal:') {
+    throw new TypeError(`Invalid URL scheme: ${link.url}, expected 'temporal:', got '${link.url.protocol}'`);
+  }
+  switch (link.type) {
+    case WORKFLOW_EVENT_TYPE:
+      return {
+        workflowEvent: convertNexusLinkToWorkflowEventLink(link),
+      };
+
+    case NEXUS_OPERATION_TYPE:
+      return {
+        nexusOperation: convertNexusLinkToNexusOperationLink(link),
+      };
+
+    default:
+      throw new TypeError(`Unknown link type: ${link.type}`);
+  }
+}
 
 export function convertWorkflowEventLinkToNexusLink(we: WorkflowEventLink): NexusLink {
   if (!we.namespace || !we.workflowId || !we.runId) {
@@ -40,11 +76,30 @@ export function convertWorkflowEventLinkToNexusLink(we: WorkflowEventLink): Nexu
   };
 }
 
-export function convertNexusLinkToWorkflowEventLink(link: NexusLink): WorkflowEventLink {
-  if (link.url.protocol !== 'temporal:') {
-    throw new TypeError(`Invalid URL scheme: ${link.url}, expected 'temporal:', got '${link.url.protocol}'`);
+export function convertNexusOperationLinkToNexusLink(opLink: NexusOperationLink): NexusLink {
+  if (!opLink.namespace || !opLink.operationId) {
+    throw new TypeError('Missing required fields: namespace, or operationId');
+  }
+
+  const url = new URL(
+    `temporal:///namespaces/${encodeURIComponent(opLink.namespace)}/nexus-operations/${encodeURIComponent(
+      opLink.operationId
+    )}`
+  );
+
+  if (opLink.runId != null) {
+    const searchParams = new URLSearchParams();
+    searchParams.set(LINK_RUN_ID_KEY, opLink.runId);
+    url.search = searchParams.toString();
   }
 
+  return {
+    url,
+    type: NEXUS_OPERATION_TYPE,
+  };
+}
+
+export function convertNexusLinkToWorkflowEventLink(link: NexusLink): WorkflowEventLink {
   // /namespaces/:namespace/workflows/:workflowId/:runId/history
   const parts = link.url.pathname.split('/');
   if (parts.length !== 7 || parts[1] !== 'namespaces' || parts[3] !== 'workflows' || parts[6] !== 'history') {
@@ -76,6 +131,25 @@ export function convertNexusLinkToWorkflowEventLink(link: NexusLink): WorkflowEv
   return workflowEventLink;
 }
 
+function convertNexusLinkToNexusOperationLink(link: NexusLink): NexusOperationLink {
+  // /namespaces/:namespace/nexus-operations/:operationId?runId=:runId
+  const parts = link.url.pathname.split('/');
+  if (parts.length !== 5 || parts[1] !== 'namespaces' || parts[3] !== 'nexus-operations') {
+    throw new TypeError(`Invalid URL path: ${link.url}`);
+  }
+  const namespace = decodeURIComponent(parts[2]!);
+  const operationId = decodeURIComponent(parts[4]!);
+
+  const query = link.url.searchParams;
+  const runId = query.get(LINK_RUN_ID_KEY);
+
+  return {
+    namespace,
+    operationId,
+    runId,
+  };
+}
+
 function convertLinkWorkflowEventEventReferenceToURLQuery(eventRef: EventReference): string {
   const params = new URLSearchParams();
   params.set(LINK_REFERENCE_TYPE_KEY, EVENT_REFERENCE_TYPE);

package/src/token.ts

@@ -1,39 +1,57 @@
 /**
- * OperationTokenType is used to identify the type of Operation token.
- * Currently, we only have one type of Operation token: WorkflowRun.
+ * Serializable token identifying a Nexus operation target.
  *
  * @internal
  * @hidden
  */
-export interface WorkflowRunOperationToken {
+export interface OperationToken {
   /**
-   * Version of the token, by default we assume we're on version 1, this field is not emitted as part of the output,
+   * Version of the token, by default we assume we're on version 0, this field is not emitted as part of the output,
    * it's only used to reject newer token versions on load.
    */
   v?: number;
 
   /**
-   * Type of the Operation. Must be OPERATION_TOKEN_TYPE_WORKFLOW_RUN.
+   * Type of the Operation.
    */
   t: OperationTokenType;
 
   /**
-   * Namespace of the workflow.
+   * Namespace of the operation.
    */
   ns: string;
 
   /**
    * ID of the workflow.
    */
+  wid?: string;
+}
+
+/**
+ * An OperationToken that identifies a WorkflowRun operation.
+ *
+ * @internal
+ * @hidden
+ */
+export interface WorkflowRunOperationToken extends OperationToken {
+  t: typeof OperationTokenType.WORKFLOW_RUN;
   wid: string;
 }
-type OperationTokenType = (typeof OperationTokenType)[keyof typeof OperationTokenType];
+
+/**
+ * OperationTokenType is used to identify the type of Operation token.
+ * Currently, we only have one type of Operation token: WorkflowRun.
+ *
+ * @internal
+ * @hidden
+ */
+export type OperationTokenType = (typeof OperationTokenType)[keyof typeof OperationTokenType];
 
 /**
  * @internal
  * @hidden
  */
-const OperationTokenType = {
+export const OperationTokenType = {
   WORKFLOW_RUN: 1,
 } as const;
 
@@ -50,11 +68,11 @@ export function generateWorkflowRunOperationToken(namespace: string, workflowId:
 }
 
 /**
- * Load and validate a workflow run Operation token.
+ * Load and validate the common fields of an Operation token.
  */
-export function loadWorkflowRunOperationToken(data: string): WorkflowRunOperationToken {
+export function loadOperationToken(data: string): OperationToken {
   if (!data) {
-    throw new TypeError('invalid workflow run token: token is empty');
+    throw new TypeError('invalid operation token: token is empty');
   }
 
   let decoded: string;
@@ -64,26 +82,57 @@ export function loadWorkflowRunOperationToken(data: string): WorkflowRunOperatio
     throw new TypeError('failed to decode token', { cause: err });
   }
 
-  let token: WorkflowRunOperationToken;
+  let token: OperationToken;
   try {
     token = JSON.parse(decoded);
   } catch (err) {
-    throw new TypeError('failed to unmarshal workflow run Operation token', { cause: err });
+    throw new TypeError('failed to unmarshal Operation token', { cause: err });
   }
 
-  if (token.t !== OperationTokenType.WORKFLOW_RUN) {
-    throw new TypeError(`invalid workflow token type: ${token.t}, expected: ${OperationTokenType.WORKFLOW_RUN}`);
+  if (typeof token !== 'object' || token == null) {
+    throw new TypeError(`invalid operation token: expected object, got ${typeof token}`);
   }
   if (token.v !== undefined && token.v !== 0) {
-    throw new TypeError('invalid workflow run token: "v" field should not be present');
+    throw new TypeError('invalid operation token: "v" field should not be present');
   }
-  if (!token.wid) {
-    throw new TypeError('invalid workflow run token: missing workflow ID (wid)');
+  if (typeof token.t !== 'number') {
+    throw new TypeError(`invalid operation token: expected token type to be a number, got ${typeof token.t}`);
+  }
+  if (!isOperationTokenType(token.t)) {
+    throw new TypeError(`invalid operation token: unknown token type: ${token.t}`);
+  }
+  if (typeof token.ns !== 'string') {
+    throw new TypeError(`invalid operation token: expected namespace to be a string, got ${typeof token.ns}`);
   }
 
   return token;
 }
 
+/**
+ * Load and validate a workflow run Operation token.
+ */
+export function loadWorkflowRunOperationToken(data: string): WorkflowRunOperationToken {
+  const token = loadOperationToken(data);
+  assertWorkflowRunOperationToken(token);
+  return token;
+}
+
+/**
+ * Assert that an OperationToken identifies a workflow run.
+ */
+export function assertWorkflowRunOperationToken(token: OperationToken): asserts token is WorkflowRunOperationToken {
+  if (token.t !== OperationTokenType.WORKFLOW_RUN) {
+    throw new TypeError(`invalid workflow token type: ${token.t}, expected: ${OperationTokenType.WORKFLOW_RUN}`);
+  }
+  if (!token.wid || typeof token.wid !== 'string') {
+    throw new TypeError('invalid workflow run token: missing workflow ID (wid)');
+  }
+}
+
+function isOperationTokenType(value: number): value is OperationTokenType {
+  return Object.values(OperationTokenType).includes(value as OperationTokenType);
+}
+
 // Exported for use in tests.
 export function base64URLEncodeNoPadding(str: string): string {
   const base64 = Buffer.from(str).toString('base64url');

package/src/workflow-helpers.ts

@@ -1,13 +1,25 @@
 import * as nexus from 'nexus-rpc';
 import type { Workflow, WorkflowResultType } from '@temporalio/common';
 import type { Replace } from '@temporalio/common/lib/type-helpers';
-import type { WorkflowStartOptions as ClientWorkflowStartOptions } from '@temporalio/client';
+import type { Client, WorkflowStartOptions as ClientWorkflowStartOptions } from '@temporalio/client';
 import { type temporal } from '@temporalio/proto';
 import type { InternalWorkflowStartOptions } from '@temporalio/client/lib/internal';
 import { InternalWorkflowStartOptionsSymbol } from '@temporalio/client/lib/internal';
-import { generateWorkflowRunOperationToken, loadWorkflowRunOperationToken } from './token';
-import { convertNexusLinkToWorkflowEventLink, convertWorkflowEventLinkToNexusLink } from './link-converter';
-import { getClient, getHandlerContext, log } from './context';
+import { convertNexusLinkToTemporalLink, convertTemporalLinkToNexusLink } from './link-converter';
+import {
+  assertWorkflowRunOperationToken,
+  generateWorkflowRunOperationToken,
+  loadOperationToken,
+  loadWorkflowRunOperationToken,
+  OperationTokenType,
+} from './token';
+import {
+  getClient,
+  getHandlerContext,
+  log,
+  type TemporalCancelOperationContext,
+  type TemporalStartOperationContext,
+} from './context';
 
 declare const isNexusWorkflowHandle: unique symbol;
 declare const workflowResultType: unique symbol;
@@ -77,9 +89,7 @@ export async function startWorkflow<T extends Workflow>(
   if (ctx.inboundLinks?.length > 0) {
     for (const l of ctx.inboundLinks) {
       try {
-        links.push({
-          workflowEvent: convertNexusLinkToWorkflowEventLink(l),
-        });
+        links.push(convertNexusLinkToTemporalLink(l));
       } catch (error) {
         log.warn('failed to convert Nexus link to Workflow event link', { error });
       }
@@ -96,10 +106,17 @@ export async function startWorkflow<T extends Workflow>(
     attachRequestId: true,
   };
 
+  // Add nexus-operation-token header to solve for race between Workflow completion
+  // and Nexus Operation start recording
+  const callbackHeaders = {
+    ...ctx.callbackHeaders,
+    'nexus-operation-token': generateWorkflowRunOperationToken(client.options.namespace, workflowOptions.workflowId),
+  };
+
   if (ctx.callbackUrl) {
     internalOptions.completionCallbacks = [
       {
-        nexus: { url: ctx.callbackUrl, header: ctx.callbackHeaders },
+        nexus: { url: ctx.callbackUrl, header: callbackHeaders },
         links, // pass in links here as well for older servers, newer servers dedupe them.
       },
     ];
@@ -113,11 +130,11 @@ export async function startWorkflow<T extends Workflow>(
   };
 
   const handle = await client.workflow.start(workflowTypeOrFunc, startOptions);
-  if (internalOptions.backLink?.workflowEvent != null) {
+  if (internalOptions.backLink != null) {
     try {
-      ctx.outboundLinks.push(convertWorkflowEventLinkToNexusLink(internalOptions.backLink.workflowEvent));
+      ctx.outboundLinks.push(convertTemporalLinkToNexusLink(internalOptions.backLink));
     } catch (error) {
-      log.warn('failed to convert Workflow event link to Nexus link', { error });
+      log.warn('failed to convert temporal link to Nexus link', { error });
     }
   }
 
@@ -156,3 +173,188 @@ export class WorkflowRunOperationHandler<I, O> implements nexus.OperationHandler
     await getClient().workflow.getHandle(decoded.wid).cancel();
   }
 }
+
+/**
+ * Module-private brand and payload key for {@link TemporalOperationResult}.
+ */
+const operationResult: unique symbol = Symbol('temporal_nexus_TemporalOperationResult');
+
+/**
+ * A result produced by a {@link TemporalOperationHandler}. Construct via
+ * {@link TemporalOperationResult.sync} or {@link TemporalOperationResult.async}.
+
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export interface TemporalOperationResult<T> {
+  readonly [operationResult]: nexus.HandlerStartOperationResult<T>;
+}
+
+export const TemporalOperationResult = {
+  sync<T>(value: T): TemporalOperationResult<T> {
+    return {
+      [operationResult]: nexus.HandlerStartOperationResult.sync(value),
+    };
+  },
+
+  async<T = unknown>(token: string): TemporalOperationResult<T> {
+    return {
+      [operationResult]: nexus.HandlerStartOperationResult.async(token),
+    };
+  },
+};
+
+/**
+ * A Nexus-aware Temporal Client for use inside {@link TemporalOperationHandler} implementations.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export interface TemporalNexusClient {
+  /**
+   * The Temporal Client for the active Nexus Operation.
+   *
+   * @experimental Nexus support in Temporal SDK is experimental.
+   */
+  readonly client: Client;
+
+  /**
+   * Starts a workflow run as the asynchronous backing operation for the current Nexus Operation.
+   *
+   * @experimental Nexus support in Temporal SDK is experimental.
+   */
+  startWorkflow<T extends Workflow>(
+    workflowTypeOrFunc: string | T,
+    workflowOptions: WorkflowStartOptions<T>
+  ): Promise<TemporalOperationResult<WorkflowResultType<T>>>;
+}
+
+class TemporalNexusClientImpl implements TemporalNexusClient {
+  private asyncOperationStarted = false;
+
+  constructor(private readonly startOperationContext: TemporalStartOperationContext) {}
+
+  /**
+   * The Temporal Client for the active Nexus Operation.
+   *
+   * @experimental Nexus support in Temporal SDK is experimental.
+   */
+  public get client(): Client {
+    return getClient();
+  }
+
+  /**
+   * Starts a workflow run as the asynchronous backing operation for the current Nexus Operation.
+   *
+   * @experimental Nexus support in Temporal SDK is experimental.
+   */
+  public async startWorkflow<T extends Workflow>(
+    workflowTypeOrFunc: string | T,
+    workflowOptions: WorkflowStartOptions<T>
+  ): Promise<TemporalOperationResult<WorkflowResultType<T>>> {
+    return await this.withAsyncOperationStartReservation(async () => {
+      const handle = await startWorkflow(this.startOperationContext, workflowTypeOrFunc, workflowOptions);
+      const { namespace } = getHandlerContext();
+      return TemporalOperationResult.async(generateWorkflowRunOperationToken(namespace, handle.workflowId));
+    });
+  }
+
+  private async withAsyncOperationStartReservation<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.asyncOperationStarted) {
+      throw new nexus.HandlerError(
+        'BAD_REQUEST',
+        'Only one async operation can be started per operation handler invocation. Use TemporalNexusClient.client for additional workflow interactions'
+      );
+    }
+
+    this.asyncOperationStarted = true;
+    try {
+      return await fn();
+    } catch (err) {
+      this.asyncOperationStarted = false;
+      throw err;
+    }
+  }
+}
+
+/**
+ * A handler function for the {@link TemporalOperationHandler} constructor.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export type TemporalOperationStartHandler<I, O> = (
+  ctx: TemporalStartOperationContext,
+  client: TemporalNexusClient,
+  input: I
+) => Promise<TemporalOperationResult<O>>;
+
+/**
+ * Options passed to a {@link TemporalOperationHandlerOptions.cancelWorkflowRun} handler describing
+ * the workflow run to cancel.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export interface CancelWorkflowRunOptions {
+  /**
+   * The ID of the workflow backing the Nexus Operation that is being canceled.
+   */
+  readonly workflowId: string;
+}
+
+/**
+ * Options for customizing a {@link TemporalOperationHandler}.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export interface TemporalOperationHandlerOptions {
+  cancelWorkflowRun?: (ctx: TemporalCancelOperationContext, options: CancelWorkflowRunOptions) => Promise<void>;
+}
+
+/**
+ * A Nexus Operation implementation for operations that interact with Temporal.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export class TemporalOperationHandler<I, O> implements nexus.OperationHandler<I, O> {
+  private readonly startHandler: TemporalOperationStartHandler<I, O>;
+  private readonly cancelWorkflowRunHandler: NonNullable<TemporalOperationHandlerOptions['cancelWorkflowRun']>;
+
+  constructor(options: { start: TemporalOperationStartHandler<I, O> } & TemporalOperationHandlerOptions) {
+    this.startHandler = options.start;
+    this.cancelWorkflowRunHandler = options.cancelWorkflowRun ?? defaultCancelWorkflowRun;
+  }
+
+  async start(ctx: nexus.StartOperationContext, input: I): Promise<nexus.HandlerStartOperationResult<O>> {
+    const result = await this.startHandler(ctx, new TemporalNexusClientImpl(ctx), input);
+    return result[operationResult];
+  }
+
+  async cancel(ctx: nexus.CancelOperationContext, token: string): Promise<void> {
+    let opToken;
+    try {
+      opToken = loadOperationToken(token);
+    } catch (err) {
+      throw new nexus.HandlerError(nexus.HandlerErrorType.BAD_REQUEST, 'invalid operation token', { cause: err });
+    }
+
+    switch (opToken.t) {
+      case OperationTokenType.WORKFLOW_RUN:
+        try {
+          assertWorkflowRunOperationToken(opToken);
+        } catch (err) {
+          throw new nexus.HandlerError(nexus.HandlerErrorType.BAD_REQUEST, 'invalid workflow run operation token', {
+            cause: err,
+          });
+        }
+        await this.cancelWorkflowRunHandler(ctx, { workflowId: opToken.wid });
+        return;
+      default:
+        throw new nexus.HandlerError(
+          nexus.HandlerErrorType.BAD_REQUEST,
+          `Unsupported operation token type: ${opToken.t}`
+        );
+    }
+  }
+}
+
+async function defaultCancelWorkflowRun(_ctx: TemporalCancelOperationContext, options: CancelWorkflowRunOptions) {
+  await getClient().workflow.getHandle(options.workflowId).cancel();
+}