Middleware & Request Processing

/**
 * Handler execution context containing request state and configuration
 * Flows through the entire middleware pipeline for each request
 */
interface HandlerExecutionContext {
  /** Logger for the current request */
  logger?: Logger;
  /** Request metadata and tracking information */
  [key: string]: any;
}

/**
 * AWS-specific handler execution context with SDK feature tracking
 * Extends base context with AWS SDK specific metadata
 */
interface AwsHandlerExecutionContext extends HandlerExecutionContext {
  /** AWS SDK specific context information */
  __aws_sdk_context?: {
    /** Feature flags and telemetry data */
    features?: AwsSdkFeatures;
  };
}

/**
 * AWS SDK feature tracking type for telemetry and debugging
 * @internal Used for SDK internal feature tracking
 */
type AwsSdkFeatures = Partial<{
  [key: string]: string;
}>;

/**
 * Generic handler function for processing requests
 * Core building block of the middleware system
 */
interface Handler<Input, Output> {
  (args: Input, context?: HandlerExecutionContext): Promise<Output>;
}

/**
 * Handler arguments containing input and context
 * Standard format for all handler functions
 */
interface HandlerArguments<Input> {
  /** Input data for the handler */
  input: Input;
}

/**
 * Handler options for configuration and metadata
 * Provides additional context for handler execution
 */
interface HandlerOptions {
  /** Handler name for debugging and tracking */
  name?: string;
  /** Handler metadata */
  [key: string]: any;
}

/**
 * Handler output containing result and context updates
 * Standard format for all handler return values
 */
interface HandlerOutput<Output> {
  /** Output data from the handler */
  output: Output;
  /** Optional response metadata */
  response?: HttpResponse;
}

/**
 * Middleware stack managing ordered request processing stages
 * Provides plugin architecture for extensible request handling
 */
interface MiddlewareStack<Input, Output> {
  /**
   * Add middleware to the stack
   * @param middleware - Middleware function to add
   * @param options - Configuration for middleware placement
   */
  add<T>(middleware: Middleware<Input, Output, T>, options?: MiddlewareOptions): void;
  
  /**
   * Add middleware with relative positioning
   * @param middleware - Middleware function to add
   * @param options - Relative positioning options
   */
  addRelativeTo<T>(
    middleware: Middleware<Input, Output, T>, 
    options: RelativeMiddlewareOptions
  ): void;
  
  /**
   * Remove middleware from the stack
   * @param toRemove - Middleware name or function to remove
   */
  remove(toRemove: string | Middleware<Input, Output>): boolean;
  
  /**
   * Create final handler by resolving the middleware stack
   * @param handler - Terminal handler for the stack
   * @param context - Execution context
   */
  resolve<T>(handler: Handler<Input, Output>, context: T): Handler<Input, Output>;
  
  /**
   * Clone the middleware stack
   */
  clone(): MiddlewareStack<Input, Output>;
}

/**
 * Middleware function that wraps handler execution
 * Can modify request, response, or both
 */
interface Middleware<Input, Output, Config = any> {
  (next: Handler<Input, Output>, context: Config): Handler<Input, Output>;
}

/**
 * Options for middleware configuration and placement
 */
interface MiddlewareOptions {
  /** Step in the pipeline (initialize, serialize, build, finalize, deserialize) */
  step?: Step;
  /** Priority within the step (high, normal, low) */
  priority?: Priority;
  /** Middleware name for identification */
  name?: string;
  /** Tags for middleware categorization */
  tags?: string[];
  /** Whether middleware can be overridden */
  override?: boolean;
}

/**
 * Relative positioning options for middleware placement
 */
interface RelativeMiddlewareOptions extends MiddlewareOptions {
  /** Relationship to target middleware */
  relation: Relation;
  /** Target middleware name */
  toMiddleware: string;
}

/**
 * Pipeline step enumeration defining middleware execution order
 */
enum Step {
  /** Initial request setup and validation */
  INITIALIZE = "initialize",
  /** Request serialization and formatting */
  SERIALIZE = "serialize", 
  /** Request building and preparation */
  BUILD = "build",
  /** Request finalization and signing */
  FINALIZE = "finalize",
  /** Response deserialization and processing */
  DESERIALIZE = "deserialize"
}

/**
 * Priority levels for middleware within each step
 */
enum Priority {
  /** High priority - executes first */
  HIGH = "high",
  /** Normal priority - default execution order */
  NORMAL = "normal", 
  /** Low priority - executes last */
  LOW = "low"
}

/**
 * Relationship types for relative middleware positioning
 */
enum Relation {
  /** Execute before target middleware */
  BEFORE = "before",
  /** Execute after target middleware */
  AFTER = "after"
}

/**
 * Initialize step handler for request setup and validation
 */
interface InitializeHandler<Input, Output> extends Handler<Input, Output> {}

interface InitializeHandlerArguments<Input> extends HandlerArguments<Input> {}

