feat(client): Add experimental support for Cloud Operations API (#1538)

Author: mjameswh

.github/workflows/ci.yml

@@ -286,6 +286,12 @@ jobs:
           RUN_INTEGRATION_TESTS: true
           REUSE_V8_CONTEXT: ${{ matrix.reuse-v8-context }}
 
+          # Cloud Tests will be skipped if TEMPORAL_CLIENT_CLOUD_API_KEY is left empty
+          TEMPORAL_CLOUD_SAAS_ADDRESS: ${{ vars.TEMPORAL_CLOUD_SAAS_ADDRESS || 'saas-api.tmprl.cloud:443' }}
+          TEMPORAL_CLIENT_CLOUD_API_KEY: ${{ secrets.TEMPORAL_CLIENT_CLOUD_API_KEY }}
+          TEMPORAL_CLIENT_CLOUD_API_VERSION: 2024-05-13-00
+          TEMPORAL_CLIENT_CLOUD_NAMESPACE: ${{ vars.TEMPORAL_CLIENT_NAMESPACE }}
+
       - name: Upload NPM logs
         uses: actions/upload-artifact@v4
         if: failure() || cancelled()

package-lock.json

@@ -23,7 +23,8 @@
   "scripts": {
     "rebuild": "npm run clean && npm run build",
     "build": "lerna run --stream build",
-    "build.watch": "lerna run --stream build.watch",
+    "build.watch": "npm run build:protos && tsc --build --watch packages/*",
+    "build:protos": "node ./packages/proto/scripts/compile-proto.js",
     "test": "lerna run --stream test",
     "test.watch": "lerna run --stream test.watch",
     "ci-stress": "node ./packages/test/lib/load/run-all-stress-ci-scenarios.js",
@@ -38,6 +39,7 @@
   },
   "dependencies": {
     "@temporalio/client": "file:packages/client",
+    "@temporalio/cloud": "file:packages/cloud",
     "@temporalio/common": "file:packages/common",
     "@temporalio/create": "file:packages/create-project",
     "@temporalio/interceptors-opentelemetry": "file:packages/interceptors-opentelemetry",
@@ -79,6 +81,7 @@
   "workspaces": [
     "packages/activity",
     "packages/client",
+    "packages/cloud",
     "packages/common",
     "packages/core-bridge",
     "packages/create-project",

package.json

@@ -1,4 +1,5 @@
 import os from 'node:os';
+import type * as _grpc from '@grpc/grpc-js'; // For JSDoc only
 import { DataConverter, LoadedDataConverter } from '@temporalio/common';
 import { isLoadedDataConverter, loadDataConverter } from '@temporalio/common/lib/internal-non-workflow';
 import { Connection } from './connection';
@@ -51,7 +52,14 @@ export function defaultBaseClientOptions(): WithDefaults<BaseClientOptions> {
 }
 
 export class BaseClient {
+  /**
+   * The underlying {@link Connection | connection} used by this client.
+   *
+   * Clients are cheap to create, but connections are expensive. Where that make sense,
+   * a single connection may and should be reused by multiple `Client`.
+   */
   public readonly connection: ConnectionLike;
+
   private readonly loadedDataConverter: LoadedDataConverter;
 
   protected constructor(options?: BaseClientOptions) {
@@ -61,19 +69,37 @@ export class BaseClient {
   }
 
   /**
-   * Set the deadline for any service requests executed in `fn`'s scope.
+   * Set a deadline for any service requests executed in `fn`'s scope.
+   *
+   * The deadline is a point in time after which any pending gRPC request will be considered as failed;
+   * this will locally result in the request call throwing a {@link _grpc.ServiceError|ServiceError}
+   * with code {@link _grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}.
+   *
+   * It is stronly recommended to explicitly set deadlines. If no deadline is set, then it is
+   * possible for the client to end up waiting forever for a response.
+   *
+   * This method is only a convenience wrapper around {@link Connection.withDeadline}.
+   *
+   * @param deadline a point in time after which the request will be considered as failed; either a
+   *                 Date object, or a number of milliseconds since the Unix epoch (UTC).
+   * @returns the value returned from `fn`
+   *
+   * @see https://grpc.io/docs/guides/deadlines/
    */
   public async withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R> {
     return await this.connection.withDeadline(deadline, fn);
   }
 
   /**
-   * Set an {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that, when aborted,
-   * cancels any ongoing service requests executed in `fn`'s scope.
+   * Set an {@link AbortSignal} that, when aborted, cancels any ongoing service requests executed in
+   * `fn`'s scope. This will locally result in the request call throwing a {@link _grpc.ServiceError|ServiceError}
+   * with code {@link _grpc.status.CANCELLED|CANCELLED}.
+   *
+   * This method is only a convenience wrapper around {@link Connection.withAbortSignal}.
    *
    * @returns value returned from `fn`
    *
-   * @see {@link Connection.withAbortSignal}
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
    */
   async withAbortSignal<R>(abortSignal: AbortSignal, fn: () => Promise<R>): Promise<R> {
     return await this.connection.withAbortSignal(abortSignal, fn);
@@ -82,9 +108,9 @@ export class BaseClient {
   /**
    * Set metadata for any service requests executed in `fn`'s scope.
    *
-   * @returns returned value of `fn`
+   * This method is only a convenience wrapper around {@link Connection.withMetadata}.
    *
-   * @see {@link Connection.withMetadata}
+   * @returns returned value of `fn`
    */
   public async withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R> {
     return await this.connection.withMetadata(metadata, fn);

packages/client/src/base-client.ts

@@ -5,14 +5,19 @@ import {
   filterNullAndUndefined,
   normalizeTlsConfig,
   TLSConfig,
-  normalizeTemporalGrpcEndpointAddress,
+  normalizeGrpcEndpointAddress,
 } from '@temporalio/common/lib/internal-non-workflow';
 import { Duration, msOptionalToNumber } from '@temporalio/common/lib/time';
 import { isGrpcServiceError, ServiceError } from './errors';
 import { defaultGrpcRetryOptions, makeGrpcRetryInterceptor } from './grpc-retry';
 import pkg from './pkg';
 import { CallContext, HealthService, Metadata, OperatorService, WorkflowService } from './types';
 
+/**
+ * The default Temporal Server's TCP port for public gRPC connections.
+ */
+const DEFAULT_TEMPORAL_GRPC_PORT = 7233;
+
 /**
  * gRPC and Temporal Server connection options
  */
@@ -174,7 +179,7 @@ function normalizeGRPCConfig(options?: ConnectionOptions): ConnectionOptions {
     }
   }
   if (rest.address) {
-    rest.address = normalizeTemporalGrpcEndpointAddress(rest.address);
+    rest.address = normalizeGrpcEndpointAddress(rest.address, DEFAULT_TEMPORAL_GRPC_PORT);
   }
   const tls = normalizeTlsConfig(tlsFromConfig);
   if (tls) {
@@ -220,29 +225,33 @@ export interface RPCImplOptions {
 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;
+
   /**
    * 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>;
   readonly apiKeyFnRef: { fn?: () => string };
 }
 
 /**
  * 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.
+ * ⚠️ Connections are expensive to construct and should be reused.
+ * Make sure to {@link close} any unused connections to avoid leaking resources.
  */
 export class Connection {
   /**
@@ -275,7 +284,12 @@ export class Connection {
    * Cloud namespace will result in gRPC `unauthorized` error.
    */
   public readonly operatorService: OperatorService;
+
+  /**
+   * Raw gRPC access to the standard gRPC {@link https://github.com/grpc/grpc/blob/92f58c18a8da2728f571138c37760a721c8915a2/doc/health-checking.md | health service}.
+   */
   public readonly healthService: HealthService;
+
   readonly callContextStorage: AsyncLocalStorage<CallContext>;
   private readonly apiKeyFnRef: { fn?: () => string };
 
@@ -424,7 +438,8 @@ export class Connection {
       const metadataContainer = new grpc.Metadata();
       const { metadata, deadline, abortSignal } = callContextStorage.getStore() ?? {};
       if (apiKeyFnRef.fn) {
-        metadataContainer.set('Authorization', `Bearer ${apiKeyFnRef.fn()}`);
+        const apiKey = apiKeyFnRef.fn();
+        if (apiKey) metadataContainer.set('Authorization', `Bearer ${apiKey}`);
       }
       for (const [k, v] of Object.entries(staticMetadata)) {
         metadataContainer.set(k, v);
@@ -452,20 +467,32 @@ export class Connection {
   }
 
   /**
-   * Set the deadline for any service requests executed in `fn`'s scope.
+   * Set a deadline for any service requests executed in `fn`'s scope.
    *
-   * @returns value returned from `fn`
+   * The deadline is a point in time after which any pending gRPC request will be considered as failed;
+   * this will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
+   * with code {@link grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}.
+   *
+   * It is stronly recommended to explicitly set deadlines. If no deadline is set, then it is
+   * possible for the client to end up waiting forever for a response.
+   *
+   * @param deadline a point in time after which the request will be considered as failed; either a
+   *                 Date object, or a number of milliseconds since the Unix epoch (UTC).
+   * @returns the value returned from `fn`
+   *
+   * @see https://grpc.io/docs/guides/deadlines/
    */
   async withDeadline<ReturnType>(deadline: number | Date, fn: () => Promise<ReturnType>): Promise<ReturnType> {
     const cc = this.callContextStorage.getStore();
     return await this.callContextStorage.run({ ...cc, deadline }, fn);
   }
 
   /**
-   * Set an {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that, when aborted,
-   * cancels any ongoing requests executed in `fn`'s scope.
+   * Set an {@link AbortSignal} that, when aborted, cancels any ongoing service requests executed in
+   * `fn`'s scope. This will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
+   * with code {@link grpc.status.CANCELLED|CANCELLED}.
    *
-   * @returns value returned from `fn`
+   * This method is only a convenience wrapper around {@link Connection.withAbortSignal}.
    *
    * @example
    *
@@ -475,6 +502,10 @@ export class Connection {
    * // 👇 throws if incomplete by the timeout.
    * await conn.withAbortSignal(ctrl.signal, () => client.workflow.execute(myWorkflow, options));
    * ```
+   *
+   * @returns value returned from `fn`
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
    */
   async withAbortSignal<ReturnType>(abortSignal: AbortSignal, fn: () => Promise<ReturnType>): Promise<ReturnType> {
     const cc = this.callContextStorage.getStore();
@@ -572,5 +603,6 @@ export class Connection {
    */
   public async close(): Promise<void> {
     this.client.close();
+    this.callContextStorage.disable();
   }
 }

packages/client/src/connection.ts

@@ -96,8 +96,24 @@ export interface ConnectionLike {
   workflowService: WorkflowService;
   close(): Promise<void>;
   ensureConnected(): Promise<void>;
+
   /**
-   * Set the deadline for any service requests executed in `fn`'s scope.
+   * Set a deadline for any service requests executed in `fn`'s scope.
+   *
+   * The deadline is a point in time after which any pending gRPC request will be considered as failed;
+   * this will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
+   * with code {@link grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}.
+   *
+   * It is stronly recommended to explicitly set deadlines. If no deadline is set, then it is
+   * possible for the client to end up waiting forever for a response.
+   *
+   * This method is only a convenience wrapper around {@link Connection.withDeadline}.
+   *
+   * @param deadline a point in time after which the request will be considered as failed; either a
+   *                 Date object, or a number of milliseconds since the Unix epoch (UTC).
+   * @returns the value returned from `fn`
+   *
+   * @see https://grpc.io/docs/guides/deadlines/
    */
   withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R>;
 
@@ -109,10 +125,13 @@ export interface ConnectionLike {
   withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R>;
 
   /**
-   * Set an {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that, when aborted,
-   * cancels any ongoing requests executed in `fn`'s scope.
+   * Set an {@link AbortSignal} that, when aborted, cancels any ongoing service requests executed in
+   * `fn`'s scope. This will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
+   * with code {@link grpc.status.CANCELLED|CANCELLED}.
    *
    * @returns value returned from `fn`
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
    */
   withAbortSignal<R>(abortSignal: AbortSignal, fn: () => Promise<R>): Promise<R>;
 }

packages/client/src/types.ts

@@ -0,0 +1,8 @@
+# `@temporalio/cloud`
+
+[![NPM](https://img.shields.io/npm/v/@temporalio/cloud?style=for-the-badge)](https://www.npmjs.com/package/@temporalio/cloud)
+
+Part of [Temporal](https://temporal.io)'s [TypeScript SDK](https://docs.temporal.io/typescript/introduction/).
+
+- [API reference](https://typescript.temporal.io/api/namespaces/cloud)
+- [Sample projects](https://github.com/temporalio/samples-typescript)