apcore-js 0.4.0 → 0.6.0

package/src/executor.ts

@@ -1,475 +0,0 @@
-/**
- * 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)) {
-    const value = data[key];
-    if (key.startsWith('_secret_') && value !== null && value !== undefined) {
-      data[key] = REDACTED_VALUE;
-    } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-      redactSecretPrefix(value as Record<string, unknown>);
-    }
-  }
-}
-
-export class Executor {
-  private _registry: Registry;
-  private _middlewareManager: MiddlewareManager;
-  private _acl: ACL | null;
-  private _config: Config | null;
-  private _defaultTimeout: 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._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._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 ?? {};
-    const ctx = this._createContext(moduleId, context);
-    this._checkSafety(moduleId, ctx);
-
-    const mod = this._lookupModule(moduleId);
-    this._checkAcl(moduleId, ctx);
-
-    effectiveInputs = this._validateInputs(mod, effectiveInputs, ctx);
-
-    return this._executeWithMiddleware(mod, moduleId, effectiveInputs, ctx);
-  }
-
-  /**
-   * Alias for call(). Provided for compatibility with MCP bridge packages
-   * that may call callAsync() by convention.
-   */
-  async callAsync(
-    moduleId: string,
-    inputs?: Record<string, unknown> | null,
-    context?: Context | null,
-  ): Promise<Record<string, unknown>> {
-    return this.call(moduleId, inputs, context);
-  }
-
-  /**
-   * Streaming execution pipeline. If the module exposes a stream() async generator,
-   * yields each chunk. Otherwise falls back to call() and yields a single chunk.
-   *
-   * Pipeline: context -> safety -> lookup -> ACL -> validate inputs -> before-middleware
-   *   -> stream (or fallback to execute) -> validate accumulated output -> after-middleware
-   *
-   * Note: In the streaming path, after-middleware runs on the accumulated output for
-   * validation/side-effects but its return value is not yielded since chunks were already
-   * emitted. In the non-streaming fallback, after-middleware can transform the output.
-   */
-  async *stream(
-    moduleId: string,
-    inputs?: Record<string, unknown> | null,
-    context?: Context | null,
-  ): AsyncGenerator<Record<string, unknown>> {
-    let effectiveInputs = inputs ?? {};
-    const ctx = this._createContext(moduleId, context);
-    this._checkSafety(moduleId, ctx);
-
-    const mod = this._lookupModule(moduleId);
-    this._checkAcl(moduleId, ctx);
-
-    effectiveInputs = this._validateInputs(mod, effectiveInputs, ctx);
-
-    yield* this._streamWithMiddleware(mod, moduleId, effectiveInputs, ctx);
-  }
-
-  private async *_streamWithMiddleware(
-    mod: Record<string, unknown>,
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    ctx: Context,
-  ): AsyncGenerator<Record<string, unknown>> {
-    let effectiveInputs = inputs;
-    let executedMiddlewares: Middleware[] = [];
-
-    try {
-      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) {
-            yield recovery;
-            return;
-          }
-          executedMiddlewares = [];
-          throw e.original;
-        }
-        throw e;
-      }
-
-      const streamFn = mod['stream'] as
-        | ((inputs: Record<string, unknown>, context: Context) => AsyncGenerator<Record<string, unknown>>)
-        | undefined;
-
-      if (typeof streamFn === 'function') {
-        // Module has a stream() method: iterate and yield each chunk
-        let accumulated: Record<string, unknown> = {};
-        for await (const chunk of streamFn.call(mod, effectiveInputs, ctx)) {
-          accumulated = { ...accumulated, ...chunk };
-          yield chunk;
-        }
-
-        // Validate accumulated output against output schema
-        this._validateOutput(mod, accumulated);
-
-        // Run after-middleware on the accumulated result
-        this._middlewareManager.executeAfter(moduleId, effectiveInputs, accumulated, ctx);
-      } else {
-        // Fallback: execute normally and yield single chunk
-        let output = await this._executeWithTimeout(mod, moduleId, effectiveInputs, ctx);
-        this._validateOutput(mod, output);
-        output = this._middlewareManager.executeAfter(moduleId, effectiveInputs, output, ctx);
-        yield output;
-      }
-    } catch (exc) {
-      if (executedMiddlewares.length > 0) {
-        const recovery = this._middlewareManager.executeOnError(
-          moduleId, effectiveInputs, exc as Error, ctx, executedMiddlewares,
-        );
-        if (recovery !== null) {
-          yield recovery;
-          return;
-        }
-      }
-      throw exc;
-    }
-  }
-
-  private _createContext(moduleId: string, context?: Context | null): Context {
-    if (context == null) {
-      return Context.create(this).child(moduleId);
-    }
-    return context.child(moduleId);
-  }
-
-  private _lookupModule(moduleId: string): Record<string, unknown> {
-    const module = this._registry.get(moduleId);
-    if (module === null) {
-      throw new ModuleNotFoundError(moduleId);
-    }
-    return module as Record<string, unknown>;
-  }
-
-  private _checkAcl(moduleId: string, ctx: Context): void {
-    if (this._acl !== null) {
-      const allowed = this._acl.check(ctx.callerId, moduleId, ctx);
-      if (!allowed) {
-        throw new ACLDeniedError(ctx.callerId, moduleId);
-      }
-    }
-  }
-
-  private _validateInputs(
-    mod: Record<string, unknown>,
-    inputs: Record<string, unknown>,
-    ctx: Context,
-  ): Record<string, unknown> {
-    const inputSchema = mod['inputSchema'] as TSchema | undefined;
-    if (inputSchema == null) return inputs;
-
-    this._validateSchema(inputSchema, inputs, 'Input');
-    ctx.redactedInputs = redactSensitive(
-      inputs,
-      inputSchema as unknown as Record<string, unknown>,
-    );
-    return inputs;
-  }
-
-  private _validateSchema(
-    schema: TSchema,
-    data: Record<string, unknown>,
-    direction: string,
-  ): void {
-    if (Value.Check(schema, data)) return;
-
-    const errors: Array<Record<string, unknown>> = [];
-    for (const error of Value.Errors(schema, data)) {
-      errors.push({
-        field: error.path || '/',
-        code: String(error.type),
-        message: error.message,
-      });
-    }
-    throw new SchemaValidationError(`${direction} validation failed`, errors);
-  }
-
-  private async _executeWithMiddleware(
-    mod: Record<string, unknown>,
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    ctx: Context,
-  ): Promise<Record<string, unknown>> {
-    let effectiveInputs = inputs;
-    let executedMiddlewares: Middleware[] = [];
-
-    try {
-      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;
-      }
-
-      let output = await this._executeWithTimeout(mod, moduleId, effectiveInputs, ctx);
-
-      this._validateOutput(mod, output);
-
-      output = this._middlewareManager.executeAfter(moduleId, effectiveInputs, output, ctx);
-      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;
-    }
-  }
-
-  private _validateOutput(mod: Record<string, unknown>, output: Record<string, unknown>): void {
-    const outputSchema = mod['outputSchema'] as TSchema | undefined;
-    if (outputSchema != null) {
-      this._validateSchema(outputSchema, output, 'Output');
-    }
-  }
-
-  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'];
-    if (typeof executeFn !== 'function') {
-      throw new InvalidInputError(`Module '${moduleId}' has no execute method`);
-    }
-
-    const executionPromise = Promise.resolve(
-      (executeFn as (inputs: Record<string, unknown>, context: Context) => Promise<Record<string, unknown>> | Record<string, unknown>)
-        .call(mod, inputs, ctx),
-    );
-
-    if (timeoutMs === 0) {
-      console.warn('[apcore:executor] Timeout is 0, timeout limit disabled');
-      return executionPromise;
-    }
-
-    let timer: ReturnType<typeof setTimeout>;
-    const timeoutPromise = new Promise<never>((_, reject) => {
-      timer = setTimeout(() => {
-        reject(new ModuleTimeoutError(moduleId, timeoutMs));
-      }, timeoutMs);
-    });
-
-    return Promise.race([executionPromise, timeoutPromise]).finally(() => {
-      clearTimeout(timer);
-    });
-  }
-}

