@temporalio/common 0.18.0 → 0.19.0

package/src/converter/protobuf-payload-converters.ts

@@ -0,0 +1,192 @@
+import {
+  errorMessage,
+  hasOwnProperties,
+  hasOwnProperty,
+  isRecord,
+  PayloadConverterError,
+  ValueError,
+} from '@temporalio/internal-workflow-common';
+import * as protoJsonSerializer from 'proto3-json-serializer';
+import type { Message, Namespace, Root, Type } from 'protobufjs';
+import { CompositePayloadConverter } from './payload-converter';
+import {
+  BinaryPayloadConverter,
+  JsonPayloadConverter,
+  PayloadConverterWithEncoding,
+  UndefinedPayloadConverter,
+} from './payload-converters';
+import {
+  EncodingType,
+  encodingTypes,
+  METADATA_ENCODING_KEY,
+  METADATA_MESSAGE_TYPE_KEY,
+  Payload,
+  str,
+  u8,
+} from './types';
+
+abstract class ProtobufPayloadConverter implements PayloadConverterWithEncoding {
+  protected readonly root: Root | undefined;
+  public abstract encodingType: EncodingType;
+
+  public abstract toPayload<T>(value: T): Payload | undefined;
+  public abstract fromPayload<T>(payload: Payload): T;
+
+  // Don't use type Root here because root.d.ts doesn't export Root, so users would have to type assert
+  constructor(root?: unknown) {
+    if (root) {
+      if (!isRoot(root)) {
+        throw new TypeError('root must be an instance of a protobufjs Root');
+      }
+
+      this.root = root;
+    }
+  }
+
+  protected validatePayload(content: Payload): { messageType: Type; data: Uint8Array } {
+    if (content.data === undefined || content.data === null) {
+      throw new ValueError('Got payload with no data');
+    }
+    if (!content.metadata || !(METADATA_MESSAGE_TYPE_KEY in content.metadata)) {
+      throw new ValueError(`Got protobuf payload without metadata.${METADATA_MESSAGE_TYPE_KEY}`);
+    }
+    if (!this.root) {
+      throw new PayloadConverterError('Unable to deserialize protobuf message without `root` being provided');
+    }
+
+    const messageTypeName = str(content.metadata[METADATA_MESSAGE_TYPE_KEY]);
+    let messageType;
+    try {
+      messageType = this.root.lookupType(messageTypeName);
+    } catch (e) {
+      if (errorMessage(e)?.includes('no such type')) {
+        throw new PayloadConverterError(
+          `Got a \`${messageTypeName}\` protobuf message but cannot find corresponding message class in \`root\``
+        );
+      }
+
+      throw e;
+    }
+
+    return { messageType, data: content.data };
+  }
+
+  protected constructPayload({ messageTypeName, message }: { messageTypeName: string; message: Uint8Array }): Payload {
+    return {
+      metadata: {
+        [METADATA_ENCODING_KEY]: u8(this.encodingType),
+        [METADATA_MESSAGE_TYPE_KEY]: u8(messageTypeName),
+      },
+      data: message,
+    };
+  }
+}
+
+/**
+ * Converts between protobufjs Message instances and serialized Protobuf Payload
+ */
+export class ProtobufBinaryPayloadConverter extends ProtobufPayloadConverter {
+  public encodingType = encodingTypes.METADATA_ENCODING_PROTOBUF;
+
+  /**
+   * @param root The value returned from {@link patchProtobufRoot}
+   */
+  constructor(root?: unknown) {
+    super(root);
+  }
+
+  public toPayload(value: unknown): Payload | undefined {
+    if (!isProtobufMessage(value)) return undefined;
+
+    return this.constructPayload({
+      messageTypeName: getNamespacedTypeName(value.$type),
+      message: value.$type.encode(value).finish(),
+    });
+  }
+
+  public fromPayload<T>(content: Payload): T {
+    const { messageType, data } = this.validatePayload(content);
+    return messageType.decode(data) as unknown as T;
+  }
+}
+
+/**
+ * Converts between protobufjs Message instances and serialized JSON Payload
+ */
+export class ProtobufJsonPayloadConverter extends ProtobufPayloadConverter {
+  public encodingType = encodingTypes.METADATA_ENCODING_PROTOBUF_JSON;
+
+  /**
+   * @param root The value returned from {@link patchProtobufRoot}
+   */
+  constructor(root?: unknown) {
+    super(root);
+  }
+
+  public toPayload(value: unknown): Payload | undefined {
+    if (!isProtobufMessage(value)) return undefined;
+
+    const jsonValue = protoJsonSerializer.toProto3JSON(value);
+
+    return this.constructPayload({
+      messageTypeName: getNamespacedTypeName(value.$type),
+      message: u8(JSON.stringify(jsonValue)),
+    });
+  }
+
+  public fromPayload<T>(content: Payload): T {
+    const { messageType, data } = this.validatePayload(content);
+    return protoJsonSerializer.fromProto3JSON(messageType, JSON.parse(str(data))) as unknown as T;
+  }
+}
+
+function isProtobufType(type: unknown): type is Type {
+  return (
+    isRecord(type) &&
+    type.constructor.name === 'Type' &&
+    hasOwnProperties(type, ['parent', 'name', 'create', 'encode', 'decode']) &&
+    typeof type.name === 'string' &&
+    typeof type.create === 'function' &&
+    typeof type.encode === 'function' &&
+    typeof type.decode === 'function'
+  );
+}
+
+function isProtobufMessage(value: unknown): value is Message {
+  return isRecord(value) && hasOwnProperty(value, '$type') && isProtobufType(value.$type);
+}
+
+function getNamespacedTypeName(node: Type | Namespace): string {
+  if (node.parent && !isRoot(node.parent)) {
+    return getNamespacedTypeName(node.parent) + '.' + node.name;
+  } else {
+    return node.name;
+  }
+}
+
+function isRoot(root: unknown): root is Root {
+  return isRecord(root) && root.constructor.name === 'Root';
+}
+
+export interface DefaultPayloadConverterWithProtobufsOptions {
+  /**
+   * The `root` provided to {@link ProtobufJsonPayloadConverter} and {@link ProtobufBinaryPayloadConverter}
+   */
+  protobufRoot: Record<string, unknown>;
+}
+
+export class DefaultPayloadConverterWithProtobufs extends CompositePayloadConverter {
+  // Match the order used in other SDKs.
+  //
+  // Go SDK:
+  // https://github.com/temporalio/sdk-go/blob/5e5645f0c550dcf717c095ae32c76a7087d2e985/converter/default_data_converter.go#L28
+  constructor({ protobufRoot }: DefaultPayloadConverterWithProtobufsOptions) {
+    super(
+      new UndefinedPayloadConverter(),
+      new BinaryPayloadConverter(),
+      new ProtobufJsonPayloadConverter(protobufRoot),
+      new ProtobufBinaryPayloadConverter(protobufRoot),
+      new JsonPayloadConverter()
+    );
+  }
+}

