@temporalio/client 1.2.0 → 1.4.0

package/src/client.ts

@@ -0,0 +1,151 @@
+import { DataConverter, LoadedDataConverter } from '@temporalio/common';
+import { filterNullAndUndefined, loadDataConverter } from '@temporalio/common/lib/internal-non-workflow';
+import { Replace } from '@temporalio/common/lib/type-helpers';
+import { temporal } from '@temporalio/proto';
+import os from 'os';
+import { AsyncCompletionClient } from './async-completion-client';
+import { Connection } from './connection';
+import { ClientInterceptors } from './interceptors';
+import { ConnectionLike, Metadata, WorkflowService } from './types';
+import { WorkflowClient } from './workflow-client';
+
+export interface ClientOptions {
+  /**
+   * {@link DataConverter} to use for serializing and deserializing payloads
+   */
+  dataConverter?: DataConverter;
+
+  /**
+   * Used to override and extend default Connection functionality
+   *
+   * Useful for injecting auth headers and tracing Workflow executions
+   */
+  interceptors?: ClientInterceptors;
+
+  /**
+   * Identity to report to the server
+   *
+   * @default `${process.pid}@${os.hostname()}`
+   */
+  identity?: string;
+
+  /**
+   * Connection to use to communicate with the server.
+   *
+   * By default `WorkflowClient` connects to localhost.
+   *
+   * Connections are expensive to construct and should be reused.
+   */
+  connection?: ConnectionLike;
+
+  /**
+   * Server namespace
+   *
+   * @default default
+   */
+  namespace?: string;
+
+  workflow?: {
+    /**
+     * Should a query be rejected by closed and failed workflows
+     *
+     * @default QUERY_REJECT_CONDITION_UNSPECIFIED which means that closed and failed workflows are still queryable
+     */
+    queryRejectCondition?: temporal.api.enums.v1.QueryRejectCondition;
+  };
+}
+
+export type ClientOptionsWithDefaults = Replace<
+  Required<ClientOptions>,
+  {
+    connection?: ConnectionLike;
+  }
+>;
+
+export type LoadedClientOptions = ClientOptionsWithDefaults & {
+  loadedDataConverter: LoadedDataConverter;
+};
+
+export function defaultClientOptions(): ClientOptionsWithDefaults {
+  return {
+    dataConverter: {},
+    identity: `${process.pid}@${os.hostname()}`,
+    interceptors: {},
+    namespace: 'default',
+    workflow: {
+      queryRejectCondition: temporal.api.enums.v1.QueryRejectCondition.QUERY_REJECT_CONDITION_UNSPECIFIED,
+    },
+  };
+}
+
+/**
+ * High level SDK client.
+ */
+export class Client {
+  /**
+   * Underlying gRPC connection to the Temporal service
+   */
+  public readonly connection: ConnectionLike;
+  public readonly options: LoadedClientOptions;
+  /**
+   * Workflow sub-client - use to start and interact with Workflows
+   */
+  public readonly workflow: WorkflowClient;
+  /**
+   * (Async) Activity completion sub-client - use to manually manage Activities
+   */
+  public readonly activity: AsyncCompletionClient;
+
+  constructor(options?: ClientOptions) {
+    this.connection = options?.connection ?? Connection.lazy();
+    this.options = {
+      ...defaultClientOptions(),
+      ...filterNullAndUndefined(options ?? {}),
+      loadedDataConverter: loadDataConverter(options?.dataConverter),
+    };
+
+    const { workflow, loadedDataConverter, interceptors, ...base } = this.options;
+
+    this.workflow = new WorkflowClient({
+      ...base,
+      ...workflow,
+      connection: this.connection,
+      dataConverter: loadedDataConverter,
+      interceptors: interceptors.workflow,
+    });
+
+    this.activity = new AsyncCompletionClient({
+      ...base,
+      connection: this.connection,
+      dataConverter: loadedDataConverter,
+    });
+  }
+
+  /**
+   * Raw gRPC access to the Temporal service.
+   *
+   * **NOTE**: The namespace provided in {@link options} is **not** automatically set on requests made via this service
+   * object.
+   */
+  get workflowService(): WorkflowService {
+    return this.connection.workflowService;
+  }
+
+  /**
+   * Set the deadline for any service requests executed in `fn`'s scope.
+   */
+  async withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R> {
+    return await this.connection.withDeadline(deadline, fn);
+  }
+
+  /**
+   * Set metadata for any service requests executed in `fn`'s scope.
+   *
+   * @returns returned value of `fn`
+   *
+   * @see {@link Connection.withMetadata}
+   */
+  async withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R> {
+    return await this.connection.withMetadata(metadata, fn);
+  }
+}

