Service Client Architecture

/**
 * Base client interface for all AWS service clients
 * Provides consistent API across all AWS services
 */
interface Client<Input, Output, ResolvedClientConfiguration> {
  /** Resolved client configuration */
  readonly config: ResolvedClientConfiguration;
  
  /**
   * Send a command to the AWS service
   * @param command - Command object containing the operation and input
   * @param options - Optional request-specific configuration
   * @returns Promise resolving to the command output
   */
  send<InputType, OutputType>(
    command: Command<InputType, OutputType, Input, Output>,
    options?: any
  ): Promise<OutputType>;
  
  /**
   * Destroy the client and clean up resources
   * Should be called when the client is no longer needed
   */
  destroy(): void;
}

import { Client } from "@aws-sdk/types";

// Example AWS service client interface
interface S3Client extends Client<any, any, S3Configuration> {
  readonly config: S3Configuration;
}

// Using a client
const s3Client: S3Client = new S3Client({
  region: "us-east-1",
  credentials: {
    accessKeyId: "your-key",
    secretAccessKey: "your-secret"
  }
});

// Send a command
const response = await s3Client.send(new GetObjectCommand({
  Bucket: "my-bucket",
  Key: "my-object"
}));

// Clean up when done
s3Client.destroy();

/**
 * Base command interface for AWS service operations
 * Encapsulates operation logic and middleware configuration
 */
interface Command<Input, Output, ClientInput = Input, ClientOutput = Output> {
  /** Input data for the command */
  readonly input: Input;
  
  /**
   * Resolve middleware for this command
   * @param stack - Middleware stack to configure
   * @param configuration - Client configuration
   * @param options - Command-specific options
   * @returns Configured handler for execution
   */
  resolveMiddleware(
    stack: MiddlewareStack<ClientInput, ClientOutput>,
    configuration: any,
    options: any
  ): Handler<Input, Output>;
}

import { Command, MiddlewareStack, Handler } from "@aws-sdk/types";

// Example command implementation
class GetObjectCommand implements Command<GetObjectInput, GetObjectOutput> {
  readonly input: GetObjectInput;
  
  constructor(input: GetObjectInput) {
    this.input = input;
  }
  
  resolveMiddleware(
    stack: MiddlewareStack<any, any>,
    configuration: S3Configuration,
    options: any
  ): Handler<GetObjectInput, GetObjectOutput> {
    // Configure middleware stack for this specific operation
    const handler = stack.resolve(
      async (args) => {
        // Terminal handler implementation
        return await makeHttpRequest(args);
      },
      configuration
    );
    
    return handler;
  }
}

// Using the command
const command = new GetObjectCommand({
  Bucket: "my-bucket",
  Key: "my-object"
});

const result = await client.send(command);

/**
 * Request handler interface for making HTTP requests
 * Abstracts the underlying HTTP client implementation
 */
interface RequestHandler<RequestType = HttpRequest, ResponseType = HttpResponse> {
  /**
   * Handle an HTTP request
   * @param request - Request to send
   * @param options - Handler-specific options
   * @returns Promise resolving to the response
   */
  handle(
    request: RequestType,
    options?: RequestHandlerOptions
  ): Promise<RequestHandlerOutput<ResponseType>>;
  
  /** 
   * Update HTTP client configuration
   * @param key - Configuration key
   * @param value - Configuration value
   * @param isAsync - Whether the update is asynchronous
   */
  updateHttpClientConfig(key: string, value: any, isAsync?: boolean): void;
  
  /**
   * Get HTTP handler metadata
   * @returns Handler metadata object
   */
  httpHandlerConfigs(): RequestHandlerMetadata;
}

/**
 * Options for request handler configuration
 */
interface RequestHandlerOptions {
  /** Request timeout in milliseconds */
  requestTimeout?: number;
  /** Connection timeout in milliseconds */
  connectionTimeout?: number;
  /** Socket timeout in milliseconds */
  socketTimeout?: number;
  /** Additional handler-specific options */
  [key: string]: any;
}

/**
 * Request handler output containing response and metadata
 */
interface RequestHandlerOutput<ResponseType = HttpResponse> {
  /** HTTP response */
  response: ResponseType;
}

/**
 * Request handler metadata for debugging and configuration
 */