package/src/converter/types.ts

@@ -1,7 +1,7 @@
-import type * as iface from '@temporalio/proto/lib/coresdk';
-import { TextEncoder, TextDecoder } from '../encoding';
+import type { coresdk } from '@temporalio/proto/lib/coresdk';
+import { TextDecoder, TextEncoder } from './encoding';
 
-export type Payload = iface.coresdk.common.IPayload;
+export type Payload = coresdk.common.IPayload;
 
 /**
  * Transform an *ascii* string into a Uint8Array
@@ -22,6 +22,7 @@ export const encodingTypes = {
   METADATA_ENCODING_PROTOBUF_JSON: 'json/protobuf',
   METADATA_ENCODING_PROTOBUF: 'binary/protobuf',
 } as const;
+export type EncodingType = typeof encodingTypes[keyof typeof encodingTypes];
 
 export const encodingKeys = {
   METADATA_ENCODING_NULL: u8(encodingTypes.METADATA_ENCODING_NULL),
@@ -30,3 +31,5 @@ export const encodingKeys = {
   METADATA_ENCODING_PROTOBUF_JSON: u8(encodingTypes.METADATA_ENCODING_PROTOBUF_JSON),
   METADATA_ENCODING_PROTOBUF: u8(encodingTypes.METADATA_ENCODING_PROTOBUF),
 } as const;
+
+export const METADATA_MESSAGE_TYPE_KEY = 'messageType';

package/src/failure.ts

@@ -1,9 +1,10 @@
+import { checkExtends, hasOwnProperties, isRecord } from '@temporalio/internal-workflow-common';
 import type { temporal } from '@temporalio/proto/lib/coresdk';
-import { DataConverter, arrayFromPayloads } from './converter/data-converter';
-import { checkExtends, hasOwnProperties, isRecord } from './type-helpers';
+import { arrayFromPayloads, fromPayloadsAtIndex, PayloadConverter, toPayloads } from './converter/payload-converter';
 
 export const FAILURE_SOURCE = 'TypeScriptSDK';
 export type ProtoFailure = temporal.api.failure.v1.IFailure;
+
 // Avoid importing the proto implementation to reduce workflow bundle size
 // Copied from temporal.api.enums.v1.TimeoutType
 export enum TimeoutType {
@@ -78,7 +79,7 @@ export class ServerFailure extends TemporalFailure {
  * Any unhandled exception which doesn't extend {@link TemporalFailure} is converted to an
  * instance of this class before being returned to a caller.
  *
- * The {@link type} property is used by {@link io.temporal.common.RetryOptions} to determine if
+ * The {@link type} property is used by {@link temporal.common.RetryOptions} to determine if
  * an instance of this exception is non retryable. Another way to avoid retrying an exception of
  * this type is by setting {@link nonRetryable} flag to `true`.
  *
@@ -210,11 +211,11 @@ export class ChildWorkflowFailure extends TemporalFailure {
 /**
  * Converts an error to a Failure proto message if defined or returns undefined
  */
