@gati-framework/runtime/dist/enhanced-route-manager.d.ts

Gati runtime execution engine for running handler-based applications

/**
 * @module runtime/enhanced-route-manager
 * @description Enhanced Route Manager with version resolution and Timescape integration
 *
 * This implements Task 9 from the runtime architecture spec:
 * - Version resolution using Timescape
 * - Manifest, GType, and health status caching
 * - Handler instance selection and routing
 * - Policy enforcement (rate limiting, authentication)
 * - Warm pool management
 * - Usage tracking for auto-decommissioning
 */
import type { Handler } from './types/handler.js';
import type { HttpMethod } from './types/request.js';
import type { TSV } from './timescape/types.js';
import { VersionRegistry } from './timescape/registry.js';
import { VersionResolver } from './timescape/resolver.js';
import { TransformerEngine, type TransformerPair, type TransformResult } from './timescape/transformer.js';
/**
 * Handler manifest containing metadata and policies
 */
export interface HandlerManifest {
    handlerId: string;
    path: string;
    method: HttpMethod | HttpMethod[];
    version: TSV;
    gtypes: {
        request?: string;
        response?: string;
        params?: string;
        headers?: string;
    };
    hooks?: {
        before?: string[];
        after?: string[];
        catch?: string[];
    };
    policies?: {
        roles?: string[];
        rateLimit?: {
            limit: number;
            window: number;
        };
    };
    dependencies?: {
        modules?: string[];
        plugins?: string[];
    };
    hash: string;
}
/**
 * Handler instance representing a deployed handler version
 */
export interface HandlerInstance {
    id: string;
    handlerId: string;
    version: TSV;
    handler: Handler;
    manifest: HandlerManifest;
    health: HealthStatus;
    createdAt: number;
    lastAccessed: number;
}
/**
 * Health status for handler instances
 */
export interface HealthStatus {
    status: 'healthy' | 'degraded' | 'unhealthy';
    lastCheck: number;
    consecutiveFailures: number;
    message?: string;
}
/**
 * Authentication context for policy enforcement
 */
export interface AuthContext {
    userId?: string;
    roles: string[];
    token?: string;
}
/**
 * Request descriptor for routing
 */
export interface RequestDescriptor {
    requestId: string;
    path: string;
    method: HttpMethod;
    headers: Record<string, string | string[] | undefined>;
    query: Record<string, string | string[] | undefined>;
    body?: unknown;
    authContext?: AuthContext;
    clientId: string;
}
/**
 * Routing result
 */
export interface RoutingResult {
    instance: HandlerInstance;
    manifest: HandlerManifest;
    version: TSV;
    cached: boolean;
    transformedRequest?: TransformResult;
    requiresResponseTransform?: boolean;
    originalVersion?: TSV;
}
/**
 * Routing error
 */
export interface RoutingError {
    code: 'NO_HANDLER' | 'NO_VERSION' | 'RATE_LIMITED' | 'UNAUTHORIZED' | 'UNHEALTHY';
    message: string;
    details?: unknown;
}
/**
 * Warm pool configuration
 */
export interface WarmPoolConfig {
    minInstances: number;
    maxInstances: number;
    targetUtilization: number;
}
/**
 * Usage metrics for tracking
 */
export interface UsageMetrics {
    requestCount: number;
    errorCount: number;
    avgLatency: number;
    lastAccessed: number;
}
/**
 * Enhanced Route Manager with version resolution and Timescape integration
 */