interface InitializeHandlerOptions extends HandlerOptions {}

interface InitializeHandlerOutput<Output> extends HandlerOutput<Output> {}

interface InitializeMiddleware<Input, Output> 
  extends Middleware<Input, Output> {}

/**
 * Serialize step handler for request serialization
 */
interface SerializeHandler<Input, Output> extends Handler<Input, Output> {}

interface SerializeHandlerArguments<Input> extends HandlerArguments<Input> {
  /** Request being serialized */
  request: HttpRequest;
}

interface SerializeHandlerOptions extends HandlerOptions {}

interface SerializeHandlerOutput<Output> extends HandlerOutput<Output> {
  /** Serialized request */
  request: HttpRequest;
}

interface SerializeMiddleware<Input, Output> 
  extends Middleware<Input, Output> {}

/**
 * Build step handler for request building and preparation
 */
interface BuildHandler<Input, Output> extends Handler<Input, Output> {}

interface BuildHandlerArguments<Input> extends HandlerArguments<Input> {
  /** Request being built */
  request: HttpRequest;
}

interface BuildHandlerOptions extends HandlerOptions {}

interface BuildHandlerOutput<Output> extends HandlerOutput<Output> {
  /** Built request */
  request: HttpRequest;
}

interface BuildMiddleware<Input, Output> 
  extends Middleware<Input, Output> {}

/**
 * Finalize step handler for request finalization and signing
 */
interface FinalizeHandler<Input, Output> extends Handler<Input, Output> {}

interface FinalizeHandlerArguments<Input> extends HandlerArguments<Input> {
  /** Request being finalized */
  request: HttpRequest;
}

interface FinalizeRequestHandlerOptions extends HandlerOptions {}

interface FinalizeHandlerOutput<Output> extends HandlerOutput<Output> {
  /** Finalized request */
  request: HttpRequest;
}

interface FinalizeRequestMiddleware<Input, Output> 
  extends Middleware<Input, Output> {}

/**
 * Deserialize step handler for response processing
 */
interface DeserializeHandler<Input, Output> extends Handler<Input, Output> {}

interface DeserializeHandlerArguments<Input> extends HandlerArguments<Input> {
  /** Request that was sent */
  request: HttpRequest;
}

interface DeserializeHandlerOptions extends HandlerOptions {}

interface DeserializeHandlerOutput<Output> extends HandlerOutput<Output> {
  /** HTTP response received */
  response: HttpResponse;
}

interface DeserializeMiddleware<Input, Output> 
  extends Middleware<Input, Output> {}

/**
 * Pluggable middleware with metadata
 * Used for middleware that can be dynamically loaded
 */
interface Pluggable<Input, Output> {
  /** Apply the plugin to a middleware stack */
  applyToStack: (stack: MiddlewareStack<Input, Output>) => void;
}

/**
 * Terminal middleware - final handler in the stack
 * Typically the HTTP request handler
 */
interface Terminalware<Input, Output> {
  (args: FinalizeHandlerArguments<Input>): Promise<DeserializeHandlerOutput<Output>>;
}

/**
 * Middleware type enumeration for categorization
 */
enum MiddlewareType {
  /** Initialization middleware */
  INITIALIZE = "initialize",
  /** Serialization middleware */  
  SERIALIZE = "serialize",
  /** Building middleware */
  BUILD = "build",
  /** Finalization middleware */
  FINALIZE = "finalize", 
  /** Deserialization middleware */
  DESERIALIZE = "deserialize"
}

/**
 * Absolute location specification for precise middleware placement
 */
interface AbsoluteLocation {
  /** Pipeline step */
  step: Step;
  /** Priority within step */
  priority: Priority;
}

/**
 * Relative location specification for middleware positioning
 */
interface RelativeLocation {
  /** Relationship to target */
  relation: Relation;
  /** Target middleware name */
  toMiddleware: string;
}

import { 
  MiddlewareStack, 
  InitializeMiddleware,
  BuildMiddleware,
  Step,
  Priority 
} from "@aws-sdk/types";

// Create custom initialization middleware
const loggingMiddleware: InitializeMiddleware<any, any> = (next, context) => {
  return async (args) => {
    console.log("Request starting:", args.input);
    const result = await next(args);
    console.log("Request completed:", result.output);
    return result;
  };
};

// Create custom build middleware for header injection
const headerMiddleware: BuildMiddleware<any, any> = (next, context) => {
  return async (args) => {
    // Add custom header to request
    args.request.headers["X-Custom-Header"] = "my-value";
    return next(args);
  };
};

// Add middleware to stack
const stack: MiddlewareStack<any, any> = createMiddlewareStack();

stack.add(loggingMiddleware, {
  step: Step.INITIALIZE,
  priority: Priority.HIGH,
  name: "loggingMiddleware"
});

stack.add(headerMiddleware, {
  step: Step.BUILD,
  priority: Priority.NORMAL,
  name: "headerMiddleware"
});