@output.ai/core 0.0.7 → 0.0.9

package/src/interface/utils.js

@@ -1,9 +1,46 @@
-// This is rigged to return which folder had the source of calls for both interface methods (step workflow) functions
-// Important, if to refactor, pay attention to the depth in the stack trace to extract the info
-// now is 3 cause (1 line is name, 2 line is this function, 3 line is step/workflow, 4 line is caller)
-export const getInvocationDir = _ => new Error()
+/**
+ * Function rigged to return the folder path of the source of calls for the interface methods (step/workflow)
+ *
+ * IMPORTANT!!!
+ * If to refactor this, pay attention to the depth in the stack trace to extract the info.
+ * Currently it is 3:
+ * - 1st line is the name of the function;
+ * - 2nd line is this function;
+ * - 3rd line is step/workflow;
+ * - 4th line is caller;
+ *
+ * @returns {string} The folder path of the caller
+ */
+export const getInvocationDir = () => new Error()
   .stack.split( '\n' )[3]
   .split( ' ' )
   .at( -1 )
   .replace( /\((.+):\d+:\d+\)/, '$1' )
   .split( '/' ).slice( 0, -1 ).join( '/' );
+
+/**
+ * This mouthful function will invoke a function with given arguments, and validate its return
+ * using a given validator.
+ *
+ * It will preserver the execution model (asynchronous vs synchronous), so if the function is
+ * sync the validation happens here, if it is async (returns Promise) the validation is attached
+ * to a .then().
+ *
+ *
+ * @param {Function} fn - The function to execute
+ * @param {any} input - The payload to call the function
+ * @param {Function} validate - The validator function
+ * @returns {any} Function result (Promise or not)
+ */
+export const invokeFnAndValidateOutputPreservingExecutionModel = ( fn, input, validate ) => {
+  const uniformReturn = output => {
+    validate( output );
+    return output;
+  };
+
+  const output = fn( input );
+  if ( output?.constructor === Promise ) {
+    return output.then( resolvedOutput => uniformReturn( resolvedOutput ) );
+  }
+  return uniformReturn( output );
+};

package/src/interface/utils.spec.js

@@ -0,0 +1,71 @@
+import { describe, it, expect, vi } from 'vitest';
+import { getInvocationDir, invokeFnAndValidateOutputPreservingExecutionModel } from './utils.js';
+
+describe( 'interface/utils', () => {
+  describe( 'getInvocationDir', () => {
+    it( 'returns the caller directory from stack trace', () => {
+      const fakeCaller = '/tmp/project/src/caller/file.js';
+      const OriginalError = Error;
+      // Provide a deterministic stack shape for the function under test
+      // Lines: 1) Error, 2) getInvocationDir, 3) step/workflow, 4) actual caller
+      // Include typical V8 formatting with leading spaces and without function name
+      // for the caller line
+
+      Error = class extends OriginalError {
+        constructor( ...args ) {
+          super( ...args );
+          this.stack = [
+            'Error',
+            '    at getInvocationDir (a:1:1)',
+            '    at step (b:1:1)',
+            `    at ${fakeCaller}:10:20`
+          ].join( '\n' );
+        }
+      };
+      try {
+        const dir = getInvocationDir();
+        expect( dir ).toBe( '/tmp/project/src/caller' );
+      } finally {
+
+        Error = OriginalError;
+      }
+    } );
+  } );
+
+  describe( 'invokeFnAndValidateOutputPreservingExecutionModel', () => {
+    it( 'validates and returns sync output', () => {
+      const fn = vi.fn( x => x * 2 );
+      const validate = vi.fn();
+      const result = invokeFnAndValidateOutputPreservingExecutionModel( fn, 3, validate );
+      expect( result ).toBe( 6 );
+      expect( validate ).toHaveBeenCalledWith( 6 );
+    } );
+
+    it( 'validates and returns async output preserving promise', async () => {
+      const fn = vi.fn( async x => x + 1 );
+      const validate = vi.fn();
+      const resultPromise = invokeFnAndValidateOutputPreservingExecutionModel( fn, 4, validate );
+      expect( resultPromise ).toBeInstanceOf( Promise );
+      const result = await resultPromise;
+      expect( result ).toBe( 5 );
+      expect( validate ).toHaveBeenCalledWith( 5 );
+    } );
+
+    it( 'propagates validator errors (sync)', () => {
+      const fn = vi.fn( x => x );
+      const validate = vi.fn( () => {
+        throw new Error( 'invalid' );
+      } );
+      expect( () => invokeFnAndValidateOutputPreservingExecutionModel( fn, 'a', validate ) ).toThrow( 'invalid' );
+    } );
+
+    it( 'propagates validator errors (async)', async () => {
+      const fn = vi.fn( async x => x );
+      const validate = vi.fn( () => {
+        throw new Error( 'invalid' );
+      } );
+      await expect( invokeFnAndValidateOutputPreservingExecutionModel( fn, 'a', validate ) ).rejects.toThrow( 'invalid' );
+    } );
+  } );
+} );
+