package/src/middleware/adapters.ts

@@ -1,54 +0,0 @@
-/**
- * Function adapter classes for the middleware system.
- */
-
-import type { Context } from '../context.js';
-import { Middleware } from './base.js';
-
-export type BeforeCallback = (
-  moduleId: string,
-  inputs: Record<string, unknown>,
-  context: Context,
-) => Record<string, unknown> | null;
-
-export type AfterCallback = (
-  moduleId: string,
-  inputs: Record<string, unknown>,
-  output: Record<string, unknown>,
-  context: Context,
-) => Record<string, unknown> | null;
-
-export class BeforeMiddleware extends Middleware {
-  private _callback: BeforeCallback;
-
-  constructor(callback: BeforeCallback) {
-    super();
-    this._callback = callback;
-  }
-
-  override before(
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    context: Context,
-  ): Record<string, unknown> | null {
-    return this._callback(moduleId, inputs, context);
-  }
-}
-
-export class AfterMiddleware extends Middleware {
-  private _callback: AfterCallback;
-
-  constructor(callback: AfterCallback) {
-    super();
-    this._callback = callback;
-  }
-
-  override after(
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    output: Record<string, unknown>,
-    context: Context,
-  ): Record<string, unknown> | null {
-    return this._callback(moduleId, inputs, output, context);
-  }
-}

