@travetto/runtime 5.0.0-rc.2

package/src/env.ts

@@ -0,0 +1,109 @@
+const IS_TRUE = /^(true|yes|on|1)$/i;
+const IS_FALSE = /^(false|no|off|0)$/i;
+
+export class EnvProp<T> {
+  constructor(public readonly key: string) { }
+
+  /** Set value according to prop type */
+  set(val: T | undefined | null): void {
+    if (val === undefined || val === null) {
+      delete process.env[this.key];
+    } else {
+      process.env[this.key] = Array.isArray(val) ? `${val.join(',')}` : `${val}`;
+    }
+  }
+
+  /** Remove value */
+  clear(): void {
+    this.set(null);
+  }
+
+  /** Export value */
+  export(val: T | undefined): Record<string, string> {
+    let out: string;
+    if (val === undefined || val === '' || val === null) {
+      out = '';
+    } else if (Array.isArray(val)) {
+      out = val.join(',');
+    } else if (typeof val === 'object') {
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      out = Object.entries(val as Record<string, string>).map(([k, v]) => `${k}=${v}`).join(',');
+    } else {
+      out = `${val}`;
+    }
+    return { [this.key]: out };
+  }
+
+  /** Read value as string */
+  get val(): string | undefined { return process.env[this.key] || undefined; }
+
+  /** Read value as list */
+  get list(): string[] | undefined {
+    const val = this.val;
+    return (val === undefined || val === '') ?
+      undefined : val.split(/[, ]+/g).map(x => x.trim()).filter(x => !!x);
+  }
+
+  /** Read value as object */
+  get object(): Record<string, string> | undefined {
+    const items = this.list;
+    return items ? Object.fromEntries(items.map(x => x.split(/[:=]/g))) : undefined;
+  }
+
+  /** Add values to list */
+  add(...items: string[]): void {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    this.set([... new Set([...this.list ?? [], ...items])] as T);
+  }
+
+  /** Read value as int  */
+  get int(): number | undefined {
+    const vi = parseInt(this.val ?? '', 10);
+    return Number.isNaN(vi) ? undefined : vi;
+  }
+
+  /** Read value as boolean */
+  get bool(): boolean | undefined {
+    const val = this.val;
+    return (val === undefined || val === '') ? undefined : IS_TRUE.test(val);
+  }
+
+  /** Determine if the underlying value is truthy */
+  get isTrue(): boolean {
+    return IS_TRUE.test(this.val ?? '');
+  }
+
+  /** Determine if the underlying value is falsy */
+  get isFalse(): boolean {
+    return IS_FALSE.test(this.val ?? '');
+  }
+
+  /** Determine if the underlying value is set */
+  get isSet(): boolean {
+    const val = this.val;
+    return val !== undefined && val !== '';
+  }
+}
+
+type AllType = {
+  [K in keyof TravettoEnv]: Pick<EnvProp<TravettoEnv[K]>, 'key' | 'export' | 'val' | 'set' | 'clear' | 'isSet' |
+    (TravettoEnv[K] extends unknown[] ? 'list' | 'add' : never) |
+    (Extract<TravettoEnv[K], object> extends never ? never : 'object') |
+    (Extract<TravettoEnv[K], number> extends never ? never : 'int') |
+    (Extract<TravettoEnv[K], boolean> extends never ? never : 'bool' | 'isTrue' | 'isFalse')
+  >
+};
+
+function delegate<T extends object>(base: T): AllType & T {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  return new Proxy(base as AllType & T, {
+    get(target, prop): unknown {
+      return typeof prop !== 'string' ? undefined :
+        // @ts-expect-error
+        (prop in base ? base[prop] : target[prop] ??= new EnvProp(prop));
+    }
+  });
+}
+
+/** Basic utils for reading known environment variables */
+export const Env = delegate({});

package/src/error.ts

