@solidxai/core 0.1.12 → 0.1.13-beta.2

package/src/services/workflow/workflow-definition-validator.service.ts

@@ -0,0 +1,223 @@
+import { BadRequestException, Injectable } from '@nestjs/common';
+import {
+  WorkflowDefinitionDsl,
+  WorkflowNodeDefinition,
+  WorkflowTriggerDefinition,
+} from '../../types/workflow-dsl.types';
+import { WorkflowNodeRegistryService } from './workflow-node-registry.service';
+import { CronExpressionParser } from 'cron-parser';
+
+@Injectable()
+export class WorkflowDefinitionValidatorService {
+  constructor(private readonly registry: WorkflowNodeRegistryService) {}
+
+  validate(definition: WorkflowDefinitionDsl) {
+    if (!definition || !Array.isArray(definition.nodes)) {
+      throw new BadRequestException(
+        'Workflow definition YAML must include a nodes array.',
+      );
+    }
+
+    if (
+      definition.triggers !== undefined &&
+      definition.triggers !== null &&
+      !Array.isArray(definition.triggers)
+    ) {
+      throw new BadRequestException(
+        'Workflow definition triggers must be an array when provided.',
+      );
+    }
+
+    const nodeIds = new Set<string>();
+    this.validateNodes(definition.nodes, nodeIds);
+    this.validateTriggers(definition);
+  }
+
+  private validateTriggers(definition: WorkflowDefinitionDsl) {
+    const triggers = definition.triggers ?? [];
+    const triggerIds = new Set<string>();
+    const activeScheduleTriggers = triggers.filter(
+      (trigger) => trigger?.type === 'schedule' && !trigger.disabled,
+    );
+
+    for (const trigger of triggers) {
+      this.validateTrigger(trigger, triggerIds);
+    }
+
+    if (!activeScheduleTriggers.length) {
+      return;
+    }
+
+    const inputs = definition.inputs ?? {};
+    for (const [inputKey, inputDefinition] of Object.entries(inputs)) {
+      if (!this.inputHasDefault(inputDefinition)) {
+        throw new BadRequestException(
+          `Workflow input "${inputKey}" requires a default value before enabling a scheduled trigger.`,
+        );
+      }
+    }
+  }
+
+  private validateTrigger(
+    trigger: WorkflowTriggerDefinition,
+    triggerIds: Set<string>,
+  ) {
+    if (!trigger || typeof trigger !== 'object' || Array.isArray(trigger)) {
+      throw new BadRequestException('Every workflow trigger must be an object.');
+    }
+
+    if (!trigger.id) {
+      throw new BadRequestException('Every workflow trigger requires an id.');
+    }
+
+    if (triggerIds.has(trigger.id)) {
+      throw new BadRequestException(
+        `Duplicate workflow trigger id "${trigger.id}".`,
+      );
+    }
+    triggerIds.add(trigger.id);
+
+    if (!['schedule', 'webhook'].includes(trigger.type)) {
+      throw new BadRequestException(
+        `Workflow trigger "${trigger.id}" has unsupported type "${trigger.type}".`,
+      );
+    }
+
+    if (trigger.type === 'schedule') {
+      const cronExpression =
+        trigger.configuration?.cronExpression ?? trigger.configuration?.cron;
+      if (!cronExpression || typeof cronExpression !== 'string') {
+        throw new BadRequestException(
+          `Workflow trigger "${trigger.id}" requires a cron expression.`,
+        );
+      }
+
+      try {
+        CronExpressionParser.parse(cronExpression, {
+          currentDate: new Date(),
+          tz: trigger.configuration?.timezone ?? 'UTC',
+        });
+      } catch (error: any) {
+        throw new BadRequestException(
+          `Workflow trigger "${trigger.id}" has an invalid cron expression: ${error?.message ?? cronExpression}`,
+        );
+      }
+    }
+
+    if (trigger.type === 'webhook') {
+      const method = String(trigger.configuration?.method ?? 'POST').toUpperCase();
+      if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+        throw new BadRequestException(
+          `Workflow trigger "${trigger.id}" has unsupported webhook method "${method}".`,
+        );
+      }
+    }
+  }
+
+  private inputHasDefault(inputDefinition: any): boolean {
+    if (
+      inputDefinition &&
+      typeof inputDefinition === 'object' &&
+      !Array.isArray(inputDefinition)
+    ) {
+      return (
+        Object.prototype.hasOwnProperty.call(inputDefinition, 'default') &&
+        inputDefinition.default !== undefined &&
+        inputDefinition.default !== null
+      );
+    }
+
+    return inputDefinition !== undefined && inputDefinition !== null;
+  }
+
+  private validateNodes(nodes: WorkflowNodeDefinition[], nodeIds: Set<string>) {
+    for (const node of nodes) {
+      this.validateNode(node, nodeIds);
+    }
+  }
+
+  private validateNode(node: WorkflowNodeDefinition, nodeIds: Set<string>) {
+    if (!node || typeof node !== 'object' || Array.isArray(node)) {
+      throw new BadRequestException('Every workflow node must be an object.');
+    }
+
+    for (const unsupportedKey of ['children', 'branches', 'nodes']) {
+      if (Object.prototype.hasOwnProperty.call(node, unsupportedKey)) {
+        throw new BadRequestException(
+          `Workflow node "${node.id ?? 'unknown'}" uses unsupported child key "${unsupportedKey}". Use "tasks", "then", "else", "defaults", or "cases" instead.`,
+        );
+      }
+    }
+
+    for (const childKey of ['tasks', 'then', 'else', 'defaults'] as const) {
+      const childValue = node[childKey];
+      if (
+        childValue !== undefined &&
+        childValue !== null &&
+        !Array.isArray(childValue)
+      ) {
+        throw new BadRequestException(
+          `Workflow node "${node.id ?? 'unknown'}" field "${childKey}" must be an array when provided.`,
+        );
+      }
+    }
+
+    if (
+      node.cases !== undefined &&
+      node.cases !== null &&
+      (typeof node.cases !== 'object' || Array.isArray(node.cases))
+    ) {
+      throw new BadRequestException(
+        `Workflow node "${node.id ?? 'unknown'}" field "cases" must be an object of arrays when provided.`,
+      );
+    }
+
+    if (node.cases && typeof node.cases === 'object') {
+      for (const [caseKey, caseNodes] of Object.entries(node.cases)) {
+        if (!Array.isArray(caseNodes)) {
+          throw new BadRequestException(
+            `Workflow node "${node.id ?? 'unknown'}" case "${caseKey}" must be an array.`,
+          );
+        }
+      }
+    }
+
+    if (!node.id) {
+      throw new BadRequestException('Every workflow node requires an id.');
+    }
+
+    if (nodeIds.has(node.id)) {
+      throw new BadRequestException(`Duplicate workflow node id "${node.id}".`);
+    }
+
+    nodeIds.add(node.id);
+
+    if (!node.kind) {
+      throw new BadRequestException(`Workflow node "${node.id}" requires kind.`);
+    }
+
+    if (!['task', 'control', 'subflow'].includes(node.kind)) {
+      throw new BadRequestException(
+        `Workflow node "${node.id}" has unsupported kind "${node.kind}".`,
+      );
+    }
+
+    if (!node.type) {
+      throw new BadRequestException(`Workflow node "${node.id}" requires type.`);
+    }
+
+    if (!this.registry.has(node.type)) {
+      throw new BadRequestException(
+        `Workflow node "${node.id}" uses unregistered type "${node.type}".`,
+      );
+    }
+
+    this.validateNodes(node.tasks ?? [], nodeIds);
+    this.validateNodes(node.then ?? [], nodeIds);
+    this.validateNodes(node.else ?? [], nodeIds);
+    this.validateNodes(node.defaults ?? [], nodeIds);
+    Object.values(node.cases ?? {}).forEach((caseNodes) => {
+      this.validateNodes(caseNodes, nodeIds);
+    });
+  }
+}

