@outputai/core 0.9.3-next.c318502.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.9.3-next.c318502.0",
+  "version": "0.10.0",
   "description": "The core module of the output framework",
   "type": "module",
   "engines": {

package/src/worker/configs.js

@@ -1,5 +1,6 @@
 import * as z from 'zod';
 import { isStringboolTrue } from '#helpers/string';
+import { workerTunerEnvSchema } from './configs_tuner_schema.js';
 
 class InvalidEnvVarsErrors extends Error { }
 
@@ -28,6 +29,8 @@ const envVarSchema = z.object( {
   // How aggressively the worker pulls tasks from Temporal.
   TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_POLLS: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 5 ) ),
   TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASK_POLLS: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 5 ) ),
+  // JSON-encoded Temporal Worker tuner options.
+  TEMPORAL_WORKER_TUNER: workerTunerEnvSchema,
   // Activity configs
   // How often the worker sends a heartbeat to the Temporal Service during activity execution
   OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS: z.preprocess( coalesceEmptyString, z.coerce.number().int().positive().default( 2 * 60 * 1000 ) ), // 2min
@@ -60,6 +63,7 @@ export const maxConcurrentWorkflowTaskExecutions = envVars.TEMPORAL_MAX_CONCURRE
 export const maxCachedWorkflows = envVars.TEMPORAL_MAX_CACHED_WORKFLOWS;
 export const maxConcurrentActivityTaskPolls = envVars.TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_POLLS;
 export const maxConcurrentWorkflowTaskPolls = envVars.TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASK_POLLS;
+export const workerTuner = envVars.TEMPORAL_WORKER_TUNER;
 export const namespace = envVars.TEMPORAL_NAMESPACE;
 export const taskQueue = envVars.OUTPUT_CATALOG_ID;
 export const catalogId = envVars.OUTPUT_CATALOG_ID;

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',
+  'TEMPORAL_WORKER_TUNER',
   'OUTPUT_WORKER_TELEMETRY_INTERVAL_MS',
   'OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS',
   'OUTPUT_ACTIVITY_HEARTBEAT_ENABLED',
