/**
 * Proxy Lambda Types for Awake Lambda Development
 *
 * Defines configuration and context types for the Proxy Lambda handler
 * that routes requests to local development environments.
 *
 * @module runtime-awake/proxy-lambda
 */
import type { RuntimeAwakeFallbackMode } from '../../../lib/runtime-web/runtime-awake';
/**
 * Configuration for the Proxy Lambda handler.
 *
 * @see Requirements 1.1, 1.3, 1.4, 1.5
 */
export interface ProxyLambdaConfig {
    /** DynamoDB table name for session registry */
    readonly sessionTableName: string;
    /** S3 bucket name for large payloads */
    readonly payloadBucketName: string;
    /** AWS IoT Core endpoint URL */
    readonly iotEndpoint: string;
    /** Fallback behavior when no active session exists */
    readonly fallbackMode: RuntimeAwakeFallbackMode;
    /** Original handler module path for fallback execution */
    readonly originalHandlerPath?: string;
    /** Original handler export name (default: 'handler') */
    readonly originalHandlerExport?: string;
    /**
     * Timeout buffer in seconds subtracted from Lambda timeout.
     * Default: 5 seconds
     *
     * @see Requirements 1.5
     */
    readonly timeoutBufferSeconds?: number;
    /** AWS region for SDK clients */
    readonly region: string;
    /** Microservice name for handler identification */
    readonly microserviceName: string;
    /** Handler hash key for handler identification */
    readonly handlerHashKey: string;
    /** Lambda ID for debugging */
    readonly lambdaId: string;
    /** Maximum payload size in bytes before S3 indirection (default: 128KB) */
    readonly maxPayloadSizeBytes?: number;
}
/**
 * Environment variables for Proxy Lambda configuration.
 *
 * These are set by CDK constructs during deployment.
 */
export interface ProxyLambdaEnvironment {
    /** DynamoDB session table name */
    LIVE_DEV_SESSION_TABLE: string;
    /** S3 payload bucket name */
    LIVE_DEV_PAYLOAD_BUCKET: string;
    /** IoT Core endpoint */
    LIVE_DEV_IOT_ENDPOINT: string;
    /** Fallback mode: 'execute' | 'error' */
    LIVE_DEV_FALLBACK_MODE: string;
    /** Original handler path for fallback */
    LIVE_DEV_ORIGINAL_HANDLER_PATH?: string;
    /** Original handler export name */
    LIVE_DEV_ORIGINAL_HANDLER_EXPORT?: string;
    /** Microservice name */
    LIVE_DEV_MICROSERVICE_NAME: string;
    /** Handler hash key */
    LIVE_DEV_HANDLER_HASH_KEY: string;
    /** Lambda ID */
    LIVE_DEV_LAMBDA_ID: string;
    /** AWS region */
    AWS_REGION: string;
    /** Default Dev_ID for session lookup when not provided in request */
    LIVE_DEV_DEV_ID?: string;
}
/**
 * Result of Dev_ID resolution.
 *
 * @see Requirements 9.1, 9.2, 9.3, 9.4, 9.5
 */
export interface DevIdResolutionResult {
    /** Resolved Dev_ID */
    readonly devId: string;
    /** Source of the Dev_ID */
    readonly source: DevIdSource;
}
/**
 * Source of the resolved Dev_ID.
 */
export type DevIdSource = 'header' | 'authorizer' | 'environment' | 'none';
/**
 * Result of a proxy operation.
 */
export interface ProxyResult {
    /** Whether the request was successfully proxied */
    readonly proxied: boolean;
    /** Response from local handler (if proxied) */
    readonly response?: unknown;
    /** Error details (if failed) */
    readonly error?: {
        readonly type: 'no-session' | 'timeout' | 'mqtt-failure' | 'handler-error' | 'infrastructure-error';
        readonly message: string;
        readonly requestId: string;
    };
    /** Whether fallback was executed */
    readonly fallbackExecuted?: boolean;
}
/**
 * Timeout configuration computed from Lambda context.
 */
export interface TimeoutConfig {
    /** Total Lambda timeout in milliseconds */
    readonly lambdaTimeoutMs: number;
    /** Response wait timeout in milliseconds */
    readonly responseTimeoutMs: number;
    /** Timestamp when timeout will occur */
    readonly timeoutAt: number;
}
/**
 * Default configuration values.
 */
export declare const PROXY_LAMBDA_DEFAULTS: {
    /** Default timeout buffer in seconds */
    readonly TIMEOUT_BUFFER_SECONDS: 5;
    /** Minimum Lambda timeout required for Live Dev (seconds) */
    readonly MIN_LAMBDA_TIMEOUT_SECONDS: 6;
    /** Maximum payload size before S3 indirection (128KB) */
    readonly MAX_PAYLOAD_SIZE_BYTES: number;
    /** Protocol version */
    readonly PROTOCOL_VERSION: "1.0";
};
/**
 * Error types for proxy operations.
 */
export type ProxyErrorType = 'no-session' | 'timeout' | 'mqtt-failure' | 'handler-error' | 'infrastructure-error';
/**
 * Known error types that map to specific HTTP status codes.
 *
 * @see Requirements 17.3
 */
