From f14b614e0ef4a1f60a5db1748966f6bc4826bb3c Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Tue, 11 Apr 2023 11:36:09 +0100 Subject: [PATCH 1/2] Fix documentation and add support for CI-ing it --- .../AsyncAwait/HTTPClientResponse.swift | 2 +- Sources/AsyncHTTPClient/Docs.docc/index.md | 28 ++++++++++--------- Sources/AsyncHTTPClient/HTTPClient.swift | 2 +- Sources/AsyncHTTPClient/HTTPHandler.swift | 4 +-- docker/docker-compose.2004.55.yaml | 3 ++ docker/docker-compose.2004.56.yaml | 3 ++ docker/docker-compose.2204.57.yaml | 3 ++ docker/docker-compose.2204.58.yaml | 3 ++ docker/docker-compose.2204.main.yaml | 3 ++ docker/docker-compose.yaml | 4 +++ scripts/check-docs.sh | 23 +++++++++++++++ 11 files changed, 61 insertions(+), 17 deletions(-) create mode 100755 scripts/check-docs.sh diff --git a/Sources/AsyncHTTPClient/AsyncAwait/HTTPClientResponse.swift b/Sources/AsyncHTTPClient/AsyncAwait/HTTPClientResponse.swift index 07904b681..f37489a89 100644 --- a/Sources/AsyncHTTPClient/AsyncAwait/HTTPClientResponse.swift +++ b/Sources/AsyncHTTPClient/AsyncAwait/HTTPClientResponse.swift @@ -87,7 +87,7 @@ extension HTTPClientResponse { self.storage = storage } - /// Accumulates `Body` of ``ByteBuffer``s into a single ``ByteBuffer``. + /// Accumulates `Body` of `ByteBuffer`s into a single `ByteBuffer`. /// - Parameters: /// - maxBytes: The maximum number of bytes this method is allowed to accumulate /// - Throws: `NIOTooManyBytesError` if the the sequence contains more than `maxBytes`. diff --git a/Sources/AsyncHTTPClient/Docs.docc/index.md b/Sources/AsyncHTTPClient/Docs.docc/index.md index 60e928e7d..3a05778ce 100644 --- a/Sources/AsyncHTTPClient/Docs.docc/index.md +++ b/Sources/AsyncHTTPClient/Docs.docc/index.md @@ -2,6 +2,8 @@ This package provides simple HTTP Client library built on top of SwiftNIO. +## Overview + This library provides the following: - First class support for Swift Concurrency (since version 1.9.0) - Asynchronous and non-blocking request methods @@ -17,7 +19,7 @@ This library provides the following: --- -## Getting Started +### Getting Started #### Adding the dependency @@ -71,13 +73,13 @@ httpClient.get(url: "https://apple.com/").whenComplete { result in } ``` -You should always shut down ``HTTPClient`` instances you created using ``HTTPClient/shutdown()-96ayw()``. Please note that you must not call ``HTTPClient/shutdown()-96ayw()`` before all requests of the HTTP client have finished, or else the in-flight requests will likely fail because their network connections are interrupted. +You should always shut down ``HTTPClient`` instances you created using ``HTTPClient/shutdown()-9gcpw``. Please note that you must not call ``HTTPClient/shutdown()-9gcpw`` before all requests of the HTTP client have finished, or else the in-flight requests will likely fail because their network connections are interrupted. -### async/await examples +#### async/await examples Examples for the async/await API can be found in the [`Examples` folder](https://github.com/swift-server/async-http-client/tree/main/Examples) in the repository. -## Usage guide +### Usage guide The default HTTP Method is `GET`. In case you need to have more control over the method, or you want to add headers or body, use the ``HTTPClientRequest`` struct: @@ -134,14 +136,14 @@ httpClient.execute(request: request).whenComplete { result in } ``` -### Redirects following +#### Redirects following Enable follow-redirects behavior using the client configuration: ```swift let httpClient = HTTPClient(eventLoopGroupProvider: .createNew, configuration: HTTPClient.Configuration(followRedirects: true)) ``` -### Timeouts +#### Timeouts Timeouts (connect and read) can also be set using the client configuration: ```swift let timeout = HTTPClient.Configuration.Timeout(connect: .seconds(1), read: .seconds(1)) @@ -153,11 +155,11 @@ or on a per-request basis: httpClient.execute(request: request, deadline: .now() + .milliseconds(1)) ``` -### Streaming +#### Streaming When dealing with larger amount of data, it's critical to stream the response body instead of aggregating in-memory. The following example demonstrates how to count the number of bytes in a streaming response body: -#### Using Swift Concurrency +##### Using Swift Concurrency ```swift let httpClient = HTTPClient(eventLoopGroupProvider: .createNew) do { @@ -189,7 +191,7 @@ do { try await httpClient.shutdown() ``` -#### Using HTTPClientResponseDelegate and SwiftNIO EventLoopFuture +##### Using HTTPClientResponseDelegate and SwiftNIO EventLoopFuture ```swift import NIOCore @@ -251,7 +253,7 @@ httpClient.execute(request: request, delegate: delegate).futureResult.whenSucces } ``` -### File downloads +#### File downloads Based on the `HTTPClientResponseDelegate` example above you can build more complex delegates, the built-in `FileDownloadDelegate` is one of them. It allows streaming the downloaded data @@ -280,7 +282,7 @@ client.execute(request: request, delegate: delegate).futureResult } ``` -### Unix Domain Socket Paths +#### Unix Domain Socket Paths Connecting to servers bound to socket paths is easy: ```swift let httpClient = HTTPClient(eventLoopGroupProvider: .createNew) @@ -314,7 +316,7 @@ let secureSocketPathBasedURL = URL( ) ``` -### Disabling HTTP/2 +#### Disabling HTTP/2 The exclusive use of HTTP/1 is possible by setting ``HTTPClient/Configuration/httpVersion-swift.property`` to ``HTTPClient/Configuration/HTTPVersion-swift.struct/http1Only`` on the ``HTTPClient/Configuration``: ```swift var configuration = HTTPClient.Configuration() @@ -325,7 +327,7 @@ let client = HTTPClient( ) ``` -## Security +### Security AsyncHTTPClient's security process is documented on [GitHub](https://github.com/swift-server/async-http-client/blob/main/SECURITY.md). diff --git a/Sources/AsyncHTTPClient/HTTPClient.swift b/Sources/AsyncHTTPClient/HTTPClient.swift index 9f25cc15c..a116ea495 100644 --- a/Sources/AsyncHTTPClient/HTTPClient.swift +++ b/Sources/AsyncHTTPClient/HTTPClient.swift @@ -228,7 +228,7 @@ public class HTTPClient { /// Shuts down the ``HTTPClient`` and releases its resources. /// /// - note: You cannot use this method if you sharted the ``HTTPClient`` with - /// ``init(eventLoopGroupProvider: .createNew)`` because that will shut down the ``EventLoopGroup`` the + /// `init(eventLoopGroupProvider: .createNew)` because that will shut down the `EventLoopGroup` the /// returned future would run in. public func shutdown() -> EventLoopFuture { switch self.eventLoopGroupProvider { diff --git a/Sources/AsyncHTTPClient/HTTPHandler.swift b/Sources/AsyncHTTPClient/HTTPHandler.swift index 278bf18a8..614c55f3a 100644 --- a/Sources/AsyncHTTPClient/HTTPHandler.swift +++ b/Sources/AsyncHTTPClient/HTTPHandler.swift @@ -388,7 +388,7 @@ public final class ResponseAccumulator: HTTPClientResponseDelegate { /// until it will abort the request and throw an ``ResponseTooBigError``. /// /// Default is 2^32. - /// - precondition: not allowed to exceed 2^32 because ``ByteBuffer`` can not store more bytes + /// - precondition: not allowed to exceed 2^32 because `ByteBuffer` can not store more bytes public let maxBodySize: Int public convenience init(request: HTTPClient.Request) { @@ -400,7 +400,7 @@ public final class ResponseAccumulator: HTTPClientResponseDelegate { /// - maxBodySize: Maximum size in bytes of the HTTP response body that ``ResponseAccumulator`` will accept /// until it will abort the request and throw an ``ResponseTooBigError``. /// Default is 2^32. - /// - precondition: maxBodySize is not allowed to exceed 2^32 because ``ByteBuffer`` can not store more bytes + /// - precondition: maxBodySize is not allowed to exceed 2^32 because `ByteBuffer` can not store more bytes /// - warning: You can use ``ResponseAccumulator`` for just one request. /// If you start another request, you need to initiate another ``ResponseAccumulator``. public init(request: HTTPClient.Request, maxBodySize: Int) { diff --git a/docker/docker-compose.2004.55.yaml b/docker/docker-compose.2004.55.yaml index 71b75c0fe..d181ef142 100644 --- a/docker/docker-compose.2004.55.yaml +++ b/docker/docker-compose.2004.55.yaml @@ -9,6 +9,9 @@ services: ubuntu_version: "focal" swift_version: "5.5" + documentation-check: + image: async-http-client:20.04-5.5 + test: image: async-http-client:20.04-5.5 command: /bin/bash -xcl "swift test --parallel -Xswiftc -warnings-as-errors $${SANITIZER_ARG-}" diff --git a/docker/docker-compose.2004.56.yaml b/docker/docker-compose.2004.56.yaml index ed61267a9..b496e8484 100644 --- a/docker/docker-compose.2004.56.yaml +++ b/docker/docker-compose.2004.56.yaml @@ -9,6 +9,9 @@ services: ubuntu_version: "focal" swift_version: "5.6" + documentation-check: + image: async-http-client:20.04-5.6 + test: image: async-http-client:20.04-5.6 environment: [] diff --git a/docker/docker-compose.2204.57.yaml b/docker/docker-compose.2204.57.yaml index bea713bad..78eb83e1c 100644 --- a/docker/docker-compose.2204.57.yaml +++ b/docker/docker-compose.2204.57.yaml @@ -9,6 +9,9 @@ services: ubuntu_version: "jammy" swift_version: "5.7" + documentation-check: + image: async-http-client:22.04-5.7 + test: image: async-http-client:22.04-5.7 environment: [] diff --git a/docker/docker-compose.2204.58.yaml b/docker/docker-compose.2204.58.yaml index d5dc8432e..2d3a300d8 100644 --- a/docker/docker-compose.2204.58.yaml +++ b/docker/docker-compose.2204.58.yaml @@ -8,6 +8,9 @@ services: args: base_image: "swiftlang/swift:nightly-5.8-jammy" + documentation-check: + image: async-http-client:22.04-5.8 + test: image: async-http-client:22.04-5.8 environment: diff --git a/docker/docker-compose.2204.main.yaml b/docker/docker-compose.2204.main.yaml index 9132ed322..8dfa4c921 100644 --- a/docker/docker-compose.2204.main.yaml +++ b/docker/docker-compose.2204.main.yaml @@ -8,6 +8,9 @@ services: args: base_image: "swiftlang/swift:nightly-main-jammy" + documentation-check: + image: async-http-client:22.04-main + test: image: async-http-client:22.04-main environment: diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yaml index 803fad9b1..9ac4a6eea 100644 --- a/docker/docker-compose.yaml +++ b/docker/docker-compose.yaml @@ -26,6 +26,10 @@ services: <<: *common command: /bin/bash -xcl "./scripts/soundness.sh" + documentation-check: + <<: *common + command: /bin/bash -xcl "./scripts/check-docs.sh" + test: <<: *common command: /bin/bash -xcl "swift test --parallel -Xswiftc -warnings-as-errors --enable-test-discovery $${SANITIZER_ARG-} $${IMPORT_CHECK_ARG-}" diff --git a/scripts/check-docs.sh b/scripts/check-docs.sh new file mode 100755 index 000000000..9405b7eb4 --- /dev/null +++ b/scripts/check-docs.sh @@ -0,0 +1,23 @@ +#!/bin/bash +##===----------------------------------------------------------------------===## +## +## This source file is part of the SwiftNIO open source project +## +## Copyright (c) 2023 Apple Inc. and the SwiftNIO project authors +## Licensed under Apache License v2.0 +## +## See LICENSE.txt for license information +## See CONTRIBUTORS.txt for the list of SwiftNIO project authors +## +## SPDX-License-Identifier: Apache-2.0 +## +##===----------------------------------------------------------------------===## + +set -eu + +raw_targets=$(sed -E -n -e 's/^.* - documentation_targets: \[(.*)\].*$/\1/p' .spi.yml) +targets=(${raw_targets//,/ }) + +for target in "${targets[@]}"; do + swift package plugin generate-documentation --target "$target" --warnings-as-errors --analyze --level detailed +done From 7bbb289f56df9b514c70b66611a27a8def699ae9 Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Tue, 11 Apr 2023 11:43:32 +0100 Subject: [PATCH 2/2] Fixup license header --- scripts/check-docs.sh | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/scripts/check-docs.sh b/scripts/check-docs.sh index 9405b7eb4..61a13a56f 100755 --- a/scripts/check-docs.sh +++ b/scripts/check-docs.sh @@ -1,13 +1,13 @@ #!/bin/bash ##===----------------------------------------------------------------------===## ## -## This source file is part of the SwiftNIO open source project +## This source file is part of the AsyncHTTPClient open source project ## -## Copyright (c) 2023 Apple Inc. and the SwiftNIO project authors +## Copyright (c) 2023 Apple Inc. and the AsyncHTTPClient project authors ## Licensed under Apache License v2.0 ## ## See LICENSE.txt for license information -## See CONTRIBUTORS.txt for the list of SwiftNIO project authors +## See CONTRIBUTORS.txt for the list of AsyncHTTPClient project authors ## ## SPDX-License-Identifier: Apache-2.0 ##