@travetto/runtime 7.0.5 → 7.1.0

package/README.md

@@ -35,12 +35,12 @@ While running any code within the framework, there are common patterns/goals for
 ```typescript
 class $Runtime {
   constructor(idx: ManifestIndex, resourceOverrides?: Record<string, string>);
-  /** Get env name, with support for the default env */
-  get env(): string | undefined;
+  /** The role we are running as */
+  get role(): Role;
   /** Are we in production mode */
   get production(): boolean;
-  /** Get environment type mode */
-  get envType(): 'production' | 'development' | 'test';
+  /** Are we in development mode */
+  get localDevelopment(): boolean;
   /** Get debug value */
   get debug(): false | string;
   /** Manifest main */
@@ -87,15 +87,11 @@ interface EnvData {
      */
     NODE_ENV: 'development' | 'production';
     /** 
-     * Outputs all console.debug messages, defaults to `local` in dev, and `off` in prod. 
+     * Outputs all console.debug messages, defaults to off
      */
     DEBUG: boolean | string;
     /** 
-     * Environment to deploy, defaults to `NODE_ENV` if not `TRV_ENV` is not specified.  
-     */
-    TRV_ENV: string;
-    /** 
-     * Special role to run as, used to access additional files from the manifest during runtime.  
+     * The role we are running as, allows access to additional files from the manifest during runtime.
      */
     TRV_ROLE: Role;
     /** 
@@ -112,6 +108,11 @@ interface EnvData {
      * @default 2s
      */
     TRV_SHUTDOWN_WAIT: TimeSpan | number;
+    /** 
+     * The time to wait for stdout to drain during shutdown
+     * @default 0s
+     */
+    TRV_SHUTDOWN_STDOUT_WAIT: TimeSpan | number;
     /**
      * The desired runtime module 
      */
@@ -214,7 +215,7 @@ export function work() {
 ```javascript
 import * as Δfunction from "@travetto/runtime/src/function.js";
 import * as Δconsole from "@travetto/runtime/src/console.js";