@@ -0,0 +1,66 @@
+export type ErrorCategory =
+  'general' |
+  'notfound' |
+  'data' |
+  'permissions' |
+  'authentication' |
+  'timeout' |
+  'unavailable';
+
+/**
+ * Framework error class, with the aim of being extensible
+ */
+export class AppError<T = unknown> extends Error {
+
+  /** Convert from JSON object */
+  static fromJSON(e: unknown): AppError | undefined {
+    if (!!e && typeof e === 'object' &&
+      ('message' in e && typeof e.message === 'string') &&
+      ('category' in e && typeof e.category === 'string') &&
+      ('type' in e && typeof e.type === 'string') &&
+      ('at' in e && typeof e.at === 'number')
+    ) {
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      const err = new AppError(e.message, e.category as ErrorCategory, 'details' in e ? e.details : undefined);
+      err.at = new Date(e.at);
+      err.type = e.type;
+      return err;
+    }
+  }
+
+  type: string;
+  at = new Date();
+  details: T;
+
+  /**
+   * Build an app error
+   *
+   * @param message The error message
+   * @param category The error category, can be mapped to HTTP statuses
+   * @param details Optional error payload
+   */
+  constructor(
+    message: string,
+    public category: ErrorCategory = 'general',
+    details?: T
+
+  ) {
+    super(message);
+    this.type = this.constructor.name;
+    this.details = details!;
+  }
+
+  /**
+   * The format of the JSON output
+   */
+  toJSON(): { message: string, category: string, type: string, at: string, details?: Record<string, unknown> } {
+    return {
+      message: this.message,
+      category: this.category,
+      type: this.type,
+      at: this.at.toISOString(),
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      details: this.details as Record<string, unknown>,
+    };
+  }
+}

package/src/exec.ts

@@ -0,0 +1,156 @@
+import { ChildProcess } from 'node:child_process';
+import { Readable } from 'node:stream';
+import { createInterface } from 'node:readline/promises';
+
+const MINUTE = (1000 * 60);
+
+const RESULT = Symbol.for('@travetto/runtime:exec-result');
+
+interface ExecutionBaseResult {
+  /**
+   * Exit code
+   */
+  code: number;
+  /**
+   * Execution result message, should be inline with code
+   */
+  message?: string;
+  /**
+   * Whether or not the execution completed successfully
+   */
+  valid: boolean;
+}
+
+/**
+ * Result of an execution
+ */
+export interface ExecutionResult<T extends string | Buffer = string | Buffer> extends ExecutionBaseResult {
+  /**
+   * Stdout
+   */
+  stdout: T;
+  /**
+   * Stderr
+   */
+  stderr: T;
+}
+
+/**
+ * Standard utilities for managing executions
+ */
+export class ExecUtil {
+
+  static RESTART_EXIT_CODE = 200;
+
+  /**
+   * Run with automatic restart support
+   * @param run The factory to produce the next running process
+   * @param maxRetriesPerMinute The number of times to allow a retry within a minute
+   */
+  static async withRestart(run: () => ChildProcess, maxRetriesPerMinute?: number): Promise<ExecutionResult> {
+    const maxRetries = maxRetriesPerMinute ?? 5;
+    const restarts: number[] = [];
+
+    for (; ;) {
+      const proc = run();
+
+      const toKill = (): void => { proc.kill('SIGKILL'); };
+      const toMessage = (v: unknown): void => { proc.send?.(v!); };
+
+      // Proxy kill requests
+      process.on('message', toMessage);
+      process.on('SIGINT', toKill);
+      proc.on('message', v => process.send?.(v));
+
+      const result = await this.getResult(proc, { catch: true });
+      if (result.code !== this.RESTART_EXIT_CODE) {
+        return result;
+      } else {
+        process.off('SIGINT', toKill);
+        process.off('message', toMessage);
+        restarts.unshift(Date.now());
+        if (restarts.length === maxRetries) {
+          if ((restarts[0] - restarts[maxRetries - 1]) <= MINUTE) {
+            console.error(`Bailing, due to ${maxRetries} restarts in under a minute`);
+            return result;
+          }
+          restarts.pop(); // Keep list short
+        }
+        console.error('Restarting...', { pid: process.pid });
+      }
+    }
+  }
+
+  /**
+   * Take a child process, and some additional options, and produce a promise that
+   * represents the entire execution.  On successful completion the promise will resolve, and
+   * on failed completion the promise will reject.
+   *
+   * @param proc The process to enhance
+   * @param options The options to use to enhance the process
+   */
+  static getResult(proc: ChildProcess): Promise<ExecutionResult<string>>;
+  static getResult(proc: ChildProcess, options: { catch?: boolean, binary?: false }): Promise<ExecutionResult<string>>;
+  static getResult(proc: ChildProcess, options: { catch?: boolean, binary: true }): Promise<ExecutionResult<Buffer>>;
+  static getResult<T extends string | Buffer>(proc: ChildProcess, options: { catch?: boolean, binary?: boolean } = {}): Promise<ExecutionResult<T>> {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const res = (proc as unknown as { [RESULT]: Promise<ExecutionResult> })[RESULT] ??= new Promise<ExecutionResult>(resolve => {
+      const stdout: Buffer[] = [];
+      const stderr: Buffer[] = [];
+      let done = false;
+      const finish = (result: ExecutionBaseResult): void => {
+        if (done) {
+          return;
+        }
+        done = true;
+
+        const buffers = {
+          stdout: Buffer.concat(stdout),
+          stderr: Buffer.concat(stderr),
+        };
+
+        const final = {
+          stdout: options.binary ? buffers.stdout : buffers.stdout.toString('utf8'),
+          stderr: options.binary ? buffers.stderr : buffers.stderr.toString('utf8'),
+          ...result
+        };
+
+        resolve(!final.valid ?
+          { ...final, message: `${final.message || final.stderr || final.stdout || 'failed'}` } :
+          final
+        );
+      };
+
+      proc.stdout?.on('data', (d: string | Buffer) => stdout.push(Buffer.from(d)));
+      proc.stderr?.on('data', (d: string | Buffer) => stderr.push(Buffer.from(d)));
+
+      proc.on('error', (err: Error) =>
+        finish({ code: 1, message: err.message, valid: false }));
+
+      proc.on('close', (code: number) =>
+        finish({ code, valid: code === null || code === 0 }));
+
+      if (proc.exitCode !== null) { // We are already done
+        finish({ code: proc.exitCode, valid: proc.exitCode === 0 });
+      }
+    });
+
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return (options.catch ? res : res.then(v => {
+      if (v.valid) {
+        return v;
+      } else {
+        throw new Error(v.message);
+      }
+    })) as Promise<ExecutionResult<T>>;
+  }
+
+  /**
+   * Consume lines
+   */
+  static async readLines(stream: Readable, handler: (input: string) => unknown | Promise<unknown>): Promise<void> {
+    for await (const item of createInterface(stream)) {
+      await handler(item);
+    }
+  }
+}