@@ -64,6 +65,7 @@ describe( 'worker/configs', () => {
     expect( configs.maxCachedWorkflows ).toBe( 1000 );
     expect( configs.maxConcurrentActivityTaskPolls ).toBe( 5 );
     expect( configs.maxConcurrentWorkflowTaskPolls ).toBe( 5 );
+    expect( configs.workerTuner ).toBeUndefined();
     expect( configs.workerTelemetryIntervalMs ).toBe( 0 );
     expect( configs.activityHeartbeatIntervalMs ).toBe( 2 * 60 * 1000 );
     expect( configs.activityHeartbeatEnabled ).toBe( true );
@@ -87,6 +89,25 @@ describe( 'worker/configs', () => {
     expect( configs.workerTelemetryIntervalMs ).toBe( 0 );
   } );
 
+  it( 'parses Temporal worker tuner JSON', async () => {
+    const workerTuner = {
+      tunerOptions: {
+        targetMemoryUsage: 0.8,
+        targetCpuUsage: 0.9
+      },
+      activityTaskSlotOptions: {
+        minimumSlots: 1,
+        maximumSlots: 100,
+        rampThrottle: '50ms'
+      }
+    };
+
+    setEnv( { TEMPORAL_WORKER_TUNER: JSON.stringify( workerTuner ) } );
+    const configs = await loadConfigs();
+
+    expect( configs.workerTuner ).toEqual( workerTuner );
+  } );
+
   it( 'parses custom numeric env vars', async () => {
     setEnv( {
       TEMPORAL_MAX_CONCURRENT_ACTIVITY_TASK_EXECUTIONS: '10',

package/src/worker/configs_tuner_schema.js

@@ -0,0 +1,81 @@
+import * as z from 'zod';
+
+const coalesceEmptyString = v => v === '' ? undefined : v;
+
+const durationSchema = z.preprocess(
+  coalesceEmptyString,
+  z.string()
+    .regex( /^\d+$|^\d+(\.\d+)?\s?(ms|s|m|h|d)$/i )
+    .optional()
+);
+
+const resourceBasedTunerOptionsSchema = z.strictObject( {
+  targetMemoryUsage: z.number().min( 0 ).max( 1 ),
+  targetCpuUsage: z.number().min( 0 ).max( 1 )
+} );
+
+const resourceBasedSlotOptionsSchema = z.strictObject( {
+  minimumSlots: z.number().int().positive().optional(),
+  maximumSlots: z.number().int().positive().optional(),
+  rampThrottle: durationSchema
+} ).superRefine( ( value, ctx ) => {
+  if ( value.minimumSlots !== undefined && value.maximumSlots !== undefined && value.minimumSlots > value.maximumSlots ) {
+    ctx.addIssue( {
+      code: 'custom',
+      message: 'minimumSlots must be less than or equal to maximumSlots'
+    } );
+  }
+} );
+
+const resourceBasedTunerSchema = z.strictObject( {
+  tunerOptions: resourceBasedTunerOptionsSchema,
+  workflowTaskSlotOptions: resourceBasedSlotOptionsSchema.optional(),
+  activityTaskSlotOptions: resourceBasedSlotOptionsSchema.optional(),
+  localActivityTaskSlotOptions: resourceBasedSlotOptionsSchema.optional(),
+  nexusTaskSlotOptions: resourceBasedSlotOptionsSchema.optional()
+} );
+
+const fixedSizeSlotSupplierSchema = z.strictObject( {
+  type: z.literal( 'fixed-size' ),
+  numSlots: z.number().int().positive()
+} );
+
+const resourceBasedSlotSupplierSchema = resourceBasedSlotOptionsSchema.extend( {
+  type: z.literal( 'resource-based' ),
+  tunerOptions: resourceBasedTunerOptionsSchema
+} );
+
+const slotSupplierSchema = z.union( [
+  fixedSizeSlotSupplierSchema,
+  resourceBasedSlotSupplierSchema
+] );
+
+const tunerHolderSchema = z.strictObject( {
+  workflowTaskSlotSupplier: slotSupplierSchema,
+  activityTaskSlotSupplier: slotSupplierSchema,
+  localActivityTaskSlotSupplier: slotSupplierSchema,
+  nexusTaskSlotSupplier: slotSupplierSchema
+} );
+
+const workerTunerSchema = z.union( [
+  resourceBasedTunerSchema,
+  tunerHolderSchema
+] );
+
+export const workerTunerEnvSchema = z.preprocess(
+  coalesceEmptyString,
+  /* eslint-disable consistent-return */
+  z.string().optional().transform( ( value, ctx ) => {
+    if ( value === undefined ) {
+      return undefined;
+    }
+
+    try {
+      return JSON.parse( value );
+    } catch ( error ) {
+      ctx.addIssue( { code: 'custom', message: `Expected valid JSON: ${error.message}` } );
+      return z.NEVER;
+    }
+  } ).pipe( workerTunerSchema.optional() )
+  /* eslint-enable consistent-return */
+);

package/src/worker/configs_tuner_schema.spec.js

@@ -0,0 +1,127 @@
+import { describe, expect, it } from 'vitest';
+import { workerTunerEnvSchema } from './configs_tuner_schema.js';
+
+const parseWorkerTuner = value => workerTunerEnvSchema.parse( value );
+
+describe( 'worker/configs_tuner_schema', () => {
+  it( 'treats empty string as unset', () => {
+    expect( parseWorkerTuner( '' ) ).toBeUndefined();
+  } );
+
+  it( 'parses resource-based Temporal worker tuner JSON', () => {
+    const workerTuner = {
+      tunerOptions: {
+        targetMemoryUsage: 0.8,
+        targetCpuUsage: 0.9
+      },
+      activityTaskSlotOptions: {
+        minimumSlots: 1,
+        maximumSlots: 100,
+        rampThrottle: '50ms'
+      }
+    };
+
+    expect( parseWorkerTuner( JSON.stringify( workerTuner ) ) ).toEqual( workerTuner );
+  } );
+
+  it( 'parses per-task Temporal worker tuner JSON', () => {
+    const resourceBasedSupplier = {
+      type: 'resource-based',
+      tunerOptions: {
+        targetMemoryUsage: 0.8,
+        targetCpuUsage: 0.9
+      },
+      minimumSlots: 1,
+      maximumSlots: 100,
+      rampThrottle: '50ms'
+    };
+    const workerTuner = {
+      workflowTaskSlotSupplier: {
+        type: 'fixed-size',
+        numSlots: 10
+      },
+      activityTaskSlotSupplier: resourceBasedSupplier,
+      localActivityTaskSlotSupplier: {
+        type: 'fixed-size',
+        numSlots: 10
+      },
+      nexusTaskSlotSupplier: {
+        type: 'fixed-size',
+        numSlots: 10
+      }
+    };
+
+    expect( parseWorkerTuner( JSON.stringify( workerTuner ) ) ).toEqual( workerTuner );
+  } );
+
+  it( 'throws when tuner is not valid JSON', () => {
+    expect( () => parseWorkerTuner( '{invalid' ) ).toThrow();
+  } );
+
+  it( 'throws when tuner is not a JSON object', () => {
+    expect( () => parseWorkerTuner( '[]' ) ).toThrow();
+  } );
+
+  it( 'throws when tuner is missing required per-task suppliers', () => {
+    const workerTuner = {
+      workflowTaskSlotSupplier: {
+        type: 'fixed-size',
+        numSlots: 10
+      },
+      activityTaskSlotSupplier: {
+        type: 'fixed-size',
+        numSlots: 10
+      }
+    };
+
+    expect( () => parseWorkerTuner( JSON.stringify( workerTuner ) ) ).toThrow();
+  } );
+
+  it( 'throws when tuner uses custom suppliers', () => {
+    const workerTuner = {
+      workflowTaskSlotSupplier: {
+        type: 'custom'
+      },
+      activityTaskSlotSupplier: {
+        type: 'fixed-size',
+        numSlots: 10
+      },
+      localActivityTaskSlotSupplier: {
+        type: 'fixed-size',
+        numSlots: 10
+      },
+      nexusTaskSlotSupplier: {
+        type: 'fixed-size',
+        numSlots: 10
+      }
+    };
+
+    expect( () => parseWorkerTuner( JSON.stringify( workerTuner ) ) ).toThrow();
+  } );
+
+  it( 'throws when target usage is outside range', () => {
+    const workerTuner = {
+      tunerOptions: {
+        targetMemoryUsage: 1.5,
+        targetCpuUsage: 0.9
+      }
+    };
+
+    expect( () => parseWorkerTuner( JSON.stringify( workerTuner ) ) ).toThrow();
+  } );
+
+  it( 'throws when minimum slots exceeds maximum slots', () => {
+    const workerTuner = {
+      tunerOptions: {
+        targetMemoryUsage: 0.8,
+        targetCpuUsage: 0.9
+      },
+      activityTaskSlotOptions: {
+        minimumSlots: 10,
+        maximumSlots: 5
+      }
+    };
+
+    expect( () => parseWorkerTuner( JSON.stringify( workerTuner ) ) ).toThrow();
+  } );
+} );

package/src/worker/index.js

@@ -36,7 +36,8 @@ const {
   maxConcurrentActivityTaskPolls,
   maxConcurrentWorkflowTaskPolls,
   shutdownForceTime,
-  shutdownGraceTime
+  shutdownGraceTime,
+  workerTuner
 } = configs;
 
 const state = {
@@ -88,6 +89,9 @@ const execute = async () => {
   state.catalogJob = new CatalogJob( { connection: state.connection, namespace, catalog, catalogHash } );
 
   log.info( 'Creating worker...' );
+  if ( workerTuner ) {
+    log.info( 'Using worker tuner options', { ...workerTuner } );
+  }
   const worker = await Worker.create( {
     connection: state.connection,
     namespace,
@@ -96,8 +100,13 @@ const execute = async () => {
     activities,
     sinks,
     interceptors: initInterceptors( { activities, workflows } ),
-    maxConcurrentWorkflowTaskExecutions,
-    maxConcurrentActivityTaskExecutions,
+    // tuner isn't compatible with concurrent task executions configs
+    ...( workerTuner ? {
+      tuner: workerTuner
+    } : {
+      maxConcurrentWorkflowTaskExecutions,
+      maxConcurrentActivityTaskExecutions
+    } ),
     maxCachedWorkflows,
     maxConcurrentActivityTaskPolls,
     maxConcurrentWorkflowTaskPolls,

package/src/worker/index.spec.js

@@ -45,6 +45,7 @@ const {
     maxCachedWorkflows: 1000,
     maxConcurrentActivityTaskPolls: 5,
     maxConcurrentWorkflowTaskPolls: 5,
+    workerTuner: undefined,
     processFailureShutdownDelay: 0,
     shutdownForceTime: undefined,
     shutdownGraceTime: undefined
@@ -185,6 +186,7 @@ describe( 'worker/index', () => {
     resetPromises();
     configValues.apiKey = undefined;
     configValues.grpcProxy = undefined;
+    configValues.workerTuner = undefined;
     configValues.shutdownForceTime = undefined;
     configValues.shutdownGraceTime = undefined;
     catalogJobInstance.error = null;
@@ -263,6 +265,32 @@ describe( 'worker/index', () => {
     expect( mockLog.info ).toHaveBeenCalledWith( 'Bye' );
   } );
 
+  it( 'passes worker tuner instead of incompatible execution concurrency options', async () => {
+    configValues.workerTuner = {
+      tunerOptions: {
+        targetMemoryUsage: 0.8,
+        targetCpuUsage: 0.9
+      }
+    };
+    const { Worker } = await import( '@temporalio/worker' );
+
+    await importWorker();
+
+    await vi.waitFor( () => expect( Worker.create ).toHaveBeenCalled() );
+
+    const workerOptions = Worker.create.mock.calls[0][0];
+    expect( workerOptions ).toEqual( expect.objectContaining( {
+      tuner: configValues.workerTuner,
+      maxCachedWorkflows: configValues.maxCachedWorkflows,
+      maxConcurrentActivityTaskPolls: configValues.maxConcurrentActivityTaskPolls,
+      maxConcurrentWorkflowTaskPolls: configValues.maxConcurrentWorkflowTaskPolls
+    } ) );
+    expect( workerOptions ).not.toHaveProperty( 'maxConcurrentWorkflowTaskExecutions' );
+    expect( workerOptions ).not.toHaveProperty( 'maxConcurrentActivityTaskExecutions' );
+
+    await settleWorker();
+  } );
+
   it( 'enables TLS when apiKey is set', async () => {
     configValues.apiKey = 'secret';
     const { NativeConnection } = await import( '@temporalio/worker' );