gthinking 1.3.0 → 2.1.1

package/src/core/pipeline.ts

@@ -0,0 +1,424 @@
+/**
+ * Dynamic Pipeline for GThinking
+ * 
+ * Implements a configurable pipeline system that supports parallel
+ * execution, dependency management, and error recovery.
+ * 
+ * @module core/pipeline
+ */
+
+import { EventEmitter } from 'eventemitter3';
+import type { 
+  ThinkingStage, 
+  StageResult, 
+  StreamChunk,
+} from '../types/core';
+import type { PipelineConfig } from './config';
+import { StageError, TimeoutError } from './errors';
+import { logger, createComponentLogger, Timer } from '../utils';
+
+/**
+ * Stage executor function type
+ */
+export type StageExecutor<TInput = unknown, TOutput = unknown> = (
+  input: TInput,
+  context: PipelineContext
+) => Promise<TOutput>;
+
+/**
+ * Pipeline context passed to each stage
+ */
+export interface PipelineContext {
+  stage: ThinkingStage;
+  requestId: string;
+  sessionId: string;
+  previousResults: Map<ThinkingStage, StageResult>;
+  abortSignal: AbortSignal;
+}
+
+/**
+ * Pipeline stage definition
+ */
+export interface PipelineStageDefinition {
+  stage: ThinkingStage;
+  executor: StageExecutor;
+  enabled: boolean;
+  parallel: boolean;
+  dependencies: ThinkingStage[];
+  timeoutMs: number;
+  retryCount: number;
+  skipOnError: boolean;
+}
+
+/**
+ * Pipeline events
+ */
+export interface PipelineEvents {
+  'stage:start': { stage: ThinkingStage; requestId: string };
+  'stage:complete': { stage: ThinkingStage; result: StageResult; requestId: string };
+  'stage:error': { stage: ThinkingStage; error: Error; requestId: string };
+  'stage:retry': { stage: ThinkingStage; attempt: number; requestId: string };
+  'pipeline:complete': { results: StageResult[]; requestId: string; durationMs: number };
+  'pipeline:error': { error: Error; requestId: string };
+  'chunk': { chunk: StreamChunk; requestId: string };
+}
+
+/**
+ * Dynamic pipeline implementation
+ */
+export class DynamicPipeline extends EventEmitter<PipelineEvents> {
+  private readonly stages: Map<ThinkingStage, PipelineStageDefinition> = new Map();
+  private readonly config: PipelineConfig;
+  private readonly logger = createComponentLogger('Pipeline');
+
+  constructor(config: PipelineConfig) {
+    super();
+    this.config = config;
+    this.validateConfig();
+  }
+
+  /**
+   * Register a stage executor
+   */
+  registerStage(
+    stage: ThinkingStage,
+    executor: StageExecutor,
+    options: Partial<Omit<PipelineStageDefinition, 'stage' | 'executor'>> = {}
+  ): void {
+    const stageConfig = (this.config.stages as any)[stage];
+    
+    this.stages.set(stage, {
+      stage,
+      executor,
+      enabled: options.enabled ?? stageConfig?.enabled ?? true,
+      parallel: options.parallel ?? stageConfig?.parallel ?? false,
+      dependencies: options.dependencies ?? stageConfig?.dependencies ?? [],
+      timeoutMs: options.timeoutMs ?? stageConfig?.timeoutMs ?? 30000,
+      retryCount: options.retryCount ?? stageConfig?.retryCount ?? 0,
+      skipOnError: options.skipOnError ?? stageConfig?.skipOnError ?? false,
+    });
+
+    this.logger.debug('Stage registered', { stage, enabled: this.stages.get(stage)?.enabled });
+  }
+
+  /**
+   * Execute the pipeline
+   */
+  async execute<TInput>(
+    input: TInput,
+    requestId: string,
+    sessionId: string,
+    streamResults = false
+  ): Promise<StageResult[]> {
+    const timer = new Timer();
+    const results: Map<ThinkingStage, StageResult> = new Map();
+    const abortController = new AbortController();
+    
+    // Set global timeout if configured
+    let globalTimeoutId: NodeJS.Timeout | null = null;
+    if (this.config.defaultTimeout !== undefined) {
+      globalTimeoutId = setTimeout(() => {
+        abortController.abort(new TimeoutError('Pipeline global timeout exceeded', this.config.defaultTimeout as any));
+      }, this.config.defaultTimeout);
+    }
+
+    try {
+      // Get execution order based on dependencies
+      const executionOrder = this.getExecutionOrder();
+      
+      for (const stageGroup of executionOrder) {
+        // Check if aborted
+        if (abortController.signal.aborted) {
+          throw abortController.signal.reason;
+        }
+
+        if (stageGroup.length === 1) {
+          // Sequential execution
+          const stage = stageGroup[0]!;
+          const result = await this.executeStage(
+            stage,
+            input,
+            requestId,
+            sessionId,
+            results,
+            abortController.signal,
+            streamResults
+          );
+          results.set(stage, result);
+          
+          // Handle error based on configuration
+          if (result.status === 'failed' && !this.stages.get(stage)?.skipOnError) {
+            if (this.config.errorHandling === 'stop') {
+              throw new StageError(
+                `Stage ${stage} failed: ${result.error?.message}`,
+                stage,
+                false
+              );
+            }
+          }
+        } else {
+          // Parallel execution
+          const parallelResults = await Promise.all(
+            stageGroup.map(stage =>
+              this.executeStage(
+                stage,
+                input,
+                requestId,
+                sessionId,
+                results,
+                abortController.signal,
+                streamResults
+              )
+            )
+          );
+          
+          for (const result of parallelResults) {
+            results.set(result.stage, result);
+          }
+        }
+      }
+
+      const stageResults = Array.from(results.values());
+      const durationMs = timer.elapsed();
+      
+      this.emit('pipeline:complete', { results: stageResults, requestId, durationMs });
+      
+      return stageResults;
+    } catch (error) {
+      this.emit('pipeline:error', { error: error as Error, requestId });
+      throw error;
+    } finally {
+      if (globalTimeoutId !== null) {
+        clearTimeout(globalTimeoutId);
+      }
+    }
+  }
+
+  /**
+   * Execute a single stage
+   */
+  private async executeStage<TInput>(
+    stage: ThinkingStage,
+    input: TInput,
+    requestId: string,
+    sessionId: string,
+    previousResults: Map<ThinkingStage, StageResult>,
+    abortSignal: AbortSignal,
+    streamResults: boolean
+  ): Promise<StageResult> {
+    const stageDef = this.stages.get(stage);
+    
+    if (stageDef === undefined) {
+      return {
+        stage,
+        status: 'skipped',
+        timestamp: new Date(),
+        data: null,
+      };
+    }
+
+    if (!stageDef.enabled) {
+      return {
+        stage,
+        status: 'skipped',
+        timestamp: new Date(),
+        data: null,
+      };
+    }
+
+    // Check dependencies
+    for (const dep of stageDef.dependencies) {
+      const depResult = previousResults.get(dep);
+      if (depResult?.status === 'failed' && !stageDef.skipOnError) {
+        return {
+          stage,
+          status: 'skipped',
+          error: new Error(`Dependency stage ${dep} failed`),
+          timestamp: new Date(),
+          data: null,
+        };
+      }
+    }
+
+    // Emit stage start
+    this.emit('stage:start', { stage, requestId });
+    if (streamResults) {
+      this.emit('chunk', {
+        chunk: { type: 'stage_start', stage, timestamp: Date.now() },
+        requestId,
+      });
+    }
+
+    const timer = new Timer();
+    let lastError: Error | undefined;
+
+    // Retry loop
+    for (let attempt = 0; attempt <= stageDef.retryCount; attempt++) {
+      try {
+        if (attempt > 0) {
+          this.emit('stage:retry', { stage, attempt, requestId });
+        }
+
+        const context: PipelineContext = {
+          stage,
+          requestId,
+          sessionId,
+          previousResults,
+          abortSignal,
+        };
+
+        // Execute with timeout
+        const output = await this.executeWithTimeout(
+          () => stageDef.executor(input, context),
+          stageDef.timeoutMs
+        );
+
+        const result: StageResult = {
+          stage,
+          status: 'completed',
+          data: output,
+          duration: timer.elapsed(),
+          timestamp: new Date(),
+        };
+
+        this.emit('stage:complete', { stage, result, requestId });
+        if (streamResults) {
+          this.emit('chunk', {
+            chunk: { type: 'stage_complete', stage, data: output, timestamp: Date.now() },
+            requestId,
+          });
+        }
+
+        return result;
+      } catch (error) {
+        lastError = error as Error;
+        this.logger.warn(`Stage ${stage} attempt ${attempt + 1} failed`, {
+          stage,
+          attempt,
+          error: lastError.message,
+        });
+      }
+    }
+
+    // All retries exhausted
+    const failedResult: StageResult = {
+      stage,
+      status: 'failed',
+      error: lastError,
+      duration: timer.elapsed(),
+      timestamp: new Date(),
+      data: null,
+    };
+          this.emit('stage:error', { stage, error: lastError!, requestId });
+    if (streamResults) {
+      this.emit('chunk', {
+        chunk: { type: 'error', stage, data: lastError?.message, timestamp: Date.now() },
+        requestId,
+      });
+    }
+
+    return failedResult;
+  }
+
+  /**
+   * Execute a function with timeout
+   */
+  private async executeWithTimeout<T>(
+    fn: () => Promise<T>,
+    timeoutMs: number
+  ): Promise<T> {
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        reject(new TimeoutError(`Operation timed out after ${timeoutMs}ms`, timeoutMs as any));
+      }, timeoutMs);
+
+      fn()
+        .then(resolve)
+        .catch(reject)
+        .finally(() => clearTimeout(timeoutId));
+    });
+  }
+
+  /**
+   * Get execution order based on dependencies
+   */
+  private getExecutionOrder(): ThinkingStage[][] {
+    const visited = new Set<ThinkingStage>();
+    const order: ThinkingStage[][] = [];
+    const stages = Array.from(this.stages.entries())
+      .filter(([, def]) => def.enabled)
+      .map(([stage]) => stage);
+
+    while (visited.size < stages.length) {
+      const group: ThinkingStage[] = [];
+      
+      for (const stage of stages) {
+        if (visited.has(stage)) continue;
+        
+        const stageDef = this.stages.get(stage);
+        if (stageDef === undefined) continue;
+        
+        // Check if all dependencies are visited
+        const depsSatisfied = stageDef.dependencies.every(dep => visited.has(dep));
+        
+        if (depsSatisfied) {
+          group.push(stage);
+        }
+      }
+      
+      if (group.length === 0) {
+        // Circular dependency detected
+        throw new StageError('Circular dependency detected in pipeline', stages[0]!, false);
+      }
+      
+      for (const stage of group) {
+        visited.add(stage);
+      }
+      
+      order.push(group);
+    }
+
+    return order;
+  }
+
+  /**
+   * Validate pipeline configuration
+   */
+  private validateConfig(): void {
+    const stageNames = Object.keys(this.config.stages);
+    const uniqueStages = new Set(stageNames);
+    
+    if (stageNames.length !== uniqueStages.size) {
+      throw new StageError('Duplicate stages in pipeline configuration', 'search' as any, false);
+    }
+  }
+
+  /**
+   * Enable a stage
+   */
+  enableStage(stage: ThinkingStage): void {
+    const stageDef = this.stages.get(stage);
+    if (stageDef !== undefined) {
+      stageDef.enabled = true;
+    }
+  }
+
+  /**
+   * Disable a stage
+   */
+  disableStage(stage: ThinkingStage): void {
+    const stageDef = this.stages.get(stage);
+    if (stageDef !== undefined) {
+      stageDef.enabled = false;
+    }
+  }
+
+  /**
+   * Get enabled stages
+   */
+  getEnabledStages(): ThinkingStage[] {
+    return Array.from(this.stages.entries())
+      .filter(([, def]) => def.enabled)
+      .map(([stage]) => stage);
+  }
+}