package/src/middleware/base.ts

@@ -1,33 +0,0 @@
-/**
- * Middleware base class for apcore.
- */
-
-import type { Context } from '../context.js';
-
-export class Middleware {
-  before(
-    _moduleId: string,
-    _inputs: Record<string, unknown>,
-    _context: Context,
-  ): Record<string, unknown> | null {
-    return null;
-  }
-
-  after(
-    _moduleId: string,
-    _inputs: Record<string, unknown>,
-    _output: Record<string, unknown>,
-    _context: Context,
-  ): Record<string, unknown> | null {
-    return null;
-  }
-
-  onError(
-    _moduleId: string,
-    _inputs: Record<string, unknown>,
-    _error: Error,
-    _context: Context,
-  ): Record<string, unknown> | null {
-    return null;
-  }
-}

package/src/middleware/logging.ts

@@ -1,103 +0,0 @@
-/**
- * LoggingMiddleware for structured module call logging.
- */
-
-import type { Context } from '../context.js';
-import { Middleware } from './base.js';
-
-export interface Logger {
-  info(message: string, extra?: Record<string, unknown>): void;
-  error(message: string, extra?: Record<string, unknown>): void;
-}
-
-const defaultLogger: Logger = {
-  info(message: string, extra?: Record<string, unknown>) {
-    console.info(message, extra ?? '');
-  },
-  error(message: string, extra?: Record<string, unknown>) {
-    console.error(message, extra ?? '');
-  },
-};
-
-export class LoggingMiddleware extends Middleware {
-  private _logger: Logger;
-  private _logInputs: boolean;
-  private _logOutputs: boolean;
-  private _logErrors: boolean;
-
-  constructor(options?: {
-    logger?: Logger;
-    logInputs?: boolean;
-    logOutputs?: boolean;
-    logErrors?: boolean;
-  }) {
-    super();
-    this._logger = options?.logger ?? defaultLogger;
-    this._logInputs = options?.logInputs ?? true;
-    this._logOutputs = options?.logOutputs ?? true;
-    this._logErrors = options?.logErrors ?? true;
-  }
-
-  override before(
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    context: Context,
-  ): null {
-    context.data['_logging_mw_start'] = performance.now();
-
-    if (this._logInputs) {
-      const redacted = context.redactedInputs ?? inputs;
-      this._logger.info(`[${context.traceId}] START ${moduleId}`, {
-        traceId: context.traceId,
-        moduleId,
-        callerId: context.callerId,
-        inputs: redacted,
-      });
-    }
-
-    return null;
-  }
-
-  override after(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    output: Record<string, unknown>,
-    context: Context,
-  ): null {
-    const startTime = (context.data['_logging_mw_start'] as number) ?? performance.now();
-    const durationMs = performance.now() - startTime;
-
-    if (this._logOutputs) {
-      this._logger.info(
-        `[${context.traceId}] END ${moduleId} (${durationMs.toFixed(2)}ms)`,
-        {
-          traceId: context.traceId,
-          moduleId,
-          durationMs,
-          output,
-        },
-      );
-    }
-
-    return null;
-  }
-
-  override onError(
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    error: Error,
-    context: Context,
-  ): null {
-    if (this._logErrors) {
-      const redacted = context.redactedInputs ?? inputs;
-      this._logger.error(`[${context.traceId}] ERROR ${moduleId}: ${error}`, {
-        traceId: context.traceId,
-        moduleId,
-        error: String(error),
-        inputs: redacted,
-      });
-    }
-
-    return null;
-  }
-}