package/src/file-loader.ts

@@ -0,0 +1,59 @@
+import { createReadStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { AppError } from './error';
+
+/**
+ * File loader that will search for files across the provided search paths
+ */
+export class FileLoader {
+
+  #searchPaths: readonly string[];
+
+  constructor(paths: string[]) {
+    this.#searchPaths = paths;
+  }
+
+  /**
+   * The paths that will be searched on resolve
+   */
+  get searchPaths(): readonly string[] {
+    return this.#searchPaths;
+  }
+
+  /**
+   * Return the absolute path for the given relative path
+   * @param relativePath The path to resolve
+   */
+  async resolve(relativePath: string): Promise<string> {
+    for (const sub of this.searchPaths) {
+      const resolved = path.join(sub, relativePath);
+      if (await fs.stat(resolved).catch(() => false)) {
+        return resolved;
+      }
+    }
+    throw new AppError(`Unable to find: ${relativePath}, searched=${this.searchPaths.join(',')}`, 'notfound');
+  }
+
+  /**
+   * Read a file, after resolving the path
+   * @param relativePath The path to read
+   */
+  async read(relativePath: string, binary?: false): Promise<string>;
+  async read(relativePath: string, binary: true): Promise<Buffer>;
+  async read(relativePath: string, binary = false): Promise<string | Buffer> {
+    const file = await this.resolve(relativePath);
+    return fs.readFile(file, binary ? undefined : 'utf8');
+  }
+
+  /**
+   * Read a file as a stream
+   * @param relativePath The path to read
+   */
+  async readStream(relativePath: string, binary = true): Promise<Readable> {
+    const file = await this.resolve(relativePath);
+    return createReadStream(file, { encoding: binary ? undefined : 'utf8' });
+  }
+}

package/src/function.ts

@@ -0,0 +1,42 @@
+export type FunctionMetadataTag = { hash: number, lines: [number, number] };
+export type FunctionMetadata = FunctionMetadataTag & {
+  id: string;
+  import: string;
+  methods?: Record<string, FunctionMetadataTag>;
+  synthetic?: boolean;
+  abstract?: boolean;
+};
+
+const METADATA = Symbol.for('@travetto/runtime:function-metadata');
+
+/**
+ * Initialize the meta data for a function/class
+ * @param fn Class
+ * @param `file` Filename
+ * @param `hash` Hash of class contents
+ * @param `line` Line number in source
+ * @param `methods` Methods and their hashes
+ * @param `abstract` Is the class abstract
+ * @param `synthetic` Is this code generated at build time
+ * @private
+ */
+export function register(
+  fn: Function, module: [string, string], tag: FunctionMetadataTag,
+  methods?: Record<string, FunctionMetadataTag>, abstract?: boolean, synthetic?: boolean
+): void {
+  let id = module.join(':');
+  if (fn.name) {
+    id = `${id}￮${fn.name}`;
+  }
+  const value = { id, import: module.join('/'), ...tag, methods, abstract, synthetic };
+  Object.defineProperties(fn, { Ⲑid: { value: id }, [METADATA]: { value } });
+}
+
+/**
+ * Read metadata
+ */
+export function describeFunction(fn: Function): FunctionMetadata;
+export function describeFunction(fn?: Function): FunctionMetadata | undefined {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  return (fn as unknown as { [METADATA]: FunctionMetadata })?.[METADATA];
+}

package/src/global.d.ts

@@ -0,0 +1,3 @@
+declare interface Function {
+  Ⲑid: string;
+}

package/src/manifest-index.ts

@@ -0,0 +1,4 @@
+import { ManifestIndex } from '@travetto/manifest';
+
+/** Runtime manifest index */
+export const RuntimeIndex = new ManifestIndex();

package/src/resources.ts

@@ -0,0 +1,26 @@
+import { Runtime } from './context';
+import { Env } from './env';
+import { FileLoader } from './file-loader';
+
+/**
+ * Environment aware file loader
+ */
+class $RuntimeResources extends FileLoader {
+  #computed: string[];
+  #env: string;
+
+  constructor() {
+    super(Runtime.resourcePaths());
+  }
+
+  override get searchPaths(): readonly string[] {
+    if (this.#env !== Env.TRV_RESOURCES.val) {
+      this.#env = Env.TRV_RESOURCES.val!;
+      this.#computed = Runtime.resourcePaths();
+    }
+    return this.#computed ?? super.searchPaths;
+  }
+}
+
+/** Runtime resources */
+export const RuntimeResources = new $RuntimeResources();

package/src/shutdown.ts

@@ -0,0 +1,65 @@
+import { Env } from './env';
+import { Util } from './util';
+import { TimeUtil } from './time';
+
+/**
+ * Shutdown manager, allowing for listening for graceful shutdowns
+ */
+export class ShutdownManager {
+
+  static #registered = false;
+  static #handlers: { name?: string, handler: () => Promise<void> }[] = [];
+
+  /**
+   * On Shutdown requested
+   * @param name name to log for
+   * @param handler synchronous or asynchronous handler
+   */
+  static onGracefulShutdown(handler: () => Promise<void>, name?: string | { constructor: { Ⲑid: string } }): () => void {
+    if (!this.#registered) {
+      this.#registered = true;
+      const done = (): void => { this.gracefulShutdown(0); };
+      process.on('SIGUSR2', done).on('SIGTERM', done).on('SIGINT', done);
+    }
+    this.#handlers.push({ handler, name: typeof name === 'string' ? name : name?.constructor.Ⲑid });
+    return () => {
+      const idx = this.#handlers.findIndex(x => x.handler === handler);
+      if (idx >= 0) {
+        this.#handlers.splice(idx, 1);
+      }
+    };
+  }
+
+  /**
+   * Wait for graceful shutdown to run and complete
+   */
+  static async gracefulShutdown(code: number | string | undefined = process.exitCode): Promise<void> {
+    if (code !== undefined) {
+      process.exitCode = code;
+    }
+
+    if (this.#handlers.length) {
+      console.debug('Graceful shutdown: started');
+
+      const items = this.#handlers.splice(0, this.#handlers.length);
+      const handlers = Promise.all(items.map(({ name, handler }) => {
+        if (name) {
+          console.debug('Stopping', { name });
+        }
+        return handler().catch(err => {
+          console.error('Error shutting down', { name, err });
+        });
+      }));
+
+      await Promise.race([
+        Util.nonBlockingTimeout(TimeUtil.fromValue(Env.TRV_SHUTDOWN_WAIT.val) ?? 2000), // Wait 2s and then force finish
+        handlers,
+      ]);
+
+      console.debug('Graceful shutdown: completed');
+    }
+    if (code !== undefined) {
+      process.exit();
+    }
+  }
+}

package/src/time.ts

@@ -0,0 +1,101 @@
+const MIN = 1000 * 60;
+const DAY = 24 * MIN * 60;
+const TIME_UNITS = {
+  y: DAY * 365,
+  M: DAY * 30,
+  w: DAY * 7,
+  d: DAY,
+  h: MIN * 60,
+  m: MIN,
+  s: 1000,
+  ms: 1
+};
+
+export type TimeSpan = `${number}${keyof typeof TIME_UNITS}`;
+export type TimeUnit = keyof typeof TIME_UNITS;
+
+export class TimeUtil {
+
+  static #timePattern = new RegExp(`^(?<amount>-?[0-9.]+)(?<unit>${Object.keys(TIME_UNITS).join('|')})$`);
+
+  /**
+   * Test to see if a string is valid for relative time
+   * @param val
+   */
+  static isTimeSpan(val: string): val is TimeSpan {
+    return this.#timePattern.test(val);
+  }
+
+  /**
+   * Returns time units convert to ms
+   * @param amount Number of units to extend
+   * @param unit Time unit to extend ('ms', 's', 'm', 'h', 'd', 'w', 'y')
+   */
+  static asMillis(amount: Date | number | TimeSpan, unit?: TimeUnit): number {
+    if (amount instanceof Date) {
+      return amount.getTime();
+    } else if (typeof amount === 'string') {
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      const { groups } = (amount.match(this.#timePattern) as { groups: { amount?: string, unit?: TimeUnit } });
+      const amountStr = groups?.amount ?? `${amount}`;
+      unit = groups?.unit ?? unit ?? 'ms';
+      if (!TIME_UNITS[unit]) {
+        return NaN;
+      }
+      amount = amountStr.includes('.') ? parseFloat(amountStr) : parseInt(amountStr, 10);
+    }
+    return amount * TIME_UNITS[unit ?? 'ms'];
+  }
+
+  /**
+   * Returns the time converted to seconds
+   * @param date The date to convert
+   */
+  static asSeconds(date: Date | number | TimeSpan, unit?: TimeUnit): number {
+    return Math.trunc(this.asMillis(date, unit) / 1000);
+  }
+
+  /**
+   * Returns the time converted to a Date
+   * @param date The date to convert
+   */
+  static asDate(date: Date | number | TimeSpan, unit?: TimeUnit): Date {
+    return new Date(this.asMillis(date, unit));
+  }
+
+  /**
+   * Resolve time or span to possible time
+   */
+  static fromValue(value: Date | number | string | undefined): number | undefined {
+    if (value === undefined) {
+      return value;
+    }
+    const val = (typeof value === 'string' && /\d+[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(val) ? undefined : val;
+  }
+
+  /**
+   * Returns a new date with `amount` units into the future
+   * @param amount Number of units to extend
+   * @param unit Time unit to extend ('ms', 's', 'm', 'h', 'd', 'w', 'y')
+   */
+  static fromNow(amount: number | TimeSpan, unit: TimeUnit = 'ms'): Date {
+    return new Date(Date.now() + this.asMillis(amount, unit));
+  }
+
+  /**
+   * Returns a pretty timestamp
+   * @param time Time in milliseconds
+   */
+  static asClock(time: number): string {
+    const s = Math.trunc(time / 1000);
+    return [
+      s > 3600 ? `${Math.trunc(s / 3600).toString().padStart(2, '0')}h` : '',
+      s > 60 ? `${Math.trunc((s % 3600) / 60).toString().padStart(2, '0')}m` : '',
+      `${(s % 60).toString().padStart(2, '0')}s`
+    ].filter(x => !!x).slice(0, 2).join(' ');
+  }
+}

package/src/trv.d.ts

@@ -0,0 +1,59 @@
+import type { ManifestModuleRole } from '@travetto/manifest';
+
+import type { TimeSpan } from './time';
+
+type Role = Exclude<ManifestModuleRole, 'std' | 'compile'>;
+
+
+declare global {
+  interface TravettoEnv {
+    /** 
+     * The node environment we are running in
+     * @default development
+     */
+    NODE_ENV: 'development' | 'production';
+    /** 
+     * Outputs all console.debug messages, defaults to `local` in dev, and `off` in prod. 
+     */
+    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.  
+     */
+    TRV_ROLE: Role;
+    /** 
+     * Whether or not to run the program in dynamic mode, allowing for real-time updates  
+     */
+    TRV_DYNAMIC: boolean;
+    /** 
+     * The folders to use for resource lookup
+     */
+    TRV_RESOURCES: string[];
+    /** 
+     * Resource path overrides
+     * @private
+     */
+    TRV_RESOURCE_OVERRIDES: Record<string, string>;
+    /** 
+     * The max time to wait for shutdown to finish after initial SIGINT, 
+     * @default 2s
+     */
+    TRV_SHUTDOWN_WAIT: TimeSpan | number;
+    /**
+     * The desired runtime module 
+     */
+    TRV_MODULE: string;
+    /**
+     * The location of the manifest file
+     * @default undefined
+     */
+    TRV_MANIFEST: string;
+    /**
+     * trvc log level
+     */
+    TRV_BUILD: 'none' | 'info' | 'debug' | 'error' | 'warn'
+  }
+}