@output.ai/core 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {

package/src/interface/workflow.js

@@ -2,7 +2,7 @@
 import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, uuid4, ParentClosePolicy, continueAsNew } from '@temporalio/workflow';
 import { validateWorkflow } from './validations/static.js';
 import { validateWithSchema } from './validations/runtime.js';
-import { SHARED_STEP_PREFIX, ACTIVITY_GET_TRACE_DESTINATIONS } from '#consts';
+import { SHARED_STEP_PREFIX, ACTIVITY_GET_TRACE_DESTINATIONS, METADATA_ACCESS_SYMBOL } from '#consts';
 import { deepMerge, mergeActivityOptions, setMetadata } from '#utils';
 import { FatalError, ValidationError } from '#errors';
 
@@ -93,47 +93,59 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
       activityOptions: memo.activityOptions ?? activityOptions // Also preserve the original activity options
     } );
 
-    // validation comes after setting memo to have that info already set for interceptor even if validations fail
-    validateWithSchema( inputSchema, input, `Workflow ${name} input` );
+    // Run the internal activity to retrieve the workflow trace destinations (if it is root workflow, not nested)
+    const traceDestinations = isRoot ? ( await steps[ACTIVITY_GET_TRACE_DESTINATIONS]( { startTime, workflowId, workflowName: name } ) ) : null;
+    const traceObject = { trace: { destinations: traceDestinations } };
 
-    // binds the methods called in the code that Webpack loader will add, they will exposed via "this"
-    const output = await fn.call( {
-      invokeStep: async ( stepName, input, options ) => steps[`${name}#${stepName}`]( input, options ),
-      invokeSharedStep: async ( stepName, input, options ) => steps[`${SHARED_STEP_PREFIX}#${stepName}`]( input, options ),
-      invokeEvaluator: async ( evaluatorName, input, options ) => steps[`${name}#${evaluatorName}`]( input, options ),
+    try {
+      // validation comes after setting memo to have that info already set for interceptor even if validations fail
+      validateWithSchema( inputSchema, input, `Workflow ${name} input` );
 
-      /**
-       * Start a child workflow
-       *
-       * @param {string} childName
-       * @param {unknown} input
-       * @param {object} extra
-       * @param {boolean} extra.detached
-       * @param {import('@temporalio/workflow').ActivityOptions} extra.options
-       * @returns
-       */
-      startWorkflow: async ( childName, input, extra = {} ) =>
-        executeChild( childName, {
-          args: input ? [ input ] : [],
-          workflowId: `${workflowId}-${childName}-${uuid4()}`,
-          parentClosePolicy: ParentClosePolicy[extra?.detached ? 'ABANDON' : 'TERMINATE'],
-          memo: {
-            executionContext,
-            parentId: workflowId,
-            // new configuration for activities of the child workflow, this will be omitted so it will use what that workflow have defined
-            ...( extra?.options && { activityOptions: mergeActivityOptions( activityOptions, extra.options ) } )
-          }
-        } )
-    }, input, context );
-
-    validateWithSchema( outputSchema, output, `Workflow ${name} output` );
-
-    if ( isRoot ) {
-      const destinations = await steps[ACTIVITY_GET_TRACE_DESTINATIONS]( { startTime, workflowId, workflowName: name } );
-      return { output, trace: { destinations } };
-    }
+      // binds the methods called in the code that Webpack loader will add, they will exposed via "this"
+      const output = await fn.call( {
+        invokeStep: async ( stepName, input, options ) => steps[`${name}#${stepName}`]( input, options ),
+        invokeSharedStep: async ( stepName, input, options ) => steps[`${SHARED_STEP_PREFIX}#${stepName}`]( input, options ),
+        invokeEvaluator: async ( evaluatorName, input, options ) => steps[`${name}#${evaluatorName}`]( input, options ),
+
+        /**
+         * Start a child workflow
+         *
+         * @param {string} childName
+         * @param {unknown} input
+         * @param {object} extra
+         * @param {boolean} extra.detached
+         * @param {import('@temporalio/workflow').ActivityOptions} extra.options
+         * @returns
+         */
+        startWorkflow: async ( childName, input, extra = {} ) =>
+          executeChild( childName, {
+            args: input ? [ input ] : [],
+            workflowId: `${workflowId}-${childName}-${uuid4()}`,
+            parentClosePolicy: ParentClosePolicy[extra?.detached ? 'ABANDON' : 'TERMINATE'],
+            memo: {
+              executionContext,
+              parentId: workflowId,
+              // new configuration for activities of the child workflow, this will be omitted so it will use what that workflow have defined
+              ...( extra?.options && { activityOptions: mergeActivityOptions( activityOptions, extra.options ) } )
+            }
+          } )
+      }, input, context );
+
+      validateWithSchema( outputSchema, output, `Workflow ${name} output` );
 
-    return output;
+      if ( isRoot ) {
+        // Append the trace info to the result of the workflow
+        return { output, ...traceObject };
+      }
+
+      return output;
+    } catch ( e ) {
+      // Append the trace info as metadata of the error, so it can be read by the interceptor.
+      if ( isRoot ) {
+        e[METADATA_ACCESS_SYMBOL] = { ...( e[METADATA_ACCESS_SYMBOL] ?? {} ), ...traceObject };
+      }
+      throw e;
+    }
   };
 
   setMetadata( wrapper, { name, description, inputSchema, outputSchema } );

