@gati-framework/runtime/dist/hook-orchestrator.d.ts

Gati runtime execution engine for running handler-based applications

/**
 * @module runtime/hook-orchestrator
 * @description Hook orchestration system for request lifecycle management
 *
 * Implements Task 5: LCC Lifecycle Orchestration
 * - Executes hooks in correct order (global → route → local)
 * - Supports async hooks with timeout and retry
 * - Emits lifecycle events for observability
 * - Integrates request/response validation
 */
import type { LocalContext, GlobalContext } from './types/context.js';
import type { Request } from './types/index.js';
import type { GType } from './gtype/index.js';
import { HookPlayback } from './playground/hook-playback.js';
/**
 * Hook function signature
 */
export type HookFunction = (lctx: LocalContext, gctx: GlobalContext) => void | Promise<void>;
/**
 * Hook with metadata
 */
export interface Hook {
    /**
     * Unique hook identifier
     */
    id: string;
    /**
     * Hook function
     */
    fn: HookFunction;
    /**
     * Hook level (global, route, local)
     */
    level: 'global' | 'route' | 'local';
    /**
     * Timeout in milliseconds
     */
    timeout?: number;
    /**
     * Number of retries on failure
     */
    retries?: number;
    /**
     * Whether hook is async
     */
    async: boolean;
}
/**
 * Lifecycle event types
 */
export type LifecycleEventType = 'hook:start' | 'hook:end' | 'hook:error' | 'hook:retry' | 'handler:start' | 'handler:end' | 'handler:error' | 'validation:start' | 'validation:end' | 'validation:error' | 'compensation:start' | 'compensation:end' | 'compensation:error' | 'compensation:alert';
/**
 * Lifecycle event
 */
export interface LifecycleEvent {
    type: LifecycleEventType;
    timestamp: number;
    requestId: string;
    hookId?: string;
    error?: Error;
    duration?: number;
    metadata?: Record<string, unknown>;
}
/**
 * Compensating action function signature
 */
export type CompensatingAction = () => void | Promise<void>;
/**
 * Compensating action with metadata
 */
export interface CompensatingActionEntry {
    /**
     * Unique action identifier
     */
    id: string;
    /**
     * Compensating action function
     */
    action: CompensatingAction;
    /**
     * Timestamp when action was registered
     */
    registeredAt: number;
}
/**
 * Hook orchestrator configuration
 */
export interface HookOrchestratorConfig {
    /**
     * Default timeout for hooks (ms)
     */
    defaultTimeout?: number;
    /**
     * Default number of retries
     */
    defaultRetries?: number;
    /**
     * Whether to emit lifecycle events
     */
    emitEvents?: boolean;
    /**
     * Event handler
     */
    onEvent?: (event: LifecycleEvent) => void;
    /**
     * Alert handler for compensating action failures
     */
    onAlert?: (message: string, error: Error, metadata?: Record<string, unknown>) => void;
}
/**
 * Hook orchestrator for managing request lifecycle
 */
export declare class HookOrchestrator {
    private beforeHooks;
    private afterHooks;
    private catchHooks;
    private compensatingActions;
    private config;
    private playback;
    constructor(config?: HookOrchestratorConfig);
    /**
     * Enable hook playback recording
     */
    enablePlayback(): HookPlayback;
    /**
     * Disable hook playback recording
     */
    disablePlayback(): void;
    /**
     * Get playback instance
     */
    getPlayback(): HookPlayback | null;
    /**
     * Register a before hook
     */
    registerBefore(hook: Omit<Hook, 'async'>): void;
    /**
     * Register an after hook
     */
    registerAfter(hook: Omit<Hook, 'async'>): void;
    /**
     * Register a catch hook
     */
    registerCatch(hook: Omit<Hook, 'async'>): void;
    /**
     * Execute before hooks
     */
    executeBefore(lctx: LocalContext, gctx: GlobalContext): Promise<void>;
    /**
     * Execute after hooks
     */
    executeAfter(lctx: LocalContext, gctx: GlobalContext): Promise<void>;
    /**
     * Execute catch hooks
     */
    executeCatch(error: Error, lctx: LocalContext, gctx: GlobalContext): Promise<void>;
    /**
     * Register a compensating action
     * Compensating actions are executed in reverse order when an error occurs
     */
    registerCompensatingAction(action: CompensatingAction, id?: string): void;
    /**
     * Execute all compensating actions in reverse order
     */
    executeCompensatingActions(lctx: LocalContext): Promise<void>;
    /**
     * Clear all compensating actions without executing them
     */
    clearCompensatingActions(): void;
    /**
     * Get all registered compensating actions
     */
    getCompensatingActions(): CompensatingActionEntry[];
    /**
     * Validate request against schema
     */
    validateRequest(req: Request, schema: GType, lctx: LocalContext): void;
    /**
     * Validate response against schema
     */
    validateResponse(data: unknown, schema: GType, lctx: LocalContext): void;
    /**
     * Execute a single hook with timeout and retry
     */
    private executeHook;
    /**
     * Execute function with timeout
     */
    private executeWithTimeout;
    /**
     * Check if function is async
     */
    private isAsync;
    /**
     * Sort hooks by level
     */
    private sortHooks;
    /**
     * Emit lifecycle event
     */
    private emitEvent;
    /**
     * Get hook type from hook arrays
     */
    private getHookType;
    /**
     * Get all registered hooks
     */
    getHooks(): {
        before: Hook[];
        after: Hook[];
        catch: Hook[];
    };
    /**
     * Clear all hooks and compensating actions
     */
    clear(): void;
}
//# sourceMappingURL=hook-orchestrator.d.ts.map