export declare class EnhancedRouteManager {
    private registry;
    private resolver;
    private transformerEngine;
    private instances;
    private manifestCache;
    private gtypeCache;
    private healthCache;
    private rateLimitState;
    private warmPools;
    private usageMetrics;
    private readonly maxCacheSize;
    private readonly healthCheckInterval;
    private readonly rateLimitCleanupInterval;
    constructor(registry?: VersionRegistry, transformerEngine?: TransformerEngine);
    /**
     * Register a handler instance
     */
    registerHandler(path: string, version: TSV, handler: Handler, manifest: HandlerManifest): void;
    /**
     * Resolve handler version using Timescape
     */
    resolveVersion(path: string, query?: Record<string, string | string[] | undefined>, headers?: Record<string, string | string[] | undefined>): TSV | RoutingError;
    /**
     * Route a request to the appropriate handler instance
     */
    routeRequest(descriptor: RequestDescriptor): Promise<RoutingResult | RoutingError>;
    /**
     * Enforce rate limiting policies
     */
    enforceRateLimit(manifest: HandlerManifest, clientId: string): RoutingError | null;
    /**
     * Verify authentication requirements
     */
    verifyAuthentication(manifest: HandlerManifest, authContext?: AuthContext): RoutingError | null;
    /**
     * Get handler instance
     */
    private getInstance;
    /**
     * Cache manifest
     */
    private cacheManifest;
    /**
     * Get cached manifest
     */
    getManifest(handlerId: string): HandlerManifest | undefined;
    /**
     * Cache GType schema
     */
    cacheGType(ref: string, schema: unknown): void;
    /**
     * Get cached GType schema
     */
    getGType(ref: string): unknown | undefined;
    /**
     * Maintain warm pool for critical versions
     */
    maintainWarmPool(handlerId: string, config: WarmPoolConfig): void;
    /**
     * Get warm pool configuration
     */
    getWarmPoolConfig(handlerId: string): WarmPoolConfig | undefined;
    /**
     * Track usage metrics
     */
    trackUsage(instanceId: string, metrics: Partial<UsageMetrics>): void;
    /**
     * Get usage metrics
     */
    getUsageMetrics(instanceId: string): UsageMetrics | undefined;
    /**
     * Get all instances for a path
     */
    getInstances(path: string): HandlerInstance[];
    /**
     * Get all registered paths
     */
    getPaths(): string[];
    /**
     * Update health status
     */
    updateHealth(path: string, version: TSV, health: HealthStatus): void;
    /**
     * Get health status
     */
    getHealth(path: string, version: TSV): HealthStatus | undefined;
    /**
     * Start health check loop
     */
    private startHealthCheckLoop;
    /**
     * Perform health checks on all instances
     */
    private performHealthChecks;
    /**
     * Start rate limit cleanup
     */
    private startRateLimitCleanup;
    /**
     * Clean up expired rate limit entries
     */
    private cleanupRateLimits;
    /**
     * Get registry for external access
     */
    getRegistry(): VersionRegistry;
    /**
     * Get resolver for external access
     */
    getResolver(): VersionResolver;
    /**
     * Clear all caches
     */
    clearCaches(): void;
    /**
     * Get cache statistics
     */
    getCacheStats(): {
        manifests: number;
        gtypes: number;
        health: number;
        rateLimits: number;
    };
    /**
     * Register a transformer pair
     */
    registerTransformer(transformer: TransformerPair): void;
    /**
     * Get transformer between two versions
     */
    getTransformer(from: TSV, to: TSV): TransformerPair | undefined;
    /**
     * Check if transformer exists
     */
    hasTransformer(from: TSV, to: TSV): boolean;
    /**
     * Transform request data from one version to another
     */
    transformRequest(data: unknown, fromVersion: TSV, toVersion: TSV, path: string): Promise<TransformResult>;
    /**
     * Transform response data from one version to another
     */
    transformResponse(data: unknown, fromVersion: TSV, toVersion: TSV, path: string): Promise<TransformResult>;
    /**
     * Get all versions for a path (sorted by timestamp)
     */
    private getVersionsForPath;
    /**
     * Extract timestamp from TSV
     */
    private extractTimestamp;
    /**
     * Extract requested version from headers
     */
    private extractRequestedVersion;
    /**
     * Get transformer engine for external access
     */
    getTransformerEngine(): TransformerEngine;
    /**
     * Get all registered transformers
     */
    getAllTransformers(): TransformerPair[];
    /**
     * Get transformer count
     */
    getTransformerCount(): number;
}
/**
 * Create an enhanced route manager instance
 */
export declare function createEnhancedRouteManager(registry?: VersionRegistry, transformerEngine?: TransformerEngine): EnhancedRouteManager;
//# sourceMappingURL=enhanced-route-manager.d.ts.map