package/src/tracing/processors/local/index.js

@@ -6,71 +6,76 @@ import { EOL } from 'node:os';
 
 const __dirname = dirname( fileURLToPath( import.meta.url ) );
 
-const PURGE_TEMP_FILES_THRESHOLD = 1000 * 60 * 60 * 24 * 7; // 1 week in milliseconds
+const tempFilesTTL = 1000 * 60 * 60 * 24 * 7; // 1 week in milliseconds
 
-// The path to the project root
-const LOCAL_PROJECT_ROOT_PATH = process.argv[2] || process.cwd();
+// Retrieves the caller path from the standard args used to start workflows
+const callerDir = process.argv[2];
 
-// The path to the local trace logs
-const LOCAL_TRACE_LOG_PATH = join( LOCAL_PROJECT_ROOT_PATH, 'logs' );
-
-// The path to the temporary trace logs
-const TMP_TRACE_LOG_PATH = join( __dirname, 'temp', 'traces' );
+const tempTraceFilesDir = join( __dirname, 'temp', 'traces' );
 
 const accumulate = ( { entry, executionContext: { workflowId, startTime } } ) => {
-  const path = join( TMP_TRACE_LOG_PATH, `${startTime}_${workflowId}.trace` );
+  const path = join( tempTraceFilesDir, `${startTime}_${workflowId}.trace` );
   appendFileSync( path, JSON.stringify( entry ) + EOL, 'utf-8' );
   return readFileSync( path, 'utf-8' ).split( EOL ).slice( 0, -1 ).map( v => JSON.parse( v ) );
 };
 
-const cleanupOldTempFiles = ( threshold = Date.now() - PURGE_TEMP_FILES_THRESHOLD ) =>
-  readdirSync( TMP_TRACE_LOG_PATH )
+const cleanupOldTempFiles = ( threshold = Date.now() - tempFilesTTL ) =>
+  readdirSync( tempTraceFilesDir )
     .filter( f => +f.split( '_' )[0] < threshold )
-    .forEach( f => rmSync( join( TMP_TRACE_LOG_PATH, f ) ) );
+    .forEach( f => rmSync( join( tempTraceFilesDir, f ) ) );
 
 /**
- * Get the host trace log path, which is used for reporting trace locations.
- * In containerized environments (e.g., Docker), this can be different from the local path
- * to map container paths to host filesystem paths.
- * @returns {string} The host trace log path from HOST_TRACE_PATH env var, or local path as fallback
+ * Resolves the deep folder structure that stores a workflow trace.
+ * @param {string} workflowName - Name of the workflow
+ * @returns {string}
  */
-const getHostTraceLogPath = () => {
-  return process.env.HOST_TRACE_PATH || LOCAL_TRACE_LOG_PATH;
-};
-
-/**
- * Init this processor
- */
-export const init = () => {
-  mkdirSync( TMP_TRACE_LOG_PATH, { recursive: true } );
-  cleanupOldTempFiles();
-};
+const resolveTraceFolder = workflowName => join( 'runs', workflowName );
 
 /**
- * Get the local file system path for ALL file I/O operations (read/write)
- * Uses the project root path passed as argv[2], falls back to cwd
+ * Resolves the local file system path for ALL file I/O operations (read/write)
+ * Uses the project root path
  * @param {string} workflowName - The name of the workflow
  * @returns {string} The local filesystem path for file operations
  */
-const getLocalOutputDir = workflowName => {
-  return join( LOCAL_PROJECT_ROOT_PATH, 'logs', 'runs', workflowName );
-};
+const resolveIOPath = workflowName => join( callerDir, 'logs', resolveTraceFolder( workflowName ) );
 
 /**
- * Get the host path for reporting trace file locations to users
- * Uses HOST_TRACE_PATH if set (for Docker), otherwise uses project root
+ * Resolves the file path to be reported as the trace destination.
+ *
+ * Considering that in containerized environments (e.g., Docker), the file path might differ from the host machine,
+ * this value takes in consideration the TRACE_HOST_PATH env variable instead of the local filesystem to mount
+ * the final file path.
+ *
+ * If the env variable is not present, it falls back to the same value used to write files locally.
+ *
  * @param {string} workflowName - The name of the workflow
- * @returns {string} The path to report to users/API
+ * @returns {string} The path to report, reflecting the actual filesystem
  */