package/src/services/workflow/workflow-execution-writer.service.ts

@@ -0,0 +1,244 @@
+import { Injectable } from '@nestjs/common';
+import { InjectEntityManager } from '@nestjs/typeorm';
+import { randomUUID } from 'crypto';
+import { EntityManager } from 'typeorm';
+import { WorkflowDefinition } from '../../entities/workflow-definition.entity';
+import { WorkflowExecutionArtifact } from '../../entities/workflow-execution-artifact.entity';
+import { WorkflowExecutionLog } from '../../entities/workflow-execution-log.entity';
+import { WorkflowExecution } from '../../entities/workflow-execution.entity';
+import { WorkflowStepExecution } from '../../entities/workflow-step-execution.entity';
+import {
+  WorkflowArtifactEmitRequest,
+  WorkflowExecutionRequest,
+  WorkflowLogEmitRequest,
+  WorkflowNodeDefinition,
+  WorkflowStepExecutionStatus,
+} from '../../types/workflow-dsl.types';
+
+@Injectable()
+export class WorkflowExecutionWriterService {
+  constructor(
+    @InjectEntityManager('default')
+    private readonly entityManager: EntityManager,
+  ) {}
+
+  async createExecution(
+    definition: WorkflowDefinition,
+    request: WorkflowExecutionRequest,
+  ): Promise<WorkflowExecution> {
+    const execution = this.entityManager.create(WorkflowExecution, {
+      executionIdentifier: this.createKey('wf'),
+      workflowDefinition: definition,
+      workflowKey: definition.key,
+      workflowDisplayName: definition.displayName,
+      status: 'running',
+      triggerType: request.triggerType ?? 'manual',
+      startedAt: new Date(),
+      inputPayload: request.input ?? {},
+      definitionVersion: definition.definitionVersion,
+      definitionChecksum: definition.definitionChecksum,
+      definitionSnapshot: definition.definitionYaml,
+      requestedByUserId: request.requestedByUserId as any,
+    });
+
+    return this.entityManager.save(WorkflowExecution, execution);
+  }
+
+  async createEnqueuedExecution(
+    definition: WorkflowDefinition,
+    request: WorkflowExecutionRequest,
+  ): Promise<WorkflowExecution> {
+    const execution = this.entityManager.create(WorkflowExecution, {
+      executionIdentifier: this.createKey('wf'),
+      workflowDefinition: definition,
+      workflowKey: definition.key,
+      workflowDisplayName: definition.displayName,
+      status: 'enqueued',
+      triggerType: request.triggerType ?? 'manual',
+      // While enqueued, keep the original request here so the subscriber can
+      // resume without duplicating large output state or adding a schema field.
+      inputPayload: request ?? {},
+      definitionVersion: definition.definitionVersion,
+      definitionChecksum: definition.definitionChecksum,
+      definitionSnapshot: definition.definitionYaml,
+      requestedByUserId: request.requestedByUserId as any,
+    });
+
+    return this.entityManager.save(WorkflowExecution, execution);
+  }
+
+  async startExecution(
+    execution: WorkflowExecution,
+    request: WorkflowExecutionRequest,
+  ): Promise<WorkflowExecution> {
+    execution.status = 'running';
+    execution.startedAt = new Date();
+    execution.inputPayload = request.input ?? {};
+    execution.triggerType = request.triggerType ?? execution.triggerType ?? 'manual';
+    execution.requestedByUserId = request.requestedByUserId as any;
+    return this.entityManager.save(WorkflowExecution, execution);
+  }
+
+  async completeExecution(
+    execution: WorkflowExecution,
+    _outputPayload: any,
+  ): Promise<WorkflowExecution> {
+    const finishedAt = new Date();
+    execution.status = 'success';
+    execution.finishedAt = finishedAt;
+    execution.durationMs = this.duration(execution.startedAt, finishedAt) as any;
+    // Do not persist the combined workflow output here. Large workflows and
+    // loops can duplicate every step output into one huge JSON payload; clients
+    // should read outputs from workflowStepExecution rows instead.
+    execution.outputPayload = null;
+    return this.entityManager.save(WorkflowExecution, execution);
+  }
+
+  async failExecution(
+    execution: WorkflowExecution,
+    error: unknown,
+  ): Promise<WorkflowExecution> {
+    const finishedAt = new Date();
+    execution.status = 'failed';
+    execution.finishedAt = finishedAt;
+    execution.durationMs = this.duration(execution.startedAt, finishedAt) as any;
+    execution.errorSummary = this.errorMessage(error);
+    execution.errorDetails = this.errorDetails(error);
+    return this.entityManager.save(WorkflowExecution, execution);
+  }
+
+  async createStep(
+    execution: WorkflowExecution,
+    node: WorkflowNodeDefinition,
+    sequenceNumber: number,
+    inputPayload: any,
+    parentNodeId?: string,
+    parentStepExecutionKey?: string,
+  ): Promise<WorkflowStepExecution> {
+    const step = this.entityManager.create(WorkflowStepExecution, {
+      stepExecutionKey: this.createKey('step'),
+      workflowExecution: execution,
+      nodeId: node.id,
+      nodeName: node.name,
+      nodeKind: node.kind,
+      nodeType: node.type,
+      status: 'running',
+      attemptNumber: 1,
+      retryCount: 0,
+      maxRetries: node.retryPolicy?.maxRetries,
+      parentNodeId,
+      parentStepExecutionKey,
+      sequenceNumber,
+      startedAt: new Date(),
+      timeoutMs: node.timeoutMs as any,
+      inputPayload,
+      nodeSnapshot: node,
+    });
+
+    return this.entityManager.save(WorkflowStepExecution, step);
+  }
+
+  async completeStep(
+    step: WorkflowStepExecution,
+    status: WorkflowStepExecutionStatus,
+    outputPayload: any,
+    runtimeContext?: any,
+  ): Promise<WorkflowStepExecution> {
+    const finishedAt = new Date();
+    step.status = status;
+    step.finishedAt = finishedAt;
+    step.durationMs = this.duration(step.startedAt, finishedAt) as any;
+    step.outputPayload = outputPayload;
+    step.runtimeContext = runtimeContext;
+    return this.entityManager.save(WorkflowStepExecution, step);
+  }
+
+  async failStep(
+    step: WorkflowStepExecution,
+    error: unknown,
+  ): Promise<WorkflowStepExecution> {
+    const finishedAt = new Date();
+    step.status = 'failed';
+    step.finishedAt = finishedAt;
+    step.durationMs = this.duration(step.startedAt, finishedAt) as any;
+    step.errorSummary = this.errorMessage(error);
+    step.errorDetails = this.errorDetails(error);
+    return this.entityManager.save(WorkflowStepExecution, step);
+  }
+
+  async writeLog(
+    execution: WorkflowExecution,
+    step: WorkflowStepExecution | undefined,
+    entry: WorkflowLogEmitRequest,
+    sequenceNumber: number,
+  ): Promise<WorkflowExecutionLog> {
+    const log = this.entityManager.create(WorkflowExecutionLog, {
+      logKey: this.createKey('log'),
+      workflowExecution: execution,
+      workflowStepExecution: step,
+      level: entry.level ?? 'info',
+      message: entry.message,
+      eventType: entry.eventType,
+      source: entry.source ?? 'workflow-engine',
+      nodeId: step?.nodeId,
+      nodeType: step?.nodeType,
+      sequenceNumber,
+      occurredAt: new Date(),
+      context: entry.context,
+      metadata: entry.metadata,
+    });
+
+    return this.entityManager.save(WorkflowExecutionLog, log);
+  }
+
+  async writeArtifact(
+    execution: WorkflowExecution,
+    step: WorkflowStepExecution | undefined,
+    entry: WorkflowArtifactEmitRequest,
+  ): Promise<WorkflowExecutionArtifact> {
+    const artifact = this.entityManager.create(WorkflowExecutionArtifact, {
+      artifactKey: this.createKey('artifact'),
+      workflowExecution: execution,
+      workflowStepExecution: step,
+      name: entry.name,
+      description: entry.description,
+      artifactType: entry.artifactType ?? 'payload',
+      nodeId: step?.nodeId,
+      nodeType: step?.nodeType,
+      uri: entry.uri,
+      fileName: entry.fileName,
+      mimeType: entry.mimeType,
+      sizeBytes: entry.sizeBytes as any,
+      checksum: entry.checksum,
+      producedAt: new Date(),
+      payload: entry.payload,
+      metadata: entry.metadata,
+    });
+
+    return this.entityManager.save(WorkflowExecutionArtifact, artifact);
+  }
+
+  private createKey(prefix: string): string {
+    return `${prefix}-${Date.now()}-${randomUUID().slice(0, 8)}`;
+  }
+
+  private duration(startedAt?: Date, finishedAt = new Date()): number {
+    return startedAt ? finishedAt.getTime() - startedAt.getTime() : 0;
+  }
+
+  private errorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+  }
+
+  private errorDetails(error: unknown): any {
+    if (error instanceof Error) {
+      return {
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      };
+    }
+
+    return { error };
+  }
+}

