Add centralized error handling through Configuration

This introduces ErrorHandler protocols that allow customization of error
handling for both client and server operations, enabling centralized error
management, logging, and monitoring capabilities.

## Changes

### New Error Handler Protocols
- Add `ClientErrorHandler` protocol for client-side error handling
- Add `ServerErrorHandler` protocol for server-side error handling
- Add `ClientErrorContext` and `ServerErrorContext` for rich error context
- Provide `DefaultClientErrorHandler` and `DefaultServerErrorHandler` as
  backward-compatible default implementations

### Configuration Integration
- Add `clientErrorHandler` property to `Configuration` (default: `DefaultClientErrorHandler()`)
- Add `serverErrorHandler` property to `Configuration` (default: `DefaultServerErrorHandler()`)
- Both properties have default values, ensuring zero breaking changes

### Runtime Integration
- Update `UniversalClient` to use configured `ClientErrorHandler`
- Update `UniversalServer` to use configured `ServerErrorHandler`
- All errors now flow through the configured handlers, providing a single
  interception point for logging, monitoring, and transformation

### Testing
- Add comprehensive unit tests for both error handlers (11 tests)
- Add integration tests for end-to-end error handling flow (9 tests)
- All 226 existing tests continue to pass

## Usage Example

```swift
// Custom error handler with logging
struct LoggingClientErrorHandler: ClientErrorHandler {
    func handleClientError(_ error: any Error, context: ClientErrorContext) -> any Error {
        // Add logging/monitoring
        logger.error("Client error in \(context.operationID): \(error)")

        // Use default transformation
        return DefaultClientErrorHandler().handleClientError(error, context: context)
    }
}

// Configure client with custom handler
let config = Configuration(
    clientErrorHandler: LoggingClientErrorHandler()
)
let client = UniversalClient(configuration: config, transport: transport)
```

## Benefits

- **Backward Compatible**: Default handlers maintain existing behavior
- **Centralized**: Single interception point for all errors
- **Extensible**: Easy to add logging, monitoring, or custom transformations
- **Type-Safe**: Protocol-based design with compile-time verification
- **Rich Context**: Full operation context available at error handling time

Author: winnisx7

Sources/OpenAPIRuntime/Conversion/Configuration.swift

