@temporalio/client 0.22.0 → 1.0.0-rc.1

package/src/errors.ts

@@ -0,0 +1,57 @@
+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
+ * completes with failure.
+ *
+ * The failure type will be set in the `cause` attribute.
+ *
+ * For example if the workflow is cancelled, `cause` will be set to
+ * {@link CancelledFailure}.
+ */
+export class WorkflowFailedError extends Error {
+  public readonly name: string = 'WorkflowFailedError';
+  public constructor(
+    message: string,
+    public readonly cause: TemporalFailure | undefined,
+    public readonly retryState: RetryState
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * Thrown the by client while waiting on Workflow execution result if Workflow
+ * continues as new.
+ *
+ * Only thrown if asked not to follow the chain of execution (see {@link WorkflowOptions.followRuns}).
+ */
+export class WorkflowContinuedAsNewError extends Error {
+  public readonly name: string = 'WorkflowExecutionContinuedAsNewError';
+  public constructor(message: string, public readonly newExecutionRunId: string) {
+    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;
+}

package/src/grpc-retry.ts

@@ -0,0 +1,119 @@
+import {
+  InterceptingCall,
+  Interceptor,
+  ListenerBuilder,
+  Metadata,
+  RequesterBuilder,
+  StatusObject,
+} from '@grpc/grpc-js';
+import * as grpc from '@grpc/grpc-js';
+
+export interface GrpcRetryOptions {
+  /** Maximum number of allowed retries. Defaults to 10. */
+  maxRetries: number;
+
+  /**
+   * A function which accepts the current retry attempt (starts at 0) and returns the millisecond
+   * delay that should be applied before the next retry.
+   */
+  delayFunction: (attempt: number) => number;
+
+  /**
+   * A function which accepts a failed status object and returns true if the call should be retried
+   */
+  retryableDecider: (status: StatusObject) => boolean;
+}
+
+export function defaultGrpcRetryOptions(): GrpcRetryOptions {
+  return {
+    maxRetries: 10,
+    delayFunction: backOffAmount,
+    retryableDecider: isRetryableError,
+  };
+}
+
+const retryableCodes = new Set([
+  grpc.status.UNKNOWN,
+  grpc.status.RESOURCE_EXHAUSTED,
+  grpc.status.UNAVAILABLE,
+  grpc.status.ABORTED,
+  grpc.status.DATA_LOSS,
+  grpc.status.OUT_OF_RANGE,
+]);
+
+export function isRetryableError(status: StatusObject): boolean {
+  return retryableCodes.has(status.code);
+}
+
+/** Return backoff amount in ms */
+export function backOffAmount(attempt: number): number {
+  return 2 ** attempt * 20;
+}
+
+/**
+ * Returns a GRPC interceptor that will perform automatic retries for some types of failed calls
+ *
+ * @param retryOptions Options for the retry interceptor
+ */
+export function makeGrpcRetryInterceptor(retryOptions: GrpcRetryOptions): Interceptor {
+  return (options, nextCall) => {
+    let savedMetadata: Metadata;
+    let savedSendMessage: any;
+    let savedReceiveMessage: any;
+    let savedMessageNext: any;
+    const requester = new RequesterBuilder()
+      .withStart(function (metadata, _listener, next) {
+        savedMetadata = metadata;
+        const newListener = new ListenerBuilder()
+          .withOnReceiveMessage((message, next) => {
+            savedReceiveMessage = message;
+            savedMessageNext = next;
+          })
+          .withOnReceiveStatus((status, next) => {
+            let retries = 0;
+            const retry = (message: any, metadata: Metadata) => {
+              retries++;
+              const newCall = nextCall(options);
+              newCall.start(metadata, {
+                onReceiveMessage: (message) => {
+                  savedReceiveMessage = message;
+                },
+                onReceiveStatus: (status) => {
+                  if (retryOptions.retryableDecider(status)) {
+                    if (retries <= retryOptions.maxRetries) {
+                      setTimeout(() => retry(message, metadata), retryOptions.delayFunction(retries));
+                    } else {
+                      savedMessageNext(savedReceiveMessage);
+                      next(status);
+                    }
+                  } else {
+                    savedMessageNext(savedReceiveMessage);
+                    // TODO: For reasons that are completely unclear to me, if you pass a handcrafted
+                    //   status object here, node will magically just exit at the end of this line.
+                    //   No warning, no nothing. Here be dragons.
+                    next(status);
+                  }
+                },
+              });
+              newCall.sendMessage(message);
+              newCall.halfClose();
+            };
+
+            if (retryOptions.retryableDecider(status)) {
+              setTimeout(() => retry(savedSendMessage, savedMetadata), backOffAmount(retries));
+            } else {
+              savedMessageNext(savedReceiveMessage);
+              next(status);
+            }
+          })
+          .build();
+        next(metadata, newListener);
+      })
+      .withSendMessage((message, next) => {
+        savedSendMessage = message;
+        next(message);
+      })
+      .build();
+    return new InterceptingCall(nextCall(options), requester);
+  };
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Client for communicating with Temporal Server.
+ *
+ * Most functionality is available through {@link WorkflowClient}, but you can also call gRPC methods directly using {@link Connection.workflowService} and {@link Connection.operatorService}.
+ *
+ * ### Usage
+ * <!--SNIPSTART typescript-hello-client-->
+ * <!--SNIPEND-->
+ * @module
+ */
+
+export {
+  ActivityFailure,
+  ApplicationFailure,
+  CancelledFailure,
+  ChildWorkflowFailure,
+  DataConverter,
+  defaultPayloadConverter,
+  ProtoFailure,
+  ServerFailure,
+  TemporalFailure,
+  TerminatedFailure,
+  TimeoutFailure,
+} from '@temporalio/common';
+export { TLSConfig } from '@temporalio/internal-non-workflow-common';
+export { RetryPolicy } from '@temporalio/internal-workflow-common';
+export * from '@temporalio/internal-workflow-common/lib/errors';
+export * from '@temporalio/internal-workflow-common/lib/interfaces';
+export * from '@temporalio/internal-workflow-common/lib/workflow-handle';
+export * from './async-completion-client';
+export { Connection, ConnectionOptions, ConnectionOptionsWithDefaults, LOCAL_TARGET } from './connection';
+export * from './errors';
+export * from './grpc-retry';
+export * from './interceptors';
+export * from './types';
+export * from './workflow-client';
+export * from './workflow-options';

package/src/interceptors.ts

@@ -0,0 +1,132 @@
+/**
+ * Definitions for Connection interceptors.
+ *
+ * @module
+ */
+
+import { Headers, Next } from '@temporalio/internal-workflow-common';
+import { temporal } from '@temporalio/proto';
+import {
+  DescribeWorkflowExecutionResponse,
+  RequestCancelWorkflowExecutionResponse,
+  TerminateWorkflowExecutionResponse,
+  WorkflowExecution,
+} from './types';
+import { CompiledWorkflowOptions } from './workflow-options';
+
+export { Next, Headers };
+
+/** Input for WorkflowClientCallsInterceptor.start */
+export interface WorkflowStartInput {
+  /** Name of Workflow to start */
+  readonly workflowType: string;
+  readonly headers: Headers;
+  readonly options: CompiledWorkflowOptions;
+}
+
+/** Input for WorkflowClientCallsInterceptor.signal */
+export interface WorkflowSignalInput {
+  readonly signalName: string;
+  readonly args: unknown[];
+  readonly workflowExecution: WorkflowExecution;
+  readonly headers: Headers;
+}
+
+/** Input for WorkflowClientCallsInterceptor.signalWithStart */
+export interface WorkflowSignalWithStartInput {
+  readonly workflowType: string;
+  readonly signalName: string;
+  readonly signalArgs: unknown[];
+  readonly headers: Headers;
+  readonly options: CompiledWorkflowOptions;
+}
+
+/** Input for WorkflowClientCallsInterceptor.query */
+export interface WorkflowQueryInput {
+  readonly queryType: string;
+  readonly args: unknown[];
+  readonly workflowExecution: WorkflowExecution;
+  readonly queryRejectCondition?: temporal.api.enums.v1.QueryRejectCondition;
+  readonly headers: Headers;
+}
+
+/** Input for WorkflowClientCallsInterceptor.terminate */
+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;
+}
+
+/** Input for WorkflowClientCallsInterceptor.describe */
+export interface WorkflowDescribeInput {
+  readonly workflowExecution: WorkflowExecution;
+}
+
+/**
+ * Implement any of these methods to intercept WorkflowClient outbound calls
+ */
+export interface WorkflowClientCallsInterceptor {
+  /**
+   * Intercept a service call to startWorkflowExecution
+   *
+   * If you implement this method,
+   * {@link signalWithStart} most likely needs to be implemented too
+   */
+  start?: (input: WorkflowStartInput, next: Next<this, 'start'>) => Promise<string /* runId */>;
+  /**
+   * Intercept a service call to signalWorkflowExecution
+   *
+   * If you implement this method,
+   * {@link signalWithStart} most likely needs to be implemented too
+   */
+  signal?: (input: WorkflowSignalInput, next: Next<this, 'signal'>) => Promise<void>;
+  /**
+   * Intercept a service call to signalWithStartWorkflowExecution
+   */
+  signalWithStart?: (input: WorkflowSignalWithStartInput, next: Next<this, 'signalWithStart'>) => Promise<string>;
+  /**
+   * Intercept a service call to queryWorkflow
+   */
+  query?: (input: WorkflowQueryInput, next: Next<this, 'query'>) => Promise<unknown>;
+  /**
+   * Intercept a service call to terminateWorkflowExecution
+   */
+  terminate?: (
+    input: WorkflowTerminateInput,
+    next: Next<this, 'terminate'>
+  ) => Promise<TerminateWorkflowExecutionResponse>;
+  /**
+   * Intercept a service call to requestCancelWorkflowExecution
+   */
+  cancel?: (input: WorkflowCancelInput, next: Next<this, 'cancel'>) => Promise<RequestCancelWorkflowExecutionResponse>;
+  /**
+   * Intercept a service call to describeWorkflowExecution
+   */
+  describe?: (input: WorkflowDescribeInput, next: Next<this, 'describe'>) => Promise<DescribeWorkflowExecutionResponse>;
+}
+
+interface WorkflowClientCallsInterceptorFactoryInput {
+  workflowId: string;
+  runId?: string;
+}
+
+/**
+ * A function that takes {@link CompiledWorkflowOptions} and returns an interceptor
+ */
+export interface WorkflowClientCallsInterceptorFactory {
+  (input: WorkflowClientCallsInterceptorFactoryInput): WorkflowClientCallsInterceptor;
+}
+
+/**
+ * A mapping of interceptor type of a list of factory functions
+ */
+export interface WorkflowClientInterceptors {
+  calls?: WorkflowClientCallsInterceptorFactory[];
+}

package/src/pkg.ts

@@ -0,0 +1,7 @@
+// ../package.json is outside of the TS project rootDir which causes TS to complain about this import.
+// We do not want to change the rootDir because it messes up the output structure.
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+import pkg from '../package.json';
+
+export default pkg as { name: string; version: string };

package/src/types.ts

@@ -0,0 +1,88 @@
+import type { SearchAttributes } from '@temporalio/internal-workflow-common';
+import { temporal } from '@temporalio/proto';
+import type * as grpc from '@grpc/grpc-js';
+
+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;
+export type TerminateWorkflowExecutionResponse = temporal.api.workflowservice.v1.ITerminateWorkflowExecutionResponse;
+export type RequestCancelWorkflowExecutionResponse =
+  temporal.api.workflowservice.v1.IRequestCancelWorkflowExecutionResponse;
+
+export type WorkflowExecutionStatusName =
+  | 'UNSPECIFIED'
+  | 'RUNNING'
+  | 'COMPLETED'
+  | 'FAILED'
+  | 'CANCELLED'
+  | 'TERMINATED'
+  | 'CONTINUED_AS_NEW'
+  | 'TIMED_OUT'
+  | 'UNKNOWN'; // UNKNOWN is reserved for future enum values
+
+export interface WorkflowExecutionDescription {
+  type: string;
+  workflowId: string;
+  runId: string;
+  taskQueue: string;
+  status: { code: temporal.api.enums.v1.WorkflowExecutionStatus; name: WorkflowExecutionStatusName };
+  historyLength: Long;
+  startTime: Date;
+  executionTime?: Date;
+  closeTime?: Date;
+  memo?: Record<string, unknown>;
+  searchAttributes: SearchAttributes;
+  parentExecution?: Required<temporal.api.common.v1.IWorkflowExecution>;
+  raw: DescribeWorkflowExecutionResponse;
+}
+
+export type WorkflowService = temporal.api.workflowservice.v1.WorkflowService;
+export const { WorkflowService } = temporal.api.workflowservice.v1;
+export type OperatorService = temporal.api.operatorservice.v1.OperatorService;
+export const { OperatorService } = temporal.api.operatorservice.v1;
+
+/**
+ * Mapping of string to valid gRPC metadata value
+ */
+export type Metadata = Record<string, grpc.MetadataValue>;
+
+/**
+ * User defined context for gRPC client calls
+ */
+export interface CallContext {
+  /**
+   * {@link Deadline | https://grpc.io/blog/deadlines/} for gRPC client calls
+   */
+  deadline?: number | Date;
+  /**
+   * Metadata to set on gRPC requests
+   */
+  metadata?: Metadata;
+}
+
+/**
+ * Connection interface used by high level SDK clients.
+ *
+ * NOTE: Currently the SDK only supports grpc-js based connection but in the future
+ * we might support grpc-web and native Rust connections.
+ */
+export interface ConnectionLike {
+  workflowService: WorkflowService;
+  close(): Promise<void>;
+  ensureConnected(): Promise<void>;
+  /**
+   * Set the deadline for any service requests executed in `fn`'s scope.
+   */
+  withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R>;
+
+  /**
+   * Set metadata for any service requests executed in `fn`'s scope.
+   *
+   * @returns returned value of `fn`
+   */
+  withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R>;
+}