package/src/interface/validations/ajv_provider.js

@@ -0,0 +1,3 @@
+import Ajv from 'ajv';
+
+export const ajv = new Ajv();

package/src/interface/validations/runtime.js

@@ -0,0 +1,69 @@
+import { FatalError } from '#errors';
+import { ajv } from './ajv_provider.js';
+
+/**
+ * Error type for when the input/output of a step/workflow doesn't match its input/output schema, respectively
+ */
+export class MismatchSchemaError extends FatalError {}
+/**
+ * Error type for when the input of a step/workflow doesn't match its input schema
+ * @extends MismatchSchemaError
+ */
+export class InvalidInputError extends MismatchSchemaError {}
+/**
+ * Error type for when the output of a step/workflow doesn't match its output schema
+ * @extends MismatchSchemaError
+ */
+export class InvalidOutputError extends MismatchSchemaError {}
+
+const validate = ( ErrorClass, type, name, schema, payload ) => {
+  const validate = ajv.compile( schema );
+  const valid = validate( payload );
+
+  if ( !valid ) {
+    throw new ErrorClass( `Invalid input at ${type} "${name}": ${ajv.errorsText( validate.errors )}` );
+  }
+};
+
+const validateInput = validate.bind( null, InvalidInputError );
+const validateOutput = validate.bind( null, InvalidOutputError );
+
+/**
+ * Validates step input
+ *
+ * @param {name} name - step's name
+ * @param {object} schema - step's input schema
+ * @param {any} - the input to validate
+ * @throws InvalidInputError
+ */
+export const validateStepInput = validateInput.bind( null, 'step' );
+
+/**
+ * Validates step output
+ *
+ * @param {name} name - step's name
+ * @param {object} schema - step's output schema
+ * @param {any} - the output to validate
+ * @throws InvalidOutputError
+ */
+export const validateStepOutput = validateOutput.bind( null, 'step' );
+
+/**
+ * Validates workflow input
+ *
+ * @param {name} name - workflow's name
+ * @param {object} schema - workflow's input schema
+ * @param {any} - the input to validate
+ * @throws InvalidInputError
+ */
+export const validateWorkflowInput = validateInput.bind( null, 'workflow' );
+
+/**
+ * Validates workflow output
+ *
+ * @param {name} name - workflow's name
+ * @param {object} schema - workflow's output schema
+ * @param {any} - the output to validate
+ * @throws InvalidOutputError
+ */
+export const validateWorkflowOutput = validateOutput.bind( null, 'workflow' );

package/src/interface/validations/runtime.spec.js

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { validateStepInput, validateWorkflowInput, InvalidInputError } from './runtime.js';
+
+describe( 'Runtime validations spec', () => {
+  describe( 'validateStepInput', () => {
+    it( 'passes with matching payload', () => {
+      const schema = {
+        type: 'object',
+        properties: { id: { type: 'string' }, count: { type: 'integer', minimum: 0 } },
+        required: [ 'id' ],
+        additionalProperties: false
+      };
+      expect( () => validateStepInput( 'myStep', schema, { id: 'x', count: 2 } ) ).not.toThrow();
+    } );
+
+    it( 'rejects invalid payload', () => {
+      const schema = {
+        type: 'object',
+        properties: { id: { type: 'string' }, count: { type: 'integer', minimum: 0 } },
+        required: [ 'id' ],
+        additionalProperties: false
+      };
+      const error = new InvalidInputError( 'Invalid input at step "myStep": data must have required property \'id\'' );
+      expect( () => validateStepInput( 'myStep', schema, { count: -1 } ) ).toThrow( error );
+    } );
+  } );
+
+  describe( 'validateWorkflowInput', () => {
+    it( 'passes with matching payload', () => {
+      const schema = {
+        type: 'object',
+        properties: { name: { type: 'string' }, enabled: { type: 'boolean' } },
+        required: [ 'name' ],
+        additionalProperties: false
+      };
+      expect( () => validateWorkflowInput( 'myWorkflow', schema, { name: 'wf', enabled: true } ) ).not.toThrow();
+    } );
+
+    it( 'rejects invalid payload', () => {
+      const schema = {
+        type: 'object',
+        properties: { name: { type: 'string' }, enabled: { type: 'boolean' } },
+        required: [ 'name' ],
+        additionalProperties: false
+      };
+      const error = new InvalidInputError( 'Invalid input at workflow "myWorkflow": data must have required property \'name\'' );
+      expect( () => validateWorkflowInput( 'myWorkflow', schema, { enabled: 'yes' } ) ).toThrow( error );
+    } );
+  } );
+} );

