/**
 * @file Per-Route Middleware Chain
 * @description Implements middleware chain patterns for route-level processing.
 * Enables authentication, logging, analytics, and other cross-cutting concerns.
 *
 * @module @/lib/routing/advanced/route-middleware
 *
 * This module provides:
 * - Middleware chain definitions
 * - Execution order control
 * - Async middleware support
 * - Error handling in chains
 * - Middleware composition
 *
 * @example
 * ```typescript
 * import { MiddlewareChain, createMiddleware } from '@/lib/routing/advanced/route-middleware';
 *
 * const chain = new MiddlewareChain()
 *   .use(loggingMiddleware)
 *   .use(authMiddleware)
 *   .use(analyticsMiddleware);
 *
 * await chain.execute(context);
 * ```
 */
/**
 * Middleware function signature
 */
export type MiddlewareFunction<TContext = MiddlewareContext> = (context: TContext, next: NextFunction) => void | Promise<void>;
/**
 * Next function to continue chain execution
 */
export type NextFunction = () => void | Promise<void>;
/**
 * Middleware context
 */
export interface MiddlewareContext {
    /** Current route path */
    readonly path: string;
    /** Route parameters */
    readonly params: Record<string, string>;
    /** Query parameters */
    readonly query: Record<string, string>;
    /** Request headers (if available) */
    readonly headers?: Record<string, string>;
    /** User context (if authenticated) */
    readonly user?: MiddlewareUser;
    /** Request timestamp */
    readonly timestamp: number;
    /** Unique request ID */
    readonly requestId: string;
    /** Custom data store */
    data: Record<string, unknown>;
    /** Response controls */
    response: MiddlewareResponse;
}
/**
 * User context in middleware
 */
export interface MiddlewareUser {
    /** User ID */
    readonly id: string;
    /** User roles */
    readonly roles: readonly string[];
    /** User permissions */
    readonly permissions: readonly string[];
    /** Session data */
    readonly session?: Record<string, unknown>;
}
/**
 * Response controls in middleware
 */
export interface MiddlewareResponse {
    /** Redirect to another path */
    redirect: (path: string, options?: {
        status?: number;
    }) => void;
    /** Send error response */
    error: (status: number, message: string) => void;
    /** Set response header */
    setHeader: (name: string, value: string) => void;
    /** Whether response has been sent */
    readonly sent: boolean;
    /** Response status code */
    readonly status: number | null;
    /** Response headers */
    readonly headers: Record<string, string>;
    /** Redirect target (if redirected) */
    readonly redirectTarget: string | null;
    /** Error message (if error) */
    readonly errorMessage: string | null;
}
/**
 * Middleware configuration
 */
export interface MiddlewareConfig {
    /** Middleware name (for debugging) */
    readonly name: string;
    /** Middleware function */
    readonly handler: MiddlewareFunction;
    /** Priority (lower = runs first) */
    readonly priority?: number;
    /** Routes to apply to (glob patterns) */
    readonly routes?: readonly string[];
    /** Routes to exclude (glob patterns) */
    readonly exclude?: readonly string[];
    /** Whether middleware is enabled */
    readonly enabled?: boolean;
    /** Timeout in ms */
    readonly timeout?: number;
    /** Feature flag for this middleware */
    readonly featureFlag?: string;
}
/**
 * Registered middleware
 */
export interface RegisteredMiddleware extends MiddlewareConfig {
    /** Unique middleware ID */
    readonly id: string;
    /** Registration timestamp */
    readonly registeredAt: number;
}
/**
 * Chain execution result
 */
export interface ChainExecutionResult {
    /** Whether chain completed successfully */
    readonly success: boolean;
    /** Execution duration (ms) */
    readonly durationMs: number;
    /** Middleware that failed (if any) */
    readonly failedMiddleware: string | null;
    /** Error that occurred (if any) */
    readonly error: Error | null;
    /** Final response state */
    readonly response: Pick<MiddlewareResponse, 'sent' | 'status' | 'redirectTarget' | 'errorMessage'>;
    /** Middleware execution order */
    readonly executionOrder: readonly string[];
}
/**
 * Chain execution options
 */
export interface ChainExecutionOptions {
    /** Abort signal for cancellation */
    readonly signal?: AbortSignal;
    /** Skip specific middleware by name */
    readonly skip?: readonly string[];
    /** Only run specific middleware by name */
    readonly only?: readonly string[];
    /** Override timeout */
    readonly timeout?: number;
}
/**
 * Create a middleware context
 */
export declare function createMiddlewareContext(options: Partial<Omit<MiddlewareContext, 'response' | 'data'>> & {
    path: string;
}): MiddlewareContext;
/**
 * Manages a chain of middleware
 *
 * @example
 * ```typescript
 * const chain = new MiddlewareChain();
 *
 * chain
 *   .use(async (ctx, next) => {
 *     console.log('Before:', ctx.path);
 *     await next();
 *     console.log('After:', ctx.path);
 *   })
 *   .use(authMiddleware, { name: 'auth', priority: 1 });
 *
 * const result = await chain.execute(context);
 * ```
 */