-export async function optionalErrorToOptionalFailure(
+export function optionalErrorToOptionalFailure(
   err: unknown,
-  dataConverter: DataConverter
-): Promise<ProtoFailure | undefined> {
-  return err ? await errorToFailure(err, dataConverter) : undefined;
+  payloadConverter: PayloadConverter
+): ProtoFailure | undefined {
+  return err ? errorToFailure(err, payloadConverter) : undefined;
 }
 
 /**
@@ -225,6 +226,8 @@ const CUTOFF_STACK_PATTERNS = [
   /\s+at Activity\.execute \(.*[\\/]worker[\\/](?:src|lib)[\\/]activity\.[jt]s:\d+:\d+\)/,
   /** Workflow activation */
   /\s+at Activator\.\S+NextHandler \(webpack-internal:\/\/\/.*\/internals\.[jt]s:\d+:\d+\)/,
+  /** Workflow run anything in context */
+  /\s+at Script\.runInContext/,
 ];
 
 /**
@@ -245,14 +248,14 @@ export function cutoffStackTrace(stack?: string): string {
 /**
  * Converts a caught error to a Failure proto message
  */
-export async function errorToFailure(err: unknown, dataConverter: DataConverter): Promise<ProtoFailure> {
+export function errorToFailure(err: unknown, payloadConverter: PayloadConverter): ProtoFailure {
   if (err instanceof TemporalFailure) {
     if (err.failure) return err.failure;
 
     const base = {
       message: err.message,
       stackTrace: cutoffStackTrace(err.stack),
-      cause: await optionalErrorToOptionalFailure(err.cause, dataConverter),
+      cause: optionalErrorToOptionalFailure(err.cause, payloadConverter),
       source: FAILURE_SOURCE,
     };
     if (err instanceof ActivityFailure) {
@@ -281,9 +284,7 @@ export async function errorToFailure(err: unknown, dataConverter: DataConverter)
           type: err.type,
           nonRetryable: err.nonRetryable,
           details:
-            err.details && err.details.length
-              ? { payloads: await dataConverter.toPayloads(...err.details) }
-              : undefined,
+            err.details && err.details.length ? { payloads: toPayloads(payloadConverter, ...err.details) } : undefined,
         },
       };
     }
@@ -292,9 +293,7 @@ export async function errorToFailure(err: unknown, dataConverter: DataConverter)
         ...base,
         canceledFailureInfo: {
           details:
-            err.details && err.details.length
-              ? { payloads: await dataConverter.toPayloads(...err.details) }
-              : undefined,
+            err.details && err.details.length ? { payloads: toPayloads(payloadConverter, ...err.details) } : undefined,
         },
       };
     }