export type KnownErrorType = 'ValidationError' | 'NotFoundError' | 'UnauthorizedError' | 'ForbiddenError' | 'TimeoutError';
/**
 * Infrastructure error types used internally by the proxy.
 */
export type InfrastructureErrorType = 'no-session' | 'timeout' | 'mqtt-failure' | 'handler-error' | 'infrastructure-error';
/**
 * All error types that can be mapped to HTTP status codes.
 */
export type MappableErrorType = KnownErrorType | InfrastructureErrorType;
/**
 * Default HTTP status code for unknown error types.
 */
export declare const DEFAULT_ERROR_STATUS_CODE = 500;
/**
 * Maps error types to HTTP status codes.
 *
 * Handler error types (thrown by user code):
 * - ValidationError → 400 Bad Request
 * - NotFoundError → 404 Not Found
 * - UnauthorizedError → 401 Unauthorized
 * - ForbiddenError → 403 Forbidden
 * - TimeoutError → 504 Gateway Timeout
 *
 * Infrastructure error types (internal proxy errors):
 * - no-session → 503 Service Unavailable
 * - timeout → 504 Gateway Timeout
 * - mqtt-failure → 503 Service Unavailable
 * - handler-error → 500 Internal Server Error
 * - infrastructure-error → 500 Internal Server Error
 *
 * Unknown error types default to 500 Internal Server Error.
 *
 * @see Requirements 17.3
 */
export declare const ERROR_TYPE_TO_STATUS: Record<string, number>;
/**
 * Maps an error type to its corresponding HTTP status code.
 *
 * This function provides a type-safe way to convert error types from
 * RuntimeAwakeErrorResponse to appropriate HTTP status codes for API Gateway.
 *
 * @param errorType - The error type string from the error response
 * @returns HTTP status code (400-504 for known types, 500 for unknown)
 *
 * @example
 * ```typescript
 * mapErrorTypeToStatus('ValidationError'); // Returns 400
 * mapErrorTypeToStatus('NotFoundError');   // Returns 404
 * mapErrorTypeToStatus('UnknownError');    // Returns 500 (default)
 * ```
 *
 * @see Requirements 17.3
 */
export declare function mapErrorTypeToStatus(errorType: string): number;
/**
 * Checks if an error type is a known handler error type.
 *
 * Handler errors are thrown by user code and should be mapped to
 * appropriate 4xx/5xx status codes.
 *
 * @param errorType - The error type to check
 * @returns True if the error type is a known handler error
 */
export declare function isKnownHandlerErrorType(errorType: string): errorType is KnownErrorType;
/**
 * Checks if an error type is an infrastructure error type.
 *
 * Infrastructure errors are internal to the proxy and indicate
 * issues with the Live Dev system rather than user code.
 *
 * @param errorType - The error type to check
 * @returns True if the error type is an infrastructure error
 */
export declare function isInfrastructureErrorType(errorType: string): errorType is InfrastructureErrorType;
/**
 * Error thrown when S3 upload fails.
 *
 * @see Requirements 3.5
 */
export declare class S3UploadError extends Error {
    readonly requestId: string;
    readonly key: string;
    readonly errorType: "s3-upload-error";
    constructor(message: string, requestId: string, key: string);
}
/**
 * Error thrown when S3 download fails.
 *
 * @see Requirements 3.5
 */
export declare class S3DownloadError extends Error {
    readonly bucket: string;
    readonly key: string;
    readonly errorType: "s3-download-error";
    constructor(message: string, bucket: string, key: string);
}
/**
 * Type guard to check if an error is an S3UploadError.
 *
 * @param error - Error to check
 * @returns True if error is an S3UploadError
 */
export declare function isS3UploadError(error: unknown): error is S3UploadError;
/**
 * Type guard to check if an error is an S3DownloadError.
 *
 * @param error - Error to check
 * @returns True if error is an S3DownloadError
 */
export declare function isS3DownloadError(error: unknown): error is S3DownloadError;
/**
 * Session lookup match type.
 *
 * Indicates how a session was matched during lookup.
 *
 * @see Requirements 4.1, 4.2
 */
export type SessionMatchType = 'exact' | 'wildcard' | 'none';
/**
 * Result of session lookup operation.
 *
 * @see Requirements 4.1, 4.2, 4.3
 */
export interface SessionLookupResult {
    /** Whether a session was found */
    readonly found: boolean;
    /** The matched session (if found) */
    readonly session?: {
        readonly devId: string;
        readonly functionName: string;
        readonly hostname: string;
        readonly appName: string;
        readonly stage: string;
        readonly cliVersion: string;
        readonly iotClientId: string;
    };
    /** How the session was matched */
    readonly matchType: SessionMatchType;
    /** The requested function name */
    readonly requestedFunctionName: string;
    /** Whether the session TTL was valid */
    readonly ttlValid?: boolean;
}
/**
 * Determines the session match type based on the requested and matched function names.
 *
 * @param requestedFunctionName - The function name that was requested
 * @param matchedFunctionName - The function name that was matched (or undefined if no match)
 * @returns The match type: 'exact', 'wildcard', or 'none'
 *
 * @see Requirements 4.1, 4.2
 */
export declare function determineSessionMatchType(requestedFunctionName: string, matchedFunctionName: string | undefined): SessionMatchType;