@@ -152,6 +152,20 @@ public struct Configuration: Sendable {
     /// Custom XML coder for encoding and decoding xml bodies.
     public var xmlCoder: (any CustomCoder)?
 
+    /// The handler for client-side errors.
+    ///
+    /// This handler is invoked whenever an error occurs during client operations
+    /// (request serialization, transport, or response deserialization).
+    /// Customize this to add logging, monitoring, or custom error transformation.
+    public var clientErrorHandler: any ClientErrorHandler
+
+    /// The handler for server-side errors.
+    ///
+    /// This handler is invoked whenever an error occurs during server operations
+    /// (request deserialization, handler execution, or response serialization).
+    /// Customize this to add logging, monitoring, or custom error transformation.
+    public var serverErrorHandler: any ServerErrorHandler
+
     /// Creates a new configuration with the specified values.
     ///
     /// - Parameters:
@@ -160,15 +174,21 @@ public struct Configuration: Sendable {
     ///   - jsonEncodingOptions: The options for the underlying JSON encoder.
     ///   - multipartBoundaryGenerator: The generator to use when creating mutlipart bodies.
     ///   - xmlCoder: Custom XML coder for encoding and decoding xml bodies. Only required when using XML body payloads.
+    ///   - clientErrorHandler: The handler for client-side errors. Defaults to ``DefaultClientErrorHandler``.
+    ///   - serverErrorHandler: The handler for server-side errors. Defaults to ``DefaultServerErrorHandler``.
     public init(
         dateTranscoder: any DateTranscoder = .iso8601,
         jsonEncodingOptions: JSONEncodingOptions = [.sortedKeys, .prettyPrinted],
         multipartBoundaryGenerator: any MultipartBoundaryGenerator = .random,
-        xmlCoder: (any CustomCoder)? = nil
+        xmlCoder: (any CustomCoder)? = nil,
+        clientErrorHandler: any ClientErrorHandler = DefaultClientErrorHandler(),
+        serverErrorHandler: any ServerErrorHandler = DefaultServerErrorHandler()
     ) {
         self.dateTranscoder = dateTranscoder
         self.jsonEncodingOptions = jsonEncodingOptions
         self.multipartBoundaryGenerator = multipartBoundaryGenerator
         self.xmlCoder = xmlCoder
+        self.clientErrorHandler = clientErrorHandler
+        self.serverErrorHandler = serverErrorHandler
     }
 }

Sources/OpenAPIRuntime/Errors/ErrorHandler.swift

@@ -0,0 +1,256 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftOpenAPIGenerator open source project
+//
+// Copyright (c) 2023 Apple Inc. and the SwiftOpenAPIGenerator project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftOpenAPIGenerator project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+import Foundation
+import HTTPTypes
+
+// MARK: - Client Error Handler
+
+/// A protocol for handling errors that occur during client operations.
+///
+/// Implement this protocol to customize how client-side errors are processed,
+/// logged, and transformed before being thrown to the caller.
+public protocol ClientErrorHandler: Sendable {
+    /// Handles an error that occurred during a client operation.
+    ///
+    /// This method is called whenever an error occurs during request serialization,
+    /// transport, or response deserialization in the client.
+    ///
+    /// - Parameters:
+    ///   - error: The original error that was thrown.
+    ///   - context: Context information about the operation and request/response.
+    /// - Returns: An error to be thrown to the caller. This can be the original error,
+    ///            a transformed error, or a new error based on your error handling logic.
+    func handleClientError(
+        _ error: any Error,
+        context: ClientErrorContext
+    ) -> any Error
+}
+
+/// Context information for client error handling.
+public struct ClientErrorContext: Sendable {
+    /// The operation identifier.
+    public let operationID: String
+
+    /// The operation input that was being sent.
+    public let operationInput: (any Sendable)?
+
+    /// The HTTP request, if it was created before the error occurred.
+    public let request: HTTPRequest?
+
+    /// The HTTP request body, if it was created before the error occurred.
+    public let requestBody: HTTPBody?
+
+    /// The base URL used for the request.
+    public let baseURL: URL?
+
+    /// The HTTP response, if it was received before the error occurred.
+    public let response: HTTPResponse?
+
+    /// The HTTP response body, if it was received before the error occurred.
+    public let responseBody: HTTPBody?
+
+    /// Creates a new client error context.
+    public init(
+        operationID: String,
+        operationInput: (any Sendable)? = nil,
+        request: HTTPRequest? = nil,
+        requestBody: HTTPBody? = nil,
+        baseURL: URL? = nil,
+        response: HTTPResponse? = nil,
+        responseBody: HTTPBody? = nil
+    ) {
+        self.operationID = operationID
+        self.operationInput = operationInput
+        self.request = request
+        self.requestBody = requestBody
+        self.baseURL = baseURL
+        self.response = response
+        self.responseBody = responseBody
+    }
+}
+
+/// The default client error handler implementation.
+///
+/// This handler wraps errors in a ``ClientError`` struct that includes
+/// context information about the operation, request, and response.
+public struct DefaultClientErrorHandler: ClientErrorHandler {
+    /// Creates a new default client error handler.
+    public init() {}
+
+    public func handleClientError(
+        _ error: any Error,
+        context: ClientErrorContext
+    ) -> any Error {
+        // If already a ClientError, update it with missing context
+        if var clientError = error as? ClientError {
+            clientError.request = clientError.request ?? context.request
+            clientError.requestBody = clientError.requestBody ?? context.requestBody
+            clientError.baseURL = clientError.baseURL ?? context.baseURL
+            clientError.response = clientError.response ?? context.response
+            clientError.responseBody = clientError.responseBody ?? context.responseBody
+            return clientError
+        }
+
+        // Extract description and underlying error
+        let causeDescription: String
+        let underlyingError: any Error
+        if let runtimeError = error as? RuntimeError {
+            causeDescription = runtimeError.prettyDescription
+            underlyingError = runtimeError.underlyingError ?? error
+        } else {
+            causeDescription = "Unknown"
+            underlyingError = error
+        }
+
+        // Create new ClientError with full context
+        return ClientError(
+            operationID: context.operationID,
+            operationInput: context.operationInput,
+            request: context.request,
+            requestBody: context.requestBody,
+            baseURL: context.baseURL,
+            response: context.response,
+            responseBody: context.responseBody,
+            causeDescription: causeDescription,
+            underlyingError: underlyingError
+        )
+    }
+}
+
+// MARK: - Server Error Handler
+
+/// A protocol for handling errors that occur during server operations.
+///
+/// Implement this protocol to customize how server-side errors are processed,
+/// logged, and transformed into HTTP responses.
+public protocol ServerErrorHandler: Sendable {
+    /// Handles an error that occurred during a server operation.
+    ///
+    /// This method is called whenever an error occurs during request deserialization,
+    /// handler execution, or response serialization in the server.
+    ///
+    /// - Parameters:
+    ///   - error: The original error that was thrown.
+    ///   - context: Context information about the operation and request/response.
+    /// - Returns: An error to be thrown to the middleware. This can be the original error,
+    ///            a transformed error, or a new error based on your error handling logic.
+    func handleServerError(
+        _ error: any Error,
+        context: ServerErrorContext
+    ) -> any Error
+}
+
+/// Context information for server error handling.
+public struct ServerErrorContext: Sendable {
+    /// The operation identifier.
+    public let operationID: String
+
+    /// The HTTP request that was received.
+    public let request: HTTPRequest
+
+    /// The HTTP request body that was received.
+    public let requestBody: HTTPBody?
+
+    /// Metadata about the server request.
+    public let requestMetadata: ServerRequestMetadata
+
+    /// The operation input, if it was successfully deserialized before the error occurred.
+    public let operationInput: (any Sendable)?
+
+    /// The operation output, if it was produced before the error occurred.
+    public let operationOutput: (any Sendable)?
+
+    /// Creates a new server error context.
+    public init(
+        operationID: String,
+        request: HTTPRequest,
+        requestBody: HTTPBody? = nil,
+        requestMetadata: ServerRequestMetadata,
+        operationInput: (any Sendable)? = nil,
+        operationOutput: (any Sendable)? = nil
+    ) {
+        self.operationID = operationID
+        self.request = request
+        self.requestBody = requestBody
+        self.requestMetadata = requestMetadata
+        self.operationInput = operationInput
+        self.operationOutput = operationOutput
+    }
+}
+
+/// The default server error handler implementation.
+///
+/// This handler wraps errors in a ``ServerError`` struct that includes
+/// context information about the operation, request, and the HTTP response to be sent.
+public struct DefaultServerErrorHandler: ServerErrorHandler {
+    /// Creates a new default server error handler.
+    public init() {}
+
+    public func handleServerError(
+        _ error: any Error,
+        context: ServerErrorContext
+    ) -> any Error {
+        // If already a ServerError, update it with missing context
+        if var serverError = error as? ServerError {
+            serverError.operationInput = serverError.operationInput ?? context.operationInput
+            serverError.operationOutput = serverError.operationOutput ?? context.operationOutput
+            return serverError
+        }
+
+        // Extract description and underlying error
+        let causeDescription: String
+        let underlyingError: any Error
+        if let runtimeError = error as? RuntimeError {
+            causeDescription = runtimeError.prettyDescription
+            underlyingError = runtimeError.underlyingError ?? error
+        } else {
+            causeDescription = "Unknown"
+            underlyingError = error
+        }
+
+        // Determine HTTP response properties
+        let httpStatus: HTTPResponse.Status
+        let httpHeaderFields: HTTPTypes.HTTPFields
+        let httpBody: OpenAPIRuntime.HTTPBody?
+
+        if let httpConvertibleError = underlyingError as? (any HTTPResponseConvertible) {
+            httpStatus = httpConvertibleError.httpStatus
+            httpHeaderFields = httpConvertibleError.httpHeaderFields
+            httpBody = httpConvertibleError.httpBody
+        } else if let httpConvertibleError = error as? (any HTTPResponseConvertible) {
+            httpStatus = httpConvertibleError.httpStatus
+            httpHeaderFields = httpConvertibleError.httpHeaderFields
+            httpBody = httpConvertibleError.httpBody
+        } else {
+            httpStatus = .internalServerError
+            httpHeaderFields = [:]
+            httpBody = nil
+        }
+
+        // Create new ServerError with full context
+        return ServerError(
+            operationID: context.operationID,
+            request: context.request,
+            requestBody: context.requestBody,
+            requestMetadata: context.requestMetadata,
+            operationInput: context.operationInput,
+            operationOutput: context.operationOutput,
+            causeDescription: causeDescription,
+            underlyingError: underlyingError,
+            httpStatus: httpStatus,
+            httpHeaderFields: httpHeaderFields,
+            httpBody: httpBody
+        )
+    }
+}

Sources/OpenAPIRuntime/Interface/UniversalClient.swift

@@ -98,6 +98,7 @@ import struct Foundation.URL
             }
         }
         let baseURL = serverURL