@@ -304,7 +303,7 @@ export async function errorToFailure(err: unknown, dataConverter: DataConverter)
         timeoutFailureInfo: {
           timeoutType: err.timeoutType,
           lastHeartbeatDetails: err.lastHeartbeatDetails
-            ? { payloads: await dataConverter.toPayloads(err.lastHeartbeatDetails) }
+            ? { payloads: toPayloads(payloadConverter, err.lastHeartbeatDetails) }
             : undefined,
         },
       };
@@ -334,7 +333,7 @@ export async function errorToFailure(err: unknown, dataConverter: DataConverter)
       ...base,
       message: String(err.message) ?? '',
       stackTrace: cutoffStackTrace(String(err.stack)),
-      cause: await optionalErrorToOptionalFailure(err.cause, dataConverter),
+      cause: optionalErrorToOptionalFailure(err.cause, payloadConverter),
     };
   }
 
@@ -371,11 +370,11 @@ export function ensureTemporalFailure(err: unknown): TemporalFailure {
 /**
  * Converts a Failure proto message to a JS Error object if defined or returns undefined.
  */
-export async function optionalFailureToOptionalError(
+export function optionalFailureToOptionalError(
   failure: ProtoFailure | undefined | null,
-  dataConverter: DataConverter
-): Promise<TemporalFailure | undefined> {
-  return failure ? await failureToError(failure, dataConverter) : undefined;
+  payloadConverter: PayloadConverter
+): TemporalFailure | undefined {
+  return failure ? failureToError(failure, payloadConverter) : undefined;
 }
 
 /**
@@ -383,44 +382,41 @@ export async function optionalFailureToOptionalError(
  *
  * Does not set common properties, that is done in {@link failureToError}.
  */
-export async function failureToErrorInner(
-  failure: ProtoFailure,
-  dataConverter: DataConverter
-): Promise<TemporalFailure> {
+export function failureToErrorInner(failure: ProtoFailure, payloadConverter: PayloadConverter): TemporalFailure {
   if (failure.applicationFailureInfo) {
     return new ApplicationFailure(
       failure.message ?? undefined,
       failure.applicationFailureInfo.type,
       Boolean(failure.applicationFailureInfo.nonRetryable),
-      await arrayFromPayloads(dataConverter, failure.applicationFailureInfo.details?.payloads),
-      await optionalFailureToOptionalError(failure.cause, dataConverter)
+      arrayFromPayloads(payloadConverter, failure.applicationFailureInfo.details?.payloads),
+      optionalFailureToOptionalError(failure.cause, payloadConverter)
     );
   }
   if (failure.serverFailureInfo) {
     return new ServerFailure(
       failure.message ?? undefined,
       Boolean(failure.serverFailureInfo.nonRetryable),
-      await optionalFailureToOptionalError(failure.cause, dataConverter)
+      optionalFailureToOptionalError(failure.cause, payloadConverter)
     );
   }
   if (failure.timeoutFailureInfo) {
     return new TimeoutFailure(
       failure.message ?? undefined,
-      await dataConverter.fromPayloads(0, failure.timeoutFailureInfo.lastHeartbeatDetails?.payloads),
+      fromPayloadsAtIndex(payloadConverter, 0, failure.timeoutFailureInfo.lastHeartbeatDetails?.payloads),
       failure.timeoutFailureInfo.timeoutType ?? TimeoutType.TIMEOUT_TYPE_UNSPECIFIED
     );
   }
   if (failure.terminatedFailureInfo) {
     return new TerminatedFailure(
       failure.message ?? undefined,
-      await optionalFailureToOptionalError(failure.cause, dataConverter)
+      optionalFailureToOptionalError(failure.cause, payloadConverter)
     );
   }
   if (failure.canceledFailureInfo) {
     return new CancelledFailure(
       failure.message ?? undefined,
-      await arrayFromPayloads(dataConverter, failure.canceledFailureInfo.details?.payloads),
-      await optionalFailureToOptionalError(failure.cause, dataConverter)
+      arrayFromPayloads(payloadConverter, failure.canceledFailureInfo.details?.payloads),
+      optionalFailureToOptionalError(failure.cause, payloadConverter)
     );
   }
   if (failure.resetWorkflowFailureInfo) {
@@ -428,8 +424,8 @@ export async function failureToErrorInner(
       failure.message ?? undefined,
       'ResetWorkflow',
       false,
-      await arrayFromPayloads(dataConverter, failure.resetWorkflowFailureInfo.lastHeartbeatDetails?.payloads),
-      await optionalFailureToOptionalError(failure.cause, dataConverter)
+      arrayFromPayloads(payloadConverter, failure.resetWorkflowFailureInfo.lastHeartbeatDetails?.payloads),
+      optionalFailureToOptionalError(failure.cause, payloadConverter)
     );
   }
   if (failure.childWorkflowExecutionFailureInfo) {
@@ -442,7 +438,7 @@ export async function failureToErrorInner(
       workflowExecution,
       workflowType.name,
       retryState ?? RetryState.RETRY_STATE_UNSPECIFIED,
-      await optionalFailureToOptionalError(failure.cause, dataConverter)
+      optionalFailureToOptionalError(failure.cause, payloadConverter)
     );
   }
   if (failure.activityFailureInfo) {
@@ -454,20 +450,20 @@ export async function failureToErrorInner(
       failure.activityFailureInfo.activityId ?? undefined,
       failure.activityFailureInfo.retryState ?? RetryState.RETRY_STATE_UNSPECIFIED,
       failure.activityFailureInfo.identity ?? undefined,
-      await optionalFailureToOptionalError(failure.cause, dataConverter)
+      optionalFailureToOptionalError(failure.cause, payloadConverter)
     );
   }
   return new TemporalFailure(
     failure.message ?? undefined,
-    await optionalFailureToOptionalError(failure.cause, dataConverter)
+    optionalFailureToOptionalError(failure.cause, payloadConverter)
   );
 }
 
 /**
  * Converts a Failure proto message to a JS Error object.
  */
-export async function failureToError(failure: ProtoFailure, dataConverter: DataConverter): Promise<TemporalFailure> {
-  const err = await failureToErrorInner(failure, dataConverter);
+export function failureToError(failure: ProtoFailure, payloadConverter: PayloadConverter): TemporalFailure {
+  const err = failureToErrorInner(failure, payloadConverter);
   err.stack = failure.stackTrace ?? '';
   err.failure = failure;
   return err;

package/src/index.ts

@@ -1,17 +1,15 @@
 /**
- * Common library for both isolated Workflow and normal non-Workflow code
+ * Common library for code that's used across the Client, Worker, and/or Workflow
  *
  * @module
  */
-export * from './activity-options';
+export { ActivityFunction, ActivityInterface, Headers, Next, 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/time';
 export * from './converter/data-converter';
-export * from './errors';
+export * from './converter/payload-codec';
+export * from './converter/payload-converter';
+export * from './converter/payload-converters';
+export * from './converter/types';
 export * from './failure';
-export * from './interceptors';
-export * from './interfaces';
-export * from './retry-policy';
-export * from './time';
-export * from './tls-config';
-export * from './workflow-handle';
-export * from './workflow-options';
-export * from './utils';

package/src/protobufs.ts

@@ -0,0 +1,15 @@
+/**
+ * Entry point for classes and utilities related to using
+ * [Protobufs](https://docs.temporal.io/docs/typescript/data-converters#protobufs) for serialization.
+ *
+ * Import from `@temporalio/common/lib/protobufs`, for example:
+ *
+ * ```
+ * import { patchProtobufRoot } from '@temporalio/common/lib/protobufs';
+ * ```
+ * @module
+ */
+
+// Don't export from index, so we save space in Workflow bundles of users who don't use Protobufs
+export * from './converter/protobuf-payload-converters';
+export * from './converter/patch-protobuf-root';

package/tsconfig.json

@@ -4,6 +4,6 @@
     "outDir": "./lib",
     "rootDir": "./src"
   },
-  "include": ["./src/**/*.ts"],
-  "exclude": ["node_modules"]
+  "references": [{ "path": "../internal-workflow-common" }],
+  "include": ["./src/**/*.ts"]
 }