package/src/interface/validations/static.js

@@ -0,0 +1,67 @@
+import { ajv } from './ajv_provider.js';
+import * as z from 'zod';
+
+/**
+ * Error is thrown when the definition of a step/workflow has problems
+ */
+export class StaticValidationError extends Error {};
+
+// Custom validation for zod, to be used when validating JSONSchema def with ajv
+const refineJsonSchema = ( value, ctx ) => {
+  if ( value && !ajv.validateSchema( value ) ) {
+    ctx.addIssue( {
+      code: 'invalid_format',
+      message: ajv.errorsText( ajv.errors )
+    } );
+  }
+};
+
+const stepAndWorkflowSchema = z.object( {
+  name: z.string().regex( /^[a-z_][a-z0-9_]*$/i ),
+  description: z.string().optional(),
+  inputSchema: z.looseObject( {} ).optional().superRefine( refineJsonSchema ),
+  outputSchema: z.looseObject( {} ).optional().superRefine( refineJsonSchema ),
+  fn: z.function()
+} );
+
+const webhookSchema = z.object( {
+  url: z.url( { protocol: /^https?$/ } ),
+  payload: z.any().optional()
+} );
+
+const validateAgainstSchema = ( schema, args ) => {
+  const result = schema.safeParse( args );
+  if ( !result.success ) {
+    throw new StaticValidationError( z.prettifyError( result.error ) );
+  }
+};
+
+/**
+ * Validate step payload
+ *
+ * @param {object} args - The step arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+export function validateStep( args ) {
+  validateAgainstSchema( stepAndWorkflowSchema, args );
+};
+
+/**
+ * Validate workflow payload
+ *
+ * @param {object} args - The workflow arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+export function validateWorkflow( args ) {
+  validateAgainstSchema( stepAndWorkflowSchema, args );
+};
+
+/**
+ * Validate createWebhook payload
+ *
+ * @param {object} args - The createWebhook arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+export function validateCreateWebhook( args ) {
+  validateAgainstSchema( webhookSchema, args );
+};

package/src/interface/validations/static.spec.js

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest';
+import { validateStep, validateWorkflow, validateCreateWebhook, StaticValidationError } from './static.js';
+
+const validArgs = Object.freeze( {
+  name: 'valid_name',
+  description: 'desc',
+  inputSchema: { type: 'object' },
+  outputSchema: { type: 'object' },
+  fn: () => {}
+} );
+
+describe( 'interface/validator', () => {
+  describe( 'validateStep', () => {
+    it( 'passes for valid args', () => {
+      expect( () => validateStep( { ...validArgs } ) ).not.toThrow();
+    } );
+
+    it( 'rejects missing name', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected string, received undefined\n  → at name' );
+      expect( () => validateStep( { ...validArgs, name: undefined } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-string name', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected string, received number\n  → at name' );
+      expect( () => validateStep( { ...validArgs, name: 123 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects invalid name pattern', () => {
+      const error = new StaticValidationError( '✖ Invalid string: must match pattern /^[a-z_][a-z0-9_]*$/i\n  → at name' );
+      expect( () => validateStep( { ...validArgs, name: '-bad' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-string description', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected string, received number\n  → at description' );
+      expect( () => validateStep( { ...validArgs, description: 10 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-object inputSchema', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected object, received string\n  → at inputSchema' );
+      expect( () => validateStep( { ...validArgs, inputSchema: 'not-an-object' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects invalid inputSchema structure', () => {
+      const error = new StaticValidationError( '✖ data/type must be equal to one of the allowed values, \
+data/type must be array, data/type must match a schema in anyOf\n  → at inputSchema' );
+      expect( () => validateStep( { ...validArgs, inputSchema: { type: 1 } } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-object outputSchema', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected object, received number\n  → at outputSchema' );
+      expect( () => validateStep( { ...validArgs, outputSchema: 10 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects invalid outputSchema structure', () => {
+      const error = new StaticValidationError( '✖ data/type must be equal to one of the allowed values, \
+data/type must be array, data/type must match a schema in anyOf\n  → at outputSchema' );
+      expect( () => validateStep( { ...validArgs, outputSchema: { type: 1 } } ) ).toThrow( error );
+    } );
+
+    it( 'rejects missing fn', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received undefined\n  → at fn' );
+      expect( () => validateStep( { ...validArgs, fn: undefined } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-function fn', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received string\n  → at fn' );
+      expect( () => validateStep( { ...validArgs, fn: 'not-fn' } ) ).toThrow( error );
+    } );
+  } );
+
+  describe( 'validateWorkflow', () => {
+    it( 'passes for valid args', () => {
+      expect( () => validateWorkflow( { ...validArgs } ) ).not.toThrow();
+    } );
+  } );
+
+  describe( 'validate webhook', () => {
+    it( 'passes with valid http url', () => {
+      expect( () => validateCreateWebhook( { url: 'http://example.com' } ) ).not.toThrow();
+    } );
+
+    it( 'passes with valid https url', () => {
+      expect( () => validateCreateWebhook( { url: 'https://example.com/path?q=1' } ) ).not.toThrow();
+    } );
+
+    it( 'rejects missing url', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected string, received undefined\n  → at url' );
+      expect( () => validateCreateWebhook( { } ) ).toThrow( error );
+    } );
+
+    it( 'rejects invalid scheme', () => {
+      const error = new StaticValidationError( '✖ Invalid URL\n  → at url' );
+      expect( () => validateCreateWebhook( { url: 'ftp://example.com' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects malformed url', () => {
+      const error = new StaticValidationError( '✖ Invalid URL\n  → at url' );
+      expect( () => validateCreateWebhook( { url: 'http:////' } ) ).toThrow( error );
+    } );
+  } );
+} );

package/src/interface/webhook.js

@@ -1,18 +1,19 @@
-import { defineSignal, setHandler } from '@temporalio/workflow';
+// THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
+import { defineSignal, setHandler, proxyActivities, workflowInfo } from '@temporalio/workflow';
+import { SEND_WEBHOOK_ACTIVITY_NAME } from '#consts';
+import { validateCreateWebhook } from './validations/static.js';
 
-export function createWebhook( workflowId, requestDispatcher ) {
-  return async function webhook( { name: _name, description: _description, url, payload } ) {
-    const { error } = await requestDispatcher( { url, workflowId, payload } );
-    if ( error ) {
-      throw new Error( 'Webhook call failed' );
-    }
+export async function createWebhook( { url, payload } ) {
+  validateCreateWebhook( { url, payload } );
+  const workflowId = workflowInfo();
 
-    const resumeSignal = defineSignal( 'resume' );
+  await proxyActivities( temporalActivityConfigs )[SEND_WEBHOOK_ACTIVITY_NAME]( { url, workflowId, payload } );
 
-    return new Promise( resolve => {
-      setHandler( resumeSignal, responsePayload => {
-        resolve( responsePayload );
-      } );
-    } );
-  };
+  const resumeSignal = defineSignal( 'resume' );
+
+  return new Promise( resolve =>
+    setHandler( resumeSignal, responsePayload => {
+      resolve( responsePayload );
+    } )
+  );
 };

package/src/interface/workflow.js

@@ -1,10 +1,10 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
-import { proxyActivities, IllegalStateError, executeChild, workflowInfo } from '@temporalio/workflow';
-import { getInvocationDir } from './utils.js';
-import { createWebhook } from './webhook.js';
-import { setName } from './metadata.js';
-import { sendWebhookPostName } from '#consts';
+import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, ApplicationFailure } from '@temporalio/workflow';
+import { getInvocationDir, invokeFnAndValidateOutputPreservingExecutionModel } from './utils.js';
+import { setMetadata } from './metadata.js';
 import { FatalError, ValidationError } from '../errors.js';
+import { validateWorkflow } from './validations/static.js';
+import { validateWorkflowInput, validateWorkflowOutput } from './validations/runtime.js';
 
 const temporalActivityConfigs = {
   startToCloseTimeout: '20 minute',
@@ -17,53 +17,58 @@ const temporalActivityConfigs = {
   }
 };
 
-export function workflow( { name, description: _description, fn } ) {
+export function workflow( { name, description, inputSchema, outputSchema, fn } ) {
+  validateWorkflow( { name, description, inputSchema, outputSchema, fn } );
   const workflowPath = getInvocationDir();
 
-  // This wraps the actually function call so before being invoked it creates the activity proxies and export the context
+  const steps = proxyActivities( temporalActivityConfigs );
+
   const wrapper = async input => {
     try {
-      const { workflowId } = workflowInfo();
+      if ( inputSchema ) {
+        validateWorkflowInput( name, inputSchema, input );
+      }
+
+      // this returns a plain function, for example, in unit tests
+      if ( !inWorkflowContext() ) {
+        if ( outputSchema ) {
+          return invokeFnAndValidateOutputPreservingExecutionModel( fn, input, validateWorkflowOutput.bind( null, name, outputSchema ) );
+        }
+        return fn( input );
+      }
 
-      // enrich context information needed for tracking
       Object.assign( workflowInfo().memo, { workflowPath } );
 
-      const proxies = proxyActivities( temporalActivityConfigs );
-      const context = {
-        steps: new Proxy( {}, {
-          get( _target, name ) {
-            return proxies[`${workflowPath}#${name}`];
-          }
-        } ),
-        tools: {
-          webhook: createWebhook( workflowId, proxies[sendWebhookPostName] )
-        }
-      };
+      // binds the methods called in the code that  Webpack loader will add, they will exposed via "this"
+      const boundFn = fn.bind( {
+        invokeStep: async ( stepName, input ) => steps[`${workflowPath}#${stepName}`]( input ),
 
-      return fn( input, context );
+        startWorkflow: async ( name, input ) => {
+          const { memo, workflowId, workflowType } = workflowInfo();
 
-    } catch ( error ) {
-      // IllegalStateError is thrown when temporal is not running and one try to access workflowInfo()
-      if ( error instanceof IllegalStateError ) {
-        return fn( input, { steps: null, workflowId: null } );
-      }
+          // Checks if current memo has rootWorkflowId, which means current execution is already a child
+          // Then it sets the memory for the child execution passing along who's the original workflow is and its type
+          const workflowMemory = memo.rootWorkflowId ?
+            { parentWorkflowId: workflowId, rootWorkflowType: memo.rootWorkflowType, rootWorkflowId: memo.rootWorkflowId } :
+            { parentWorkflowId: workflowId, rootWorkflowId: workflowId, rootWorkflowType: workflowType };
 
-      throw error;
+          return executeChild( name, { args: input ? [ input ] : [], memo: workflowMemory } );
+        }
+      } );
+
+      if ( outputSchema ) {
+        return invokeFnAndValidateOutputPreservingExecutionModel( boundFn, input, validateWorkflowOutput.bind( null, name, outputSchema ) );
+      }
+      return boundFn( input );
+    } catch ( error ) {
+      /*
+       * Any errors in the workflow will interrupt its execution since the workflow is designed to orchestrate and
+       * IOs should be made in steps
+       */
+      throw new ApplicationFailure( error.message, error.constructor.name );
     }
   };
 
