@temporalio/client 1.0.0-rc.0 → 1.0.1

package/src/async-completion-client.ts

@@ -0,0 +1,256 @@
+import { Status } from '@grpc/grpc-js/build/src/constants';
+import { DataConverter, ensureTemporalFailure, LoadedDataConverter } from '@temporalio/common';
+import {
+  encodeErrorToFailure,
+  encodeToPayloads,
+  filterNullAndUndefined,
+  loadDataConverter,
+} from '@temporalio/internal-non-workflow-common';
+import { Replace } from '@temporalio/internal-workflow-common';
+import os from 'os';
+import { Connection } from './connection';
+import { isServerErrorResponse } from './errors';
+import { ConnectionLike, WorkflowService } from './types';
+
+/**
+ * Thrown by {@link AsyncCompletionClient} when trying to complete or heartbeat an Activity that does not exist in the
+ * system.
+ */
+export class ActivityNotFoundError extends Error {
+  public readonly name = 'ActivityNotFoundError';
+}
+
+/**
+ * Thrown by {@link AsyncCompletionClient} when trying to complete or heartbeat
+ * an Activity for any reason apart from {@link ActivityNotFoundError}.
+ */
+export class ActivityCompletionError extends Error {
+  public readonly name = 'ActivityCompletionError';
+}
+
+/**
+ * Thrown by {@link AsyncCompletionClient.heartbeat} when the Workflow has
+ * requested to cancel the reporting Activity.
+ */
+export class ActivityCancelledError extends Error {
+  public readonly name = 'ActivityCancelledError';
+}
+
+/**
+ * Options used to configure {@link AsyncCompletionClient}
+ */
+export interface AsyncCompletionClientOptions {
+  /**
+   * {@link DataConverter} to use for serializing and deserializing payloads
+   */
+  dataConverter?: DataConverter;
+
+  /**
+   * Identity to report to the server
+   *
+   * @default `${process.pid}@${os.hostname()}`
+   */
+  identity?: string;
+
+  connection?: ConnectionLike;
+
+  /**
+   * Server namespace
+   *
+   * @default default
+   */
+  namespace?: string;
+}
+
+export type AsyncCompletionClientOptionsWithDefaults = Replace<
+  Required<AsyncCompletionClientOptions>,
+  {
+    connection?: ConnectionLike;
+  }
+>;
+
+export function defaultAsyncCompletionClientOptions(): AsyncCompletionClientOptionsWithDefaults {
+  return {
+    dataConverter: {},
+    identity: `${process.pid}@${os.hostname()}`,
+    namespace: 'default',
+  };
+}
+
+/**
+ * A mostly unique Activity identifier including its scheduling workflow's ID
+ * and an optional runId.
+ *
+ * Activity IDs may be reused in a single Workflow run as long as a previous
+ * Activity with the same ID has completed already.
+ */
+export interface FullActivityId {
+  workflowId: string;
+  runId?: string;
+  activityId: string;
+}
+
+/**
+ * A client for asynchronous completion and heartbeating of Activities.
+ */
+export class AsyncCompletionClient {
+  public readonly options: AsyncCompletionClientOptionsWithDefaults;
+  protected readonly dataConverter: LoadedDataConverter;
+  public readonly connection: ConnectionLike;
+
+  constructor(options?: AsyncCompletionClientOptions) {
+    this.connection = options?.connection ?? Connection.lazy();
+    this.dataConverter = loadDataConverter(options?.dataConverter);
+    this.options = { ...defaultAsyncCompletionClientOptions(), ...filterNullAndUndefined(options ?? {}) };
+  }
+
+  get workflowService(): WorkflowService {
+    return this.connection.workflowService;
+  }
+
+  /**
+   * Transforms grpc errors into well defined TS errors.
+   */
+  protected handleError(err: unknown): never {
+    if (isServerErrorResponse(err)) {
+      if (err.code === Status.NOT_FOUND) {
+        throw new ActivityNotFoundError('Not found');
+      }
+      throw new ActivityCompletionError(err.details || err.message);
+    }
+    throw new ActivityCompletionError('Unexpected failure');
+  }
+
+  /**
+   * Complete an Activity by task token
+   */
+  async complete(taskToken: Uint8Array, result: unknown): Promise<void>;
+  /**
+   * Complete an Activity by full ID
+   */
+  async complete(fullActivityId: FullActivityId, result: unknown): Promise<void>;
+
+  async complete(taskTokenOrFullActivityId: Uint8Array | FullActivityId, result: unknown): Promise<void> {
+    try {
+      if (taskTokenOrFullActivityId instanceof Uint8Array) {
+        await this.workflowService.respondActivityTaskCompleted({
+          identity: this.options.identity,
+          namespace: this.options.namespace,
+          taskToken: taskTokenOrFullActivityId,
+          result: { payloads: await encodeToPayloads(this.dataConverter, result) },
+        });
+      } else {
+        await this.workflowService.respondActivityTaskCompletedById({
+          identity: this.options.identity,
+          namespace: this.options.namespace,
+          ...taskTokenOrFullActivityId,
+          result: { payloads: await encodeToPayloads(this.dataConverter, result) },
+        });
+      }
+    } catch (err) {
+      this.handleError(err);
+    }
+  }
+
+  /**
+   * Fail an Activity by task token
+   */
+  async fail(taskToken: Uint8Array, err: unknown): Promise<void>;
+  /**
+   * Fail an Activity by full ID
+   */
+  async fail(fullActivityId: FullActivityId, err: unknown): Promise<void>;
+
+  async fail(taskTokenOrFullActivityId: Uint8Array | FullActivityId, err: unknown): Promise<void> {
+    try {
+      if (taskTokenOrFullActivityId instanceof Uint8Array) {
+        await this.workflowService.respondActivityTaskFailed({
+          identity: this.options.identity,
+          namespace: this.options.namespace,
+          taskToken: taskTokenOrFullActivityId,
+          failure: await encodeErrorToFailure(this.dataConverter, ensureTemporalFailure(err)),
+        });
+      } else {
+        await this.workflowService.respondActivityTaskFailedById({
+          identity: this.options.identity,
+          namespace: this.options.namespace,
+          ...taskTokenOrFullActivityId,
+          failure: await encodeErrorToFailure(this.dataConverter, err),
+        });
+      }
+    } catch (err) {
+      this.handleError(err);
+    }
+  }
+
+  /**
+   * Report Activity cancellation by task token
+   */
+  reportCancellation(taskToken: Uint8Array, details?: unknown): Promise<void>;
+  /**
+   * Report Activity cancellation by full ID
+   */
+  reportCancellation(fullActivityId: FullActivityId, details?: unknown): Promise<void>;
+
+  async reportCancellation(taskTokenOrFullActivityId: Uint8Array | FullActivityId, details?: unknown): Promise<void> {
+    try {
+      if (taskTokenOrFullActivityId instanceof Uint8Array) {
+        await this.workflowService.respondActivityTaskCanceled({
+          identity: this.options.identity,
+          namespace: this.options.namespace,
+          taskToken: taskTokenOrFullActivityId,
+          details: { payloads: await encodeToPayloads(this.dataConverter, details) },
+        });
+      } else {
+        await this.workflowService.respondActivityTaskCanceledById({
+          identity: this.options.identity,
+          namespace: this.options.namespace,
+          ...taskTokenOrFullActivityId,
+          details: { payloads: await encodeToPayloads(this.dataConverter, details) },
+        });
+      }
+    } catch (err) {
+      this.handleError(err);
+    }
+  }
+
+  /**
+   * Send Activity heartbeat by task token
+   */
+  heartbeat(taskToken: Uint8Array, details?: unknown): Promise<void>;
+  /**
+   * Send Activity heartbeat by full ID
+   */
+  heartbeat(fullActivityId: FullActivityId, details?: unknown): Promise<void>;
+
+  async heartbeat(taskTokenOrFullActivityId: Uint8Array | FullActivityId, details?: unknown): Promise<void> {
+    try {
+      if (taskTokenOrFullActivityId instanceof Uint8Array) {
+        const { cancelRequested } = await this.workflowService.recordActivityTaskHeartbeat({
+          identity: this.options.identity,
+          namespace: this.options.namespace,
+          taskToken: taskTokenOrFullActivityId,
+          details: { payloads: await encodeToPayloads(this.dataConverter, details) },
+        });
+        if (cancelRequested) {
+          throw new ActivityCancelledError('cancelled');
+        }
+      } else {
+        const { cancelRequested } = await this.workflowService.recordActivityTaskHeartbeatById({
+          identity: this.options.identity,
+          namespace: this.options.namespace,
+          ...taskTokenOrFullActivityId,
+          details: { payloads: await encodeToPayloads(this.dataConverter, details) },
+        });
+        if (cancelRequested) {
+          throw new ActivityCancelledError('cancelled');
+        }
+      }
+    } catch (err) {
+      if (err instanceof ActivityCancelledError) {
+        throw err;
+      }
+      this.handleError(err);
+    }
+  }
+}

