feat(toolkit-lib): emit marker messages during actions

Author: mrgrain

.projenrc.ts

@@ -705,6 +705,7 @@ const tmpToolkitHelpers = configureProject(
       'archiver',
       'glob',
       'semver',
+      'uuid',
       'yaml@^1',
     ],
     tsconfig: {

packages/@aws-cdk/tmp-toolkit-helpers/.projen/deps.json

@@ -1,4 +1,5 @@
 export * from './io-helper';
 export * from './level-priority';
+export * from './marker';
 export * from './message-maker';
 export * from './types';

packages/@aws-cdk/tmp-toolkit-helpers/.projen/tasks.json

@@ -1,38 +1,59 @@
 import type { IIoHost } from '../io-host';
 import type { IoMessage, IoRequest } from '../io-message';
 import type { ToolkitAction } from '../toolkit-action';
+import type { MarkerEnd, MarkerStart, MarkerDefinition } from './marker';
+import { Marker } from './marker';
 
-export type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
-export type SimplifiedMessage<T> = Pick<IoMessage<T>, 'level' | 'code' | 'message' | 'data'>;
 export type ActionLessMessage<T> = Omit<IoMessage<T>, 'action'>;
 export type ActionLessRequest<T, U> = Omit<IoRequest<T, U>, 'action'>;
 
 /**
- * Helper for IO messaging.
- *
- * Wraps a client provided IoHost and provides additional features & services to toolkit internal classes.
+ * A class containing helper tools to interact with IoHost
  */
-export interface IoHelper extends IIoHost {
-  notify<T>(msg: ActionLessMessage<T>): Promise<void>;
-  requestResponse<T, U>(msg: ActionLessRequest<T, U>): Promise<U>;
+export class IoHelper implements IIoHost {
+  public static fromIoHost(ioHost: IIoHost, action: ToolkitAction) {
+    return new IoHelper(ioHost, action);
+  }
+
+  private readonly ioHost: IIoHost;
+  private readonly action: ToolkitAction;
+
+  private constructor(ioHost: IIoHost, action: ToolkitAction) {
+    this.ioHost = ioHost;
+    this.action = action;
+  }
+
+  /**
+   * Forward a message to the IoHost, while injection the current action
+   */
+  public notify<T>(msg: ActionLessMessage<T>): Promise<void> {
+    return this.ioHost.notify({
+      ...msg,
+      action: this.action,
+    });
+  }
+
+  /**
+   * Forward a request to the IoHost, while injection the current action
+   */
+  public requestResponse<T, U>(msg: ActionLessRequest<T, U>): Promise<U> {
+    return this.ioHost.requestResponse({
+      ...msg,
+      action: this.action,
+    });
+  }
+
+  /**
+   * Create a new marker from a given registry entry
+   */
+  public marker<S extends MarkerStart, E extends MarkerEnd>(type: MarkerDefinition<S, E>): Marker<S, E> {
+    return new Marker(this, type);
+  }
 }
 
 /**
  * Wraps an IoHost and creates an IoHelper from it
  */
 export function asIoHelper(ioHost: IIoHost, action: ToolkitAction): IoHelper {
-  return {
-    notify: async <T>(msg: Omit<IoMessage<T>, 'action'>) => {
-      await ioHost.notify({
-        ...msg,
-        action,
-      });
-    },
-    requestResponse: async <T, U>(msg: Omit<IoRequest<T, U>, 'action'>) => {
-      return ioHost.requestResponse({
-        ...msg,
-        action,
-      });
-    },
-  };
+  return IoHelper.fromIoHost(ioHost, action);
 }

packages/@aws-cdk/tmp-toolkit-helpers/package.json

@@ -0,0 +1,141 @@
+import * as util from 'node:util';
+import * as uuid from 'uuid';
+import type { IoHelper } from './io-helper';
+import type { IoMessageMaker } from './message-maker';
+import { formatTime } from '../../../util';
+
+export interface MarkerStart {
+  readonly marker: string;
+}
+
+export interface MarkerEnd {
+  readonly marker: string;
+  readonly duration: number;
+}
+
+/**
+ * Describes a specific marker
+ *
+ * A marker definition is a pair of `IoMessageMaker`s to create a start and end message respectively
+ * and a display name that is used to auto-generate messages.
+ */
+export interface MarkerDefinition<S extends MarkerStart, E extends MarkerEnd> {
+  readonly name: string;
+  readonly start: IoMessageMaker<S>;
+  readonly end: IoMessageMaker<E>;
+}
+
+/**
+ * Used in conditional types to check if a type (e.g. after omitting fields) is an empty object
+ * This is needed because counter-intuitive neither `object` nor `{}` represent that.
+ */
+type EmptyObject = {
+  [index: string | number | symbol]: never;
+}
+
+/**
+ * Helper type to force a parameter to be not present of the computed type is an empty object
+ */
+type VoidWhenEmpty<T> = T extends EmptyObject ? void : T
+
+/**
+ * Helper type to force a parameter to be an empty object if the computed type is an empty object
+ * This is weird, but some computed types (e.g. using `Omit`) don't end up enforcing this.
+ */
+type ForceEmpty<T> = T extends EmptyObject ? EmptyObject : T
+
+/**
+ * A minimal interface that provides a single function to end the marker
+ */
+interface CanEndMarker<E extends MarkerEnd> {
+  end(payload: VoidWhenEmpty<Omit<E, keyof MarkerEnd>>): Promise<ObservedDuration>;
+  end(message: string, payload: ForceEmpty<Omit<E, keyof MarkerEnd>>): Promise<ObservedDuration>;
+}
+
+/**
+ * Ending the marker returns the observed duration
+ */
+export interface ObservedDuration {
+  readonly marker: string;
+  readonly asMs: number;
+  readonly asSec: number;
+}
+
+/**
+ * Helper class to mark task blocks
+ *
+ * Blocks will be enclosed by a start and end message.
+ * Both messages share a unique id.
+ * The end message contains the time passed between start and end.
+ */
+export class Marker<S extends MarkerStart, E extends MarkerEnd> {
+  public readonly type: MarkerDefinition<S, E>;
+  private readonly ioHelper: IoHelper;
+  private startTime: number;
+  private id: string;
+
+  public constructor(ioHelper: IoHelper, type: MarkerDefinition<S, E>) {
+    this.type = type;
+    this.ioHelper = ioHelper;
+    this.startTime = new Date().getTime();
+    this.id = uuid.v4();
+  }
+
+  /**
+   * Starts the marker and notifies the IoHost.
+   * @returns an object that can end the marker
+   */
+  public async start(payload: VoidWhenEmpty<Omit<S, keyof MarkerStart>>): Promise<CanEndMarker<E>>;
+  public async start(message: string, payload: Omit<S, keyof MarkerStart>): Promise<CanEndMarker<E>>;
+  public async start(first: any, second?: Omit<S, keyof MarkerStart>): Promise<CanEndMarker<E>> {
+    this.startTime = new Date().getTime();
+
+    const msg = second ? first : 'Starting %s ...';
+    const payload = second ?? first;
+
+    await this.ioHelper.notify(this.type.start.msg(
+      util.format(msg, this.type.name), {
+        marker: this.id,
+        ...payload,
+      } as S));
+
+    return {
+      end: (a: any, b?: Omit<E, keyof MarkerEnd>): Promise<ObservedDuration> => {
+        return this.end(a, b);
+      },
+    } as CanEndMarker<E>;
+  }
+
+  /**
+   * Ends the current timer as a specified timing and notifies the IoHost.
+   * @returns the elapsed time
+   */
+  private async end(first: any | undefined, second?: Omit<E, keyof MarkerEnd>): Promise<ObservedDuration> {
+    const duration = this.time();
+
+    const msg = second ? first : `\n✨  %s time: ${duration.asSec}s\n`;
+    const payload = second ?? first;
+
+    await this.ioHelper.notify(this.type.end.msg(
+      util.format(msg, this.type.name), {
+        marker: this.id,
+        duration: duration.asMs,
+        ...payload,
+      } as E));
+
+    return duration;
+  }
+
+  /**
+   * Get the current timer for the marker
+   * @returns the elapsed time
+   */
+  private time(): ObservedDuration {
+    const elapsedTime = new Date().getTime() - this.startTime;
+    return {
+      marker: this.id,
+      asMs: elapsedTime,
+      asSec: formatTime(elapsedTime),
+    };
+  }
+}

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/private/index.ts

@@ -229,6 +229,12 @@ export class BootstrapSource {
 }
 
 export interface BootstrapEnvironmentProgress {
+  /**
+   * Uniquely identifies this marker amongst concurrent messages
+   *
+   * This is an otherwise meaningless identifier.
+   */
+  readonly marker: string;
   /**
    * The total number of environments being deployed
    */

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/private/io-helper.ts

@@ -1,4 +1,5 @@
 import type { CloudFormationStackArtifact } from '@aws-cdk/cx-api';
+import type { IManifestEntry } from 'cdk-assets';
 import type { BaseDeployOptions } from './private/deploy-options';
 import type { Tag } from '../../api/aws-cdk';
 import type { ConfirmationRequest } from '../../toolkit/types';
@@ -219,6 +220,12 @@ export interface HotswapProperties {
 }
 
 export interface StackDeployProgress {
+  /**
+   * Uniquely identifies this marker amongst concurrent messages
+   *
+   * This is an otherwise meaningless identifier.
+   */
+  readonly marker: string;
   /**
    * The total number of stacks being deployed
    */
@@ -245,3 +252,30 @@ export interface DeployConfirmationRequest extends ConfirmationRequest {
    */
   readonly permissionChangeType: PermissionChangeType;
 }
+
+export interface BuildAsset {
+  /**
+   * Uniquely identifies this marker amongst concurrent messages
+   *
+   * This is an otherwise meaningless identifier.
+   */
+  readonly marker: string;
+  /**
+   * The asset that is build
+   */
+  readonly asset: IManifestEntry;
+}
+
+export interface PublishAsset {
+  /**
+   * Uniquely identifies this marker amongst concurrent messages
+   *
+   * This is an otherwise meaningless identifier.
+   */
+  readonly marker: string;
+
+  /**
+   * The asset that is published
+   */
+  readonly asset: IManifestEntry;
+}

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/private/marker.ts

@@ -21,6 +21,12 @@ export interface DestroyOptions {
 }
 
 export interface StackDestroyProgress {
+  /**
+   * Uniquely identifies this marker amongst concurrent messages
+   *
+   * This is an otherwise meaningless identifier.
+   */
+  readonly marker: string;
   /**
    * The total number of stacks being destroyed
    */