apcore-js 0.1.0

package/src/errors.ts

@@ -0,0 +1,369 @@
+/**
+ * Error hierarchy for the apcore framework.
+ */
+
+export class ModuleError extends Error {
+  readonly code: string;
+  readonly details: Record<string, unknown>;
+  readonly cause?: Error;
+  readonly traceId?: string;
+  readonly timestamp: string;
+
+  constructor(
+    code: string,
+    message: string,
+    details?: Record<string, unknown>,
+    cause?: Error,
+    traceId?: string,
+  ) {
+    super(message);
+    this.name = 'ModuleError';
+    this.code = code;
+    this.details = details ?? {};
+    this.cause = cause;
+    this.traceId = traceId;
+    this.timestamp = new Date().toISOString();
+  }
+
+  override toString(): string {
+    return `[${this.code}] ${this.message}`;
+  }
+}
+
+export class ConfigNotFoundError extends ModuleError {
+  constructor(configPath: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'CONFIG_NOT_FOUND',
+      `Configuration file not found: ${configPath}`,
+      { configPath },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'ConfigNotFoundError';
+  }
+}
+
+export class ConfigError extends ModuleError {
+  constructor(message: string, options?: { cause?: Error; traceId?: string }) {
+    super('CONFIG_INVALID', message, {}, options?.cause, options?.traceId);
+    this.name = 'ConfigError';
+  }
+}
+
+export class ACLRuleError extends ModuleError {
+  constructor(message: string, options?: { cause?: Error; traceId?: string }) {
+    super('ACL_RULE_ERROR', message, {}, options?.cause, options?.traceId);
+    this.name = 'ACLRuleError';
+  }
+}
+
+export class ACLDeniedError extends ModuleError {
+  constructor(callerId: string | null, targetId: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'ACL_DENIED',
+      `Access denied: ${callerId} -> ${targetId}`,
+      { callerId, targetId },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'ACLDeniedError';
+  }
+
+  get callerId(): string | null {
+    return this.details['callerId'] as string | null;
+  }
+
+  get targetId(): string {
+    return this.details['targetId'] as string;
+  }
+}
+
+export class ModuleNotFoundError extends ModuleError {
+  constructor(moduleId: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'MODULE_NOT_FOUND',
+      `Module not found: ${moduleId}`,
+      { moduleId },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'ModuleNotFoundError';
+  }
+}
+
+export class ModuleTimeoutError extends ModuleError {
+  constructor(moduleId: string, timeoutMs: number, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'MODULE_TIMEOUT',
+      `Module ${moduleId} timed out after ${timeoutMs}ms`,
+      { moduleId, timeoutMs },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'ModuleTimeoutError';
+  }
+
+  get moduleId(): string {
+    return this.details['moduleId'] as string;
+  }
+
+  get timeoutMs(): number {
+    return this.details['timeoutMs'] as number;
+  }
+}
+
+export class SchemaValidationError extends ModuleError {
+  constructor(
+    message: string = 'Schema validation failed',
+    errors?: Array<Record<string, unknown>>,
+    options?: { cause?: Error; traceId?: string },
+  ) {
+    super(
+      'SCHEMA_VALIDATION_ERROR',
+      message,
+      { errors: errors ?? [] },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'SchemaValidationError';
+  }
+}
+
+export class SchemaNotFoundError extends ModuleError {
+  constructor(schemaId: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'SCHEMA_NOT_FOUND',
+      `Schema not found: ${schemaId}`,
+      { schemaId },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'SchemaNotFoundError';
+  }
+}
+
+export class SchemaParseError extends ModuleError {
+  constructor(message: string, options?: { cause?: Error; traceId?: string }) {
+    super('SCHEMA_PARSE_ERROR', message, {}, options?.cause, options?.traceId);
+    this.name = 'SchemaParseError';
+  }
+}
+
+export class SchemaCircularRefError extends ModuleError {
+  constructor(refPath: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'SCHEMA_CIRCULAR_REF',
+      `Circular reference detected: ${refPath}`,
+      { refPath },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'SchemaCircularRefError';
+  }
+}
+
+export class CallDepthExceededError extends ModuleError {
+  constructor(depth: number, maxDepth: number, callChain: string[], options?: { cause?: Error; traceId?: string }) {
+    super(
+      'CALL_DEPTH_EXCEEDED',
+      `Call depth ${depth} exceeds maximum ${maxDepth}`,
+      { depth, maxDepth, callChain },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'CallDepthExceededError';
+  }
+
+  get currentDepth(): number {
+    return this.details['depth'] as number;
+  }
+
+  get maxDepth(): number {
+    return this.details['maxDepth'] as number;
+  }
+}
+
+export class CircularCallError extends ModuleError {
+  constructor(moduleId: string, callChain: string[], options?: { cause?: Error; traceId?: string }) {
+    super(
+      'CIRCULAR_CALL',
+      `Circular call detected for module ${moduleId}`,
+      { moduleId, callChain },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'CircularCallError';
+  }
+
+  get moduleId(): string {
+    return this.details['moduleId'] as string;
+  }
+}
+
+export class CallFrequencyExceededError extends ModuleError {
+  constructor(
+    moduleId: string,
+    count: number,
+    maxRepeat: number,
+    callChain: string[],
+    options?: { cause?: Error; traceId?: string },
+  ) {
+    super(
+      'CALL_FREQUENCY_EXCEEDED',
+      `Module ${moduleId} called ${count} times, max is ${maxRepeat}`,
+      { moduleId, count, maxRepeat, callChain },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'CallFrequencyExceededError';
+  }
+
+  get moduleId(): string {
+    return this.details['moduleId'] as string;
+  }
+
+  get count(): number {
+    return this.details['count'] as number;
+  }
+
+  get maxRepeat(): number {
+    return this.details['maxRepeat'] as number;
+  }
+}
+
+export class InvalidInputError extends ModuleError {
+  constructor(message: string = 'Invalid input', options?: { cause?: Error; traceId?: string }) {
+    super('GENERAL_INVALID_INPUT', message, {}, options?.cause, options?.traceId);
+    this.name = 'InvalidInputError';
+  }
+}
+
+export class FuncMissingTypeHintError extends ModuleError {
+  constructor(functionName: string, parameterName: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'FUNC_MISSING_TYPE_HINT',
+      `Parameter '${parameterName}' in function '${functionName}' has no type annotation. Add a type hint like '${parameterName}: str'.`,
+      { functionName, parameterName },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'FuncMissingTypeHintError';
+  }
+}
+
+export class FuncMissingReturnTypeError extends ModuleError {
+  constructor(functionName: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'FUNC_MISSING_RETURN_TYPE',
+      `Function '${functionName}' has no return type annotation. Add a return type like '-> dict'.`,
+      { functionName },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'FuncMissingReturnTypeError';
+  }
+}
+
+export class BindingInvalidTargetError extends ModuleError {
+  constructor(target: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'BINDING_INVALID_TARGET',
+      `Invalid binding target '${target}'. Expected format: 'module.path:callable_name'.`,
+      { target },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'BindingInvalidTargetError';
+  }
+}
+
+export class BindingModuleNotFoundError extends ModuleError {
+  constructor(modulePath: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'BINDING_MODULE_NOT_FOUND',
+      `Cannot import module '${modulePath}'.`,
+      { modulePath },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'BindingModuleNotFoundError';
+  }
+}
+
+export class BindingCallableNotFoundError extends ModuleError {
+  constructor(callableName: string, modulePath: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'BINDING_CALLABLE_NOT_FOUND',
+      `Cannot find callable '${callableName}' in module '${modulePath}'.`,
+      { callableName, modulePath },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'BindingCallableNotFoundError';
+  }
+}
+
+export class BindingNotCallableError extends ModuleError {
+  constructor(target: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'BINDING_NOT_CALLABLE',
+      `Resolved target '${target}' is not callable.`,
+      { target },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'BindingNotCallableError';
+  }
+}
+
+export class BindingSchemaMissingError extends ModuleError {
+  constructor(target: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'BINDING_SCHEMA_MISSING',
+      `No schema available for target '${target}'. Add type hints or provide an explicit schema.`,
+      { target },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'BindingSchemaMissingError';
+  }
+}
+
+export class BindingFileInvalidError extends ModuleError {
+  constructor(filePath: string, reason: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'BINDING_FILE_INVALID',
+      `Invalid binding file '${filePath}': ${reason}`,
+      { filePath, reason },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'BindingFileInvalidError';
+  }
+}
+
+export class CircularDependencyError extends ModuleError {
+  constructor(cyclePath: string[], options?: { cause?: Error; traceId?: string }) {
+    super(
+      'CIRCULAR_DEPENDENCY',
+      `Circular dependency detected: ${cyclePath.join(' -> ')}`,
+      { cyclePath },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'CircularDependencyError';
+  }
+}
+
+export class ModuleLoadError extends ModuleError {
+  constructor(moduleId: string, reason: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'MODULE_LOAD_ERROR',
+      `Failed to load module '${moduleId}': ${reason}`,
+      { moduleId, reason },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'ModuleLoadError';
+  }
+}

package/src/executor.ts

@@ -0,0 +1,348 @@
+/**
+ * Executor and related utilities for apcore.
+ *
+ * Async-only execution pipeline. Python's call() + call_async() merge into one async call().
+ * Timeout uses Promise.race instead of threading.
+ */
+
+import type { TSchema } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import type { ACL } from './acl.js';
+import type { Config } from './config.js';
+import { Context } from './context.js';
+import {
+  ACLDeniedError,
+  CallDepthExceededError,
+  CallFrequencyExceededError,
+  CircularCallError,
+  InvalidInputError,
+  ModuleNotFoundError,
+  ModuleTimeoutError,
+  SchemaValidationError,
+} from './errors.js';
+import { AfterMiddleware, BeforeMiddleware, Middleware } from './middleware/index.js';
+import { MiddlewareChainError, MiddlewareManager } from './middleware/manager.js';
+import type { ValidationResult } from './module.js';
+import type { Registry } from './registry/registry.js';
+
+export const REDACTED_VALUE: string = '***REDACTED***';
+
+export function redactSensitive(
+  data: Record<string, unknown>,
+  schemaDict: Record<string, unknown>,
+): Record<string, unknown> {
+  const redacted = JSON.parse(JSON.stringify(data));
+  redactFields(redacted, schemaDict);
+  redactSecretPrefix(redacted);
+  return redacted;
+}
+
+function redactFields(data: Record<string, unknown>, schemaDict: Record<string, unknown>): void {
+  const properties = schemaDict['properties'] as Record<string, Record<string, unknown>> | undefined;
+  if (!properties) return;
+
+  for (const [fieldName, fieldSchema] of Object.entries(properties)) {
+    if (!(fieldName in data)) continue;
+    const value = data[fieldName];
+
+    if (fieldSchema['x-sensitive'] === true) {
+      if (value !== null && value !== undefined) {
+        data[fieldName] = REDACTED_VALUE;
+      }
+      continue;
+    }
+
+    if (fieldSchema['type'] === 'object' && 'properties' in fieldSchema && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      redactFields(value as Record<string, unknown>, fieldSchema);
+      continue;
+    }
+
+    if (fieldSchema['type'] === 'array' && 'items' in fieldSchema && Array.isArray(value)) {
+      const itemsSchema = fieldSchema['items'] as Record<string, unknown>;
+      if (itemsSchema['x-sensitive'] === true) {
+        for (let i = 0; i < value.length; i++) {
+          if (value[i] !== null && value[i] !== undefined) {
+            value[i] = REDACTED_VALUE;
+          }
+        }
+      } else if (itemsSchema['type'] === 'object' && 'properties' in itemsSchema) {
+        for (const item of value) {
+          if (typeof item === 'object' && item !== null) {
+            redactFields(item as Record<string, unknown>, itemsSchema);
+          }
+        }
+      }
+    }
+  }
+}
+
+function redactSecretPrefix(data: Record<string, unknown>): void {
+  for (const key of Object.keys(data)) {
+    if (key.startsWith('_secret_') && data[key] !== null && data[key] !== undefined) {
+      data[key] = REDACTED_VALUE;
+    }
+  }
+}
+
+export class Executor {
+  private _registry: Registry;
+  private _middlewareManager: MiddlewareManager;
+  private _acl: ACL | null;
+  private _config: Config | null;
+  private _defaultTimeout: number;
+  private _globalTimeout: number;
+  private _maxCallDepth: number;
+  private _maxModuleRepeat: number;
+
+  constructor(options: {
+    registry: Registry;
+    middlewares?: Middleware[] | null;
+    acl?: ACL | null;
+    config?: Config | null;
+  }) {
+    this._registry = options.registry;
+    this._middlewareManager = new MiddlewareManager();
+    this._acl = options.acl ?? null;
+    this._config = options.config ?? null;
+
+    if (options.middlewares) {
+      for (const mw of options.middlewares) {
+        this._middlewareManager.add(mw);
+      }
+    }
+
+    if (this._config !== null) {
+      this._defaultTimeout = (this._config.get('executor.default_timeout') as number) ?? 30000;
+      this._globalTimeout = (this._config.get('executor.global_timeout') as number) ?? 60000;
+      this._maxCallDepth = (this._config.get('executor.max_call_depth') as number) ?? 32;
+      this._maxModuleRepeat = (this._config.get('executor.max_module_repeat') as number) ?? 3;
+    } else {
+      this._defaultTimeout = 30000;
+      this._globalTimeout = 60000;
+      this._maxCallDepth = 32;
+      this._maxModuleRepeat = 3;
+    }
+  }
+
+  get registry(): Registry {
+    return this._registry;
+  }
+
+  get middlewares(): Middleware[] {
+    return this._middlewareManager.snapshot();
+  }
+
+  use(middleware: Middleware): Executor {
+    this._middlewareManager.add(middleware);
+    return this;
+  }
+
+  useBefore(callback: (moduleId: string, inputs: Record<string, unknown>, context: Context) => Record<string, unknown> | null): Executor {
+    this._middlewareManager.add(new BeforeMiddleware(callback));
+    return this;
+  }
+
+  useAfter(callback: (moduleId: string, inputs: Record<string, unknown>, output: Record<string, unknown>, context: Context) => Record<string, unknown> | null): Executor {
+    this._middlewareManager.add(new AfterMiddleware(callback));
+    return this;
+  }
+
+  remove(middleware: Middleware): boolean {
+    return this._middlewareManager.remove(middleware);
+  }
+
+  async call(
+    moduleId: string,
+    inputs?: Record<string, unknown> | null,
+    context?: Context | null,
+  ): Promise<Record<string, unknown>> {
+    let effectiveInputs = inputs ?? {};
+
+    // Step 1 -- Context
+    let ctx: Context;
+    if (context == null) {
+      ctx = Context.create(this);
+      ctx = ctx.child(moduleId);
+    } else {
+      ctx = context.child(moduleId);
+    }
+
+    // Step 2 -- Safety Checks
+    this._checkSafety(moduleId, ctx);
+
+    // Step 3 -- Lookup
+    const module = this._registry.get(moduleId);
+    if (module === null) {
+      throw new ModuleNotFoundError(moduleId);
+    }
+
+    const mod = module as Record<string, unknown>;
+
+    // Step 4 -- ACL
+    if (this._acl !== null) {
+      const allowed = this._acl.check(ctx.callerId, moduleId, ctx);
+      if (!allowed) {
+        throw new ACLDeniedError(ctx.callerId, moduleId);
+      }
+    }
+
+    // Step 5 -- Input Validation and Redaction
+    const inputSchema = mod['inputSchema'] as TSchema | undefined;
+    if (inputSchema != null) {
+      if (!Value.Check(inputSchema, effectiveInputs)) {
+        const errors: Array<Record<string, unknown>> = [];
+        for (const error of Value.Errors(inputSchema, effectiveInputs)) {
+          errors.push({
+            field: error.path || '/',
+            code: String(error.type),
+            message: error.message,
+          });
+        }
+        throw new SchemaValidationError('Input validation failed', errors);
+      }
+
+      ctx.redactedInputs = redactSensitive(
+        effectiveInputs,
+        inputSchema as unknown as Record<string, unknown>,
+      );
+    }
+
+    let executedMiddlewares: Middleware[] = [];
+
+    try {
+      // Step 6 -- Middleware Before
+      try {
+        [effectiveInputs, executedMiddlewares] = this._middlewareManager.executeBefore(moduleId, effectiveInputs, ctx);
+      } catch (e) {
+        if (e instanceof MiddlewareChainError) {
+          executedMiddlewares = e.executedMiddlewares;
+          const recovery = this._middlewareManager.executeOnError(
+            moduleId, effectiveInputs, e.original, ctx, executedMiddlewares,
+          );
+          if (recovery !== null) return recovery;
+          executedMiddlewares = [];
+          throw e.original;
+        }
+        throw e;
+      }
+
+      // Step 7 -- Execute with timeout
+      let output = await this._executeWithTimeout(mod, moduleId, effectiveInputs, ctx);
+
+      // Step 8 -- Output Validation
+      const outputSchema = mod['outputSchema'] as TSchema | undefined;
+      if (outputSchema != null) {
+        if (!Value.Check(outputSchema, output)) {
+          const errors: Array<Record<string, unknown>> = [];
+          for (const error of Value.Errors(outputSchema, output)) {
+            errors.push({
+              field: error.path || '/',
+              code: String(error.type),
+              message: error.message,
+            });
+          }
+          throw new SchemaValidationError('Output validation failed', errors);
+        }
+      }
+
+      // Step 9 -- Middleware After
+      output = this._middlewareManager.executeAfter(moduleId, effectiveInputs, output, ctx);
+
+      // Step 10 -- Return
+      return output;
+    } catch (exc) {
+      if (executedMiddlewares.length > 0) {
+        const recovery = this._middlewareManager.executeOnError(
+          moduleId, effectiveInputs, exc as Error, ctx, executedMiddlewares,
+        );
+        if (recovery !== null) return recovery;
+      }
+      throw exc;
+    }
+  }
+
+  validate(moduleId: string, inputs: Record<string, unknown>): ValidationResult {
+    const module = this._registry.get(moduleId);
+    if (module === null) {
+      throw new ModuleNotFoundError(moduleId);
+    }
+
+    const mod = module as Record<string, unknown>;
+    const inputSchema = mod['inputSchema'] as TSchema | undefined;
+
+    if (inputSchema == null) {
+      return { valid: true, errors: [] };
+    }
+
+    if (Value.Check(inputSchema, inputs)) {
+      return { valid: true, errors: [] };
+    }
+
+    const errors: Array<Record<string, string>> = [];
+    for (const error of Value.Errors(inputSchema, inputs)) {
+      errors.push({
+        field: error.path || '/',
+        code: String(error.type),
+        message: error.message,
+      });
+    }
+    return { valid: false, errors };
+  }
+
+  private _checkSafety(moduleId: string, ctx: Context): void {
+    const callChain = ctx.callChain;
+
+    // Depth check
+    if (callChain.length > this._maxCallDepth) {
+      throw new CallDepthExceededError(callChain.length, this._maxCallDepth, [...callChain]);
+    }
+
+    // Circular detection (strict cycles of length >= 2)
+    const priorChain = callChain.slice(0, -1);
+    const lastIdx = priorChain.lastIndexOf(moduleId);
+    if (lastIdx !== -1) {
+      const subsequence = priorChain.slice(lastIdx + 1);
+      if (subsequence.length > 0) {
+        throw new CircularCallError(moduleId, [...callChain]);
+      }
+    }
+
+    // Frequency check
+    const count = callChain.filter((id) => id === moduleId).length;
+    if (count > this._maxModuleRepeat) {
+      throw new CallFrequencyExceededError(moduleId, count, this._maxModuleRepeat, [...callChain]);
+    }
+  }
+
+  private async _executeWithTimeout(
+    mod: Record<string, unknown>,
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    ctx: Context,
+  ): Promise<Record<string, unknown>> {
+    const timeoutMs = this._defaultTimeout;
+
+    if (timeoutMs < 0) {
+      throw new InvalidInputError(`Negative timeout: ${timeoutMs}ms`);
+    }
+
+    const executeFn = mod['execute'] as (
+      inputs: Record<string, unknown>,
+      context: Context,
+    ) => Promise<Record<string, unknown>> | Record<string, unknown>;
+
+    const executionPromise = Promise.resolve(executeFn.call(mod, inputs, ctx));
+
+    if (timeoutMs === 0) {
+      return executionPromise;
+    }
+
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => {
+        reject(new ModuleTimeoutError(moduleId, timeoutMs));
+      }, timeoutMs);
+    });
+
+    return Promise.race([executionPromise, timeoutPromise]);
+  }
+}