+        let errorHandler = converter.configuration.clientErrorHandler
         @Sendable func makeError(
             request: HTTPRequest? = nil,
             requestBody: HTTPBody? = nil,
@@ -106,34 +107,16 @@ import struct Foundation.URL
             responseBody: HTTPBody? = nil,
             error: any Error
         ) -> any Error {
-            if var error = error as? ClientError {
-                error.request = error.request ?? request
-                error.requestBody = error.requestBody ?? requestBody
-                error.baseURL = error.baseURL ?? baseURL
-                error.response = error.response ?? response
-                error.responseBody = error.responseBody ?? responseBody
-                return error
-            }
-            let causeDescription: String
-            let underlyingError: any Error
-            if let runtimeError = error as? RuntimeError {
-                causeDescription = runtimeError.prettyDescription
-                underlyingError = runtimeError.underlyingError ?? error
-            } else {
-                causeDescription = "Unknown"
-                underlyingError = error
-            }
-            return ClientError(
+            let context = ClientErrorContext(
                 operationID: operationID,
                 operationInput: input,
                 request: request,
                 requestBody: requestBody,
                 baseURL: baseURL,
                 response: response,
-                responseBody: responseBody,
-                causeDescription: causeDescription,
-                underlyingError: underlyingError
+                responseBody: responseBody
             )
+            return errorHandler.handleClientError(error, context: context)
         }
         let (request, requestBody): (HTTPRequest, HTTPBody?) = try await wrappingErrors {
             try serializer(input)