Add RetryingClientMiddleware example (#433)

### Motivation

Adds a retrying middleware example.

### Modifications

Ditto.

### Result

Now we can point to how to do retries in a middleware, the part about
potentially calling `next` multiple times might not be immediately
obvious, so it's an important example to show.

### Test Plan

Tested manually by tweaking a local server to return 500 randomly and
saw the retry work.

---------

Co-authored-by: Si Beaumont <[email protected]>

Author: czechboy0

Examples/README.md

@@ -23,6 +23,12 @@ The following packages show working with various content types, such as JSON, UR
 - [`SwaggerUIEndpointsServer`](./SwaggerUIEndpointsServer) - a server that vends its OpenAPI document as a raw file and also provides a rendered documentation viewer using swagger-ui.
 - [`PostgresDatabaseServer`](./PostgresDatabaseServer) - a server using Postgres for persistent state.
 
+## Middleware
+
+- [`LoggingMiddlewareOSLog`](./LoggingMiddlewareOSLog) - a client middleware that logs requests and responses using OSLog.
+- [`LoggingMiddlewareSwiftLog`](./LoggingMiddlewareSwiftLog) - a client and server middleware that logs requests and responses using SwiftLog.
+- [`RetryingClientMiddleware`](./RetryingClientMiddleware) - a client middleware that retries failed requests.
+
 ## Project and target types
 
 The following examples show various ways that Swift OpenAPI Generator can be adopted from a consumer Swift package or an Xcode project.

Examples/RetryingClientMiddleware/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.build
+/Packages
+/*.xcodeproj
+xcuserdata/
+DerivedData/
+.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
+.vscode
+/Package.resolved
+.ci/
+.docc-build/

Examples/RetryingClientMiddleware/Package.swift

@@ -0,0 +1,43 @@
+// swift-tools-version:5.9
+//===----------------------------------------------------------------------===//
+//
+// 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 PackageDescription
+
+let package = Package(
+    name: "RetryingClientMiddleware",
+    platforms: [.macOS(.v10_15), .iOS(.v13), .tvOS(.v13), .watchOS(.v6), .visionOS(.v1)],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-openapi-generator", exact: "1.0.0-alpha.1"),
+        .package(url: "https://github.com/apple/swift-openapi-runtime", exact: "1.0.0-alpha.1"),
+        .package(url: "https://github.com/apple/swift-openapi-urlsession", exact: "1.0.0-alpha.1"),
+        .package(url: "https://github.com/apple/swift-http-types", from: "1.0.0"),
+    ],
+    targets: [
+        .target(
+            name: "RetryingClientMiddleware",
+            dependencies: [
+                .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),
+                .product(name: "HTTPTypes", package: "swift-http-types"),
+            ]
+        ),
+        .executableTarget(
+            name: "HelloWorldURLSessionClient",
+            dependencies: [
+                "RetryingClientMiddleware", .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),
+                .product(name: "OpenAPIURLSession", package: "swift-openapi-urlsession"),
+            ],
+            plugins: [.plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator")]
+        ),
+    ]
+)

Examples/RetryingClientMiddleware/README.md

@@ -0,0 +1,32 @@
+# Client Retrying Middleware
+
+In this example we'll implement a `ClientMiddleware` that retries certain failed responses again.
+
+## Overview
+
+This example extends the [HelloWorldURLSessionClient](../HelloWorldURLSessionClient)
+with a new target, `RetryingClientMiddleware`, which is then used when creating
+the `Client`.
+
+Requests with a body are only retried if the request body has `iterationPolicy` of `multiple`, as otherwise
+the request body cannot be iterated again. 
+
+NOTE: This example shows just one way of retrying HTTP failures in a middleware
+and is purely for illustrative purposes.
+
+The tool uses the [URLSession](https://developer.apple.com/documentation/foundation/urlsession) API to perform the HTTP call, wrapped in the [Swift OpenAPI URLSession Transport](https://github.com/apple/swift-openapi-urlsession).
+
+The server can be started by running the any of the `HelloWorld*Server` examples locally.
+
+## Usage
+
+Build and run the client CLI using:
+
+```
+$ swift run
+Attempt 1
+Retrying with code 500
+Attempt 2
+Returning the received response, either because of success or ran out of attempts.
+Hello, Stranger!
+```

Examples/RetryingClientMiddleware/Sources/HelloWorldURLSessionClient/HelloWorldURLSessionClient.swift

@@ -0,0 +1,34 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 OpenAPIURLSession
+import Foundation
+import RetryingClientMiddleware
+
+@main struct HelloWorldURLSessionClient {
+    static func main() async throws {
+        let client = Client(
+            serverURL: URL(string: "http://localhost:8080/api")!,
+            transport: URLSessionTransport(),
+            middlewares: [
+                RetryingMiddleware(
+                    signals: [.code(429), .range(500..<600), .errorThrown],
+                    policy: .upToAttempts(count: 3),
+                    delay: .constant(seconds: 1)
+                )
+            ]
+        )
+        let response = try await client.getGreeting()
+        print(try response.ok.body.json.message)
+    }
+}

Examples/RetryingClientMiddleware/Sources/HelloWorldURLSessionClient/openapi-generator-config.yaml

@@ -0,0 +1,3 @@
+generate:
+  - types
+  - client

Examples/RetryingClientMiddleware/Sources/HelloWorldURLSessionClient/openapi.yaml

@@ -0,0 +1,36 @@
+openapi: '3.1.0'
+info:
+  title: GreetingService
+  version: 1.0.0
+servers:
+  - url: https://example.com/api
+    description: Example service deployment.
+paths:
+  /greet:
+    get:
+      operationId: getGreeting
+      parameters:
+        - name: name
+          required: false
+          in: query
+          description: The name used in the returned greeting.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: A success response with a greeting.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Greeting'
+components:
+  schemas:
+    Greeting:
+      type: object
+      description: A value with the greeting contents.
+      properties:
+        message:
+          type: string
+          description: The string representation of the greeting.
+      required:
+        - message

Examples/RetryingClientMiddleware/Sources/RetryingClientMiddleware/RetryingClientMiddleware.swift

@@ -0,0 +1,142 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 OpenAPIRuntime
+import Foundation
+import HTTPTypes
+
+/// A middleware that retries the request under certain conditions.
+///
+/// Only meant to be used for illustrative purposes.
+package struct RetryingMiddleware {
+
+    /// The failure signal that can lead to a retried request.
+    package enum RetryableSignal: Hashable {
+
+        /// Retry if the response code matches this code.
+        case code(Int)
+
+        /// Retry if the response code falls into this range.
+        case range(Range<Int>)
+
+        /// Retry if an error is thrown by a downstream middleware or transport.
+        case errorThrown
+    }
+
+    /// The policy to use when a retryable signal hints that a retry might be appropriate.
+    package enum RetryingPolicy: Hashable {
+
+        /// Don't retry.
+        case never
+
+        /// Retry up to the provided number of attempts.
+        case upToAttempts(count: Int)
+    }
+
+    /// The policy of delaying the retried request.
+    package enum DelayPolicy: Hashable {
+
+        /// Don't delay, retry immediately.
+        case none
+
+        /// Constant delay.
+        case constant(seconds: TimeInterval)
+    }
+
+    /// The signals that lead to the retry policy being evaluated.
+    package var signals: Set<RetryableSignal>
+
+    /// The policy used to evaluate whether to perform a retry.
+    package var policy: RetryingPolicy
+
+    /// The delay policy for retries.
+    package var delay: DelayPolicy
+
+    /// Creates a new retrying middleware.
+    /// - Parameters:
+    ///   - signals: The signals that lead to the retry policy being evaluated.
+    ///   - policy: The policy used to evaluate whether to perform a retry.
+    ///   - delay: The delay policy for retries.
+    package init(
+        signals: Set<RetryableSignal> = [.code(429), .range(500..<600), .errorThrown],
+        policy: RetryingPolicy = .upToAttempts(count: 3),
+        delay: DelayPolicy = .constant(seconds: 1)
+    ) {
+        self.signals = signals
+        self.policy = policy
+        self.delay = delay
+    }
+}
+
+extension RetryingMiddleware: ClientMiddleware {
+    package func intercept(
+        _ request: HTTPRequest,
+        body: HTTPBody?,
+        baseURL: URL,
+        operationID: String,
+        next: (HTTPRequest, HTTPBody?, URL) async throws -> (HTTPResponse, HTTPBody?)
+    ) async throws -> (HTTPResponse, HTTPBody?) {
+        guard case .upToAttempts(count: let maxAttemptCount) = policy else {
+            return try await next(request, body, baseURL)
+        }
+        if let body { guard body.iterationBehavior == .multiple else { return try await next(request, body, baseURL) } }
+        func willRetry() async throws {
+            switch delay {
+            case .none: return
+            case .constant(seconds: let seconds): try await Task.sleep(nanoseconds: UInt64(seconds * 1_000_000_000))
+            }
+        }
+        for attempt in 1...maxAttemptCount {
+            print("Attempt \(attempt)")
+            let (response, responseBody): (HTTPResponse, HTTPBody?)
+            if signals.contains(.errorThrown) {
+                do { (response, responseBody) = try await next(request, body, baseURL) } catch {
+                    if attempt == maxAttemptCount {
+                        throw error
+                    } else {
+                        print("Retrying after an error")
+                        try await willRetry()
+                        continue
+                    }
+                }
+            } else {
+                (response, responseBody) = try await next(request, body, baseURL)
+            }
+            if signals.contains(response.status.code) && attempt < maxAttemptCount {
+                print("Retrying with code \(response.status.code)")
+                try await willRetry()
+                continue
+            } else {
+                print("Returning the received response, either because of success or ran out of attempts.")
+                return (response, responseBody)
+            }
+        }
+        preconditionFailure("Unreachable")
+    }
+}
+
+extension Set where Element == RetryingMiddleware.RetryableSignal {
+    /// Checks whether the provided response code matches the retryable signals.
+    /// - Parameter code: The provided code to check.
+    /// - Returns: `true` if the code matches at least one of the signals, `false` otherwise.
+    func contains(_ code: Int) -> Bool {
+        for signal in self {
+            switch signal {
+            case .code(let int): if code == int { return true }
+            case .range(let range): if range.contains(code) { return true }
+            case .errorThrown: break
+            }
+        }
+        return false
+    }
+}