@output.ai/core 0.3.6 → 0.3.7

package/package.json

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

package/src/consts.js

@@ -10,3 +10,7 @@ export const ComponentType = {
   INTERNAL_STEP: 'internal_step',
   STEP: 'step'
 };
+
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 2 * 60 * 1000; // 2 minutes
+export const HEARTBEAT_INTERVAL_MS = Number( process.env.OUTPUT_HEARTBEAT_INTERVAL_MS ) || DEFAULT_HEARTBEAT_INTERVAL_MS;
+export const HEARTBEAT_ENABLED = process.env.OUTPUT_HEARTBEAT_ENABLED !== 'false'; // on by default, set to 'false' to disable

package/src/interface/workflow.js

@@ -40,6 +40,7 @@ class Context {
 
 const defaultActivityOptions = {
   startToCloseTimeout: '20m',
+  heartbeatTimeout: '5m',
   retry: {
     initialInterval: '10s',
     backoffCoefficient: 2.0,

package/src/worker/interceptors/activity.js

@@ -2,16 +2,23 @@ import { Context } from '@temporalio/activity';
 import { Storage } from '#async_storage';
 import { addEventStart, addEventEnd, addEventError } from '#tracing';
 import { headersToObject } from '../sandboxed_utils.js';
-import { METADATA_ACCESS_SYMBOL } from '#consts';
+import { METADATA_ACCESS_SYMBOL, HEARTBEAT_INTERVAL_MS, HEARTBEAT_ENABLED } from '#consts';
 
 /*
-  This interceptor is called for every activity execution
+  This interceptor wraps every activity execution with cross-cutting concerns:
 
-  It will have access to the activity scope.
+  1. Tracing: records start/end/error events and sets up AsyncLocalStorage context
+     so nested operations (e.g. HTTP calls inside steps) can be traced back to the parent activity.
 
-  What it does is to wrap the execution using Node's AsyncLocalStorage to save context info for tracing.
+  2. Heartbeating: sends periodic heartbeat signals to Temporal so it can detect dead workers
+     without waiting for the full startToCloseTimeout (which can be up to 1h+).
+     This is critical during deploys — when a worker restarts, Temporal will notice
+     the missing heartbeat within the heartbeatTimeout window and retry the activity
+     on a new worker, instead of waiting the entire startToCloseTimeout.
 
-  Some information it needs for its context comes from Temporal's Activity Context others are injected in the headers
+  Context information comes from two sources:
+  - Temporal's Activity Context (workflowId, activityId, activityType)
+  - Headers injected by the workflow interceptor (executionContext)
 */
 export class ActivityExecutionInterceptor {
   constructor( activities ) {
@@ -23,17 +30,27 @@ export class ActivityExecutionInterceptor {
     const { executionContext } = headersToObject( input.headers );
     const { type: kind } = this.activities?.[activityType]?.[METADATA_ACCESS_SYMBOL];
 
+    // --- Tracing: record the start of the activity ---
     const traceArguments = { kind, id: activityId, parentId: workflowId, name: activityType, executionContext };
     addEventStart( { details: input.args[0], ...traceArguments } );
 
-    // creates a context for the nested tracing
+    // --- Heartbeating: signal Temporal periodically that this worker is still alive ---
+    const heartbeatInterval = HEARTBEAT_ENABLED ?
+      setInterval( () => Context.current().heartbeat(), HEARTBEAT_INTERVAL_MS ) :
+      null;
+
     try {
+      // --- Execution: run the activity within an AsyncLocalStorage context for nested tracing ---
       const output = await Storage.runWithContext( async _ => next( input ), { parentId: activityId, executionContext } );
       addEventEnd( { details: output, ...traceArguments } );
       return output;
     } catch ( error ) {
       addEventError( { details: error, ...traceArguments } );
       throw error;
+    } finally {
+      if ( heartbeatInterval ) {
+        clearInterval( heartbeatInterval );
+      }
     }
   }
 };

package/src/worker/interceptors/activity.spec.js

@@ -0,0 +1,178 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const METADATA_ACCESS_SYMBOL = Symbol( '__metadata' );
+
+const heartbeatMock = vi.fn();
+const contextInfoMock = {
+  workflowExecution: { workflowId: 'wf-1' },
+  activityId: 'act-1',
+  activityType: 'myWorkflow#myStep'
+};
+
+vi.mock( '@temporalio/activity', () => ( {
+  Context: {
+    current: () => ( {
+      info: contextInfoMock,
+      heartbeat: heartbeatMock
+    } )
+  }
+} ) );
+
+vi.mock( '#async_storage', () => ( {
+  Storage: {
+    runWithContext: async fn => fn()
+  }
+} ) );
+
+const addEventStartMock = vi.fn();
+const addEventEndMock = vi.fn();
+const addEventErrorMock = vi.fn();
+vi.mock( '#tracing', () => ( {
+  addEventStart: addEventStartMock,
+  addEventEnd: addEventEndMock,
+  addEventError: addEventErrorMock
+} ) );
+
+vi.mock( '../sandboxed_utils.js', () => ( {
+  headersToObject: () => ( { executionContext: { workflowId: 'wf-1' } } )
+} ) );
+
+const mockConfig = { heartbeatEnabled: true, heartbeatIntervalMs: 50 };
+
+vi.mock( '#consts', () => ( {
+  get METADATA_ACCESS_SYMBOL() {
+    return METADATA_ACCESS_SYMBOL;
+  },
+  get HEARTBEAT_ENABLED() {
+    return mockConfig.heartbeatEnabled;
+  },
+  get HEARTBEAT_INTERVAL_MS() {
+    return mockConfig.heartbeatIntervalMs;
+  }
+} ) );
+
+const makeActivities = () => ( {
+  'myWorkflow#myStep': { [METADATA_ACCESS_SYMBOL]: { type: 'step' } }
+} );
+
+const makeInput = () => ( {
+  args: [ { someInput: 'data' } ],
+  headers: {}
+} );
+
+describe( 'ActivityExecutionInterceptor', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+    mockConfig.heartbeatEnabled = true;
+    mockConfig.heartbeatIntervalMs = 50;
+  } );
+
+  afterEach( () => {
+    vi.useRealTimers();
+  } );
+
+  it( 'records trace start and end events on successful execution', async () => {
+    const { ActivityExecutionInterceptor } = await import( './activity.js' );
+    const interceptor = new ActivityExecutionInterceptor( makeActivities() );
+    const next = vi.fn().mockResolvedValue( { result: 'ok' } );
+
+    const promise = interceptor.execute( makeInput(), next );
+    vi.advanceTimersByTime( 0 );
+    const output = await promise;
+
+    expect( output ).toEqual( { result: 'ok' } );
+    expect( addEventStartMock ).toHaveBeenCalledOnce();
+    expect( addEventEndMock ).toHaveBeenCalledOnce();
+    expect( addEventErrorMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'records trace error event on failed execution', async () => {
+    const { ActivityExecutionInterceptor } = await import( './activity.js' );
+    const interceptor = new ActivityExecutionInterceptor( makeActivities() );
+    const error = new Error( 'step failed' );
+    const next = vi.fn().mockRejectedValue( error );
+
+    const promise = interceptor.execute( makeInput(), next );
+    vi.advanceTimersByTime( 0 );
+
+    await expect( promise ).rejects.toThrow( 'step failed' );
+    expect( addEventStartMock ).toHaveBeenCalledOnce();
+    expect( addEventErrorMock ).toHaveBeenCalledOnce();
+    expect( addEventEndMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'sends periodic heartbeats during activity execution', async () => {
+    const { ActivityExecutionInterceptor } = await import( './activity.js' );
+    const interceptor = new ActivityExecutionInterceptor( makeActivities() );
+
+    // next() resolves only after we manually resolve it, simulating a long-running activity
+    const deferred = { resolve: null };
+    const next = vi.fn().mockImplementation( () => new Promise( r => {
+      deferred.resolve = r;
+    } ) );
+
+    const promise = interceptor.execute( makeInput(), next );
+
+    expect( heartbeatMock ).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime( 50 );
+    expect( heartbeatMock ).toHaveBeenCalledTimes( 1 );
+
+    vi.advanceTimersByTime( 50 );
+    expect( heartbeatMock ).toHaveBeenCalledTimes( 2 );
+
+    vi.advanceTimersByTime( 50 );
+    expect( heartbeatMock ).toHaveBeenCalledTimes( 3 );
+
+    deferred.resolve( { result: 'done' } );
+    await promise;
+  } );
+
+  it( 'clears heartbeat interval after activity completes', async () => {
+    const { ActivityExecutionInterceptor } = await import( './activity.js' );
+    const interceptor = new ActivityExecutionInterceptor( makeActivities() );
+    const next = vi.fn().mockResolvedValue( { result: 'ok' } );
+
+    const promise = interceptor.execute( makeInput(), next );
+    vi.advanceTimersByTime( 0 );
+    await promise;
+
+    heartbeatMock.mockClear();
+    vi.advanceTimersByTime( 500 );
+    expect( heartbeatMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'clears heartbeat interval after activity fails', async () => {
+    const { ActivityExecutionInterceptor } = await import( './activity.js' );
+    const interceptor = new ActivityExecutionInterceptor( makeActivities() );
+    const next = vi.fn().mockRejectedValue( new Error( 'boom' ) );
+
+    const promise = interceptor.execute( makeInput(), next );
+    vi.advanceTimersByTime( 0 );
+    await promise.catch( () => {} );
+
+    heartbeatMock.mockClear();
+    vi.advanceTimersByTime( 500 );
+    expect( heartbeatMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'does not heartbeat when HEARTBEAT_ENABLED is false', async () => {
+    mockConfig.heartbeatEnabled = false;
+    const { ActivityExecutionInterceptor } = await import( './activity.js' );
+    const interceptor = new ActivityExecutionInterceptor( makeActivities() );
+
+    const deferred = { resolve: null };
+    const next = vi.fn().mockImplementation( () => new Promise( r => {
+      deferred.resolve = r;
+    } ) );
+
+    const promise = interceptor.execute( makeInput(), next );
+
+    vi.advanceTimersByTime( 200 );
+    expect( heartbeatMock ).not.toHaveBeenCalled();
+
+    deferred.resolve( { result: 'done' } );
+    await promise;
+  } );
+} );