package/src/services/workflow/workflow-expression.service.ts

@@ -0,0 +1,175 @@
+import { Injectable } from '@nestjs/common';
+import {
+  WorkflowExpressionResolver,
+  WorkflowRuntimeContext,
+} from '../../types/workflow-dsl.types';
+
+@Injectable()
+export class WorkflowExpressionService implements WorkflowExpressionResolver {
+  interpolate<T = any>(value: T, context: WorkflowRuntimeContext): T {
+    if (Array.isArray(value)) {
+      return value.map((entry) => this.interpolate(entry, context)) as T;
+    }
+
+    if (value && typeof value === 'object') {
+      return Object.entries(value).reduce((acc, [key, entry]) => {
+        acc[key] = this.interpolate(entry, context);
+        return acc;
+      }, {} as Record<string, any>) as T;
+    }
+
+    if (typeof value !== 'string') {
+      return value;
+    }
+
+    const exactExpression = value.match(/^\s*\{\{\s*(.*?)\s*\}\}\s*$/);
+    if (exactExpression) {
+      return this.resolveExpression(exactExpression[1], context);
+    }
+
+    return value.replace(/\{\{\s*(.*?)\s*\}\}/g, (_match, expression) => {
+      const resolved = this.resolveExpression(expression, context);
+      return resolved === null || resolved === undefined ? '' : String(resolved);
+    }) as T;
+  }
+
+  evaluateCondition(expression: any, context: WorkflowRuntimeContext): boolean {
+    const resolved =
+      typeof expression === 'string'
+        ? this.resolveExpression(this.unwrapExpression(expression), context)
+        : expression;
+
+    if (typeof resolved === 'string') {
+      return this.evaluateBooleanExpression(resolved, context);
+    }
+
+    return Boolean(resolved);
+  }
+
+  resolveExpression(expression: string, context: WorkflowRuntimeContext): any {
+    const trimmed = expression.trim();
+
+    if (trimmed === 'true') return true;
+    if (trimmed === 'false') return false;
+    if (trimmed === 'null') return null;
+    if (trimmed === 'undefined') return undefined;
+    if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed);
+    if (this.isQuoted(trimmed)) return trimmed.slice(1, -1);
+
+    const comparison = this.evaluateComparison(trimmed, context);
+    if (comparison !== undefined) {
+      return comparison;
+    }
+
+    return this.resolvePath(trimmed, context);
+  }
+
+  private evaluateBooleanExpression(
+    expression: string,
+    context: WorkflowRuntimeContext,
+  ): boolean {
+    const orParts = this.splitTopLevel(expression, '||');
+    if (orParts.length > 1) {
+      return orParts.some((part) => this.evaluateCondition(part, context));
+    }
+
+    const andParts = this.splitTopLevel(expression, '&&');
+    if (andParts.length > 1) {
+      return andParts.every((part) => this.evaluateCondition(part, context));
+    }
+
+    const comparison = this.evaluateComparison(expression, context);
+    if (comparison !== undefined) {
+      return comparison;
+    }
+
+    return Boolean(this.resolveExpression(expression, context));
+  }
+
+  private evaluateComparison(
+    expression: string,
+    context: WorkflowRuntimeContext,
+  ): boolean | undefined {
+    const match = expression.match(/^(.+?)\s*(===|!==|==|!=|>=|<=|>|<)\s*(.+)$/);
+    if (!match) {
+      return undefined;
+    }
+
+    const left = this.resolveOperand(match[1], context);
+    const operator = match[2];
+    const right = this.resolveOperand(match[3], context);
+
+    switch (operator) {
+      case '===':
+        return left === right;
+      case '!==':
+        return left !== right;
+      case '==':
+        return left == right;
+      case '!=':
+        return left != right;
+      case '>=':
+        return Number(left) >= Number(right);
+      case '<=':
+        return Number(left) <= Number(right);
+      case '>':
+        return Number(left) > Number(right);
+      case '<':
+        return Number(left) < Number(right);
+      default:
+        return undefined;
+    }
+  }
+
+  private resolveOperand(
+    operand: string,
+    context: WorkflowRuntimeContext,
+  ): any {
+    return this.resolveExpression(this.unwrapExpression(operand), context);
+  }
+
+  private resolvePath(path: string, context: WorkflowRuntimeContext): any {
+    const root = {
+      inputs: context.input,
+      input: context.input,
+      variables: context.variables,
+      secrets: context.secrets,
+      outputs: context.outputs,
+      execution: context.execution,
+      node: context.node,
+      item: context.item,
+      index: context.index,
+    };
+
+    const parts = path
+      .replace(/\[(?:'|")([^'"]+)(?:'|")\]/g, '.$1')
+      .split('.')
+      .filter(Boolean);
+
+    return parts.reduce((current, key) => {
+      if (current === null || current === undefined) {
+        return undefined;
+      }
+      return current[key];
+    }, root as any);
+  }
+
+  private unwrapExpression(expression: string): string {
+    const match = expression.trim().match(/^\{\{\s*(.*?)\s*\}\}$/);
+    return match ? match[1] : expression.trim();
+  }
+
+  private splitTopLevel(expression: string, token: string): string[] {
+    return expression
+      .split(token)
+      .map((part) => part.trim())
+      .filter(Boolean);
+  }
+
+  private isQuoted(value: string): boolean {
+    return (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    );
+  }
+}