package/src/core/rate-limiter.ts

@@ -0,0 +1,155 @@
+/**
+ * Rate Limiter for GThinking
+ * 
+ * Implements token bucket algorithm for rate limiting with
+ * support for burst handling and per-session tracking.
+ * 
+ * @module core/rate-limiter
+ */
+
+import { RateLimiterRes, RateLimiterMemory } from 'rate-limiter-flexible';
+import type { EngineConfig } from '../types/core';
+import { logger } from '../utils/logger';
+
+/**
+ * Rate limit check result
+ */
+export interface RateLimitResult {
+  allowed: boolean;
+  remainingPoints?: number;
+  msBeforeNext?: number;
+  retryAfterMs?: number;
+}
+
+/**
+ * Rate limiter implementation
+ */
+export class RateLimiter {
+  private readonly limiter: RateLimiterMemory;
+  private readonly enabled: boolean;
+
+  constructor(config: Pick<EngineConfig, 'rateLimitEnabled' | 'rateLimitRequestsPerMinute' | 'rateLimitBurstSize'>) {
+    this.enabled = config.rateLimitEnabled;
+    
+    // Convert requests per minute to points per second
+    const points = config.rateLimitRequestsPerMinute;
+    const duration = 60; // seconds
+
+    this.limiter = new RateLimiterMemory({
+      keyPrefix: 'gthinking',
+      points,
+      duration,
+    });
+
+    logger.info('Rate limiter initialized', {
+      enabled: this.enabled,
+      pointsPerMinute: points,
+    });
+  }
+
+  /**
+   * Check if a request is allowed
+   * 
+   * @param key - Rate limit key (e.g., session ID or IP)
+   * @param points - Points to consume (default: 1)
+   * @returns Rate limit check result
+   */
+  async checkLimit(key: string, points = 1): Promise<RateLimitResult> {
+    if (!this.enabled) {
+      return { allowed: true };
+    }
+
+    try {
+      const result = await this.limiter.consume(key, points);
+      
+      return {
+        allowed: true,
+        remainingPoints: result.remainingPoints,
+        msBeforeNext: result.msBeforeNext,
+      };
+    } catch (rejRes) {
+      if (rejRes instanceof RateLimiterRes) {
+        return {
+          allowed: false,
+          msBeforeNext: rejRes.msBeforeNext,
+          retryAfterMs: rejRes.msBeforeNext,
+        };
+      }
+      
+      // Unexpected error, allow request but log
+      logger.error('Rate limiter error', { error: String(rejRes) });
+      return { allowed: true };
+    }
+  }
+
+  /**
+   * Get current rate limit status without consuming points
+   * 
+   * @param key - Rate limit key
+   * @returns Current status
+   */
+  async getStatus(key: string): Promise<{ remainingPoints: number; resetTime: Date } | null> {
+    if (!this.enabled) {
+      return null;
+    }
+
+    try {
+      const result = await this.limiter.get(key);
+      
+      if (result === null) {
+        return null;
+      }
+
+      return {
+        remainingPoints: result.remainingPoints,
+        resetTime: new Date(Date.now() + result.msBeforeNext),
+      };
+    } catch (error) {
+      logger.error('Rate limiter getStatus error', { error: String(error) });
+      return null;
+    }
+  }
+
+  /**
+   * Reset rate limit for a key
+   * 
+   * @param key - Rate limit key
+   */
+  async reset(key: string): Promise<void> {
+    if (!this.enabled) {
+      return;
+    }
+
+    try {
+      await this.limiter.delete(key);
+      logger.debug('Rate limit reset', { key });
+    } catch (error) {
+      logger.error('Rate limiter reset error', { error: String(error) });
+    }
+  }
+
+  /**
+   * Block a key for a specific duration
+   * 
+   * @param key - Rate limit key
+   * @param durationMs - Block duration in milliseconds
+   */
+  async block(key: string, durationMs: number): Promise<void> {
+    if (!this.enabled) {
+      return;
+    }
+
+    try {
+      // Consume all points to block
+      const points = await this.limiter.get(key);
+      const pointsToConsume = points?.remainingPoints ?? 100;
+      
+      await this.limiter.consume(key, pointsToConsume);
+      
+      // Penalty will last for the specified duration
+      logger.info('Key blocked', { key, durationMs });
+    } catch (error) {
+      logger.error('Rate limiter block error', { error: String(error) });
+    }
+  }
+}