package/src/connection.ts

@@ -1,11 +1,11 @@
 import * as grpc from '@grpc/grpc-js';
-import { filterNullAndUndefined, normalizeTlsConfig, TLSConfig } from '@temporalio/internal-non-workflow-common';
+import { filterNullAndUndefined, normalizeTlsConfig, TLSConfig } from '@temporalio/common/lib/internal-non-workflow';
 import { AsyncLocalStorage } from 'async_hooks';
 import type { RPCImpl } from 'protobufjs';
 import { isServerErrorResponse, ServiceError } from './errors';
 import { defaultGrpcRetryOptions, makeGrpcRetryInterceptor } from './grpc-retry';
 import pkg from './pkg';
-import { CallContext, Metadata, OperatorService, WorkflowService } from './types';
+import { CallContext, HealthService, Metadata, OperatorService, WorkflowService } from './types';
 
 /**
  * gRPC and Temporal Server connection options
@@ -63,7 +63,7 @@ export interface ConnectionOptions {
    * Used either when connecting eagerly with {@link Connection.connect} or
    * calling {@link Connection.ensureConnected}.
    *
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    * @default 10 seconds
    */
   connectTimeout?: number | string;
@@ -146,7 +146,14 @@ export interface ConnectionCtorOptions {
    * **NOTE**: The namespace provided in {@link options} is **not** automatically set on requests made to the service.
    */
   readonly workflowService: WorkflowService;
+  /**
+   * Raw gRPC access to the Temporal {@link https://github.com/temporalio/api/blob/ddf07ab9933e8230309850e3c579e1ff34b03f53/temporal/api/operatorservice/v1/service.proto | operator service}.
+   */
   readonly operatorService: OperatorService;
+  /**
+   * Raw gRPC access to the standard gRPC {@link https://github.com/grpc/grpc/blob/92f58c18a8da2728f571138c37760a721c8915a2/doc/health-checking.md | health service}.
+   */
+  readonly healthService: HealthService;
   readonly callContextStorage: AsyncLocalStorage<CallContext>;
 }
 
@@ -181,6 +188,7 @@ export class Connection {
    * {@link https://github.com/temporalio/api/blob/master/temporal/api/operatorservice/v1/service.proto | Operator service}
    */
   public readonly operatorService: OperatorService;
+  public readonly healthService: HealthService;
   readonly callContextStorage: AsyncLocalStorage<CallContext>;
 
   protected static createCtorOptions(options?: ConnectionOptions): ConnectionCtorOptions {
@@ -214,12 +222,20 @@ export class Connection {
       interceptors: optionsWithDefaults?.interceptors,
     });
     const operatorService = OperatorService.create(operatorRpcImpl, false, false);
+    const healthRpcImpl = this.generateRPCImplementation({
+      serviceName: 'grpc.health.v1.Health',
+      client,
+      callContextStorage,
+      interceptors: optionsWithDefaults?.interceptors,
+    });
+    const healthService = HealthService.create(healthRpcImpl, false, false);
 
     return {
       client,
       callContextStorage,
       workflowService,
       operatorService,
+      healthService,
       options: optionsWithDefaults,
     };
   }
@@ -282,12 +298,14 @@ export class Connection {
     client,
     workflowService,
     operatorService,
+    healthService,
     callContextStorage,
   }: ConnectionCtorOptions) {
     this.options = options;
     this.client = client;
     this.workflowService = workflowService;
     this.operatorService = operatorService;
+    this.healthService = healthService;
     this.callContextStorage = callContextStorage;
   }
 

package/src/grpc-retry.ts

@@ -1,37 +1,102 @@
-import {
-  InterceptingCall,
-  Interceptor,
-  ListenerBuilder,
-  Metadata,
-  RequesterBuilder,
-  StatusObject,
-} from '@grpc/grpc-js';
+import { InterceptingCall, Interceptor, ListenerBuilder, RequesterBuilder, StatusObject } from '@grpc/grpc-js';
 import * as grpc from '@grpc/grpc-js';
 
+/**
+ * @experimental
+ */
 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
+   * A function which accepts the current retry attempt (starts at 1) and returns the millisecond
    * delay that should be applied before the next retry.
    */
-  delayFunction: (attempt: number) => number;
+  delayFunction: (attempt: number, status: StatusObject) => number;
 
   /**
    * A function which accepts a failed status object and returns true if the call should be retried
    */