interface RequestHandlerMetadata {
  /** Handler name or type */
  handlerProtocol: RequestHandlerProtocol;
  /** Configuration options */
  [key: string]: any;
}

/**
 * Request handler protocol enumeration
 */
enum RequestHandlerProtocol {
  /** HTTP/1.1 protocol */
  HTTP_0_9 = "http/0.9",
  /** HTTP/1.0 protocol */
  HTTP_1_0 = "http/1.0", 
  /** HTTP/1.1 protocol */
  HTTP_1_1 = "http/1.1",
  /** HTTP/2 protocol */
  HTTP_2_0 = "http/2.0"
}

/**
 * Request context containing additional request information
 * Used for advanced request processing and debugging
 */
interface RequestContext {
  /** Destination service information */
  destination: URL;
  /** Request attempt number */
  attempt?: number;
  /** Request metadata */
  [key: string]: any;
}

/**
 * Pagination configuration for AWS service operations
 * Defines how to handle multi-page responses
 */
interface PaginationConfiguration {
  /** Maximum number of items per page */
  pageSize?: number;
  /** Client instance for making requests */
  client: any;
  /** Optional starting token for pagination */
  startingToken?: any;
}

/**
 * Paginator interface for iterating through paginated results
 * Provides async iteration over all pages of results
 */
interface Paginator<T> {
  /** 
   * Async iterator for paginated results
   * Automatically handles page loading and continuation
   */
  [Symbol.asyncIterator](): AsyncIterator<T>;
  
  /**
   * Get all results as an array
   * Warning: May load large amounts of data into memory
   */
  toArray(): Promise<T[]>;
}

import { 
  RequestHandler, 
  RequestHandlerOptions,
  PaginationConfiguration,
  Paginator 
} from "@aws-sdk/types";

// Configure custom request handler
const customHandler: RequestHandler = {
  handle: async (request, options) => {
    // Custom HTTP request implementation
    const response = await fetch(request.url, {
      method: request.method,
      headers: Object.fromEntries(request.headers.entries()),
      body: request.body,
      timeout: options?.requestTimeout
    });
    
    return { response };
  },
  
  updateHttpClientConfig: (key, value) => {
    // Update configuration
  },
  
  httpHandlerConfigs: () => ({
    handlerProtocol: RequestHandlerProtocol.HTTP_1_1
  })
};

// Configure pagination
const paginationConfig: PaginationConfiguration = {
  pageSize: 100,
  client: s3Client
};

// Use paginator
const paginator: Paginator<S3Object> = paginateListObjects(
  paginationConfig,
  { Bucket: "my-bucket" }
);

// Iterate through all pages
for await (const page of paginator) {
  console.log("Page:", page);
}

/**
 * Waiter configuration for polling AWS resource states
 * Defines retry behavior and timing for state polling
 */
interface WaiterConfiguration {
  /** Client instance for making requests */
  client: any;
  /** Maximum wait time in seconds */
  maxWaitTime?: number;
  /** Minimum delay between attempts in seconds */
  minDelay?: number;
  /** Maximum delay between attempts in seconds */
  maxDelay?: number;
  /** Custom acceptor functions for state detection */
  acceptors?: WaiterAcceptor[];
}

/**
 * Waiter acceptor for detecting target states
 * Defines conditions that indicate completion or failure
 */
interface WaiterAcceptor {
  /** State this acceptor represents */
  state: "success" | "failure" | "retry";
  /** Matcher type for condition evaluation */
  matcher: "status" | "error" | "output" | "outputPath";
  /** Expected value for the matcher */
  expected: any;
  /** JMESPath expression for output matching */
  argument?: string;
}

import { WaiterConfiguration } from "@aws-sdk/types";

// Configure waiter for S3 object existence
const waiterConfig: WaiterConfiguration = {
  client: s3Client,
  maxWaitTime: 300,      // 5 minutes
  minDelay: 2,           // 2 seconds
  maxDelay: 30,          // 30 seconds
  acceptors: [
    {
      state: "success",
      matcher: "status",
      expected: 200
    },
    {
      state: "failure", 
      matcher: "error",
      expected: "NoSuchBucket"
    }
  ]
};

// Wait for object to exist
await waitForObjectExists(waiterConfig, {
  Bucket: "my-bucket",
  Key: "my-object"
});