package/src/connection.ts

@@ -0,0 +1,374 @@
+import * as grpc from '@grpc/grpc-js';
+import { filterNullAndUndefined, normalizeTlsConfig, TLSConfig } from '@temporalio/internal-non-workflow-common';
+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';
+
+/**
+ * gRPC and Temporal Server connection options
+ */
+export interface ConnectionOptions {
+  /**
+   * Server hostname and optional port.
+   * Port defaults to 7233 if address contains only host.
+   *
+   * @default localhost:7233
+   */
+  address?: string;
+
+  /**
+   * TLS configuration.
+   * Pass a falsy value to use a non-encrypted connection or `true` or `{}` to
+   * connect with TLS without any customization.
+   *
+   * Either {@link credentials} or this may be specified for configuring TLS
+   */
+  tls?: TLSConfig | boolean | null;
+
+  /**
+   * Channel credentials, create using the factory methods defined {@link https://grpc.github.io/grpc/node/grpc.credentials.html | here}
+   *
+   * Either {@link tls} or this may be specified for configuring TLS
+   */
+  credentials?: grpc.ChannelCredentials;
+
+  /**
+   * GRPC Channel arguments
+   *
+   * @see option descriptions {@link https://grpc.github.io/grpc/core/group__grpc__arg__keys.html | here}
+   */
+  channelArgs?: grpc.ChannelOptions;
+
+  /**
+   * Grpc interceptors which will be applied to every RPC call performed by this connection. By
+   * default, an interceptor will be included which automatically retries retryable errors. If you
+   * do not wish to perform automatic retries, set this to an empty list (or a list with your own
+   * interceptors).
+   */
+  interceptors?: grpc.Interceptor[];
+
+  /**
+   * Optional mapping of gRPC metadata (HTTP headers) to send with each request to the server.
+   *
+   * In order to dynamically set metadata, use {@link Connection.withMetadata}
+   */
+  metadata?: Metadata;
+
+  /**
+   * Milliseconds to wait until establishing a connection with the server.
+   *
+   * 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
+   * @default 10 seconds
+   */
+  connectTimeout?: number | string;
+}
+
+export type ConnectionOptionsWithDefaults = Required<Omit<ConnectionOptions, 'tls' | 'connectTimeout'>> & {
+  connectTimeoutMs: number;
+};
+
+export const LOCAL_TARGET = '127.0.0.1:7233';
+
+export function defaultConnectionOpts(): ConnectionOptionsWithDefaults {
+  return {
+    address: LOCAL_TARGET,
+    credentials: grpc.credentials.createInsecure(),
+    channelArgs: {},
+    interceptors: [makeGrpcRetryInterceptor(defaultGrpcRetryOptions())],
+    metadata: {},
+    connectTimeoutMs: 10_000,
+  };
+}
+
+/**
+ * - Convert {@link ConnectionOptions.tls} to {@link grpc.ChannelCredentials}
+ * - Add the grpc.ssl_target_name_override GRPC {@link ConnectionOptions.channelArgs | channel arg}
+ * - Add default port to address if port not specified
+ */
+function normalizeGRPCConfig(options?: ConnectionOptions): ConnectionOptions {
+  const { tls: tlsFromConfig, credentials, ...rest } = options || {};
+  if (rest.address) {
+    // eslint-disable-next-line prefer-const
+    let [host, port] = rest.address.split(':', 2);
+    port = port || '7233';
+    rest.address = `${host}:${port}`;
+  }
+  const tls = normalizeTlsConfig(tlsFromConfig);
+  if (tls) {
+    if (credentials) {
+      throw new TypeError('Both `tls` and `credentials` ConnectionOptions were provided');
+    }
+    return {
+      ...rest,
+      credentials: grpc.credentials.createSsl(
+        tls.serverRootCACertificate,
+        tls.clientCertPair?.key,
+        tls.clientCertPair?.crt
+      ),
+      channelArgs: {
+        ...rest.channelArgs,
+        ...(tls.serverNameOverride
+          ? {
+              'grpc.ssl_target_name_override': tls.serverNameOverride,
+              'grpc.default_authority': tls.serverNameOverride,
+            }
+          : undefined),
+      },
+    };
+  } else {
+    return rest;
+  }
+}
+
+export interface RPCImplOptions {
+  serviceName: string;
+  client: grpc.Client;
+  callContextStorage: AsyncLocalStorage<CallContext>;
+  interceptors?: grpc.Interceptor[];
+}
+
+export interface ConnectionCtorOptions {
+  readonly options: ConnectionOptionsWithDefaults;
+  readonly client: grpc.Client;
+  /**
+   * Raw gRPC access to the Temporal service.
+   *
+   * **NOTE**: The namespace provided in {@link options} is **not** automatically set on requests made to the service.
+   */
+  readonly workflowService: WorkflowService;
+  readonly operatorService: OperatorService;
+  readonly callContextStorage: AsyncLocalStorage<CallContext>;
+}
+
+/**
+ * Client connection to the Temporal Server
+ *
+ * ⚠️ Connections are expensive to construct and should be reused. Make sure to {@link close} any unused connections to
+ * avoid leaking resources.
+ */
+export class Connection {
+  /**
+   * @internal
+   */
+  public static readonly Client = grpc.makeGenericClientConstructor({}, 'WorkflowService', {});
+
+  public readonly options: ConnectionOptionsWithDefaults;
+  protected readonly client: grpc.Client;
+
+  /**
+   * Used to ensure `ensureConnected` is called once.
+   */
+  protected connectPromise?: Promise<void>;
+
+  /**
+   * Raw gRPC access to Temporal Server's {@link
+   * https://github.com/temporalio/api/blob/master/temporal/api/workflowservice/v1/service.proto | Workflow service}
+   */
+  public readonly workflowService: WorkflowService;
+
+  /**
+   * Raw gRPC access to Temporal Server's
+   * {@link https://github.com/temporalio/api/blob/master/temporal/api/operatorservice/v1/service.proto | Operator service}
+   */
+  public readonly operatorService: OperatorService;
+  readonly callContextStorage: AsyncLocalStorage<CallContext>;
+
+  protected static createCtorOptions(options?: ConnectionOptions): ConnectionCtorOptions {
+    const optionsWithDefaults = {
+      ...defaultConnectionOpts(),
+      ...filterNullAndUndefined(normalizeGRPCConfig(options)),
+    };
+    // Allow overriding this
+    optionsWithDefaults.metadata['client-name'] ??= 'temporal-typescript';
+    optionsWithDefaults.metadata['client-version'] ??= pkg.version;
+
+    const client = new this.Client(
+      optionsWithDefaults.address,
+      optionsWithDefaults.credentials,
+      optionsWithDefaults.channelArgs
+    );
+    const callContextStorage = new AsyncLocalStorage<CallContext>();
+    callContextStorage.enterWith({ metadata: optionsWithDefaults.metadata });
+
+    const workflowRpcImpl = this.generateRPCImplementation({
+      serviceName: 'temporal.api.workflowservice.v1.WorkflowService',
+      client,
+      callContextStorage,
+      interceptors: optionsWithDefaults?.interceptors,
+    });
+    const workflowService = WorkflowService.create(workflowRpcImpl, false, false);
+    const operatorRpcImpl = this.generateRPCImplementation({
+      serviceName: 'temporal.api.operatorservice.v1.OperatorService',
+      client,
+      callContextStorage,
+      interceptors: optionsWithDefaults?.interceptors,
+    });
+    const operatorService = OperatorService.create(operatorRpcImpl, false, false);
+
+    return {
+      client,
+      callContextStorage,
+      workflowService,
+      operatorService,
+      options: optionsWithDefaults,
+    };
+  }
+
+  /**
+   * Ensure connection can be established.
+   *
+   * Does not need to be called if you use {@link connect}.
+   *
+   * This method's result is memoized to ensure it runs only once.
+   *
+   * Calls {@link proto.temporal.api.workflowservice.v1.WorkflowService.getSystemInfo} internally.
+   */
+  async ensureConnected(): Promise<void> {
+    if (this.connectPromise == null) {
+      const deadline = Date.now() + this.options.connectTimeoutMs;
+      this.connectPromise = (async () => {
+        await this.untilReady(deadline);
+
+        try {
+          await this.withDeadline(deadline, () => this.workflowService.getSystemInfo({}));
+        } catch (err) {
+          if (isServerErrorResponse(err)) {
+            // Ignore old servers
+            if (err.code !== grpc.status.UNIMPLEMENTED) {
+              throw new ServiceError('Failed to connect to Temporal server', { cause: err });
+            }
+          } else {
+            throw err;
+          }
+        }
+      })();
+    }
+    return this.connectPromise;
+  }
+
+  /**
+   * Create a lazy `Connection` instance.
+   *
+   * This method does not verify connectivity with the server. We recommend using {@link connect} instead.
+   */
+  static lazy(options?: ConnectionOptions): Connection {
+    return new this(this.createCtorOptions(options));
+  }
+
+  /**
+   * Establish a connection with the server and return a `Connection` instance.
+   *
+   * This is the preferred method of creating connections as it verifies connectivity by calling
+   * {@link ensureConnected}.
+   */
+  static async connect(options?: ConnectionOptions): Promise<Connection> {
+    const conn = this.lazy(options);
+    await conn.ensureConnected();
+    return conn;
+  }
+
+  protected constructor({
+    options,
+    client,
+    workflowService,
+    operatorService,
+    callContextStorage,
+  }: ConnectionCtorOptions) {
+    this.options = options;
+    this.client = client;
+    this.workflowService = workflowService;
+    this.operatorService = operatorService;
+    this.callContextStorage = callContextStorage;
+  }
+
+  protected static generateRPCImplementation({
+    serviceName,
+    client,
+    callContextStorage,
+    interceptors,
+  }: RPCImplOptions): RPCImpl {
+    return (method: { name: string }, requestData: any, callback: grpc.requestCallback<any>) => {
+      const metadataContainer = new grpc.Metadata();
+      const { metadata, deadline } = callContextStorage.getStore() ?? {};
+      if (metadata != null) {
+        for (const [k, v] of Object.entries(metadata)) {
+          metadataContainer.set(k, v);
+        }
+      }
+      return client.makeUnaryRequest(
+        `/${serviceName}/${method.name}`,
+        (arg: any) => arg,
+        (arg: any) => arg,
+        requestData,
+        metadataContainer,
+        { interceptors, deadline },
+        callback
+      );
+    };
+  }
+
+  /**
+   * Set the deadline for any service requests executed in `fn`'s scope.
+   *
+   * @returns value returned from `fn`
+   */
+  async withDeadline<ReturnType>(deadline: number | Date, fn: () => Promise<ReturnType>): Promise<ReturnType> {
+    const cc = this.callContextStorage.getStore();
+    return await this.callContextStorage.run({ deadline, metadata: cc?.metadata }, fn);
+  }
+
+  /**
+   * Set metadata for any service requests executed in `fn`'s scope.
+   *
+   * The provided metadata is merged on top of any existing metadata in current scope, including metadata provided in
+   * {@link ConnectionOptions.metadata}.
+   *
+   * @returns value returned from `fn`
+   *
+   * @example
+   *
+   *```ts
+   *const workflowHandle = await conn.withMetadata({ apiKey: 'secret' }, () =>
+   *  conn.withMetadata({ otherKey: 'set' }, () => client.start(options)))
+   *);
+   *```
+   */
+  async withMetadata<ReturnType>(metadata: Metadata, fn: () => Promise<ReturnType>): Promise<ReturnType> {
+    const cc = this.callContextStorage.getStore();
+    metadata = { ...cc?.metadata, ...metadata };
+    return await this.callContextStorage.run({ metadata, deadline: cc?.deadline }, fn);
+  }
+
+  /**
+   * Wait for successful connection to the server.
+   *
+   * @see https://grpc.github.io/grpc/node/grpc.Client.html#waitForReady__anchor
+   */
+  protected async untilReady(deadline: number): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      this.client.waitForReady(deadline, (err) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
+  // This method is async for uniformity with NativeConnection which could be used in the future to power clients
+  /**
+   * Close the underlying gRPC client.
+   *
+   * Make sure to call this method to ensure proper resource cleanup.
+   */
+  public async close(): Promise<void> {
+    this.client.close();
+  }
+}

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;
+}