-  retryableDecider: (status: StatusObject) => boolean;
+  retryableDecider: (attempt: number, status: StatusObject) => boolean;
+}
+
+/**
+ * Options for the backoff formula: `factor ^ attempt * initialIntervalMs(status) * jitter(maxJitter)`
+ *
+ * @experimental
+ */
+export interface BackoffOptions {
+  /**
+   * Exponential backoff factor
+   *
+   * @default 2
+   */
+  factor: number;
+
+  /**
+   * Maximum number of attempts
+   *
+   * @default 10
+   */
+  maxAttempts: number;
+  /**
+   * Maximum amount of jitter to apply
+   *
+   * @default 0.1
+   */
+  maxJitter: number;
+  /**
+   * Function that returns the "initial" backoff interval based on the returned status.
+   *
+   * The default is 1 second for RESOURCE_EXHAUSTED errors and 20 millis for other retryable errors.
+   */
+  initialIntervalMs(status: StatusObject): number;
+
+  /**
+   * Function that returns the "maximum" backoff interval based on the returned status.
+   *
+   * The default is 10 seconds regardless of the status.
+   */
+  maxIntervalMs(status: StatusObject): number;
 }
 
-export function defaultGrpcRetryOptions(): GrpcRetryOptions {
+/**
+ * Add defaults as documented in {@link BackoffOptions}
+ */
+function withDefaultBackoffOptions({
+  maxAttempts,
+  factor,
+  maxJitter,
+  initialIntervalMs,
+}: Partial<BackoffOptions>): BackoffOptions {
   return {
-    maxRetries: 10,
-    delayFunction: backOffAmount,
-    retryableDecider: isRetryableError,
+    maxAttempts: maxAttempts ?? 10,
+    factor: factor ?? 2,
+    maxJitter: maxJitter ?? 0.1,
+    initialIntervalMs: initialIntervalMs ?? defaultInitialIntervalMs,
+    maxIntervalMs() {
+      return 10_000;
+    },
   };
 }
 
+/**
+ * Generates the default retry behavior based on given backoff options
+ *
+ * @experimental
+ */
+export function defaultGrpcRetryOptions(options: Partial<BackoffOptions> = {}): GrpcRetryOptions {
+  const { maxAttempts, factor, maxJitter, initialIntervalMs, maxIntervalMs } = withDefaultBackoffOptions(options);
+  return {
+    delayFunction(attempt, status) {
+      return Math.min(maxIntervalMs(status), factor ** attempt * initialIntervalMs(status)) * jitter(maxJitter);
+    },
+    retryableDecider(attempt, status) {
+      return attempt < maxAttempts && isRetryableError(status);
+    },
+  };
+}
+
+/**
+ * Set of retryable gRPC status codes
+ */
 const retryableCodes = new Set([
   grpc.status.UNKNOWN,
   grpc.status.RESOURCE_EXHAUSTED,
@@ -45,69 +110,77 @@ 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;
+/**
+ * Calculates random amount of jitter between 0 and `max`
+ */
+function jitter(max: number) {
+  return 1 - max + Math.random() * max * 2;
+}
+
+/**
+ * Default implementation - backs off more on RESOURCE_EXHAUSTED errors
+ */
+function defaultInitialIntervalMs({ code }: StatusObject) {
+  // Backoff more on RESOURCE_EXHAUSTED
+  if (code === grpc.status.RESOURCE_EXHAUSTED) {
+    return 1000;
+  }
+  return 20;
 }
 
 /**
  * Returns a GRPC interceptor that will perform automatic retries for some types of failed calls
  *
  * @param retryOptions Options for the retry interceptor
+ *
+ * @experimental
  */
 export function makeGrpcRetryInterceptor(retryOptions: GrpcRetryOptions): Interceptor {
   return (options, nextCall) => {
-    let savedMetadata: Metadata;
     let savedSendMessage: any;
     let savedReceiveMessage: any;
-    let savedMessageNext: any;
+    let savedMessageNext: (message: any) => void;
+
     const requester = new RequesterBuilder()
       .withStart(function (metadata, _listener, next) {
-        savedMetadata = metadata;
-        const newListener = new ListenerBuilder()
+        // First attempt
+        let attempt = 1;
+
+        const listener = 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) => {
+            const retry = () => {
+              attempt++;
+              const call = nextCall(options);
+              call.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);
-                  }
-                },
+                onReceiveStatus,
               });
-              newCall.sendMessage(message);
-              newCall.halfClose();
+              call.sendMessage(savedSendMessage);
+              call.halfClose();
+            };
+
+            const onReceiveStatus = (status: StatusObject) => {
+              if (retryOptions.retryableDecider(attempt, status)) {
+                setTimeout(retry, retryOptions.delayFunction(attempt, 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);
+              }
             };
 
-            if (retryOptions.retryableDecider(status)) {
-              setTimeout(() => retry(savedSendMessage, savedMetadata), backOffAmount(retries));
-            } else {
-              savedMessageNext(savedReceiveMessage);
-              next(status);
-            }
+            onReceiveStatus(status);
           })
           .build();
-        next(metadata, newListener);
+        next(metadata, listener);
       })
       .withSendMessage((message, next) => {
         savedSendMessage = message;

package/src/index.ts

@@ -17,17 +17,18 @@ export {
   DataConverter,
   defaultPayloadConverter,
   ProtoFailure,
+  RetryPolicy,
   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 { TLSConfig } from '@temporalio/common/lib/internal-non-workflow';
+export * from '@temporalio/common/lib/errors';
+export * from '@temporalio/common/lib/interfaces';
+export * from '@temporalio/common/lib/workflow-handle';
 export * from './async-completion-client';
+export * from './client';
 export { Connection, ConnectionOptions, ConnectionOptionsWithDefaults, LOCAL_TARGET } from './connection';
 export * from './errors';
 export * from './grpc-retry';

package/src/interceptors.ts

@@ -4,7 +4,7 @@
  * @module
  */
 
-import { Headers, Next } from '@temporalio/internal-workflow-common';
+import { Headers, Next } from '@temporalio/common';
 import { temporal } from '@temporalio/proto';
 import {
   DescribeWorkflowExecutionResponse,
@@ -112,7 +112,7 @@ export interface WorkflowClientCallsInterceptor {
   describe?: (input: WorkflowDescribeInput, next: Next<this, 'describe'>) => Promise<DescribeWorkflowExecutionResponse>;
 }
 
-interface WorkflowClientCallsInterceptorFactoryInput {
+export interface WorkflowClientCallsInterceptorFactoryInput {
   workflowId: string;
   runId?: string;
 }
@@ -130,3 +130,12 @@ export interface WorkflowClientCallsInterceptorFactory {
 export interface WorkflowClientInterceptors {
   calls?: WorkflowClientCallsInterceptorFactory[];
 }
+
+/**
+ * Interceptors for any high-level SDK client.
+ *
+ * NOTE: Currently only for {@link WorkflowClient}. More will be added later as needed.
+ */
+export interface ClientInterceptors {
+  workflow?: WorkflowClientInterceptors;
+}

package/src/types.ts

@@ -1,18 +1,20 @@
-import type { SearchAttributes } from '@temporalio/internal-workflow-common';
-import { temporal } from '@temporalio/proto';
+import type { SearchAttributes } from '@temporalio/common';
+import * as proto from '@temporalio/proto';
 import type * as grpc from '@grpc/grpc-js';
-import Long from 'long';
 
 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 StartWorkflowExecutionRequest = proto.temporal.api.workflowservice.v1.IStartWorkflowExecutionRequest;
+export type GetWorkflowExecutionHistoryRequest =
+  proto.temporal.api.workflowservice.v1.IGetWorkflowExecutionHistoryRequest;
+export type DescribeWorkflowExecutionResponse =
+  proto.temporal.api.workflowservice.v1.IDescribeWorkflowExecutionResponse;
+export type TerminateWorkflowExecutionResponse =
+  proto.temporal.api.workflowservice.v1.ITerminateWorkflowExecutionResponse;
 export type RequestCancelWorkflowExecutionResponse =
-  temporal.api.workflowservice.v1.IRequestCancelWorkflowExecutionResponse;
+  proto.temporal.api.workflowservice.v1.IRequestCancelWorkflowExecutionResponse;
 
 export type WorkflowExecutionStatusName =
   | 'UNSPECIFIED'
@@ -30,21 +32,23 @@ export interface WorkflowExecutionDescription {
   workflowId: string;
   runId: string;
   taskQueue: string;
-  status: { code: temporal.api.enums.v1.WorkflowExecutionStatus; name: WorkflowExecutionStatusName };
-  historyLength: Long;
+  status: { code: proto.temporal.api.enums.v1.WorkflowExecutionStatus; name: WorkflowExecutionStatusName };
+  historyLength: number;
   startTime: Date;
   executionTime?: Date;
   closeTime?: Date;
   memo?: Record<string, unknown>;
   searchAttributes: SearchAttributes;
-  parentExecution?: Required<temporal.api.common.v1.IWorkflowExecution>;
+  parentExecution?: Required<proto.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;
+export type WorkflowService = proto.temporal.api.workflowservice.v1.WorkflowService;
+export const { WorkflowService } = proto.temporal.api.workflowservice.v1;
+export type OperatorService = proto.temporal.api.operatorservice.v1.OperatorService;
+export const { OperatorService } = proto.temporal.api.operatorservice.v1;
+export type HealthService = proto.grpc.health.v1.Health;
+export const { Health: HealthService } = proto.grpc.health.v1;
 
 /**
  * Mapping of string to valid gRPC metadata value