export declare class MiddlewareChain {
    private middleware;
    private idCounter;
    private defaultTimeout;
    /**
     * Add middleware to the chain
     *
     * @param handler - Middleware function or config
     * @param options - Middleware options
     * @returns Chain for fluent API
     */
    use(handler: MiddlewareFunction | MiddlewareConfig, options?: Partial<Omit<MiddlewareConfig, 'handler'>>): this;
    /**
     * Remove middleware from the chain
     *
     * @param nameOrId - Middleware name or ID
     * @returns True if middleware was found and removed
     */
    remove(nameOrId: string): boolean;
    /**
     * Execute the middleware chain
     *
     * @param context - Middleware context
     * @param options - Execution options
     * @returns Execution result
     */
    execute(context: MiddlewareContext, options?: ChainExecutionOptions): Promise<ChainExecutionResult>;
    /**
     * Get all registered middleware
     */
    getMiddleware(): readonly RegisteredMiddleware[];
    /**
     * Get middleware by name
     */
    getByName(name: string): RegisteredMiddleware | undefined;
    /**
     * Set default timeout
     */
    setDefaultTimeout(timeout: number): this;
    /**
     * Clear all middleware
     */
    clear(): this;
    /**
     * Clone the chain
     */
    clone(): MiddlewareChain;
    /**
     * Execute a function with timeout
     */
    private executeWithTimeout;
    /**
     * Check if middleware should run for a route
     */
    private matchesRoute;
    /**
     * Simple glob pattern matching
     */
    private globMatch;
}
/**
 * Create a middleware configuration
 *
 * @param config - Middleware configuration
 * @returns Validated configuration
 */
export declare function createMiddleware(config: MiddlewareConfig): MiddlewareConfig;
/**
 * Create a new middleware chain
 *
 * @returns Empty MiddlewareChain
 */
export declare function createMiddlewareChain(): MiddlewareChain;
/**
 * Create a logging middleware
 *
 * @param options - Logging options
 * @returns Logging middleware
 */
export declare function createLoggingMiddleware(options?: {
    logger?: (message: string, data?: Record<string, unknown>) => void;
    logRequest?: boolean;
    logResponse?: boolean;
}): MiddlewareConfig;
/**
 * Create an authentication check middleware
 *
 * @param options - Auth options
 * @returns Auth middleware
 */
export declare function createAuthMiddleware(options?: {
    loginPath?: string;
    isPublic?: (path: string) => boolean;
}): MiddlewareConfig;
/**
 * Create a role check middleware
 *
 * @param requiredRoles - Required roles
 * @returns Role middleware
 */
export declare function createRoleMiddleware(requiredRoles: readonly string[]): MiddlewareConfig;
/**
 * Create a rate limiting middleware
 *
 * @param options - Rate limit options
 * @returns Rate limit middleware
 */
export declare function createRateLimitMiddleware(options?: {
    maxRequests: number;
    windowMs: number;
    keyFn?: (ctx: MiddlewareContext) => string;
}): MiddlewareConfig;
/**
 * Create an analytics middleware
 *
 * @param options - Analytics options
 * @returns Analytics middleware
 */
export declare function createAnalyticsMiddleware(options?: {
    trackFn: (event: {
        path: string;
        timestamp: number;
        userId?: string;
        data?: Record<string, unknown>;
    }) => void;
}): MiddlewareConfig;
/**
 * Get the default middleware chain
 */
export declare function getMiddlewareChain(): MiddlewareChain;
/**
 * Reset the default middleware chain
 */
export declare function resetMiddlewareChain(): void;
/**
 * Compose multiple middleware into one
 *
 * @param middleware - Middleware functions to compose
 * @returns Composed middleware function
 */
export declare function compose(...middleware: MiddlewareFunction[]): MiddlewareFunction;
/**
 * Run middleware in parallel (all must complete before next)
 *
 * @param middleware - Middleware functions to run in parallel
 * @returns Parallel middleware function
 */
export declare function parallel(...middleware: MiddlewareFunction[]): MiddlewareFunction;
/**
 * Conditionally run middleware
 *
 * @param condition - Condition function
 * @param middleware - Middleware to run if condition is true
 * @returns Conditional middleware
 */
export declare function conditional(condition: (ctx: MiddlewareContext) => boolean, middleware: MiddlewareFunction): MiddlewareFunction;
/**
 * Type guard for MiddlewareContext
 */
export declare function isMiddlewareContext(value: unknown): value is MiddlewareContext;
/**
 * Type guard for ChainExecutionResult
 */
export declare function isChainExecutionResult(value: unknown): value is ChainExecutionResult;