@outputai/core 0.6.1-next.383b24b.0 → 0.6.1-next.5d7e612.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.6.1-next.383b24b.0",
+  "version": "0.6.1-next.5d7e612.0",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {
@@ -65,7 +65,7 @@
     "#bus": "./src/bus.js",
     "#consts": "./src/consts.js",
     "#errors": "./src/errors.js",
-    "#logger": "./src/logger.js",
+    "#logger": "./src/logger/index.js",
     "#utils": "./src/utils/index.js",
     "#internal_utils/*": "./src/internal_utils/*.js",
     "#tracing": "./src/tracing/internal_interface.js",

package/src/logger/development.js

@@ -0,0 +1,61 @@
+import { format, transports } from 'winston';
+import { isPlainObject, shuffleArray } from '#utils';
+
+/** Available colors enum */
+const Color = {
+  Blue: '033',
+  Green: '030',
+  Orange: '208',
+  Turquoise: '045',
+  Purple: '129',
+  Yellow: '184'
+};
+
+/**
+ * Recursively format object as friendly JSON: { name: "foo", count: 5 }
+ *
+ * @param {any} v - The input value
+ * @returns {string} Formatted result
+ */
+export const formatJson = v => {
+  if ( isPlainObject( v ) ) {
+    const entries = Object.entries( v );
+    return entries.length === 0 ? '{}' :
+      `{ ${entries.map( ( [ k, v ] ) => `${k}: ${formatJson( v )}` ).join( ', ' )} }`;
+  }
+  if ( Array.isArray( v ) ) {
+    return v.length === 0 ? '[]' : `[ ${v.map( p => formatJson( p ) ).join( ', ' )} ]`;
+  }
+  if ( typeof v === 'string' ) {
+    return JSON.stringify( v );
+  }
+  return v;
+};
+
+/** This instance color schema */
+const COLORS = shuffleArray( Object.values( Color ) );
+
+/** Stores all assigned colors per namespace. */
+const assignedColors = new Map();
+
+/**
+ * Get the previous assigned color for this value or if not present, assign a new one and store it
+ * @param {string} v - A text value
+ * @returns {string} The color
+ * */
+const getColor = v =>
+  assignedColors.get( v ) ?? assignedColors.set( v, COLORS[assignedColors.size % COLORS.length] ).get( v );
+
+export const options = {
+  level: 'debug',
+  transports: [ new transports.Console() ],
+  format: format.combine(
+    format.colorize(),
+    format.metadata(),
+    format.printf( ( { level, message, metadata } ) => {
+      const { namespace, ...fields } = metadata;
+      const jsonText = Object.keys( fields ).length > 0 ? formatJson( fields ) : null;
+      return `[${level}] \x1b[38;5;${getColor( namespace )}m${namespace}: ${message}\x1b[0m${jsonText ? ' ' + jsonText : ''}`;
+    } )
+  )
+};

package/src/logger/development.spec.js

@@ -0,0 +1,70 @@
+import { describe, expect, it, vi } from 'vitest';
+
+const LEVEL = Symbol.for( 'level' );
+const MESSAGE = Symbol.for( 'message' );
+
+vi.mock( '#utils', () => ( {
+  isPlainObject: v => Object.prototype.toString.call( v ) === '[object Object]',
+  shuffleArray: v => v
+} ) );
+
+const loadDevelopmentLogger = async () => {
+  vi.resetModules();
+  return import( './development.js' );
+};
+
+describe( 'logger/development', () => {
+  describe( 'formatJson', () => {
+    it( 'formats nested plain objects and arrays', async () => {
+      const { formatJson } = await loadDevelopmentLogger();
+
+      expect( formatJson( {
+        name: 'foo',
+        count: 5,
+        nested: { ok: true },
+        list: [ 1, 'two', { three: 3 } ]
+      } ) ).toBe( '{ name: "foo", count: 5, nested: { ok: true }, list: [ 1, "two", { three: 3 } ] }' );
+    } );
+
+    it( 'formats empty objects and arrays', async () => {
+      const { formatJson } = await loadDevelopmentLogger();
+
+      expect( formatJson( { emptyObject: {}, emptyArray: [] } ) ).toBe( '{ emptyObject: {}, emptyArray: [] }' );
+    } );
+
+    it( 'escapes string values', async () => {
+      const { formatJson } = await loadDevelopmentLogger();
+
+      expect( formatJson( { quote: 'hello "world"' } ) ).toBe( '{ quote: "hello \\"world\\"" }' );
+    } );
+  } );
+
+  describe( 'options.format', () => {
+    it( 'formats level, namespace, message, and metadata fields', async () => {
+      const { options } = await loadDevelopmentLogger();
+      const info = options.format.transform( {
+        [LEVEL]: 'info',
+        level: 'info',
+        message: 'Worker',
+        namespace: 'Telemetry',
+        status: { runState: 'RUNNING' },
+        memory: { heapUsed: 123 }
+      } );
+
+      expect( info[MESSAGE] ).toMatch( /^\[\x1b\[[\d;]+minfo\x1b\[[\d;]+m\] \x1b\[38;5;033mTelemetry: Worker\x1b\[0m /u );
+      expect( info[MESSAGE] ).toContain( '{ status: { runState: "RUNNING" }, memory: { heapUsed: 123 } }' );
+    } );
+
+    it( 'does not append metadata text when only namespace is present', async () => {
+      const { options } = await loadDevelopmentLogger();
+      const info = options.format.transform( {
+        [LEVEL]: 'debug',
+        level: 'debug',
+        message: 'Loading config...',
+        namespace: 'Worker'
+      } );
+
+      expect( info[MESSAGE] ).toMatch( /^\[\x1b\[[\d;]+mdebug\x1b\[[\d;]+m\] \x1b\[38;5;033mWorker: Loading config\.\.\.\x1b\[0m$/u );
+    } );
+  } );
+} );

package/src/logger/index.js

@@ -0,0 +1,14 @@
+import winston from 'winston';
+
+const { options } = await import( process.env.NODE_ENV === 'production' ? './production.js' : './development.js' );
+
+// creates the root winston logger
+const logger = winston.createLogger( options );
+
+/**
+ * Creates a child logger with a specific namespace
+ *
+ * @param {string} namespace - The namespace for this logger (e.g., 'Scanner', 'Tracing')
+ * @returns {winston.Logger} Child logger instance with namespace metadata
+ */
+export const createChildLogger = namespace => logger.child( { namespace } );

package/src/logger/index.spec.js

@@ -0,0 +1,27 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const loadLogger = async nodeEnv => {
+  vi.resetModules();
+  vi.stubEnv( 'NODE_ENV', nodeEnv );
+  return import( './index.js' );
+};
+
+describe( 'logger/index', () => {
+  afterEach( () => {
+    vi.unstubAllEnvs();
+  } );
+
+  it( 'loads the development logger options', async () => {
+    const { createChildLogger } = await loadLogger( 'development' );
+    const log = createChildLogger( 'Test' );
+
+    expect( typeof log.info ).toBe( 'function' );
+  } );
+
+  it( 'loads the production logger options', async () => {
+    const { createChildLogger } = await loadLogger( 'production' );
+    const log = createChildLogger( 'Test' );
+
+    expect( typeof log.info ).toBe( 'function' );
+  } );
+} );

package/src/logger/production.js

@@ -0,0 +1,15 @@
+import { transports, format } from 'winston';
+
+export const options = {
+  level: 'info',
+  transports: [ new transports.Console() ],
+  defaultMeta: {
+    service: 'output-worker',
+    environment: 'production'
+  },
+  format: format.combine(
+    format.timestamp( { format: 'YYYY-MM-DDTHH:mm:ss.SSSZ' } ),
+    format.errors( { stack: true } ),
+    format.json()
+  )
+};

package/src/logger/production.spec.js

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { options } from './production.js';
+
+const LEVEL = Symbol.for( 'level' );
+const MESSAGE = Symbol.for( 'message' );
+
+describe( 'logger/production', () => {
+  it( 'uses info level and default production metadata', () => {
+    expect( options.level ).toBe( 'info' );
+    expect( options.defaultMeta ).toEqual( {
+      service: 'output-worker',
+      environment: 'production'
+    } );
+  } );
+
+  it( 'formats logs as JSON with timestamp and metadata fields', () => {
+    const info = options.format.transform( {
+      [LEVEL]: 'info',
+      level: 'info',
+      message: 'Worker',
+      namespace: 'Telemetry',
+      status: { runState: 'RUNNING' }
+    } );
+
+    const output = JSON.parse( info[MESSAGE] );
+
+    expect( output ).toMatchObject( {
+      level: 'info',
+      message: 'Worker',
+      namespace: 'Telemetry',
+      status: { runState: 'RUNNING' }
+    } );
+    expect( output.timestamp ).toEqual( expect.stringMatching( /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}[+-]\d{2}:\d{2}$/u ) );
+  } );
+
+  it( 'includes error stack when formatting Error messages', () => {
+    const error = new Error( 'boom' );
+    const info = options.format.transform( {
+      [LEVEL]: 'error',
+      level: 'error',
+      message: error
+    } );
+
+    const output = JSON.parse( info[MESSAGE] );
+
+    expect( output ).toMatchObject( {
+      level: 'error',
+      message: 'boom'
+    } );
+    expect( output.stack ).toContain( 'Error: boom' );
+  } );
+} );

package/src/worker/configs.js

@@ -7,6 +7,7 @@ const coalesceEmptyString = v => v === '' ? undefined : v;
 
 const envVarSchema = z.object( {
   OUTPUT_CATALOG_ID: z.string().regex( /^[a-z0-9_.@-]+$/i ),
+  OUTPUT_WORKER_TELEMETRY_INTERVAL_MS: z.preprocess( coalesceEmptyString, z.coerce.number().int().nonnegative().default( 0 ) ),
   TEMPORAL_ADDRESS: z.string().default( 'localhost:7233' ),
   TEMPORAL_API_KEY: z.string().optional(),
   TEMPORAL_NAMESPACE: z.string().optional().default( 'default' ),
@@ -51,6 +52,7 @@ export const maxConcurrentWorkflowTaskPolls = envVars.TEMPORAL_MAX_CONCURRENT_WO
 export const namespace = envVars.TEMPORAL_NAMESPACE;
 export const taskQueue = envVars.OUTPUT_CATALOG_ID;
 export const catalogId = envVars.OUTPUT_CATALOG_ID;
+export const workerTelemetryIntervalMs = envVars.OUTPUT_WORKER_TELEMETRY_INTERVAL_MS;
 export const activityHeartbeatIntervalMs = envVars.OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS;
 export const activityHeartbeatEnabled = envVars.OUTPUT_ACTIVITY_HEARTBEAT_ENABLED;
 export const processFailureShutdownDelay = envVars.OUTPUT_PROCESS_FAILURE_SHUTDOWN_DELAY;

package/src/worker/configs.spec.js

@@ -10,6 +10,7 @@ const CONFIG_KEYS = [
   'TEMPORAL_MAX_CACHED_WORKFLOWS',
   'TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_POLLS',
   'TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASK_POLLS',
+  'OUTPUT_WORKER_TELEMETRY_INTERVAL_MS',
   'OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS',
   'OUTPUT_ACTIVITY_HEARTBEAT_ENABLED'
 ];
@@ -61,6 +62,7 @@ describe( 'worker/configs', () => {
     expect( configs.maxCachedWorkflows ).toBe( 1000 );
     expect( configs.maxConcurrentActivityTaskPolls ).toBe( 5 );
     expect( configs.maxConcurrentWorkflowTaskPolls ).toBe( 5 );
+    expect( configs.workerTelemetryIntervalMs ).toBe( 0 );
     expect( configs.activityHeartbeatIntervalMs ).toBe( 2 * 60 * 1000 );
     expect( configs.activityHeartbeatEnabled ).toBe( true );
     expect( configs.taskQueue ).toBe( 'test-catalog' );
@@ -74,11 +76,19 @@ describe( 'worker/configs', () => {
     expect( configs.maxConcurrentActivityTaskExecutions ).toBe( 40 );
   } );
 
+  it( 'treats empty string for worker telemetry interval as default', async () => {
+    setEnv( { OUTPUT_WORKER_TELEMETRY_INTERVAL_MS: '' } );
+    const configs = await loadConfigs();
+
+    expect( configs.workerTelemetryIntervalMs ).toBe( 0 );
+  } );
+
   it( 'parses custom numeric env vars', async () => {
     setEnv( {
       TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_EXECUTIONS: '10',
       TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASK_EXECUTIONS: '50',
       TEMPORAL_MAX_CACHED_WORKFLOWS: '500',
+      OUTPUT_WORKER_TELEMETRY_INTERVAL_MS: '30000',
       OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS: '60000'
     } );
     const configs = await loadConfigs();
@@ -86,9 +96,24 @@ describe( 'worker/configs', () => {
     expect( configs.maxConcurrentActivityTaskExecutions ).toBe( 10 );
     expect( configs.maxConcurrentWorkflowTaskExecutions ).toBe( 50 );
     expect( configs.maxCachedWorkflows ).toBe( 500 );
+    expect( configs.workerTelemetryIntervalMs ).toBe( 30000 );
     expect( configs.activityHeartbeatIntervalMs ).toBe( 60000 );
   } );
 
+  it( 'allows zero for worker telemetry interval', async () => {
+    setEnv( { OUTPUT_WORKER_TELEMETRY_INTERVAL_MS: '0' } );
+    const configs = await loadConfigs();
+
+    expect( configs.workerTelemetryIntervalMs ).toBe( 0 );
+  } );
+
+  it( 'throws when worker telemetry interval is negative', async () => {
+    setEnv( { OUTPUT_WORKER_TELEMETRY_INTERVAL_MS: '-1' } );
+    vi.resetModules();
+
+    await expect( import( './configs.js' ) ).rejects.toThrow();
+  } );
+
   it( 'throws when optional number is zero or negative', async () => {
     setEnv( { TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_EXECUTIONS: '0' } );
     vi.resetModules();

package/src/worker/index.js

@@ -11,9 +11,10 @@ import { registerShutdown } from './shutdown.js';
 import { startCatalog } from './start_catalog.js';
 import { bootstrapFetchProxy } from './proxy.js';
 import { messageBus } from '#bus';
-import './log_hooks.js';
 import { BusEventType } from '#consts';
 import { hashSourceCode } from './loader_tools.js';
+import { setupTelemetry } from './setup_telemetry.js';
+import './log_hooks.js';
 
 const log = createChildLogger( 'Worker' );
 
@@ -84,6 +85,8 @@ const callerDir = process.argv[2];
 
   registerShutdown( { worker, log } );
 
+  setupTelemetry( { worker } );
+
   log.info( 'Running worker...' );
   await Promise.all( [ worker.run(), startCatalog( { connection, namespace, catalog, catalogHash } ) ] );
 

package/src/worker/index.spec.js

@@ -62,6 +62,9 @@ vi.mock( './proxy.js', () => ( { bootstrapFetchProxy: bootstrapFetchProxyMock }
 const registerShutdownMock = vi.fn();
 vi.mock( './shutdown.js', () => ( { registerShutdown: registerShutdownMock } ) );
 
+const setupTelemetryMock = vi.fn();
+vi.mock( './setup_telemetry.js', () => ( { setupTelemetry: setupTelemetryMock } ) );
+
 vi.mock( './log_hooks.js', () => ( {} ) );
 
 const runState = { resolve: null };
@@ -129,6 +132,7 @@ describe( 'worker/index', () => {
     } ) );
     expect( initInterceptorsMock ).toHaveBeenCalledWith( { activities: {}, workflows: [], connection: mockConnection } );
     expect( registerShutdownMock ).toHaveBeenCalledWith( { worker: mockWorker, log: mockLog } );
+    expect( setupTelemetryMock ).toHaveBeenCalledWith( { worker: mockWorker } );
     expect( startCatalogMock ).toHaveBeenCalledWith( {
       connection: mockConnection,
       namespace: configValues.namespace,

package/src/worker/setup_telemetry.js

@@ -0,0 +1,19 @@
+import { createChildLogger } from '#logger';
+import { workerTelemetryIntervalMs } from './configs.js';
+
+const log = createChildLogger( 'Telemetry' );
+
+export const setupTelemetry = ( { worker } ) => {
+  if ( workerTelemetryIntervalMs > 0 ) {
+    setInterval( () => {
+      log.info( 'Worker', {
+        status: worker.getStatus(),
+        memory: {
+          availableMemory: process.availableMemory(),
+          constrainedMemory: process.constrainedMemory(),
+          memoryUsage: process.memoryUsage()
+        }
+      } );
+    }, workerTelemetryIntervalMs ).unref();
+  }
+};

package/src/worker/setup_telemetry.spec.js

@@ -0,0 +1,80 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const configMock = vi.hoisted( () => ( { workerTelemetryIntervalMs: 0 } ) );
+const logMock = vi.hoisted( () => ( { info: vi.fn() } ) );
+const createChildLoggerMock = vi.hoisted( () => vi.fn( () => logMock ) );
+
+vi.mock( './configs.js', () => ( {
+  get workerTelemetryIntervalMs() {
+    return configMock.workerTelemetryIntervalMs;
+  }
+} ) );
+
+vi.mock( '#logger', () => ( { createChildLogger: createChildLoggerMock } ) );
+
+const loadSetupTelemetry = async () => {
+  vi.resetModules();
+  return import( './setup_telemetry.js' );
+};
+
+const mockSetInterval = unrefMock =>
+  vi.spyOn( globalThis, 'setInterval' ).mockReturnValue( { unref: unrefMock } );
+
+describe( 'worker/setup_telemetry', () => {
+  const availableMemoryMock = vi.fn();
+  const constrainedMemoryMock = vi.fn();
+  const memoryUsageMock = vi.fn();
+  const unrefMock = vi.fn();
+
+  beforeEach( () => {
+    vi.clearAllMocks();
+    configMock.workerTelemetryIntervalMs = 0;
+
+    availableMemoryMock.mockReturnValue( 1_000 );
+    constrainedMemoryMock.mockReturnValue( 2_000 );
+    memoryUsageMock.mockReturnValue( { heapUsed: 300 } );
+
+    vi.spyOn( process, 'availableMemory' ).mockImplementation( availableMemoryMock );
+    vi.spyOn( process, 'constrainedMemory' ).mockImplementation( constrainedMemoryMock );
+    vi.spyOn( process, 'memoryUsage' ).mockImplementation( memoryUsageMock );
+  } );
+
+  afterEach( () => {
+    vi.restoreAllMocks();
+  } );
+
+  it( 'does not create an interval when telemetry interval is disabled', async () => {
+    const setIntervalMock = mockSetInterval( unrefMock );
+    const { setupTelemetry } = await loadSetupTelemetry();
+
+    setupTelemetry( { worker: { getStatus: vi.fn() } } );
+
+    expect( setIntervalMock ).not.toHaveBeenCalled();
+    expect( logMock.info ).not.toHaveBeenCalled();
+  } );
+
+  it( 'logs worker status and memory on the configured interval', async () => {
+    const setIntervalMock = mockSetInterval( unrefMock );
+    configMock.workerTelemetryIntervalMs = 5_000;
+    const worker = { getStatus: vi.fn().mockReturnValue( { runState: 'RUNNING' } ) };
+    const { setupTelemetry } = await loadSetupTelemetry();
+
+    setupTelemetry( { worker } );
+
+    expect( createChildLoggerMock ).toHaveBeenCalledWith( 'Telemetry' );
+    expect( setIntervalMock ).toHaveBeenCalledWith( expect.any( Function ), 5_000 );
+    expect( unrefMock ).toHaveBeenCalled();
+
+    const [ callback ] = setIntervalMock.mock.calls[0];
+    callback();
+
+    expect( logMock.info ).toHaveBeenCalledWith( 'Worker', {
+      status: { runState: 'RUNNING' },
+      memory: {
+        availableMemory: 1_000,
+        constrainedMemory: 2_000,
+        memoryUsage: { heapUsed: 300 }
+      }
+    } );
+  } );
+} );

package/src/logger.js

@@ -1,73 +0,0 @@
-import winston from 'winston';
-import { shuffleArray } from '#utils';
-
-const isProduction = process.env.NODE_ENV === 'production';
-
-const levels = {
-  error: 0,
-  warn: 1,
-  info: 2,
-  http: 3,
-  debug: 4
-};
-
-const colors = shuffleArray( [
-  '033', // blue
-  '030', // green
-  '208', // orange
-  '045', // turquoise
-  '129', // purple
-  '184' // yellow
-] );
-const assignedColors = new Map();
-
-// Format metadata as friendly JSON: "{ name: "foo", count: 5 }"
-const formatMeta = obj => {
-  const entries = Object.entries( obj );
-  if ( !entries.length ) {
-    return '';
-  }
-  return ' { ' + entries.map( ( [ k, v ] ) => `${k}: ${JSON.stringify( v )}` ).join( ', ' ) + ' }';
-};
-// Distribute the namespace in a map and assign it the next available color
-const getColor = v =>
-  assignedColors.has( v ) ? assignedColors.get( v ) : assignedColors.set( v, colors[assignedColors.size % colors.length] ).get( v );
-
-// Colorize a text using the namespace string
-const colorizeByNamespace = ( namespace, text ) => `\x1b[38;5;${getColor( namespace )}m${text}\x1b[0m`;
-
-// Development format: colorized with namespace prefix
-const devFormat = winston.format.combine(
-  winston.format.colorize(),
-  winston.format.printf( ( { level, message, namespace, service: _, environment: __, ...rest } ) => {
-    const ns = 'Core' + ( namespace ? `.${namespace}` : '' );
-    const meta = formatMeta( rest );
-    return `[${level}] ${colorizeByNamespace( ns, `${namespace}: ${message}` )}${meta}`;
-  } )
-);
-
-// Production format: structured JSON
-const prodFormat = winston.format.combine(
-  winston.format.timestamp( { format: 'YYYY-MM-DDTHH:mm:ss.SSSZ' } ),
-  winston.format.errors( { stack: true } ),
-  winston.format.json()
-);
-
-export const logger = winston.createLogger( {
-  levels,
-  level: isProduction ? 'info' : 'debug',
-  format: isProduction ? prodFormat : devFormat,
-  defaultMeta: {
-    service: 'output-worker',
-    environment: process.env.NODE_ENV || 'development'
-  },
-  transports: [ new winston.transports.Console() ]
-} );
-
-/**
- * Creates a child logger with a specific namespace
- *
- * @param {string} namespace - The namespace for this logger (e.g., 'Scanner', 'Tracing')
- * @returns {winston.Logger} Child logger instance with namespace metadata
- */
-export const createChildLogger = namespace => logger.child( { namespace } );