package/src/services/workflow/workflow-invocation.service.ts

@@ -0,0 +1,39 @@
+import { Injectable } from '@nestjs/common';
+import {
+  WorkflowExecutionRequest,
+  WorkflowExecutionResponse,
+} from '../../types/workflow-dsl.types';
+import { WorkflowRuntimeService } from './workflow-runtime.service';
+
+@Injectable()
+export class WorkflowInvocationService {
+  constructor(private readonly workflowRuntimeService: WorkflowRuntimeService) {}
+
+  executeById(
+    id: number,
+    request: WorkflowExecutionRequest = {},
+  ): Promise<WorkflowExecutionResponse> {
+    return this.workflowRuntimeService.executeDefinitionById(id, request);
+  }
+
+  executeByIdAsync(
+    id: number,
+    request: WorkflowExecutionRequest = {},
+  ): Promise<WorkflowExecutionResponse> {
+    return this.workflowRuntimeService.executeDefinitionByIdAsync(id, request);
+  }
+
+  executeByKey(
+    key: string,
+    request: WorkflowExecutionRequest = {},
+  ): Promise<WorkflowExecutionResponse> {
+    return this.workflowRuntimeService.executeDefinitionByKey(key, request);
+  }
+
+  executeByKeyAsync(
+    key: string,
+    request: WorkflowExecutionRequest = {},
+  ): Promise<WorkflowExecutionResponse> {
+    return this.workflowRuntimeService.executeDefinitionByKeyAsync(key, request);
+  }
+}