-const getReportOutputDir = workflowName => {
-  return join( getHostTraceLogPath(), 'runs', workflowName );
-};
+const resolveReportPath = workflowName => process.env.TRACE_HOST_PATH ?
+  join( process.env.TRACE_HOST_PATH, resolveTraceFolder( workflowName ) ) :
+  resolveIOPath( workflowName );
 
-const buildOutputFileName = ( { startTime, workflowId } ) => {
+/**
+ * Builds the actual trace filename
+ *
+ * @param {object} options
+ * @param {number} options.startTime
+ * @param {string} options.workflowId
+ * @returns {string}
+ */
+const buildTraceFilename = ( { startTime, workflowId } ) => {
   const timestamp = new Date( startTime ).toISOString().replace( /[:T.]/g, '-' );
   return `${timestamp}_${workflowId}.json`;
 };
 
+/**
+ * Init this processor
+ */
+export const init = () => {
+  mkdirSync( tempTraceFilesDir, { recursive: true } );
+  cleanupOldTempFiles();
+};
+
 /**
  * Execute this processor:
  *
@@ -84,24 +89,23 @@ const buildOutputFileName = ( { startTime, workflowId } ) => {
 export const exec = ( { entry, executionContext } ) => {
   const { workflowId, workflowName, startTime } = executionContext;
   const content = buildTraceTree( accumulate( { entry, executionContext } ) );
-
-  // Always use local path for writing files
-  const dir = getLocalOutputDir( workflowName );
-  const path = join( dir, buildOutputFileName( { startTime, workflowId } ) );
+  const dir = resolveIOPath( workflowName );
+  const path = join( dir, buildTraceFilename( { startTime, workflowId } ) );
 
   mkdirSync( dir, { recursive: true } );
   writeFileSync( path, JSON.stringify( content, undefined, 2 ) + EOL, 'utf-8' );
 };
 
 /**
- * Returns where the trace is saved as an absolute path
+ * Returns where the trace is saved as an absolute path.
+ *
+ * This uses the optional TRACE_HOST_PATH to return values relative to the host OS, not the container, if applicable.
+ *
  * @param {object} args
  * @param {string} args.startTime - The start time of the workflow
  * @param {string} args.workflowId - The id of the workflow execution
  * @param {string} args.workflowName - The name of the workflow
  * @returns {string} The absolute path where the trace will be saved
  */
-export const getDestination = ( { startTime, workflowId, workflowName } ) => {
-  // Use report path for reporting to users/API
-  return join( getReportOutputDir( workflowName ), buildOutputFileName( { workflowId, startTime } ) );
-};
+export const getDestination = ( { startTime, workflowId, workflowName } ) =>
+  join( resolveReportPath( workflowName ), buildTraceFilename( { workflowId, startTime } ) );

package/src/tracing/processors/local/index.spec.js

@@ -29,7 +29,7 @@ describe( 'tracing/processors/local', () => {
     vi.clearAllMocks();
     store.files.clear();
     process.argv[2] = '/tmp/project';
-    delete process.env.HOST_TRACE_PATH; // Clear HOST_TRACE_PATH for clean tests
+    delete process.env.TRACE_HOST_PATH; // Clear TRACE_HOST_PATH for clean tests
   } );
 
   it( 'init(): creates temp dir and cleans up old files', async () => {
@@ -62,7 +62,7 @@ describe( 'tracing/processors/local', () => {
 
     expect( writeFileSyncMock ).toHaveBeenCalledTimes( 3 );
     const [ writtenPath, content ] = writeFileSyncMock.mock.calls.at( -1 );
-    // Changed: Now uses process.cwd() + '/logs' fallback when HOST_TRACE_PATH not set
+    // Changed: Now uses process.cwd() + '/logs' fallback when TRACE_HOST_PATH not set
     expect( writtenPath ).toMatch( /\/runs\/WF\// );
     expect( JSON.parse( content.trim() ).count ).toBe( 3 );
   } );
@@ -81,11 +81,11 @@ describe( 'tracing/processors/local', () => {
     expect( destination ).toContain( '/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json' );
   } );
 
-  it( 'exec(): writes to container path regardless of HOST_TRACE_PATH', async () => {
+  it( 'exec(): writes to container path regardless of TRACE_HOST_PATH', async () => {
     const { exec, init } = await import( './index.js' );
 
-    // Set HOST_TRACE_PATH to simulate Docker environment
-    process.env.HOST_TRACE_PATH = '/host/path/logs';
+    // Set TRACE_HOST_PATH to simulate Docker environment
+    process.env.TRACE_HOST_PATH = '/host/path/logs';
 
     init();
 
@@ -97,16 +97,16 @@ describe( 'tracing/processors/local', () => {
     expect( writeFileSyncMock ).toHaveBeenCalledTimes( 1 );
     const [ writtenPath ] = writeFileSyncMock.mock.calls.at( -1 );
 
-    // Should write to process.cwd()/logs, NOT to HOST_TRACE_PATH
+    // Should write to process.cwd()/logs, NOT to TRACE_HOST_PATH
     expect( writtenPath ).not.toContain( '/host/path/logs' );
     expect( writtenPath ).toMatch( /logs\/runs\/WF\// );
   } );
 
-  it( 'getDestination(): returns HOST_TRACE_PATH when set', async () => {
+  it( 'getDestination(): returns TRACE_HOST_PATH when set', async () => {
     const { getDestination } = await import( './index.js' );
 
-    // Set HOST_TRACE_PATH to simulate Docker environment
-    process.env.HOST_TRACE_PATH = '/host/path/logs';
+    // Set TRACE_HOST_PATH to simulate Docker environment
+    process.env.TRACE_HOST_PATH = '/host/path/logs';
 
     const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
     const workflowId = 'workflow-id-123';
@@ -114,15 +114,15 @@ describe( 'tracing/processors/local', () => {
 
     const destination = getDestination( { startTime, workflowId, workflowName } );
 
-    // Should return HOST_TRACE_PATH-based path for reporting
+    // Should return TRACE_HOST_PATH-based path for reporting
     expect( destination ).toBe( '/host/path/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json' );
   } );
 
   it( 'separation of write and report paths works correctly', async () => {
     const { exec, getDestination, init } = await import( './index.js' );
 
-    // Set HOST_TRACE_PATH to simulate Docker environment
-    process.env.HOST_TRACE_PATH = '/Users/ben/project/logs';
+    // Set TRACE_HOST_PATH to simulate Docker environment
+    process.env.TRACE_HOST_PATH = '/Users/ben/project/logs';
 
     init();
 
@@ -142,7 +142,7 @@ describe( 'tracing/processors/local', () => {
     expect( writtenPath ).not.toContain( '/Users/ben/project' );
     expect( writtenPath ).toMatch( /logs\/runs\/test-workflow\// );
 
-    // Verify report path uses HOST_TRACE_PATH
+    // Verify report path uses TRACE_HOST_PATH
     expect( destination ).toBe( '/Users/ben/project/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json' );
   } );
 } );

package/src/worker/interceptors/workflow.js

@@ -2,6 +2,7 @@
 import { workflowInfo, proxySinks, ApplicationFailure, ContinueAsNew } from '@temporalio/workflow';
 import { memoToHeaders } from '../sandboxed_utils.js';
 import { mergeActivityOptions } from '#utils';
+import { METADATA_ACCESS_SYMBOL } from '#consts';
 // this is a dynamic generated file with activity configs overwrites
 import stepOptions from '../temp/__activity_options.js';
 
@@ -37,15 +38,28 @@ class WorkflowExecutionInterceptor {
       sinks.trace.addWorkflowEventEnd( output );
       return output;
     } catch ( error ) {
-      /* When the error is ContinueAsNew it represents the point where the actual workflow code was
-      delegated to another run. In this case the result in the traces will be the string below and
-      a new trace file will be generated */
+      /*
+       * When the error is a ContinueAsNew instance, it represents the point where the actual workflow code was
+       * delegated to another run. In this case the result in the traces will be the string below and
+       * a new trace file will be generated
+       */
       if ( error instanceof ContinueAsNew ) {
         sinks.trace.addWorkflowEventEnd( '<continued_as_new>' );
         throw error;
       }
+
       sinks.trace.addWorkflowEventError( error );
-      throw new ApplicationFailure( error.message, error.constructor.name );
+      const failure = new ApplicationFailure( error.message, error.constructor.name );
+
+      /*
+       * If intercepted error has metadata, set it to .details property of Temporal's ApplicationFailure instance.
+       * This make it possible for this information be retrieved by Temporal's client instance.
+       * Ref: https://typescript.temporal.io/api/classes/common.ApplicationFailure#details
+       */
+      if ( error[METADATA_ACCESS_SYMBOL] ) {
+        failure.details = [ error[METADATA_ACCESS_SYMBOL] ];
+      }
+      throw failure;
     }
   }
 };