-var Δm_1 = ["@travetto/runtime", "doc/transpile.ts"];
+const Δm_1 = ["@travetto/runtime", "doc/transpile.ts"];
 export function work() {
     Δconsole.log({ level: "debug", import: Δm_1, line: 2, scope: "work", args: ['Start Work'] });
     try {
@@ -282,7 +283,7 @@ tpl`{{age:20}} {{name: 'bob'}}</>;
 ```
 
 ## Time Utilities
-[TimeUtil](https://github.com/travetto/travetto/tree/main/module/runtime/src/time.ts#L19) contains general helper methods, created to assist with time-based inputs via environment variables, command line interfaces, and other string-heavy based input.
+[TimeUtil](https://github.com/travetto/travetto/tree/main/module/runtime/src/time.ts#L20) contains general helper methods, created to assist with time-based inputs via environment variables, command line interfaces, and other string-heavy based input.
 
 **Code: Time Utilities**
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/runtime",
-  "version": "7.0.5",
+  "version": "7.1.0",
   "type": "module",
   "description": "Runtime for travetto applications.",
   "keywords": [
@@ -26,12 +26,12 @@
     "directory": "module/runtime"
   },
   "dependencies": {
-    "@travetto/manifest": "^7.0.4",
+    "@travetto/manifest": "^7.1.0",
     "@types/debug": "^4.1.12",
     "debug": "^4.4.3"
   },
   "peerDependencies": {
-    "@travetto/transformer": "^7.0.5"
+    "@travetto/transformer": "^7.1.0"
   },
   "peerDependenciesMeta": {
     "@travetto/transformer": {

package/src/context.ts

@@ -7,6 +7,7 @@ import { Env } from './env.ts';
 import { RuntimeIndex } from './manifest-index.ts';
 import { describeFunction } from './function.ts';
 import { JSONUtil } from './json.ts';
+import type { Role } from './trv';
 
 /** Constrained version of {@type ManifestContext} */
 class $Runtime {
@@ -26,9 +27,10 @@ class $Runtime {
     };
   }
 
-  /** Get env name, with support for the default env */
-  get env(): string | undefined {
-    return Env.TRV_ENV.value || (!this.production ? this.#idx.manifest.workspace.defaultEnv : undefined);
+  /** The role we are running as */
+  get role(): Role {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return Env.TRV_ROLE.value as Role ?? 'std';
   }
 
   /** Are we in production mode */
@@ -36,19 +38,14 @@ class $Runtime {
     return process.env.NODE_ENV === 'production';
   }
 
-  /** Get environment type mode */
-  get envType(): 'production' | 'development' | 'test' {
-    switch (process.env.NODE_ENV) {
-      case 'production': return 'production';
-      case 'test': return 'test';
-      default: return 'development';
-    }
+  /** Are we in development mode */
+  get localDevelopment(): boolean {
+    return !this.production && this.role === 'std';
   }
 
   /** Get debug value */
   get debug(): false | string {
-    const value = Env.DEBUG.value ?? '';
-    return (!value && this.production) || Env.DEBUG.isFalse ? false : value;
+    return Env.DEBUG.isFalse ? false : (Env.DEBUG.value || false);
   }
 
   /** Manifest main */

package/src/exec.ts

@@ -42,29 +42,19 @@ export class ExecUtil {
   /**
    * Defer control to subprocess execution, mainly used for nested execution
    */
-  static async deferToSubprocess(child: ChildProcess, relayInterrupt: boolean = true): Promise<ExecutionResult> {
-    if (!relayInterrupt) {
-      process.removeAllListeners('SIGINT'); // Remove any existing listeners
-      process.on('SIGINT', () => { }); // Prevents SIGINT from killing parent process, the child will handle
+  static async deferToSubprocess(child: ChildProcess): Promise<ExecutionResult> {
+    const messageToChild = (value: unknown): void => { child.send(value!); };
+    const messageToParent = (value: unknown): void => { process.send?.(value); };
+
+    try {
+      process.on('message', messageToChild);
+      child.on('message', messageToParent);
+      const result = await this.getResult(child, { catch: true });
+      process.exitCode = child.exitCode;
+      return result;
+    } finally {
+      process.off('message', messageToChild);
     }
-
-    child.on('message', value => process.send?.(value));
-
-    const interrupt = (): void => { child?.kill('SIGINT'); };
-    const toMessage = (value: unknown): void => { child?.send(value!); };
-
-    // Proxy kill requests
-    process.on('message', toMessage);
-
-    if (relayInterrupt) {
-      process.on('SIGINT', interrupt);
-    }
-
-    const result = await ExecUtil.getResult(child, { catch: true });
-    process.exitCode = child.exitCode;
-    process.off('message', toMessage);
-    process.off('SIGINT', interrupt);
-    return result;
   }
 
   /**

package/src/shutdown.ts

@@ -2,93 +2,99 @@ import { Env } from './env.ts';
 import { Util } from './util.ts';
 import { TimeUtil } from './time.ts';
 
+type Handler = (event: Event) => unknown;
+
 /**
  * Shutdown manager, allowing for listening for graceful shutdowns
  */
 export class ShutdownManager {
 
-  static #registered = false;
-  static #handlers: { scope?: string, handler: () => (void | Promise<void>) }[] = [];
-  static #pending: (PromiseWithResolvers<void> & { time: number }) | undefined;
+  static #shouldIgnoreInterrupt = false;
+  static #registered = new Map<Handler, Handler>();
+  static #pending: Function[] = [];
+  static #controller = new AbortController();
+  static #startedAt: number = 0;
+  static #addListener = this.#controller.signal.addEventListener.bind(this.#controller.signal);
+  static #removeListener = this.#controller.signal.removeEventListener.bind(this.#controller.signal);
 
-  static #ensureExitListeners(): void {
-    if (this.#registered) {
-      return;
-    }
-    this.#registered = true;
-    const cleanup = (signal: string): void => {
-      if (this.#pending && (Date.now() - this.#pending.time) > 500) {
-        console.warn('Shutdown already in progress, exiting immediately', { signal });
-        process.exit(0); // Quit immediately
-      }
-      this.gracefulShutdown(signal).then(() => process.exit(0));
+  static {
+    this.#controller.signal.addEventListener = (type: 'abort', listener: Handler): void => this.onGracefulShutdown(listener);
+    this.#controller.signal.removeEventListener = (type: 'abort', listener: Handler): void => {
+      this.#removeListener(type, this.#registered.get(listener) ?? listener);
     };
-    if (process.stdout.isTTY) {
-      process.on('SIGINT', () => process.stdout.write('\n')); // Ensure we get a newline on ctrl-c
-    }
-    process.on('SIGUSR2', cleanup);
-    process.on('SIGTERM', cleanup);
-    process.on('SIGINT', cleanup);
   }
 
-  /**
-   * On Shutdown requested
-   * @param source The source of the shutdown request, for logging purposes
-   * @param handler synchronous or asynchronous handler
-   */
-  static onGracefulShutdown(handler: () => (void | Promise<void>), scope?: string): () => void {
-    this.#ensureExitListeners();
-    this.#handlers.push({ handler, scope });
-    return () => {
-      const idx = this.#handlers.findIndex(item => item.handler === handler);
-      if (idx >= 0) {
-        this.#handlers.splice(idx, 1);
-      }
-    };
+  static get signal(): AbortSignal {
+    return this.#controller.signal;
+  }
+
+  static disableInterrupt(): void {
+    this.#shouldIgnoreInterrupt = true;
+  }
+
+  static onGracefulShutdown(listener: Handler): void {
+    if (!this.#registered.size) {
+      process
+        .on('SIGINT', () => this.shutdown('SIGINT')) // Ensure we get a newline on ctrl-c
+        .on('SIGUSR2', () => this.shutdown('SIGUSR2'))
+        .on('SIGTERM', () => this.shutdown('SIGTERM'));
+    }
+
+    const wrappedListener: Handler = event => { this.#pending.push(() => listener(event)); };
+    this.#registered.set(listener, wrappedListener);
+    return this.#addListener('abort', wrappedListener);
   }
 
   /**
-   * Wait for graceful shutdown to run and complete
+   * Shutdown the application gracefully
    */
-  static async gracefulShutdown(source: string): Promise<void> {
-    if (this.#pending) {
-      return this.#pending.promise;
-    } else if (!this.#handlers.length) {
+  static async shutdown(source?: string, code?: number): Promise<void> {
+    if (this.#shouldIgnoreInterrupt && source === 'SIGINT') {
       return;
     }
+    if (this.#controller.signal.aborted) {
+      if (this.#startedAt && (Date.now() - this.#startedAt) > 500) {
+        console.warn('Shutdown already in progress, exiting immediately', { source });
+        process.exit(0); // Quit immediately
+      } else {
+        return;
+      }
+    }
+
+    if (process.stdout.isTTY && source === 'SIGINT') {
+      process.stdout.write('\n');
+    }
 
-    this.#pending = { ...Promise.withResolvers<void>(), time: Date.now() };
+    process.removeAllListeners('message'); // Allow shutdown if anything is still listening
 
+    const context = source ? [{ source, pid: process.pid }] : [{ pid: process.pid }];
+    this.#startedAt = Date.now();
+    this.#controller.abort('Shutdown started');
     await Util.queueMacroTask(); // Force the event loop to wait one cycle
 
+    console.debug('Shutdown started', ...context, { pending: this.#pending.length });
+
     const timeout = TimeUtil.fromValue(Env.TRV_SHUTDOWN_WAIT.value) ?? 2000;
-    const items = this.#handlers.splice(0, this.#handlers.length);
-    console.debug('Graceful shutdown: started', { source, timeout, count: items.length });
-    const handlers = Promise.all(items.map(async ({ scope, handler }) => {
-      if (scope) {
-        console.debug('Stopping', { scope });
-      }
-      try {
-        await handler();
-        if (scope) {
-          console.debug('Stopped', { scope });
-        }
-      } catch (error) {
-        console.error('Error stopping', { error, scope });
-      }
-    }));
+    const timeoutTasks = Util.nonBlockingTimeout(timeout).then(() => this);
+    const allPendingTasks = Promise.all(this.#pending.map(fn => Promise.resolve(fn()).catch(err => {
+      console.error('Error during shutdown task', err, ...context);
+    })));
 
-    const winner = await Promise.race([
-      Util.nonBlockingTimeout(timeout).then(() => this), // Wait N seconds and then give up if not done
-      handlers,
-    ]);
+    const winner = await Promise.race([timeoutTasks, allPendingTasks]);
+
+    process.exitCode = code ?? process.exitCode ?? 0;
 
     if (winner !== this) {
-      console.debug('Graceful shutdown: completed');
+      console.debug('Shutdown completed', ...context);
     } else {
-      console.debug('Graceful shutdown: timed-out', { timeout });
+      console.warn('Shutdown timed out', ...context);
+    }
+
+    if (Env.TRV_SHUTDOWN_STDOUT_WAIT.isSet) {
+      const stdoutDrain = TimeUtil.fromValue(Env.TRV_SHUTDOWN_STDOUT_WAIT.value)!;
+      await Util.blockingTimeout(stdoutDrain);
     }
 
-    this.#pending.resolve();
+    process.exit();
   }
 }

package/src/time.ts

@@ -15,6 +15,7 @@ export type TimeSpan = `${number}${keyof typeof TIME_UNITS}`;
 export type TimeUnit = keyof typeof TIME_UNITS;
 
 const TIME_PATTERN = new RegExp(`^(?<amount>-?[0-9.]+)(?<unit>${Object.keys(TIME_UNITS).join('|')})$`);
+const TIME_LIKE_STRING = /\d{1,30}[a-z]$/i;
 
 export class TimeUtil {
 
@@ -66,14 +67,19 @@ export class TimeUtil {
    * Resolve time or span to possible time
    */
   static fromValue(value: Date | number | string | undefined): number | undefined {
-    if (value === undefined) {
-      return value;
+    switch (typeof value) {
+      case 'number': return Number.isNaN(value) ? undefined : value;
+      case 'object': return value.getTime();
+      case 'undefined': return undefined;
+      case 'string': {
+        if (TIME_LIKE_STRING.test(value)) { // Looks like span
+          return this.isTimeSpan(value) ? this.asMillis(value) : undefined;
+        } else {
+          const parsed = parseInt(value, 10);
+          return Number.isNaN(parsed) ? undefined : parsed;
+        }
+      }
     }
-    const result = (typeof value === 'string' && /\d{1,30}[a-z]$/i.test(value)) ?
-      (this.isTimeSpan(value) ? this.asMillis(value) : undefined) :
-      (typeof value === 'string' ? parseInt(value, 10) :
-        (value instanceof Date ? value.getTime() : value));
-    return Number.isNaN(result) ? undefined : result;
   }
 
   /**
@@ -90,11 +96,16 @@ export class TimeUtil {
    * @param time Time in milliseconds
    */
   static asClock(time: number): string {
-    const seconds = Math.trunc(time / 1000);
-    return [
-      seconds > 3600 ? `${Math.trunc(seconds / 3600).toString().padStart(2, '0')}h` : '',
-      seconds > 60 ? `${Math.trunc((seconds % 3600) / 60).toString().padStart(2, '0')}m` : '',
-      `${(seconds % 60).toString().padStart(2, '0')}s`
-    ].filter(part => !!part).slice(0, 2).join(' ');
+    const rawSeconds = Math.trunc(time / 1000);
+    const seconds = rawSeconds % 60;
+    const minutes = Math.trunc(rawSeconds / 60) % 60;
+    const hours = Math.trunc(rawSeconds / 3600);
+    if (hours) {
+      return `${hours.toString().padStart(2, '0')}h ${minutes.toString().padStart(2, '0')}m`;
+    } else if (minutes) {
+      return `${minutes.toString().padStart(2, '0')}m ${seconds.toString().padStart(2, '0')}s`;
+    } else {
+      return `${seconds.toString().padStart(2, '0')}s`;
+    }
   }
 }

package/src/trv.d.ts

@@ -1,6 +1,6 @@
 import { type ManifestModuleRole } from '@travetto/manifest';
 import { type TimeSpan } from './time.ts';
-type Role = Exclude<ManifestModuleRole, 'std' | 'compile'>;
+type Role = Exclude<ManifestModuleRole, 'compile'>;
 
 declare module "@travetto/runtime" {
   interface EnvData {
@@ -10,15 +10,11 @@ declare module "@travetto/runtime" {
      */
     NODE_ENV: 'development' | 'production';
     /** 
-     * Outputs all console.debug messages, defaults to `local` in dev, and `off` in prod. 
+     * Outputs all console.debug messages, defaults to off
      */
     DEBUG: boolean | string;
     /** 
-     * Environment to deploy, defaults to `NODE_ENV` if not `TRV_ENV` is not specified.  
-     */
-    TRV_ENV: string;
-    /** 
-     * Special role to run as, used to access additional files from the manifest during runtime.  
+     * The role we are running as, allows access to additional files from the manifest during runtime.
      */
     TRV_ROLE: Role;
     /** 
@@ -35,6 +31,11 @@ declare module "@travetto/runtime" {
      * @default 2s
      */
     TRV_SHUTDOWN_WAIT: TimeSpan | number;
+    /** 
+     * The time to wait for stdout to drain during shutdown
+     * @default 0s
+     */
+    TRV_SHUTDOWN_STDOUT_WAIT: TimeSpan | number;
     /**
      * The desired runtime module 
      */

package/src/watch.ts

@@ -31,26 +31,28 @@ export class WatchUtil {
 
   /** Convert exit code to a result type  */
   static exitCodeToResult(code: number): RetryRunState['result'] {
-    return code === this.#RESTART_EXIT_CODE ? 'restart' : code > 0 ? 'error' : 'stop';
+    return code === this.#RESTART_EXIT_CODE ? 'restart' : (code !== null && code > 0) ? 'error' : 'stop';
   }
 
   /** Exit with a restart exit code */
   static exitWithRestart(): void {
-    process.exit(this.#RESTART_EXIT_CODE);
+    ShutdownManager.shutdown('SIGTERM', this.#RESTART_EXIT_CODE);
   }
 
   /** Listen for restart signals */
-  static listenForRestartSignal(): void {
-    const listener = (event: unknown): void => {
-      if (event === 'WATCH_RESTART') { this.exitWithRestart(); }
-    };
-    process.on('message', listener);
-    ShutdownManager.onGracefulShutdown(() => { process.removeListener('message', listener); });
+  static listenForSignals(): void {
+    ShutdownManager.disableInterrupt();
+    process.on('message', event => {
+      switch (event) {
+        case 'WATCH_RESTART': this.exitWithRestart(); break;
+        case 'WATCH_SHUTDOWN': ShutdownManager.shutdown('SIGTERM', 0); break;
+      }
+    });
   }
 
-  /** Trigger a restart signal to a subprocess */
-  static triggerRestartSignal(subprocess?: ChildProcess): void {
-    subprocess?.connected && subprocess.send?.('WATCH_RESTART');
+  /** Trigger a watch signal signal to a subprocess */
+  static triggerSignal(subprocess: ChildProcess, signal: 'WATCH_RESTART' | 'WATCH_SHUTDOWN'): void {
+    subprocess.connected && subprocess.send?.(signal);
   }
 
   /** Compute the delay before restarting */
@@ -64,8 +66,6 @@ export class WatchUtil {
    * Run with restart capability
    */
   static async runWithRetry(run: (state: RetryRunState & { signal: AbortSignal }) => Promise<RetryRunState['result']>, options?: Partial<RetryRunConfig>): Promise<void> {
-    const controller = new AbortController();
-    const cleanup = ShutdownManager.onGracefulShutdown(() => controller.abort());
     let retryExhausted = false;
 
     const state: RetryRunState = {
@@ -82,14 +82,14 @@ export class WatchUtil {
     };
 
 
-    while (!controller.signal.aborted && !retryExhausted) {
+    outer: while (!ShutdownManager.signal.aborted && !retryExhausted) {
       if (state.iteration > 0) {
         await config.onRetry(state, config);
       }
 
-      state.result = await run({ ...state, signal: controller.signal }).catch(() => 'error' as const);
+      state.result = await run({ ...state, signal: ShutdownManager.signal }).catch(() => 'error' as const);
       switch (state.result) {
-        case 'stop': controller.abort(); break;
+        case 'stop': break outer;
         case 'error': state.errorIterations += 1; break;
         case 'restart': {
           state.startTime = Date.now();
@@ -104,8 +104,6 @@ export class WatchUtil {
     if (retryExhausted) {
       throw new AppError(`Operation failed after ${state.errorIterations} attempts`);
     }
-
-    cleanup?.();
   }
 
   /**  Watch compiler events  */