feat(client): Use runId only in handles created with getHandle (#468)

In addition:
- Adds safety to `terminate` and `cancel` so handles created with `start` can't accidentally affect workflows that are not part of the same execution chain
- Adds optional `firstExecutionRunId` param to `getHandle` for added safety
- Closes #464
- Closes #377
- Closes #365

Author: bergundy

packages/client/src/async-completion-client.ts

@@ -1,5 +1,4 @@
 import os from 'os';
-import { ServerErrorResponse } from '@grpc/grpc-js';
 import { Status } from '@grpc/grpc-js/build/src/constants';
 import {
   DataConverter,
@@ -9,6 +8,7 @@ import {
   filterNullAndUndefined,
 } from '@temporalio/common';
 import { Connection, WorkflowService } from './connection';
+import { isServerErrorResponse } from './errors';
 
 /**
  * Thrown by {@link AsyncCompletionClient} when trying to complete or heartbeat
@@ -34,14 +34,6 @@ export class ActivityCancelledError extends Error {
   public readonly name = 'ActivityCancelledError';
 }
 
-/**
- * Type assertion helper, assertion is mostly empty because any additional
- * properties are optional.
- */
-function isServerErrorResponse(err: unknown): err is ServerErrorResponse {
-  return err instanceof Error;
-}
-
 /**
  * Options used to configure {@link AsyncCompletionClient}
  */

packages/client/src/errors.ts

@@ -1,4 +1,19 @@
+import { ServerErrorResponse } from '@grpc/grpc-js';
 import { RetryState, TemporalFailure } from '@temporalio/common';
+export { WorkflowExecutionAlreadyStartedError } from '@temporalio/common';
+
+/**
+ * Generic Error class for errors coming from the service
+ */
+export class ServiceError extends Error {
+  public readonly name: string = 'ServiceError';
+  public readonly cause?: Error;
+
+  constructor(message: string, opts?: { cause: Error }) {
+    super(message);
+    this.cause = opts?.cause;
+  }
+}
 
 /**
  * Thrown by the client while waiting on Workflow execution result if execution
@@ -32,3 +47,11 @@ export class WorkflowContinuedAsNewError extends Error {
     super(message);
   }
 }
+
+/**
+ * Type assertion helper, assertion is mostly empty because any additional
+ * properties are optional.
+ */
+export function isServerErrorResponse(err: unknown): err is ServerErrorResponse {
+  return err instanceof Error;
+}

packages/client/src/interceptors.ts

@@ -48,11 +48,13 @@ export interface WorkflowTerminateInput {
   readonly workflowExecution: WorkflowExecution;
   readonly reason?: string;
   readonly details?: unknown[];
+  readonly firstExecutionRunId?: string;
 }
 
 /** Input for WorkflowClientCallsInterceptor.cancel */
 export interface WorkflowCancelInput {
   readonly workflowExecution: WorkflowExecution;
+  readonly firstExecutionRunId?: string;
 }
 
 /**

packages/client/src/types.ts

@@ -1,6 +1,9 @@
 import { temporal } from '@temporalio/proto';
 
-export type WorkflowExecution = temporal.api.common.v1.IWorkflowExecution;
+export interface WorkflowExecution {
+  workflowId: string;
+  runId?: string;
+}
 export type StartWorkflowExecutionRequest = temporal.api.workflowservice.v1.IStartWorkflowExecutionRequest;
 export type GetWorkflowExecutionHistoryRequest = temporal.api.workflowservice.v1.IGetWorkflowExecutionHistoryRequest;
 export type DescribeWorkflowExecutionResponse = temporal.api.workflowservice.v1.IDescribeWorkflowExecutionResponse;