-  setName( wrapper, name );
+  setMetadata( wrapper, { name, description, inputSchema, outputSchema } );
   return wrapper;
 };
-
-export async function startWorkflow( name, { input } = {} ) {
-  const { memo, workflowId, workflowType } = workflowInfo();
-
-  // Checks if current memo has rootWorkflowId, which means current execution is already a child
-  // Then it sets the memory for the child execution passing along who's the original workflow is and its type
-  const workflowMemory = memo.rootWorkflowId ?
-    { parentWorkflowId: workflowId, rootWorkflowType: memo.rootWorkflowType, rootWorkflowId: memo.rootWorkflowId } :
-    { parentWorkflowId: workflowId, rootWorkflowId: workflowId, rootWorkflowType: workflowType };
-
-  return executeChild( name, { args: input ? [ input ] : [], memo: workflowMemory } );
-}

package/src/internal_activities/index.js

@@ -1,17 +1,28 @@
-import { fetch } from 'undici';
 import { api as apiConfig } from '#configs';
+import { FatalError } from '#errors';
 
-export async function sendWebhookPost( { url, workflowId, payload } ) {
-  const res = await fetch( url, {
+export const sendWebhookPost = async ( { url, workflowId, payload } ) => {
+  const request = fetch( url, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       Authentication: `Basic ${apiConfig.authKey}`
     },
-    body: JSON.stringify( { workflowId, payload } )
+    body: JSON.stringify( { workflowId, payload } ),
+    signal: AbortSignal.timeout( 5000 )
   } );
 
+  const res = await ( async () => {
+    try {
+      return await request;
+    } catch {
+      throw new FatalError( 'Webhook fail: timeout' );
+    }
+  } )();
+
   console.log( '[Core.SendWebhookPost]', res.status, res.statusText );
 
-  return { error: !res.ok };
+  if ( !res.ok ) {
+    throw new FatalError( `Webhook fail: ${res.status}` );
+  }
 };