From ce83016e4bbcb86a0b25ff5a33ba069a87f26fb8 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Tue, 28 Jul 2026 10:09:12 -0700 Subject: [PATCH 1/3] initial pass fleshing out full API coverage and grammar/punctuation/spelling fixes --- README.md | 10 +-- SECURITY.md | 2 +- .../Client/HTTP2ClientTransport.swift | 12 ++- .../Client/Resolver/NameResolver+DNS.swift | 5 +- .../Client/Resolver/NameResolver+IPv4.swift | 5 +- .../Client/Resolver/NameResolver+IPv6.swift | 5 +- .../Client/Resolver/NameResolver+UDS.swift | 10 ++- .../Client/Resolver/NameResolver+VSOCK.swift | 8 +- .../Client/Resolver/NameResolver.swift | 36 ++++---- .../Resolver/NameResolverRegistry.swift | 6 +- .../Client/Resolver/SocketAddress.swift | 24 ++++-- .../WrappedChannel+Config.swift | 2 + .../WrappedChannel/WrappedChannel.swift | 85 ++++++++++--------- .../Documentation.docc/Documentation.md | 4 + .../HTTP2ClientTransport.Config.Connection.md | 18 ++++ .../reference/HTTP2ClientTransport.Config.md | 18 ++++ ...P2ClientTransport.WrappedChannel.Config.md | 17 ++++ .../HTTP2ClientTransport.WrappedChannel.md | 22 +++++ .../reference/HTTP2ClientTransport.md | 11 +++ .../HTTP2ServerTransport.Config.Connection.md | 23 +++++ .../reference/HTTP2ServerTransport.Config.md | 19 +++++ ...2ServerTransport.ConnectionConfigurator.md | 12 +++ .../HTTP2ServerTransport.Custom.Config.md | 16 ++++ .../reference/HTTP2ServerTransport.Custom.md | 18 ++++ .../reference/HTTP2ServerTransport.md | 14 +++ .../reference/NameResolver.md | 14 +++ .../SocketAddress.VirtualSocket.ContextID.md | 20 +++++ .../SocketAddress.VirtualSocket.Port.md | 17 ++++ .../reference/SocketAddress.VirtualSocket.md | 21 +++++ .../reference/SocketAddress.md | 35 ++++++++ .../Documentation.docc/reference/TLSConfig.md | 14 +++ .../GRPCNIOTransportBytes.swift | 7 +- .../Server/ConnectionConfigurator.swift | 2 +- .../Server/CustomTransport.swift | 5 +- .../Server/HTTP2ServerTransport.swift | 22 +++-- .../Server/ListenerConfigurator.swift | 4 +- Sources/GRPCNIOTransportCore/TLSConfig.swift | 17 ++-- .../Documentation.docc/Documentation.md | 50 +++++++++-- .../Config+TLS.swift | 38 +++++---- .../Documentation.docc/Documentation.md | 16 ++-- .../HTTP2ClientTransport.Posix.Config.md | 17 ++++ ...ntTransport.Posix.TransportSecurity.TLS.md | 22 +++++ ...ClientTransport.Posix.TransportSecurity.md | 20 +++++ .../reference/HTTP2ClientTransport.Posix.md | 21 +++++ .../HTTP2ServerTransport.Posix.Config.md | 17 ++++ ...erTransport.Posix.TransportSecurity.TLS.md | 22 +++++ ...ServerTransport.Posix.TransportSecurity.md | 19 +++++ .../reference/HTTP2ServerTransport.Posix.md | 23 +++++ .../HTTP2ClientTransport+Posix.swift | 10 ++- .../HTTP2ServerTransport+Posix.swift | 28 +++--- .../Config+TLS.swift | 38 +++++---- .../Documentation.docc/Documentation.md | 19 +++-- ...lientTransport.TransportServices.Config.md | 18 ++++ ...P2ClientTransport.TransportServices.TLS.md | 20 +++++ ...ort.TransportServices.TransportSecurity.md | 18 ++++ .../HTTP2ClientTransport.TransportServices.md | 22 +++++ ...erverTransport.TransportServices.Config.md | 17 ++++ ...P2ServerTransport.TransportServices.TLS.md | 20 +++++ ...ort.TransportServices.TransportSecurity.md | 16 ++++ .../HTTP2ServerTransport.TransportServices.md | 21 +++++ ...TP2ClientTransport+TransportServices.swift | 13 ++- ...TP2ServerTransport+TransportServices.swift | 14 +-- 62 files changed, 933 insertions(+), 186 deletions(-) create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.Config.Connection.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.Config.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.WrappedChannel.Config.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.WrappedChannel.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Config.Connection.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Config.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.ConnectionConfigurator.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Custom.Config.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Custom.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/NameResolver.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.VirtualSocket.ContextID.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.VirtualSocket.Port.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.VirtualSocket.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.md create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/reference/TLSConfig.md create mode 100644 Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.Config.md create mode 100644 Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.TransportSecurity.TLS.md create mode 100644 Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.TransportSecurity.md create mode 100644 Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.md create mode 100644 Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.Config.md create mode 100644 Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.TransportSecurity.TLS.md create mode 100644 Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.TransportSecurity.md create mode 100644 Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.md create mode 100644 Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.Config.md create mode 100644 Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.TLS.md create mode 100644 Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.TransportSecurity.md create mode 100644 Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.md create mode 100644 Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.Config.md create mode 100644 Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.TLS.md create mode 100644 Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.TransportSecurity.md create mode 100644 Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.md diff --git a/README.md b/README.md index 846a1f44..0431b512 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,14 @@ This repository contains high-performance HTTP/2 client and server transport implementations for [gRPC Swift][gh-grpc-swift-2] built on top of [SwiftNIO][gh-swift-nio]. -- πŸ“š **Documentation** is available on the [Swift Package Index][spi-grpc-swift-nio-transport] +- πŸ“š **Documentation** is available on the [Swift Package Index][spi-grpc-swift-nio-transport]. - πŸŽ“ **Tutorials** are available in the documentation for `grpc/grpc-swift-2` on the [Swift Package Index][spi-grpc-swift-2]. - πŸ’» **Examples** are available in the `Examples` directory of the - [`grpc/grpc-swift-2`][gh-grpc-swift-2] repository -- πŸš€ **Contributions** are welcome, please see [CONTRIBUTING.md](CONTRIBUTING.md) -- πŸͺͺ **License** is Apache 2.0, repeated in [LICENSE](License) -- πŸ”’ **Security** issues should be reported via the process in [SECURITY.md](SECURITY.md) + [`grpc/grpc-swift-2`](https://github.com/grpc/grpc-swift-2) repository. +- πŸš€ **Contributions** are welcome, please see [CONTRIBUTING.md](CONTRIBUTING.md). +- πŸͺͺ **License** is Apache 2.0, repeated in [LICENSE](License). +- πŸ”’ **Security** issues should be reported via the process in [SECURITY.md](SECURITY.md). [gh-swift-nio]: https://github.com/apple/swift-nio [gh-grpc-swift-2]: https://github.com/grpc/grpc-swift-2 diff --git a/SECURITY.md b/SECURITY.md index 1b59d329..05beaa1a 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,4 +1,4 @@ # Security -Please refer to [SECURITY.md] in the +Please refer to [SECURITY.md](https://github.com/grpc/grpc-swift-2/blob/main/SECURITY.md) in the [`grpc/grpc-swift-2`](https://github.com/grpc/grpc-swift-2) repository. diff --git a/Sources/GRPCNIOTransportCore/Client/HTTP2ClientTransport.swift b/Sources/GRPCNIOTransportCore/Client/HTTP2ClientTransport.swift index 6563e052..e4aea749 100644 --- a/Sources/GRPCNIOTransportCore/Client/HTTP2ClientTransport.swift +++ b/Sources/GRPCNIOTransportCore/Client/HTTP2ClientTransport.swift @@ -29,6 +29,7 @@ extension HTTP2ClientTransport { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ClientTransport.Config { + /// Compression configuration for the client transport. public struct Compression: Sendable, Hashable { /// The default algorithm used for compressing outbound messages. /// @@ -54,6 +55,7 @@ extension HTTP2ClientTransport.Config { } } + /// Keepalive configuration for the client transport. public struct Keepalive: Sendable, Hashable { /// The amount of time to wait after reading data before sending a keepalive ping. /// @@ -75,6 +77,7 @@ extension HTTP2ClientTransport.Config { } } + /// Connection management configuration for the client transport. public struct Connection: Sendable, Hashable { /// The maximum amount of time a connection may be idle before it's closed. /// @@ -127,6 +130,7 @@ extension HTTP2ClientTransport.Config { } } + /// Configuration for the backoff used between connection attempts. public struct Backoff: Sendable, Hashable { /// The initial duration to wait before reattempting to establish a connection. public var initial: Duration @@ -152,13 +156,14 @@ extension HTTP2ClientTransport.Config { self.jitter = jitter } - /// Default values, initial backoff is one second and maximum back off is two minutes. The + /// Default values, initial backoff is one second and maximum backoff is two minutes. The /// multiplier is `1.6` and the jitter is set to `0.2`. public static var defaults: Self { Self(initial: .seconds(1), max: .seconds(120), multiplier: 1.6, jitter: 0.2) } } + /// HTTP/2-level configuration for the client transport. public struct HTTP2: Sendable, Hashable { /// The max frame size, in bytes. /// @@ -175,7 +180,7 @@ extension HTTP2ClientTransport.Config { /// /// Any value set here will unconditionally override any value derived from the target address. /// - /// The server authority is used in the ":authority" pseudoheader and in the TLS SNI + /// The server authority is used in the `:authority` pseudo-header and in the TLS SNI /// extension, if applicable. public var authority: String? @@ -206,6 +211,7 @@ extension HTTP2ClientTransport.Config { /// A callback invoked with each new HTTP/2 stream. public var onCreateHTTP2Stream: (@Sendable (_ channel: any Channel) -> EventLoopFuture)? + /// Creates a new set of channel debugging callbacks. public init( onCreateTCPConnection: (@Sendable (_ channel: any Channel) -> EventLoopFuture)?, onCreateHTTP2Stream: (@Sendable (_ channel: any Channel) -> EventLoopFuture)? @@ -229,7 +235,7 @@ extension HTTP2ClientTransport.Config.Connection { /// until one of the following conditions is met: /// 1. ``maxFlushDelay`` has elapsed since a flush was first requested, /// 2. At least ``maxBytes`` bytes have been written since the previous flush, or - /// 3. The channel becomes unwritable (i.e. the outbound buffer has hit the high-water mark). + /// 3. The channel becomes unwritable (that is, the outbound buffer has hit the high-water mark). /// /// This means that under high load, writes naturally accumulate and are flushed together in /// fewer, larger batches. This reduces per-write overhead and typically improves both throughput diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+DNS.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+DNS.swift index aa6955af..da79acca 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+DNS.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+DNS.swift @@ -31,7 +31,7 @@ extension ResolvableTargets { /// If no port is specified then 443 is used. public var port: Int? - /// Create a new DNS target. + /// Creates a new DNS target. /// - Parameters: /// - host: The host to resolve via DNS. /// - port: The port to use with resolved addresses. @@ -60,9 +60,10 @@ extension NameResolvers { public struct DNS: NameResolverFactory, Sendable { public typealias Target = ResolvableTargets.DNS - /// Create a new DNS name resolver factory. + /// Creates a new DNS name resolver factory. public init() {} + /// Creates a resolver for the given DNS target. public func resolver(for target: Target) -> NameResolver { let resolver = Self.Resolver(target: target) // Only append the port if explicitly set. If it's nil the default port of 443 is used diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv4.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv4.swift index b43a1c2e..948295f6 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv4.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv4.swift @@ -29,7 +29,7 @@ extension ResolvableTargets { /// This array must not be empty. public var addresses: [SocketAddress.IPv4] - /// Create a new IPv4 target. + /// Creates a new IPv4 target. /// - Parameter addresses: The IPv4 addresses. Must not be empty. public init(addresses: [SocketAddress.IPv4]) { debugOnly { @@ -98,9 +98,10 @@ extension NameResolvers { public struct IPv4: NameResolverFactory, Sendable { public typealias Target = ResolvableTargets.IPv4 - /// Create a new IPv4 resolver factory. + /// Creates a new IPv4 resolver factory. public init() {} + /// Creates a resolver for the given IPv4 target. public func resolver(for target: Target) -> NameResolver { let endpoints = target.addresses.map { Endpoint(addresses: [.ipv4($0)]) } let resolutionResult = NameResolutionResult(endpoints: endpoints, serviceConfig: nil) diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv6.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv6.swift index 98ff9361..32b65822 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv6.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv6.swift @@ -29,7 +29,7 @@ extension ResolvableTargets { /// This array must not be empty. public var addresses: [SocketAddress.IPv6] - /// Create a new IPv6 target. + /// Creates a new IPv6 target. /// - Parameter addresses: The IPv6 addresses. Must not be empty. public init(addresses: [SocketAddress.IPv6]) { debugOnly { @@ -97,9 +97,10 @@ extension NameResolvers { public struct IPv6: NameResolverFactory, Sendable { public typealias Target = ResolvableTargets.IPv6 - /// Create a new IPv6 resolver factory. + /// Creates a new IPv6 resolver factory. public init() {} + /// Creates a resolver for the given IPv6 target. public func resolver(for target: Target) -> NameResolver { let endpoints = target.addresses.map { Endpoint(addresses: [.ipv6($0)]) } let resolutionResult = NameResolutionResult(endpoints: endpoints, serviceConfig: nil) diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+UDS.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+UDS.swift index 74036839..4db678a7 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+UDS.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+UDS.swift @@ -18,10 +18,10 @@ internal import GRPCCore @available(gRPCSwiftNIOTransport 2.0, *) extension ResolvableTargets { - /// A resolvable target for Unix Domain Socket address. + /// A resolvable target for a Unix Domain Socket address. /// /// ``UnixDomainSocket`` addresses can be resolved by the ``NameResolvers/UnixDomainSocket`` - /// resolver which creates a single ``Endpoint`` for target address. + /// resolver which creates a single ``Endpoint`` for the target address. public struct UnixDomainSocket: ResolvableTarget, Sendable { /// The Unix Domain Socket address. public var address: SocketAddress.UnixDomainSocket @@ -31,7 +31,7 @@ extension ResolvableTargets { /// If unset then the path of the address will be used. public var authority: String? - /// Create a new Unix Domain Socket address. + /// Creates a new Unix Domain Socket target. public init(address: SocketAddress.UnixDomainSocket, authority: String?) { self.address = address self.authority = authority @@ -42,7 +42,7 @@ extension ResolvableTargets { @available(gRPCSwiftNIOTransport 2.0, *) extension ResolvableTarget where Self == ResolvableTargets.UnixDomainSocket { /// Creates a new resolvable Unix Domain Socket target. - /// - Parameters + /// - Parameters: /// - path: The path of the socket. /// - authority: The service authority. public static func unixDomainSocket( @@ -65,8 +65,10 @@ extension NameResolvers { public struct UnixDomainSocket: NameResolverFactory, Sendable { public typealias Target = ResolvableTargets.UnixDomainSocket + /// Creates a new Unix Domain Socket resolver factory. public init() {} + /// Creates a resolver for the given Unix Domain Socket target. public func resolver(for target: Target) -> NameResolver { let endpoint = Endpoint(addresses: [.unixDomainSocket(target.address)]) let resolutionResult = NameResolutionResult(endpoints: [endpoint], serviceConfig: nil) diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+VSOCK.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+VSOCK.swift index d54d83e7..ddd6049f 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+VSOCK.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+VSOCK.swift @@ -21,10 +21,12 @@ extension ResolvableTargets { /// A resolvable target for Virtual Socket addresses. /// /// ``VirtualSocket`` addresses can be resolved by the ``NameResolvers/VirtualSocket`` - /// resolver which creates a single ``Endpoint`` for target address. + /// resolver which creates a single ``Endpoint`` for the target address. public struct VirtualSocket: ResolvableTarget, Sendable { + /// The VSOCK address. public var address: SocketAddress.VirtualSocket + /// Creates a new resolvable VSOCK target. public init(address: SocketAddress.VirtualSocket) { self.address = address } @@ -35,7 +37,7 @@ extension ResolvableTargets { extension ResolvableTarget where Self == ResolvableTargets.VirtualSocket { /// Creates a new resolvable Virtual Socket target. /// - Parameters: - /// - contextID: The context ID ('cid') of the service. + /// - contextID: The context ID (`cid`) of the service. /// - port: The port to connect to. public static func vsock( contextID: SocketAddress.VirtualSocket.ContextID, @@ -55,8 +57,10 @@ extension NameResolvers { public struct VirtualSocket: NameResolverFactory, Sendable { public typealias Target = ResolvableTargets.VirtualSocket + /// Creates a new VSOCK resolver factory. public init() {} + /// Creates a resolver for the given VSOCK target. public func resolver(for target: Target) -> NameResolver { let endpoint = Endpoint(addresses: [.vsock(target.address)]) let resolutionResult = NameResolutionResult(endpoints: [endpoint], serviceConfig: nil) diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver.swift index fb119d9b..287b271f 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver.swift @@ -23,12 +23,12 @@ public import GRPCCore /// Resolvers may be **push-based** or **pull-based**: /// /// - **Push-based resolvers** (``UpdateMode-swift.struct/push``): Addresses are pushed to the -/// resolver by an external source (e.g., file watcher, service discovery subscription). The -/// channel subscribes to changes by awaiting new values in a loop. +/// resolver by an external source (for example, a file watcher or service discovery +/// subscription). The channel subscribes to changes by awaiting new values in a loop. /// /// - **Pull-based resolvers** (``UpdateMode-swift.struct/pull``): Addresses are resolved on-demand. -/// The channel requests new results as and when needed (e.g., after receiving a `GOAWAY` from -/// the server) by calling `next()`. Each `next()` call should attempt resolution. +/// The channel requests new results as and when needed (for example, after receiving a `GOAWAY` +/// from the server) by calling `next()`. Each `next()` call should attempt resolution. /// /// ## Resolver semantics /// @@ -45,8 +45,8 @@ public import GRPCCore /// /// ### Error handling /// -/// When resolution fails (e.g., DNS timeout, network unreachable, service discovery unavailable), -/// resolvers may throw an error. If the resolver throws errors then it **must** be +/// When resolution fails (for example, a DNS timeout, unreachable network, or unavailable service +/// discovery), resolvers may throw an error. If the resolver throws errors then it **must** be /// **re-iterable**: calling `makeAsyncIterator()` multiple times must return independent iterators /// that can each attempt resolution. /// @@ -74,8 +74,8 @@ public import GRPCCore /// `makeAsyncIterator()` again. /// /// - **Push-based resolvers**: If the external source closes the subscription cleanly -/// (e.g., service discovery server restart, watch stream closes), the iterator may return nil. -/// The channel will re-establish a fresh subscription by creating a new iterator. +/// (for example, a service discovery server restart or a closed watch stream), the iterator may +/// return nil. The channel will re-establish a fresh subscription by creating a new iterator. /// /// - **Pull-based resolvers**: Should not return nil. Each `next()` call should either return /// a result or throw an error. @@ -85,26 +85,28 @@ public import GRPCCore /// `CancellationError`, the channel will **not** create a new iterator (as shutdown is in /// progress). /// -/// ## Resolver Patterns +/// ## Resolver patterns /// -/// ### Push based +/// ### Push-based /// -/// **When to use**: Consuming subscription based external sources like service discovery. +/// **When to use**: Consuming subscription-based external sources like service discovery. /// /// - `makeAsyncIterator()`: Each call establishes a new subscription to the external source. /// - `next()`: Yields updates from the subscription. Throws when the subscription fails. -/// May return `nil` when the source closes cleanly (e.g., server restart, connection closed). +/// May return `nil` when the source closes cleanly (for example, a server restart or closed +/// connection). /// - Error handling: Throw errors on subscription failure. Return nil on clean closure. /// The channel will create a new iterator after exponential backoff in either case. Must /// throw `CancellationError` when cancelled. /// -/// ### Pull based +/// ### Pull-based /// -/// **When to use**: Static addresses that never change or on-demand resolution (e.g., DNS lookup). +/// **When to use**: Static addresses that never change, or on-demand resolution (for example, a +/// DNS lookup). /// /// - `makeAsyncIterator()`: Each call returns a fresh, independent iterator. /// - `next()`: Attempts resolution each time it's called. Throws on resolution failure -/// (e.g., DNS timeout, network unreachable). +/// (for example, a DNS timeout or unreachable network). /// - Error handling: Throw errors on resolution failure. The channel will create a new iterator /// after exponential backoff. @available(gRPCSwiftNIOTransport 2.0, *) @@ -121,6 +123,7 @@ public struct NameResolver: Sendable { /// The authority of the service. public let authority: String? + /// Whether a resolver pushes new results, or produces them only on request. public struct UpdateMode: Hashable, Sendable { enum Value: Hashable, Sendable { case push @@ -133,7 +136,7 @@ public struct NameResolver: Sendable { self.value = value } - /// Addresses are pushed to the resolve by an external source. + /// Addresses are pushed to the resolver by an external source. public static var push: Self { Self(.push) } /// Addresses are resolved lazily, when the caller asks them to be resolved. @@ -163,6 +166,7 @@ public struct NameResolutionResult: Hashable, Sendable { /// This value may be `nil` if the resolver doesn't support fetching service configuration. public var serviceConfig: Result? + /// Creates a new name resolution result. public init( endpoints: [Endpoint], serviceConfig: Result? diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolverRegistry.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolverRegistry.swift index 1e7956d8..bebcf636 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolverRegistry.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolverRegistry.swift @@ -117,7 +117,7 @@ public struct NameResolverRegistry { private var factories: [Factory] - /// Creates a new name resolver registry with no resolve factories. + /// Creates a new name resolver registry with no resolver factories. public init() { self.factories = [] } @@ -187,8 +187,8 @@ public struct NameResolverRegistry { /// Returns whether the registry contains a factory capable of resolving the given target. /// - /// - Parameter target: - /// - Returns: Whether the registry contains a resolve capable of resolving the target. + /// - Parameter target: The target to check. + /// - Returns: Whether the registry contains a resolver capable of resolving the target. public func containsFactory(capableOfResolving target: some ResolvableTarget) -> Bool { self.factories.contains { $0.hasTarget(target) } } diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/SocketAddress.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/SocketAddress.swift index 0e71f93f..3ce0f40c 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/SocketAddress.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/SocketAddress.swift @@ -49,7 +49,7 @@ public struct SocketAddress: Hashable, Sendable { } } - /// Returns the address as an Unix domain socket address, if possible. + /// Returns the address as a Unix domain socket address, if possible. public var unixDomainSocket: UnixDomainSocket? { switch self.value { case .unix(let address): @@ -59,7 +59,7 @@ public struct SocketAddress: Hashable, Sendable { } } - /// Returns the address as an VSOCK address, if possible. + /// Returns the address as a VSOCK address, if possible. public var virtualSocket: VirtualSocket? { switch self.value { case .vsock(let address): @@ -139,7 +139,7 @@ extension SocketAddress { return .unixDomainSocket(UnixDomainSocket(path: path)) } - /// Create a Virtual Socket ('vsock') address. + /// Creates a virtual socket (`vsock`) address. public static func vsock(contextID: VirtualSocket.ContextID, port: VirtualSocket.Port) -> Self { return .vsock(VirtualSocket(contextID: contextID, port: port)) } @@ -163,6 +163,7 @@ extension SocketAddress: CustomStringConvertible { @available(gRPCSwiftNIOTransport 2.0, *) extension SocketAddress { + /// An IPv4 address and port. public struct IPv4: Hashable, Sendable { /// The resolved host address. public var host: String @@ -180,6 +181,7 @@ extension SocketAddress { } } + /// An IPv6 address and port. public struct IPv6: Hashable, Sendable { /// The resolved host address. public var host: String @@ -197,11 +199,12 @@ extension SocketAddress { } } + /// A Unix domain socket address. public struct UnixDomainSocket: Hashable, Sendable { /// The path name of the Unix domain socket. public var path: String - /// Create a new Unix domain socket address. + /// Creates a new Unix domain socket address. /// /// - Parameter path: The path name of the Unix domain socket. public init(path: String) { @@ -209,6 +212,7 @@ extension SocketAddress { } } + /// A VSOCK address, made up of a context ID and a port. public struct VirtualSocket: Hashable, Sendable { /// A context identifier. /// @@ -218,16 +222,17 @@ extension SocketAddress { /// The port number. public var port: Port - /// Create a new VSOCK address. + /// Creates a new VSOCK address. /// /// - Parameters: - /// - contextID: The context ID (or 'cid') of the address. + /// - contextID: The context ID (or `cid`) of the address. /// - port: The port number. public init(contextID: ContextID, port: Port) { self.contextID = contextID self.port = port } + /// A VSOCK port number. public struct Port: Hashable, Sendable, RawRepresentable, ExpressibleByIntegerLiteral { /// The port number. public var rawValue: UInt32 @@ -236,10 +241,12 @@ extension SocketAddress { self.rawValue = rawValue } + /// Creates a port from an integer literal. public init(integerLiteral value: UInt32) { self.rawValue = value } + /// Creates a port from an `Int`, truncating it to fit a `UInt32`. public init(_ value: Int) { self.init(rawValue: UInt32(bitPattern: Int32(truncatingIfNeeded: value))) } @@ -252,6 +259,7 @@ extension SocketAddress { } } + /// A VSOCK context ID (or `cid`), identifying a virtual machine or the host. public struct ContextID: Hashable, Sendable, RawRepresentable, ExpressibleByIntegerLiteral { /// The context identifier. public var rawValue: UInt32 @@ -260,10 +268,12 @@ extension SocketAddress { self.rawValue = rawValue } + /// Creates a context ID from an integer literal. public init(integerLiteral value: UInt32) { self.rawValue = value } + /// Creates a context ID from an `Int`, truncating it to fit a `UInt32`. public init(_ value: Int) { self.rawValue = UInt32(bitPattern: Int32(truncatingIfNeeded: value)) } @@ -296,7 +306,7 @@ extension SocketAddress { /// The address for local communication (loopback). /// - /// This directs packets to the same host that generated them. This is useful for testing + /// This directs packets to the same host that generated them. This is useful for testing /// applications on a single host and for debugging. /// /// This is equal to `VMADDR_CID_LOCAL (1)` on platforms that define it. diff --git a/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel+Config.swift b/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel+Config.swift index d0ca5c89..12e07b0b 100644 --- a/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel+Config.swift +++ b/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel+Config.swift @@ -18,6 +18,7 @@ public import NIOCore @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ClientTransport.WrappedChannel { + /// Configuration for a ``HTTP2ClientTransport/WrappedChannel``. public struct Config: Sendable { /// Configuration for HTTP/2 connections. public var http2: HTTP2ClientTransport.Config.HTTP2 @@ -87,6 +88,7 @@ extension HTTP2ClientTransport.WrappedChannel.Config { /// A callback invoked with each new HTTP/2 stream. public var onCreateHTTP2Stream: (@Sendable (_ channel: any Channel) -> EventLoopFuture)? + /// Creates a new set of channel debugging callbacks. public init( onCreateHTTP2Stream: (@Sendable (_ channel: any Channel) -> EventLoopFuture)? ) { diff --git a/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel.swift b/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel.swift index e881ae37..acf404da 100644 --- a/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel.swift +++ b/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel.swift @@ -19,47 +19,47 @@ public import NIOCore internal import NIOHTTP2 private import Synchronization -/// A client transport which wraps an existing SwiftNIO `Channel`. -/// -/// You can use this if you already have a connected `Channel` that you'd like to use as a gRPC -/// client connection. This is helpful if, for example, you wish to tunnel gRPC inside another -/// protocol. -/// -/// ## Limitations -/// -/// This transport offers fewer features than its regular NIO based counterparts: -/// -/// - **No reconnects.** Once the underlying `Channel` closes, the transport is done. Subsequent -/// RPCs fail with `unavailable`. -/// - **No load balancing or connection pooling.** It's a single `Channel`. -/// `ServiceConfig.loadBalancingConfig` is ignored. Retry throttling, if configured, still -/// applies. -/// - **No transparent TLS.** Wire TLS into your own pipeline before calling `configure`; the -/// transport doesn't set it up for you. -/// - **Streams queue until `SETTINGS`.** RPCs initiated before the server's first `SETTINGS` -/// frame is received are queued; if the connection fails before that, they fail with -/// `unavailable`. -/// -/// ## Constructing a transport -/// -/// Use ``wrapping(config:serviceConfig:makeChannel:)`` to build a transport. The factory hands you -/// a `configure` closure to call from inside your bootstrap's `channelInitializer`, alongside any -/// pre-gRPC handlers you need (TLS, any tunnelling handlers, etc.). -/// -/// If you already hold an active `Channel` (for example after completing a tunnel handshake) you -/// can call `configure(channel)` directly inside `makeChannel`. In that case it is your -/// responsibility to ensure that no inbound bytes have flowed past the end of your pipeline -/// before `configure` runs β€” for instance by keeping your tunnel handler installed (and not -/// firing inbound bytes) until `configure` resolves. -/// -/// ## Lifecycle -/// -/// On success the transport takes ownership of the channel and is responsible for closing it. If -/// `makeChannel` throws, ownership stays with the caller. When the channel closes, in-flight RPCs -/// see the failure on their inbound stream and any RPCs still queued waiting for `SETTINGS` are -/// resumed with `unavailable`. @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ClientTransport { + /// A client transport which wraps an existing SwiftNIO `Channel`. + /// + /// You can use this if you already have a connected `Channel` that you'd like to use as a gRPC + /// client connection. This is helpful if, for example, you wish to tunnel gRPC inside another + /// protocol. + /// + /// ## Limitations + /// + /// This transport offers fewer features than its regular NIO based counterparts: + /// + /// - **No reconnects.** Once the underlying `Channel` closes, the transport is done. Subsequent + /// RPCs fail with `unavailable`. + /// - **No load balancing or connection pooling.** It's a single `Channel`. + /// `ServiceConfig.loadBalancingConfig` is ignored. Retry throttling, if configured, still + /// applies. + /// - **No transparent TLS.** Wire TLS into your own pipeline before calling `configure`; the + /// transport doesn't set it up for you. + /// - **Streams queue until `SETTINGS`.** RPCs initiated before the server's first `SETTINGS` + /// frame is received are queued; if the connection fails before that, they fail with + /// `unavailable`. + /// + /// ## Constructing a transport + /// + /// Use ``wrapping(config:serviceConfig:makeChannel:)`` to build a transport. The factory hands you + /// a `configure` closure to call from inside your bootstrap's `channelInitializer`, alongside any + /// pre-gRPC handlers you need (TLS, any tunnelling handlers, etc.). + /// + /// If you already hold an active `Channel` (for example after completing a tunnel handshake) you + /// can call `configure(channel)` directly inside `makeChannel`. In that case it is your + /// responsibility to ensure that no inbound bytes have flowed past the end of your pipeline + /// before `configure` runs β€” for instance by keeping your tunnel handler installed (and not + /// firing inbound bytes) until `configure` resolves. + /// + /// ## Lifecycle + /// + /// On success the transport takes ownership of the channel and is responsible for closing it. If + /// `makeChannel` throws, ownership stays with the caller. When the channel closes, in-flight RPCs + /// see the failure on their inbound stream and any RPCs still queued waiting for `SETTINGS` are + /// resumed with `unavailable`. @available(gRPCSwiftNIOTransport 2.0, *) public final class WrappedChannel: ClientTransport { public typealias Bytes = GRPCNIOTransportBytes @@ -71,6 +71,7 @@ extension HTTP2ClientTransport { private let state: Mutex private let preConfigured: Configured? + /// The retry throttle derived from the service config, if any. public let retryThrottle: RetryThrottle? fileprivate struct Configured { @@ -135,10 +136,12 @@ extension HTTP2ClientTransport { } } + /// Returns the method-specific configuration for the given method, if any. public func config(forMethod descriptor: MethodDescriptor) -> MethodConfig? { return self.methodConfig[descriptor] } + /// Configures the wrapped channel's gRPC pipeline and waits for it to become ready. public func connect() async throws { switch self.state.withLock({ $0.connect() }) { case .configureChannel: @@ -211,6 +214,7 @@ extension HTTP2ClientTransport { } } + /// Begins graceful shutdown of the underlying channel. public func beginGracefulShutdown() { switch self.state.withLock({ $0.beginGracefulShutdown() }) { case .emitGracefulShutdownEvent: @@ -224,6 +228,7 @@ extension HTTP2ClientTransport { } } + /// Opens a stream on the wrapped channel and uses it as input to the given closure. public func withStream( descriptor: MethodDescriptor, options: CallOptions, @@ -356,7 +361,7 @@ extension HTTP2ClientTransport { @available(gRPCSwiftNIOTransport 2.0, *) extension ClientTransport where Self == HTTP2ClientTransport.WrappedChannel { - /// Create a new wrapping client transport from an already connection NIO `Channel`. + /// Create a new wrapping client transport from an already connected NIO `Channel`. /// /// - Parameters: /// - channel: The channel to wrap. The transport takes ownership of the lifetime of the channel diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/Documentation.md b/Sources/GRPCNIOTransportCore/Documentation.docc/Documentation.md index 58366b2c..70d25cae 100644 --- a/Sources/GRPCNIOTransportCore/Documentation.docc/Documentation.md +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/Documentation.md @@ -32,3 +32,7 @@ transport implementations built on top of SwiftNIO. ### TLS - ``TLSConfig`` + +### Message data + +- ``GRPCNIOTransportBytes`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.Config.Connection.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.Config.Connection.md new file mode 100644 index 00000000..50e67523 --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.Config.Connection.md @@ -0,0 +1,18 @@ +# ``HTTP2ClientTransport/Config/Connection`` + +## Topics + +### Creating a connection configuration + +- ``init(maxIdleTime:keepalive:)`` +- ``defaults`` + +### Idling and keepalive + +- ``maxIdleTime`` +- ``keepalive`` + +### Flush coalescing + +- ``flushCoalescing`` +- ``FlushCoalescing`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.Config.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.Config.md new file mode 100644 index 00000000..a0ff2438 --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.Config.md @@ -0,0 +1,18 @@ +# ``HTTP2ClientTransport/Config`` + +## Topics + +### Connection behavior + +- ``HTTP2ClientTransport/Config/Connection`` +- ``HTTP2ClientTransport/Config/Backoff`` +- ``HTTP2ClientTransport/Config/Keepalive`` + +### Protocol tuning + +- ``HTTP2ClientTransport/Config/HTTP2`` +- ``HTTP2ClientTransport/Config/Compression`` + +### Debugging + +- ``HTTP2ClientTransport/Config/ChannelDebuggingCallbacks`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.WrappedChannel.Config.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.WrappedChannel.Config.md new file mode 100644 index 00000000..d62a3799 --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.WrappedChannel.Config.md @@ -0,0 +1,17 @@ +# ``HTTP2ClientTransport/WrappedChannel/Config`` + +## Topics + +### Creating a configuration + +- ``init(http2:connection:compression:channelDebuggingCallbacks:)`` +- ``defaults`` +- ``defaults(_:)`` + +### Configuring behavior + +- ``http2`` +- ``connection`` +- ``compression`` +- ``channelDebuggingCallbacks`` +- ``ChannelDebuggingCallbacks`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.WrappedChannel.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.WrappedChannel.md new file mode 100644 index 00000000..01406478 --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.WrappedChannel.md @@ -0,0 +1,22 @@ +# ``HTTP2ClientTransport/WrappedChannel`` + +## Topics + +### Creating a wrapped channel + +- ``init(takingOwnershipOf:config:serviceConfig:)`` +- ``wrapping(channel:config:serviceConfig:)`` +- ``wrapping(config:serviceConfig:makeChannel:)`` +- ``ConfiguredChannel`` +- ``Config`` + +### Making requests + +- ``withStream(descriptor:options:_:)`` +- ``config(forMethod:)`` +- ``retryThrottle`` + +### Managing the connection + +- ``connect()`` +- ``beginGracefulShutdown()`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.md new file mode 100644 index 00000000..a814b941 --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ClientTransport.md @@ -0,0 +1,11 @@ +# ``HTTP2ClientTransport`` + +## Topics + +### Configuring a transport + +- ``Config`` + +### Wrapping an existing channel + +- ``WrappedChannel`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Config.Connection.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Config.Connection.md new file mode 100644 index 00000000..f1253389 --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Config.Connection.md @@ -0,0 +1,23 @@ +# ``HTTP2ServerTransport/Config/Connection`` + +## Topics + +### Creating a connection configuration + +- ``init(maxAge:maxGraceTime:maxIdleTime:keepalive:)`` +- ``defaults`` + +### Connection lifetime + +- ``maxAge`` +- ``maxGraceTime`` +- ``maxIdleTime`` + +### Keepalive + +- ``keepalive`` + +### Flush coalescing + +- ``flushCoalescing`` +- ``FlushCoalescing`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Config.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Config.md new file mode 100644 index 00000000..2f520ff4 --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Config.md @@ -0,0 +1,19 @@ +# ``HTTP2ServerTransport/Config`` + +## Topics + +### Connection behavior + +- ``HTTP2ServerTransport/Config/Connection`` +- ``HTTP2ServerTransport/Config/Keepalive`` +- ``HTTP2ServerTransport/Config/ClientKeepaliveBehavior`` + +### Protocol tuning + +- ``HTTP2ServerTransport/Config/HTTP2`` +- ``HTTP2ServerTransport/Config/Compression`` +- ``HTTP2ServerTransport/Config/RPC`` + +### Debugging + +- ``HTTP2ServerTransport/Config/ChannelDebuggingCallbacks`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.ConnectionConfigurator.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.ConnectionConfigurator.md new file mode 100644 index 00000000..2420d610 --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.ConnectionConfigurator.md @@ -0,0 +1,12 @@ +# ``HTTP2ServerTransport/ConnectionConfigurator`` + +## Topics + +### Configuring a connection + +- ``configure(channel:tls:)`` +- ``ConnectionChannel`` + +### TLS + +- ``TLS`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Custom.Config.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Custom.Config.md new file mode 100644 index 00000000..fdea7db5 --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Custom.Config.md @@ -0,0 +1,16 @@ +# ``HTTP2ServerTransport/Custom/Config`` + +## Topics + +### Creating a configuration + +- ``init(compression:connection:http2:rpc:channelDebuggingCallbacks:)`` +- ``defaults`` + +### Configuring behavior + +- ``compression`` +- ``connection`` +- ``http2`` +- ``rpc`` +- ``channelDebuggingCallbacks`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Custom.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Custom.md new file mode 100644 index 00000000..e3831bc1 --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.Custom.md @@ -0,0 +1,18 @@ +# ``HTTP2ServerTransport/Custom`` + +## Topics + +### Creating a custom transport + +- ``init(listenerFactory:config:)`` +- ``Config`` + +### Serving + +- ``listen(streamHandler:)`` +- ``configure(context:)`` +- ``listeningAddress`` + +### Shutting down + +- ``beginGracefulShutdown()`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.md new file mode 100644 index 00000000..bf40248a --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/HTTP2ServerTransport.md @@ -0,0 +1,14 @@ +# ``HTTP2ServerTransport`` + +## Topics + +### Configuring a transport + +- ``Config`` + +### Building a custom transport + +- ``Custom`` +- ``ListenerFactory`` +- ``ListenerConfigurator`` +- ``ConnectionConfigurator`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/NameResolver.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/NameResolver.md new file mode 100644 index 00000000..56a4bde5 --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/NameResolver.md @@ -0,0 +1,14 @@ +# ``NameResolver`` + +## Topics + +### Creating a name resolver + +- ``init(names:updateMode:authority:)`` + +### Inspecting a name resolver + +- ``names`` +- ``updateMode`` +- ``UpdateMode`` +- ``authority`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.VirtualSocket.ContextID.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.VirtualSocket.ContextID.md new file mode 100644 index 00000000..b65afd60 --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.VirtualSocket.ContextID.md @@ -0,0 +1,20 @@ +# ``SocketAddress/VirtualSocket/ContextID`` + +## Topics + +### Creating a context ID + +- ``init(integerLiteral:)`` +- ``init(_:)`` + +### Well-known context IDs + +- ``any`` +- ``host`` +- ``hypervisor`` +- ``local`` + +### Working with raw values + +- ``rawValue`` +- ``init(rawValue:)`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.VirtualSocket.Port.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.VirtualSocket.Port.md new file mode 100644 index 00000000..a73ba43b --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.VirtualSocket.Port.md @@ -0,0 +1,17 @@ +# ``SocketAddress/VirtualSocket/Port`` + +## Topics + +### Creating a port + +- ``init(integerLiteral:)`` +- ``init(_:)`` + +### Well-known ports + +- ``any`` + +### Working with raw values + +- ``rawValue`` +- ``init(rawValue:)`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.VirtualSocket.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.VirtualSocket.md new file mode 100644 index 00000000..0c6b92e7 --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.VirtualSocket.md @@ -0,0 +1,21 @@ +# ``SocketAddress/VirtualSocket`` + +## Topics + +### Creating a VSOCK address + +- ``init(contextID:port:)`` + +### Context ID + +- ``contextID`` +- ``ContextID`` + +### Port + +- ``port`` +- ``Port`` + +### Describing a VSOCK address + +- ``description`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.md new file mode 100644 index 00000000..c34cc0e3 --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/SocketAddress.md @@ -0,0 +1,35 @@ +# ``SocketAddress`` + +## Topics + +### Creating an IPv4 address + +- ``SocketAddress/ipv4(host:port:)`` +- ``SocketAddress/ipv4(_:)`` +- ``SocketAddress/IPv4`` +- ``SocketAddress/ipv4`` + +### Creating an IPv6 address + +- ``SocketAddress/ipv6(host:port:)`` +- ``SocketAddress/ipv6(_:)`` +- ``SocketAddress/IPv6`` +- ``SocketAddress/ipv6`` + +### Creating a Unix domain socket address + +- ``SocketAddress/unixDomainSocket(path:)`` +- ``SocketAddress/unixDomainSocket(_:)`` +- ``SocketAddress/UnixDomainSocket`` +- ``SocketAddress/unixDomainSocket`` + +### Creating a VSOCK address + +- ``SocketAddress/vsock(contextID:port:)`` +- ``SocketAddress/vsock(_:)`` +- ``SocketAddress/VirtualSocket`` +- ``SocketAddress/virtualSocket`` + +### Describing an address + +- ``SocketAddress/description`` diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/reference/TLSConfig.md b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/TLSConfig.md new file mode 100644 index 00000000..72d5935c --- /dev/null +++ b/Sources/GRPCNIOTransportCore/Documentation.docc/reference/TLSConfig.md @@ -0,0 +1,14 @@ +# ``TLSConfig`` + +## Topics + +### Certificates and keys + +- ``TLSConfig/CertificateSource`` +- ``TLSConfig/PrivateKeySource`` +- ``TLSConfig/SerializationFormat`` + +### Trust and verification + +- ``TLSConfig/TrustRootsSource`` +- ``TLSConfig/CertificateVerification`` diff --git a/Sources/GRPCNIOTransportCore/GRPCNIOTransportBytes.swift b/Sources/GRPCNIOTransportCore/GRPCNIOTransportBytes.swift index 758ef880..17bdb868 100644 --- a/Sources/GRPCNIOTransportCore/GRPCNIOTransportBytes.swift +++ b/Sources/GRPCNIOTransportCore/GRPCNIOTransportBytes.swift @@ -17,7 +17,7 @@ public import GRPCCore public import NIOCore -/// The contiguous bytes type used by the gRPC's NIO transport. +/// The contiguous bytes type used by gRPC's NIO transport. @available(gRPCSwiftNIOTransport 2.0, *) public struct GRPCNIOTransportBytes: GRPCContiguousBytes, Hashable, Sendable { @usableFromInline @@ -33,21 +33,25 @@ public struct GRPCNIOTransportBytes: GRPCContiguousBytes, Hashable, Sendable { self.buffer = ByteBuffer() } + /// Creates a new instance filled with the given byte, repeated `count` times. @inlinable public init(repeating: UInt8, count: Int) { self.buffer = ByteBuffer(repeating: repeating, count: count) } + /// Creates a new instance from a sequence of bytes. @inlinable public init(_ sequence: some Sequence) { self.buffer = ByteBuffer(bytes: sequence) } + /// The number of bytes stored. @inlinable public var count: Int { self.buffer.readableBytes } + /// Calls the given closure with a pointer to the underlying contiguous storage. @inlinable public func withUnsafeBytes( _ body: (UnsafeRawBufferPointer) throws -> R @@ -55,6 +59,7 @@ public struct GRPCNIOTransportBytes: GRPCContiguousBytes, Hashable, Sendable { try self.buffer.withUnsafeReadableBytes(body) } + /// Calls the given closure with a mutable pointer to the underlying contiguous storage. @inlinable public mutating func withUnsafeMutableBytes( _ body: (UnsafeMutableRawBufferPointer) throws -> R diff --git a/Sources/GRPCNIOTransportCore/Server/ConnectionConfigurator.swift b/Sources/GRPCNIOTransportCore/Server/ConnectionConfigurator.swift index b6ebace2..ad21d3ce 100644 --- a/Sources/GRPCNIOTransportCore/Server/ConnectionConfigurator.swift +++ b/Sources/GRPCNIOTransportCore/Server/ConnectionConfigurator.swift @@ -101,7 +101,7 @@ extension HTTP2ServerTransport { /// Configures an accepted connection channel with the gRPC HTTP/2 server pipeline. /// /// This should be called from the `childChannelInitializer` of a bootstrap, - /// *after* any transport-specific handlers (e.g. TLS) have been added. + /// *after* any transport-specific handlers (for example, TLS) have been added. /// /// - Parameters: /// - channel: The accepted connection channel to configure. diff --git a/Sources/GRPCNIOTransportCore/Server/CustomTransport.swift b/Sources/GRPCNIOTransportCore/Server/CustomTransport.swift index 835ba2fe..3d7e61e3 100644 --- a/Sources/GRPCNIOTransportCore/Server/CustomTransport.swift +++ b/Sources/GRPCNIOTransportCore/Server/CustomTransport.swift @@ -172,7 +172,7 @@ extension HTTP2ServerTransport { /// /// It is an `async` property because it will only return once the listening channel has been /// created. Returns `nil` if the listening channel doesn't have a corresponding socket address - /// (e.g. when using a non-socket-based transport) or if the server has been closed. + /// (for example, when using a non-socket-based transport) or if the server has been closed. public var listeningAddress: SocketAddress? { get async { switch self.listeningAddressState.withLock({ $0.listeningAddress }) { @@ -234,6 +234,7 @@ extension HTTP2ServerTransport { } } + /// Starts serving, using the listener factory to create the listening channel. public func listen( streamHandler: @escaping @Sendable ( @@ -416,10 +417,12 @@ extension HTTP2ServerTransport { } } + /// Begins graceful shutdown of the listening channel. public func beginGracefulShutdown() { self.serverQuiescingHelper.initiateShutdown(promise: nil) } + /// Stores the server context, making it available to accepted connections. public func configure(context: GRPCServerContext) { self.serverContext.withLock { $0 = context } } diff --git a/Sources/GRPCNIOTransportCore/Server/HTTP2ServerTransport.swift b/Sources/GRPCNIOTransportCore/Server/HTTP2ServerTransport.swift index 9bb7e0fd..27c599d8 100644 --- a/Sources/GRPCNIOTransportCore/Server/HTTP2ServerTransport.swift +++ b/Sources/GRPCNIOTransportCore/Server/HTTP2ServerTransport.swift @@ -30,6 +30,7 @@ extension HTTP2ServerTransport { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ServerTransport.Config { + /// Compression configuration for the server transport. public struct Compression: Sendable, Hashable { /// Compression algorithms enabled for inbound messages. /// @@ -49,6 +50,7 @@ extension HTTP2ServerTransport.Config { } } + /// Keepalive configuration for the server transport. public struct Keepalive: Sendable, Hashable { /// The amount of time to wait after reading data before sending a keepalive ping. public var time: Duration @@ -82,9 +84,10 @@ extension HTTP2ServerTransport.Config { } } + /// Configuration for how the server enforces client keepalive. public struct ClientKeepaliveBehavior: Sendable, Hashable { /// The minimum allowed interval the client is allowed to send keep-alive pings. - /// Pings more frequent than this interval count as 'strikes' and the connection is closed if there are + /// Pings more frequent than this interval count as β€œstrikes” and the connection is closed if there are /// too many strikes. public var minPingIntervalWithoutCalls: Duration @@ -100,14 +103,14 @@ extension HTTP2ServerTransport.Config { self.allowWithoutCalls = allowWithoutCalls } - /// Default values. The time after reading data a ping should be sent defaults to 2 hours, the timeout for - /// keepalive pings defaults to 20 seconds, pings are not permitted when no calls are in progress, and - /// the minimum allowed interval for clients to send pings defaults to 5 minutes. + /// Default values. The minimum allowed interval for clients to send pings without an active + /// call defaults to 5 minutes, and pings without an active call aren't permitted. public static var defaults: Self { Self(minPingIntervalWithoutCalls: .seconds(5 * 60), allowWithoutCalls: false) } } + /// Connection management configuration for the server transport. public struct Connection: Sendable, Hashable { /// The maximum amount of time a connection may exist before being gracefully closed. public var maxAge: Duration? @@ -171,7 +174,7 @@ extension HTTP2ServerTransport.Config { } /// Default values. The max connection age, max grace time, and max idle time default to - /// `nil` (i.e. infinite). See ``HTTP2ServerTransport/Config/Keepalive/defaults`` for keepalive + /// `nil` (that is, infinite). See ``HTTP2ServerTransport/Config/Keepalive/defaults`` for keepalive /// defaults. Flush coalescing is enabled with default values. public static var defaults: Self { Self( @@ -184,6 +187,7 @@ extension HTTP2ServerTransport.Config { } } + /// HTTP/2-level configuration for the server transport. public struct HTTP2: Sendable, Hashable { /// The maximum frame size to be used in an HTTP/2 connection. public var maxFrameSize: Int @@ -196,6 +200,7 @@ extension HTTP2ServerTransport.Config { /// The number of concurrent streams on the HTTP/2 connection. public var maxConcurrentStreams: Int? + /// Creates a new HTTP/2 configuration. public init( maxFrameSize: Int, targetWindowSize: Int, @@ -217,10 +222,12 @@ extension HTTP2ServerTransport.Config { } } + /// RPC-level configuration for the server transport. public struct RPC: Sendable, Hashable { /// The maximum request payload size. public var maxRequestPayloadSize: Int + /// Creates a new RPC configuration. public init(maxRequestPayloadSize: Int) { self.maxRequestPayloadSize = maxRequestPayloadSize } @@ -242,12 +249,13 @@ extension HTTP2ServerTransport.Config { /// A callback invoked when the server starts listening for new TCP connections. public var onBindTCPListener: (@Sendable (_ channel: any Channel) -> EventLoopFuture)? - /// A callback invoked with each new accepted TPC connection. + /// A callback invoked with each new accepted TCP connection. public var onAcceptTCPConnection: (@Sendable (_ channel: any Channel) -> EventLoopFuture)? /// A callback invoked with each accepted HTTP/2 stream. public var onAcceptHTTP2Stream: (@Sendable (_ channel: any Channel) -> EventLoopFuture)? + /// Creates a new set of channel debugging callbacks. public init( onBindTCPListener: (@Sendable (_ channel: any Channel) -> EventLoopFuture)?, onAcceptTCPConnection: (@Sendable (_ channel: any Channel) -> EventLoopFuture)?, @@ -273,7 +281,7 @@ extension HTTP2ServerTransport.Config.Connection { /// until one of the following conditions is met: /// 1. ``maxFlushDelay`` has elapsed since a flush was first requested, /// 2. At least ``maxBytes`` bytes have been written since the previous flush, or - /// 3. The channel becomes unwritable (i.e. the outbound buffer has hit the high-water mark). + /// 3. The channel becomes unwritable (that is, the outbound buffer has hit the high-water mark). /// /// This means that under high load, writes naturally accumulate and are flushed together in /// fewer, larger batches. This reduces per-write overhead and typically improves both throughput diff --git a/Sources/GRPCNIOTransportCore/Server/ListenerConfigurator.swift b/Sources/GRPCNIOTransportCore/Server/ListenerConfigurator.swift index 0eaaceca..0bfe094f 100644 --- a/Sources/GRPCNIOTransportCore/Server/ListenerConfigurator.swift +++ b/Sources/GRPCNIOTransportCore/Server/ListenerConfigurator.swift @@ -36,8 +36,8 @@ extension HTTP2ServerTransport { self.channelDebuggingCallbacks = channelDebuggingCallbacks } - /// Configures the listening channel with the necessary handlers (e.g. handlers for graceful - /// shutdown or debugging callbacks). + /// Configures the listening channel with the necessary handlers (for example, handlers for + /// graceful shutdown or debugging callbacks). /// /// This should be called from the `serverChannelInitializer` of a bootstrap. /// diff --git a/Sources/GRPCNIOTransportCore/TLSConfig.swift b/Sources/GRPCNIOTransportCore/TLSConfig.swift index d02515dc..24fda750 100644 --- a/Sources/GRPCNIOTransportCore/TLSConfig.swift +++ b/Sources/GRPCNIOTransportCore/TLSConfig.swift @@ -14,6 +14,7 @@ * limitations under the License. */ +/// A namespace for TLS configuration types. @available(gRPCSwiftNIOTransport 2.0, *) public enum TLSConfig: Sendable { /// The serialization format of the provided certificates and private keys. @@ -25,7 +26,9 @@ public enum TLSConfig: Sendable { package let wrapped: Wrapped + /// The PEM serialization format. public static let pem = Self(wrapped: .pem) + /// The DER serialization format. public static let der = Self(wrapped: .der) } @@ -44,7 +47,7 @@ public enum TLSConfig: Sendable { /// - Parameters: /// - path: The file path containing the certificate. /// - format: The certificate's format, as a ``TLSConfig/SerializationFormat``. - /// - Returns: A source describing the certificate source is the given file. + /// - Returns: A source describing a certificate stored in the given file. public static func file(path: String, format: SerializationFormat) -> Self { Self(wrapped: .file(path: path, format: format)) } @@ -53,7 +56,7 @@ public enum TLSConfig: Sendable { /// - Parameters: /// - bytes: The array of bytes making up the certificate. /// - format: The certificate's format, as a ``TLSConfig/SerializationFormat``. - /// - Returns: A source describing the certificate source is the given bytes. + /// - Returns: A source describing a certificate stored in the given bytes. public static func bytes(_ bytes: [UInt8], format: SerializationFormat) -> Self { Self(wrapped: .bytes(bytes: bytes, format: format)) } @@ -74,7 +77,7 @@ public enum TLSConfig: Sendable { /// - Parameters: /// - path: The file path containing the private key. /// - format: The private key's format, as a ``TLSConfig/SerializationFormat``. - /// - Returns: A source describing the private key source is the given file. + /// - Returns: A source describing a private key stored in the given file. public static func file(path: String, format: SerializationFormat) -> Self { Self(wrapped: .file(path: path, format: format)) } @@ -83,7 +86,7 @@ public enum TLSConfig: Sendable { /// - Parameters: /// - bytes: The array of bytes making up the private key. /// - format: The private key's format, as a ``TLSConfig/SerializationFormat``. - /// - Returns: A source describing the private key source is the given bytes. + /// - Returns: A source describing a private key stored in the given bytes. public static func bytes( _ bytes: [UInt8], format: SerializationFormat @@ -92,7 +95,7 @@ public enum TLSConfig: Sendable { } } - /// A description of where the trust roots are coming from: either a custom certificate chain, or the system default trust store. + /// A description of where the trust roots are coming from: either a custom certificate chain or the system default trust store. public struct TrustRootsSource: Sendable, Equatable { package enum Wrapped: Equatable { case certificates([CertificateSource]) @@ -128,10 +131,10 @@ public enum TLSConfig: Sendable { /// All certificate verification disabled. public static let noVerification: Self = Self(wrapped: .doNotVerify) - /// Certificates will be validated against the trust store, but will not be checked to see if they are valid for the given hostname. + /// Certificates are validated against the trust store, but aren't checked against the given hostname. public static let noHostnameVerification: Self = Self(wrapped: .noHostnameVerification) - /// Certificates will be validated against the trust store and checked against the hostname of the service we are contacting. + /// Certificates are validated against the trust store and checked against the hostname of the service you're contacting. public static let fullVerification: Self = Self(wrapped: .fullVerification) } } diff --git a/Sources/GRPCNIOTransportHTTP2/Documentation.docc/Documentation.md b/Sources/GRPCNIOTransportHTTP2/Documentation.docc/Documentation.md index 8c7ec48c..6bcc8cc5 100644 --- a/Sources/GRPCNIOTransportHTTP2/Documentation.docc/Documentation.md +++ b/Sources/GRPCNIOTransportHTTP2/Documentation.docc/Documentation.md @@ -3,18 +3,50 @@ An umbrella module providing high-performance HTTP/2 client and server transport implementations built on top of SwiftNIO. +## Overview + The module provides two variants of the client and server transport which differ in the -networking backend used by each. The two backends are: +networking backend used by each: `NIOPosix` and `NIOTransportServices`. These correspond to two +modules provided by `grpc-swift-nio-transport`: `GRPCNIOTransportHTTP2Posix`, providing +``HTTP2ClientTransport/Posix`` and ``HTTP2ServerTransport/Posix``; and +`GRPCNIOTransportHTTP2TransportServices`, providing ``HTTP2ClientTransport/TransportServices`` +and ``HTTP2ServerTransport/TransportServices``. -1. `NIOPosix`, and -2. `NIOTransportServices`. +This module, ``GRPCNIOTransportHTTP2``, re-exports the contents of both of these modules. -These correspond to two different modules provided by `grpc-swift-nio-transport`: +`GRPCNIOTransportHTTP2Posix` is available on all platforms, while +`GRPCNIOTransportHTTP2TransportServices` is only available on Darwin-based platforms. -1. [`GRPCNIOTransportHTTP2Posix`](https://swiftpackageindex.com/grpc/grpc-swift-nio-transport/documentation/grpcniotransporthttp2posix), and -2. [`GRPCNIOTransportHTTP2TransportServices`](https://swiftpackageindex.com/grpc/grpc-swift-nio-transport/documentation/grpcniotransporthttp2transportservices). +## Topics -This module, ``GRPCNIOTransportHTTP2``, re-exports the contents of both of these modules. +### Client and server transports -`GRPCNIOTransportHTTP2Posix` is available on all platforms, while -`GRPCNIOTransportHTTP2TransportServices` is only available on Darwin based platforms. +- ``HTTP2ClientTransport`` +- ``HTTP2ServerTransport`` + +### Transport extensions + +- ``ListeningServerTransport`` + +### Name resolution + +- ``ResolvableTarget`` +- ``ResolvableTargets`` +- ``NameResolvers`` +- ``NameResolverRegistry`` +- ``NameResolverFactory`` +- ``NameResolver`` +- ``NameResolutionResult`` + +### Addresses + +- ``SocketAddress`` +- ``Endpoint`` + +### TLS + +- ``TLSConfig`` + +### Message data + +- ``GRPCNIOTransportBytes`` diff --git a/Sources/GRPCNIOTransportHTTP2Posix/Config+TLS.swift b/Sources/GRPCNIOTransportHTTP2Posix/Config+TLS.swift index 6bf8e9c0..69091fde 100644 --- a/Sources/GRPCNIOTransportHTTP2Posix/Config+TLS.swift +++ b/Sources/GRPCNIOTransportHTTP2Posix/Config+TLS.swift @@ -30,7 +30,7 @@ extension HTTP2ServerTransport.Posix { package let wrapped: Wrapped - /// This connection is plaintext: no encryption will take place. + /// This connection is plaintext; no encryption takes place. public static let plaintext = Self(wrapped: .plaintext) /// Secure connections with the given TLS configuration. @@ -57,7 +57,7 @@ extension HTTP2ServerTransport.Posix { return .tls(tlsConfig) } - /// Create a new TLS config using a certificate reloader to provide the certificate chain + /// Creates a new TLS config using a certificate reloader to provide the certificate chain /// and private key. /// /// The reloader must provide an initial certificate chain and private key. If you already @@ -109,7 +109,7 @@ extension HTTP2ServerTransport.Posix { return .tls(tlsConfig) } - /// Create a new TLS config suitable for mTLS using a certificate reloader to provide the + /// Creates a new TLS config suitable for mTLS using a certificate reloader to provide the /// certificate chain and private key. /// /// The reloader must provide an initial certificate chain and private key. If you already @@ -146,6 +146,7 @@ extension HTTP2ServerTransport.Posix { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ServerTransport.Posix.TransportSecurity { + /// TLS configuration for the `Posix` server transport. public struct TLS: Sendable { /// The certificates the server will offer during negotiation. public var certificateChain: [TLSConfig.CertificateSource] @@ -169,7 +170,8 @@ extension HTTP2ServerTransport.Posix.TransportSecurity { public var certificateReloader: (any CertificateReloader)? /// Override the certificate verification with a custom callback that must return the verified certificate chain on success. - /// Note: The callback is only used when `clientCertificateVerification` is *not* set to `noVerification`! + /// + /// - Note: The callback is only used when `clientCertificateVerification` isn't set to `noVerification`. @available(gRPCSwiftNIOTransport 2.2, *) public var customVerificationCallback: ( @@ -179,7 +181,7 @@ extension HTTP2ServerTransport.Posix.TransportSecurity { ) -> Void )? - /// Create a new HTTP2 NIO Posix server transport TLS config. + /// Creates a new HTTP2 NIO Posix server transport TLS config. /// - Parameters: /// - certificateChain: The certificates the server will offer during negotiation. /// - privateKey: The private key associated with the leaf certificate. @@ -200,7 +202,7 @@ extension HTTP2ServerTransport.Posix.TransportSecurity { self.requireALPN = requireALPN } - /// Create a new HTTP2 NIO Posix transport TLS config, with some values defaulted: + /// Creates a new HTTP2 NIO Posix transport TLS config, with some values defaulted: /// - `clientCertificateVerificationMode` equals `doNotVerify` /// - `trustRoots` equals `systemDefault` /// - `requireALPN` equals `false` @@ -226,7 +228,7 @@ extension HTTP2ServerTransport.Posix.TransportSecurity { return config } - /// Create a new HTTP2 NIO Posix transport TLS config, with some values defaulted to match + /// Creates a new HTTP2 NIO Posix transport TLS config, with some values defaulted to match /// the requirements of mTLS: /// - `clientCertificateVerificationMode` equals `noHostnameVerification` /// - `trustRoots` equals `systemDefault` @@ -272,7 +274,7 @@ extension HTTP2ClientTransport.Posix { package let wrapped: Wrapped - /// This connection is plaintext: no encryption will take place. + /// This connection is plaintext; no encryption takes place. public static let plaintext = Self(wrapped: .plaintext) /// Secure the connection with the given TLS configuration. @@ -322,10 +324,10 @@ extension HTTP2ClientTransport.Posix { return .tls(tlsConfig) } - /// Create a new TLS config suitable for mTLS using a certificate reloader to provide the + /// Creates a new TLS config suitable for mTLS using a certificate reloader to provide the /// certificate chain and private key. /// - /// The reloader must provide an initial certificate chain and private key. If you have already + /// The reloader must provide an initial certificate chain and private key. If you already /// have an initial certificate chain and private key you can use /// ``mTLS(certificateChain:privateKey:configure:)`` and set the certificate reloader via /// the `configure` callback. @@ -358,6 +360,7 @@ extension HTTP2ClientTransport.Posix { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ClientTransport.Posix.TransportSecurity { + /// TLS configuration for the `Posix` client transport. public struct TLS: Sendable { /// The certificates the client will offer during negotiation. public var certificateChain: [TLSConfig.CertificateSource] @@ -369,7 +372,8 @@ extension HTTP2ClientTransport.Posix.TransportSecurity { public var serverCertificateVerification: TLSConfig.CertificateVerification /// Override the certificate verification with a custom callback that must return the verified certificate chain on success. - /// Note: The callback is only used when `serverCertificateVerification` is *not* set to `noVerification`! + /// + /// - Note: The callback is only used when `serverCertificateVerification` isn't set to `noVerification`. @available(gRPCSwiftNIOTransport 2.3, *) public var customVerificationCallback: ( @@ -386,7 +390,7 @@ extension HTTP2ClientTransport.Posix.TransportSecurity { /// use at that point in time. public var certificateReloader: (any CertificateReloader)? - /// Create a new HTTP2 NIO Posix client transport TLS config. + /// Creates a new HTTP2 NIO Posix client transport TLS config. /// - Parameters: /// - certificateChain: The certificates the client will offer during negotiation. /// - privateKey: The private key associated with the leaf certificate. @@ -404,7 +408,7 @@ extension HTTP2ClientTransport.Posix.TransportSecurity { self.trustRoots = trustRoots } - /// Create a new HTTP2 NIO Posix transport TLS config, with some values defaulted: + /// Creates a new HTTP2 NIO Posix transport TLS config, with some values defaulted: /// - `certificateChain` equals `[]` /// - `privateKey` equals `nil` /// - `serverCertificateVerification` equals `fullVerification` @@ -426,14 +430,14 @@ extension HTTP2ClientTransport.Posix.TransportSecurity { return config } - /// Create a new HTTP2 NIO Posix transport TLS config, with some values defaulted: + /// Creates a new HTTP2 NIO Posix transport TLS config, with some values defaulted: /// - `certificateChain` equals `[]` /// - `privateKey` equals `nil` /// - `serverCertificateVerification` equals `fullVerification` /// - `trustRoots` equals `systemDefault` public static var defaults: Self { .defaults() } - /// Create a new HTTP2 NIO Posix transport TLS config, with some values defaulted to match + /// Creates a new HTTP2 NIO Posix transport TLS config, with some values defaulted to match /// the requirements of mTLS: /// - `trustRoots` equals `systemDefault` /// - `serverCertificateVerification` equals `fullVerification` @@ -464,8 +468,8 @@ extension HTTP2ClientTransport.Posix.TransportSecurity { extension TLSConfig.PrivateKeySource { /// Creates a key source from a `NIOSSLCustomPrivateKey`. /// - /// This private key source is only applicable to the NIOPosix based transports. Using one - /// with a NIOTransportServices based transport is a programmer error. + /// This private key source is only applicable to the NIOPosix-based transports. Using one + /// with a NIOTransportServices-based transport is a programmer error. /// /// - Parameter key: The custom private key. /// - Returns: A private key source wrapping the custom private key. diff --git a/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/Documentation.md b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/Documentation.md index d3cf09d1..65fa970a 100644 --- a/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/Documentation.md +++ b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/Documentation.md @@ -4,14 +4,12 @@ HTTP/2 client and server transports built on top of SwiftNIO's `NIOPosix` module ## Overview -This module provides HTTP/2 transports for client and server built on top SwiftNIO's `NIOPosix` +This module provides HTTP/2 transports for client and server built on top of SwiftNIO's `NIOPosix` module and uses SwiftNIO's `NIOSSL` module to provide TLS. -The two transport types are: -- `HTTP2ClientTransport.Posix`, and -- `HTTP2ServerTransport.Posix`. +The two transport types are `HTTP2ClientTransport.Posix` and `HTTP2ServerTransport.Posix`. -### Availability +### Supported platforms These transports are available on the following platforms: @@ -21,7 +19,6 @@ These transports are available on the following platforms: - tvOS 18.0+ - watchOS 11.0+ - ### Getting started Bootstrapping a client or server is made easier using the `.http2NIOPosix` shorthand: @@ -53,3 +50,10 @@ try await withGRPCServer( // ... } ``` + +## Topics + +### Transports + +- ``HTTP2ClientTransport/Posix`` +- ``HTTP2ServerTransport/Posix`` diff --git a/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.Config.md b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.Config.md new file mode 100644 index 00000000..5d394eec --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.Config.md @@ -0,0 +1,17 @@ +# ``HTTP2ClientTransport/Posix/Config`` + +## Topics + +### Creating a configuration + +- ``init(http2:backoff:connection:compression:channelDebuggingCallbacks:)`` +- ``defaults`` +- ``defaults(configure:)`` + +### Configuring behavior + +- ``http2`` +- ``backoff`` +- ``connection`` +- ``compression`` +- ``channelDebuggingCallbacks`` diff --git a/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.TransportSecurity.TLS.md b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.TransportSecurity.TLS.md new file mode 100644 index 00000000..8d34a6f7 --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.TransportSecurity.TLS.md @@ -0,0 +1,22 @@ +# ``HTTP2ClientTransport/Posix/TransportSecurity/TLS`` + +## Topics + +### Creating a TLS configuration + +- ``init(certificateChain:privateKey:serverCertificateVerification:trustRoots:)`` +- ``defaults`` +- ``defaults(configure:)`` +- ``mTLS(certificateChain:privateKey:configure:)`` + +### Certificates and keys + +- ``certificateChain`` +- ``privateKey`` +- ``certificateReloader`` + +### Verifying the server + +- ``serverCertificateVerification`` +- ``trustRoots`` +- ``customVerificationCallback`` diff --git a/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.TransportSecurity.md b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.TransportSecurity.md new file mode 100644 index 00000000..aa4068c2 --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.TransportSecurity.md @@ -0,0 +1,20 @@ +# ``HTTP2ClientTransport/Posix/TransportSecurity`` + +## Topics + +### Connecting without TLS + +- ``plaintext`` +- ``customSecure`` + +### Connecting with TLS + +- ``tls`` +- ``tls(_:)`` +- ``tls(configure:)`` +- ``TLS`` + +### Connecting with mutual TLS + +- ``mTLS(certificateChain:privateKey:configure:)`` +- ``mTLS(certificateReloader:configure:)`` diff --git a/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.md b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.md new file mode 100644 index 00000000..d51f7021 --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ClientTransport.Posix.md @@ -0,0 +1,21 @@ +# ``HTTP2ClientTransport/Posix`` + +## Topics + +### Creating a transport + +- ``init(target:transportSecurity:config:resolverRegistry:serviceConfig:eventLoopGroup:)`` +- ``http2NIOPosix(target:transportSecurity:config:resolverRegistry:serviceConfig:eventLoopGroup:)`` +- ``Config`` +- ``TransportSecurity`` + +### Making requests + +- ``withStream(descriptor:options:_:)`` +- ``config(forMethod:)`` +- ``retryThrottle`` + +### Managing the connection + +- ``connect()`` +- ``beginGracefulShutdown()`` diff --git a/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.Config.md b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.Config.md new file mode 100644 index 00000000..183ed0e7 --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.Config.md @@ -0,0 +1,17 @@ +# ``HTTP2ServerTransport/Posix/Config`` + +## Topics + +### Creating a configuration + +- ``init(http2:rpc:connection:compression:channelDebuggingCallbacks:)`` +- ``defaults`` +- ``defaults(configure:)`` + +### Configuring behavior + +- ``http2`` +- ``rpc`` +- ``connection`` +- ``compression`` +- ``channelDebuggingCallbacks`` diff --git a/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.TransportSecurity.TLS.md b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.TransportSecurity.TLS.md new file mode 100644 index 00000000..220576fb --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.TransportSecurity.TLS.md @@ -0,0 +1,22 @@ +# ``HTTP2ServerTransport/Posix/TransportSecurity/TLS`` + +## Topics + +### Creating a TLS configuration + +- ``init(certificateChain:privateKey:clientCertificateVerification:trustRoots:requireALPN:)`` +- ``defaults(certificateChain:privateKey:configure:)`` +- ``mTLS(certificateChain:privateKey:configure:)`` + +### Certificates and keys + +- ``certificateChain`` +- ``privateKey`` +- ``certificateReloader`` + +### Verifying clients + +- ``clientCertificateVerification`` +- ``trustRoots`` +- ``customVerificationCallback`` +- ``requireALPN`` diff --git a/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.TransportSecurity.md b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.TransportSecurity.md new file mode 100644 index 00000000..71d0d7b8 --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.TransportSecurity.md @@ -0,0 +1,19 @@ +# ``HTTP2ServerTransport/Posix/TransportSecurity`` + +## Topics + +### Serving without TLS + +- ``plaintext`` + +### Serving with TLS + +- ``tls(_:)`` +- ``tls(certificateChain:privateKey:configure:)`` +- ``tls(certificateReloader:configure:)`` +- ``TLS`` + +### Serving with mutual TLS + +- ``mTLS(certificateChain:privateKey:configure:)`` +- ``mTLS(certificateReloader:configure:)`` diff --git a/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.md b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.md new file mode 100644 index 00000000..04c36e4b --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/reference/HTTP2ServerTransport.Posix.md @@ -0,0 +1,23 @@ +# ``HTTP2ServerTransport/Posix`` + +## Topics + +### Creating a transport + +- ``init(address:transportSecurity:config:eventLoopGroup:)`` +- ``http2NIOPosix(address:transportSecurity:config:eventLoopGroup:)`` +- ``init(listeningSocketDescriptor:transportSecurity:config:eventLoopGroup:)`` +- ``http2NIOPosix(listeningSocketDescriptor:transportSecurity:config:eventLoopGroup:)`` +- ``Config`` +- ``TransportSecurity`` + +### Serving + +- ``listen(streamHandler:)`` +- ``configure(context:)`` +- ``listeningAddress`` +- ``Context`` + +### Shutting down + +- ``beginGracefulShutdown()`` diff --git a/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ClientTransport+Posix.swift b/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ClientTransport+Posix.swift index 59df1590..9f95cd00 100644 --- a/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ClientTransport+Posix.swift +++ b/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ClientTransport+Posix.swift @@ -25,11 +25,11 @@ extension HTTP2ClientTransport { /// A `ClientTransport` using HTTP/2 built on top of `NIOPosix`. /// /// This transport builds on top of SwiftNIO's Posix networking layer and is suitable for use - /// on Linux and Darwin based platforms (macOS, iOS, etc.). However, it's *strongly* recommended + /// on Linux and Darwin-based platforms (macOS, iOS, etc.). However, it's *strongly* recommended /// that if you are targeting Darwin platforms then you should use the `NIOTS` variant of /// the `HTTP2ClientTransport`. /// - /// To use this transport you need to provide a 'target' to connect to which will be resolved + /// To use this transport you need to provide a `target` to connect to which will be resolved /// by an appropriate resolver from the resolver registry. By default the resolver registry can /// resolve DNS targets, IPv4 and IPv6 targets, Unix domain socket targets, and Virtual Socket /// targets. If you use a custom target you must also provide an appropriately configured @@ -104,22 +104,27 @@ extension HTTP2ClientTransport { ) } + /// The retry throttle derived from the service config, if any. public var retryThrottle: RetryThrottle? { self.channel.retryThrottle } + /// Connects to the resolved target and waits for the connection to become ready. public func connect() async throws { await self.channel.connect() } + /// Returns the method-specific configuration for the given method, if any. public func config(forMethod descriptor: MethodDescriptor) -> MethodConfig? { self.channel.config(forMethod: descriptor) } + /// Begins graceful shutdown of the underlying channel. public func beginGracefulShutdown() { self.channel.beginGracefulShutdown() } + /// Opens a stream on the channel and uses it as input to the given closure. public func withStream( descriptor: MethodDescriptor, options: CallOptions, @@ -226,6 +231,7 @@ extension HTTP2ClientTransport.Posix { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ClientTransport.Posix { + /// Configuration for the `Posix` client transport. public struct Config: Sendable { /// Configuration for HTTP/2 connections. public var http2: HTTP2ClientTransport.Config.HTTP2 diff --git a/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ServerTransport+Posix.swift b/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ServerTransport+Posix.swift index ce26f061..2404ccbf 100644 --- a/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ServerTransport+Posix.swift +++ b/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ServerTransport+Posix.swift @@ -30,7 +30,7 @@ extension HTTP2ServerTransport { /// A `ServerTransport` using HTTP/2 built on top of `NIOPosix`. /// /// This transport builds on top of SwiftNIO's Posix networking layer and is suitable for use - /// on Linux and Darwin based platform (macOS, iOS, etc.) However, it's *strongly* recommended + /// on Linux and Darwin-based platforms (macOS, iOS, etc.). However, it's *strongly* recommended /// that if you are targeting Darwin platforms then you should use the `NIOTS` variant of /// the `HTTP2ServerTransport`. /// @@ -159,7 +159,7 @@ extension HTTP2ServerTransport { /// /// It is an `async` property because it will only return once the address has been successfully bound. /// - /// - Throws: A runtime error will be thrown if the address could not be bound or is not bound any + /// - Throws: A runtime error is thrown if the address could not be bound or is not bound any /// longer, because the transport isn't listening anymore. It can also throw if the transport returned an /// invalid address. public var listeningAddress: GRPCNIOTransportCore.SocketAddress { @@ -186,13 +186,13 @@ extension HTTP2ServerTransport { } } - /// Create a new `Posix` transport. + /// Creates a new `Posix` transport. /// /// - Parameters: /// - address: The address to which the server should be bound. /// - transportSecurity: The configuration for securing network traffic. /// - config: The transport configuration. - /// - eventLoopGroup: The ELG from which to get ELs to run this transport. + /// - eventLoopGroup: The underlying NIO `EventLoopGroup` to run this transport on. public init( address: GRPCNIOTransportCore.SocketAddress, transportSecurity: TransportSecurity, @@ -207,13 +207,13 @@ extension HTTP2ServerTransport { ) } - /// Create a new `Posix` transport. + /// Creates a new `Posix` transport. /// /// - Parameters: /// - fileDescriptor: The file descriptor of an already bound listening socket. /// - transportSecurity: The configuration for securing network traffic. /// - config: The transport configuration. - /// - eventLoopGroup: The ELG from which to get ELs to run this transport. + /// - eventLoopGroup: The underlying NIO `EventLoopGroup` to run this transport on. /// - Important: gRPC takes ownership of the `fileDescriptor` passed in, you *must not* close /// the descriptor manually. @available(gRPCSwiftNIOTransport 2.6, *) @@ -257,7 +257,7 @@ extension HTTP2ServerTransport { var context = HTTP2ServerTransport.Posix.Context() do { - // The validadted certificate chain is only available when using a custom verification callback, while the + // The validated certificate chain is only available when using a custom verification callback, while the // peer certificate is only available when using the BoringSSL backend. But if we can get the certificate // chain, we can set the peer certificate (the leaf of the chain) as well. if let peerCertificateChain = @@ -277,10 +277,12 @@ extension HTTP2ServerTransport { } } + /// Stores the server context, making it available to accepted connections. public func configure(context: GRPCServerContext) { self.underlyingTransport.configure(context: context) } + /// Starts serving, binding the listening address and accepting connections. public func listen( streamHandler: @escaping @Sendable ( @@ -291,6 +293,7 @@ extension HTTP2ServerTransport { try await self.underlyingTransport.listen(streamHandler: streamHandler) } + /// Begins graceful shutdown of the listening channel. public func beginGracefulShutdown() { self.underlyingTransport.beginGracefulShutdown() } @@ -299,15 +302,16 @@ extension HTTP2ServerTransport { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ServerTransport.Posix { - /// Context for Posix TransportSpecific + /// The transport-specific context for the `Posix` server transport. public struct Context: ServerContext.TransportSpecific { - /// The peer certificate (if any) from the mTLS handshake + /// The peer certificate (if any) from the mTLS handshake. public var peerCertificate: Certificate? /// The validated peer certificate chain from the mTLS handshake. This is only available when using a custom verification callback. @available(gRPCSwiftNIOTransport 2.2, *) public var peerCertificateChain: X509.ValidatedCertificateChain? + /// Creates a new, empty context. public init() { } } @@ -329,7 +333,7 @@ extension HTTP2ServerTransport.Posix { /// Channel callbacks for debugging. public var channelDebuggingCallbacks: HTTP2ServerTransport.Config.ChannelDebuggingCallbacks - /// Construct a new `Config`. + /// Creates a new configuration. /// /// - Parameters: /// - http2: HTTP2 configuration. @@ -415,7 +419,7 @@ extension ServerBootstrap { @available(gRPCSwiftNIOTransport 2.0, *) extension ServerTransport where Self == HTTP2ServerTransport.Posix { - /// Create a new `Posix` based HTTP/2 server transport. + /// Creates a new `Posix` based HTTP/2 server transport. /// /// - Parameters: /// - address: The address to which the server should be bound. @@ -441,7 +445,7 @@ extension ServerTransport where Self == HTTP2ServerTransport.Posix { @available(gRPCSwiftNIOTransport 2.6, *) extension ServerTransport where Self == HTTP2ServerTransport.Posix { - /// Create a new `Posix` based HTTP/2 server transport. + /// Creates a new `Posix` based HTTP/2 server transport. /// /// - Parameters: /// - fileDescriptor: The file descriptor of an already bound listening socket. diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/Config+TLS.swift b/Sources/GRPCNIOTransportHTTP2TransportServices/Config+TLS.swift index a5e2cea2..d655928d 100644 --- a/Sources/GRPCNIOTransportHTTP2TransportServices/Config+TLS.swift +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/Config+TLS.swift @@ -33,7 +33,7 @@ extension HTTP2ServerTransport.TransportServices { package let wrapped: Wrapped - /// This connection is plaintext: no encryption will take place. + /// This connection is plaintext; no encryption takes place. public static let plaintext = Self(wrapped: .plaintext) /// Secures connections with the given TLS configuration. @@ -41,7 +41,7 @@ extension HTTP2ServerTransport.TransportServices { Self(wrapped: .tls(tls)) } - /// Secures connections with the TLS. + /// Secures connections with TLS. /// /// - Parameters: /// - identityProvider: A provider for the `SecIdentity` to be used when setting up TLS. @@ -57,7 +57,7 @@ extension HTTP2ServerTransport.TransportServices { return .tls(tlsConfig) } - /// Secures connections with the mutual TLS. + /// Secures connections with mutual TLS. /// /// - Parameters: /// - identityProvider: A provider for the `SecIdentity` to be used when setting up TLS. @@ -77,6 +77,7 @@ extension HTTP2ServerTransport.TransportServices { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ServerTransport.TransportServices { + /// TLS configuration for the `TransportServices` server transport. public struct TLS: Sendable { /// How to verify the client certificate, if one is presented. public var clientCertificateVerification: TLSConfig.CertificateVerification @@ -86,7 +87,7 @@ extension HTTP2ServerTransport.TransportServices { /// Whether ALPN is required. /// - /// If this is set to `true` but the client does not support ALPN, then the connection will be rejected. + /// If this is set to `true` but the client does not support ALPN, then the connection is rejected. public var requireALPN: Bool /// A provider for the `SecIdentity` to be used when setting up TLS. @@ -100,7 +101,7 @@ extension HTTP2ServerTransport.TransportServices { @available(gRPCSwiftNIOTransport 2.5, *) public var additionalCertificates: [SecCertificate] - /// Create a new HTTP2 NIO Transport Services transport TLS config. + /// Creates a new HTTP2 NIO Transport Services transport TLS config. /// - Parameters: /// - clientCertificateVerification: How to verify the client certificate, if one is presented. /// - trustRoots: The trust roots to be used when verifying client certificates. @@ -119,7 +120,7 @@ extension HTTP2ServerTransport.TransportServices { self.additionalCertificates = [] } - /// Create a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted: + /// Creates a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted: /// - `clientCertificateVerificationMode` equals `doNotVerify` /// - `trustRoots` equals `systemDefault` /// - `requireALPN` equals `false` @@ -142,7 +143,7 @@ extension HTTP2ServerTransport.TransportServices { return config } - /// Create a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted to match + /// Creates a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted to match /// the requirements of mTLS: /// - `clientCertificateVerificationMode` equals `noHostnameVerification` /// - `trustRoots` equals `systemDefault` @@ -193,15 +194,15 @@ extension HTTP2ClientTransport.TransportServices { @available(gRPCSwiftNIOTransport 2.8, *) public static let customSecure = Self(wrapped: .customSecure) - /// This connection is plaintext: no encryption will take place. + /// This connection is plaintext; no encryption takes place. public static let plaintext = Self(wrapped: .plaintext) - /// Secure connections with the given TLS configuration. + /// Secures connections with the given TLS configuration. public static func tls(_ tls: TLS) -> Self { Self(wrapped: .tls(tls)) } - /// Secure connections with TLS. + /// Secures connections with TLS. /// /// - Parameters: /// - configure: A closure which allows you to modify the defaults before returning them. @@ -212,12 +213,12 @@ extension HTTP2ClientTransport.TransportServices { return .tls(tlsConfig) } - /// Secure connections with TLS. + /// Secures connections with TLS. public static var tls: Self { return .tls() } - /// Secure connections with mutual TLS. + /// Secures connections with mutual TLS. /// /// - Parameters: /// - identityProvider: A provider for the `SecIdentity` to be used when setting up TLS. @@ -237,6 +238,7 @@ extension HTTP2ClientTransport.TransportServices { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ClientTransport.TransportServices { + /// TLS configuration for the `TransportServices` client transport. public struct TLS: Sendable { /// How to verify the server certificate, if one is presented. public var serverCertificateVerification: TLSConfig.CertificateVerification @@ -256,7 +258,7 @@ extension HTTP2ClientTransport.TransportServices { @available(gRPCSwiftNIOTransport 2.5, *) public var additionalCertificates: [SecCertificate] - /// Create a new HTTP2 NIO Transport Services transport TLS config. + /// Creates a new HTTP2 NIO Transport Services transport TLS config. /// - Parameters: /// - serverCertificateVerification: How to verify the server certificate, if one is presented. /// - trustRoots: The trust roots to be used when verifying server certificates. @@ -272,14 +274,14 @@ extension HTTP2ClientTransport.TransportServices { self.additionalCertificates = [] } - /// Create a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted: + /// Creates a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted: /// - `serverCertificateVerification` equals `fullVerification` /// - `trustRoots` equals `systemDefault` /// - `identityProvider` equals `nil` /// /// - Parameters: /// - configure: A closure which allows you to modify the defaults before returning them. - /// - Returns: A new HTTP2 NIO Posix transport TLS config. + /// - Returns: A new HTTP2 NIO Transport Services transport TLS config. public static func defaults( configure: (_ config: inout Self) -> Void = { _ in } ) -> Self { @@ -292,13 +294,13 @@ extension HTTP2ClientTransport.TransportServices { return config } - /// Create a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted: + /// Creates a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted: /// - `serverCertificateVerification` equals `fullVerification` /// - `trustRoots` equals `systemDefault` /// - `identityProvider` equals `nil` public static var defaults: Self { .defaults() } - /// Create a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted to match + /// Creates a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted to match /// the requirements of mTLS: /// - `serverCertificateVerification` equals `fullVerification` /// - `trustRoots` equals `systemDefault` @@ -306,7 +308,7 @@ extension HTTP2ClientTransport.TransportServices { /// - Parameters: /// - identityProvider: A provider for the `SecIdentity` to be used when setting up TLS. /// - configure: A closure which allows you to modify the defaults before returning them. - /// - Returns: A new HTTP2 NIO Posix transport TLS config. + /// - Returns: A new HTTP2 NIO Transport Services transport TLS config. public static func mTLS( identityProvider: @Sendable @escaping () throws -> SecIdentity, configure: (_ config: inout Self) -> Void = { _ in } diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/Documentation.md b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/Documentation.md index e442f6e9..6d6a41ef 100644 --- a/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/Documentation.md +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/Documentation.md @@ -4,14 +4,13 @@ HTTP/2 client and server transports built on top of SwiftNIO's `NIOTransportServ ## Overview -This module provides HTTP/2 transports for client and server built on top SwiftNIO's -`NIOTransportServices` module which provide TLS via Apple's Network framework. +This module provides HTTP/2 transports for client and server built on top of SwiftNIO's +`NIOTransportServices` module which provides TLS via Apple's Network framework. -The two transport types are: -- `HTTP2ClientTransport.TransportServices`, and -- `HTTP2ServerTransport.TransportServices`. +The two transport types are `HTTP2ClientTransport.TransportServices` and +`HTTP2ServerTransport.TransportServices`. -### Availability +### Supported platforms These transports are available on the following platforms: @@ -20,7 +19,6 @@ These transports are available on the following platforms: - tvOS 18.0+ - watchOS 11.0+ - ### Getting started Bootstrapping a client or server is made easier using the `.http2NIOTS` shorthand: @@ -52,3 +50,10 @@ try await withGRPCServer( // ... } ``` + +## Topics + +### Transports + +- ``HTTP2ClientTransport/TransportServices`` +- ``HTTP2ServerTransport/TransportServices`` diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.Config.md b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.Config.md new file mode 100644 index 00000000..8d3e0999 --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.Config.md @@ -0,0 +1,18 @@ +# ``HTTP2ClientTransport/TransportServices/Config`` + +## Topics + +### Creating a configuration + +- ``init(http2:backoff:connection:compression:channelDebuggingCallbacks:)`` +- ``defaults`` +- ``defaults(configure:)`` + +### Configuring behavior + +- ``http2`` +- ``backoff`` +- ``resolverBackoff`` +- ``connection`` +- ``compression`` +- ``channelDebuggingCallbacks`` diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.TLS.md b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.TLS.md new file mode 100644 index 00000000..e490021b --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.TLS.md @@ -0,0 +1,20 @@ +# ``HTTP2ClientTransport/TransportServices/TLS`` + +## Topics + +### Creating a TLS configuration + +- ``init(serverCertificateVerification:trustRoots:identityProvider:)`` +- ``defaults`` +- ``defaults(configure:)`` +- ``mTLS(identityProvider:configure:)`` + +### Identity and certificates + +- ``identityProvider`` +- ``additionalCertificates`` + +### Verifying the server + +- ``serverCertificateVerification`` +- ``trustRoots`` diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.TransportSecurity.md b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.TransportSecurity.md new file mode 100644 index 00000000..b465fb95 --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.TransportSecurity.md @@ -0,0 +1,18 @@ +# ``HTTP2ClientTransport/TransportServices/TransportSecurity`` + +## Topics + +### Connecting without TLS + +- ``plaintext`` +- ``customSecure`` + +### Connecting with TLS + +- ``tls`` +- ``tls(_:)`` +- ``tls(configure:)`` + +### Connecting with mutual TLS + +- ``mTLS(identityProvider:configure:)`` diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.md b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.md new file mode 100644 index 00000000..cdc43e00 --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ClientTransport.TransportServices.md @@ -0,0 +1,22 @@ +# ``HTTP2ClientTransport/TransportServices`` + +## Topics + +### Creating a transport + +- ``init(target:transportSecurity:config:resolverRegistry:serviceConfig:eventLoopGroup:)`` +- ``http2NIOTS(target:transportSecurity:config:resolverRegistry:serviceConfig:eventLoopGroup:)`` +- ``Config`` +- ``TransportSecurity`` +- ``TLS`` + +### Making requests + +- ``withStream(descriptor:options:_:)`` +- ``config(forMethod:)`` +- ``retryThrottle`` + +### Managing the connection + +- ``connect()`` +- ``beginGracefulShutdown()`` diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.Config.md b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.Config.md new file mode 100644 index 00000000..a21b3963 --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.Config.md @@ -0,0 +1,17 @@ +# ``HTTP2ServerTransport/TransportServices/Config`` + +## Topics + +### Creating a configuration + +- ``init(compression:connection:http2:rpc:channelDebuggingCallbacks:)`` +- ``defaults`` +- ``defaults(configure:)`` + +### Configuring behavior + +- ``http2`` +- ``rpc`` +- ``connection`` +- ``compression`` +- ``channelDebuggingCallbacks`` diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.TLS.md b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.TLS.md new file mode 100644 index 00000000..d324b698 --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.TLS.md @@ -0,0 +1,20 @@ +# ``HTTP2ServerTransport/TransportServices/TLS`` + +## Topics + +### Creating a TLS configuration + +- ``init(clientCertificateVerification:trustRoots:requireALPN:identityProvider:)`` +- ``defaults(identityProvider:configure:)`` +- ``mTLS(identityProvider:configure:)`` + +### Identity and certificates + +- ``identityProvider`` +- ``additionalCertificates`` + +### Verifying clients + +- ``clientCertificateVerification`` +- ``trustRoots`` +- ``requireALPN`` diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.TransportSecurity.md b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.TransportSecurity.md new file mode 100644 index 00000000..ccf79d2a --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.TransportSecurity.md @@ -0,0 +1,16 @@ +# ``HTTP2ServerTransport/TransportServices/TransportSecurity`` + +## Topics + +### Serving without TLS + +- ``plaintext`` + +### Serving with TLS + +- ``tls(_:)`` +- ``tls(identityProvider:configure:)`` + +### Serving with mutual TLS + +- ``mTLS(identityProvider:configure:)`` diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.md b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.md new file mode 100644 index 00000000..bd95fb23 --- /dev/null +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/reference/HTTP2ServerTransport.TransportServices.md @@ -0,0 +1,21 @@ +# ``HTTP2ServerTransport/TransportServices`` + +## Topics + +### Creating a transport + +- ``init(address:transportSecurity:config:eventLoopGroup:)`` +- ``http2NIOTS(address:transportSecurity:config:eventLoopGroup:)`` +- ``Config`` +- ``TransportSecurity`` +- ``TLS`` + +### Serving + +- ``listen(streamHandler:)`` +- ``configure(context:)`` +- ``listeningAddress`` + +### Shutting down + +- ``beginGracefulShutdown()`` diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ClientTransport+TransportServices.swift b/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ClientTransport+TransportServices.swift index cba2aad6..dc501351 100644 --- a/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ClientTransport+TransportServices.swift +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ClientTransport+TransportServices.swift @@ -31,7 +31,7 @@ extension HTTP2ClientTransport { /// If you are targeting Linux platforms then you should use the `NIOPosix` variant of /// the `HTTP2ClientTransport`. /// - /// To use this transport you need to provide a 'target' to connect to which will be resolved + /// To use this transport you need to provide a `target` to connect to which will be resolved /// by an appropriate resolver from the resolver registry. By default the resolver registry can /// resolve DNS targets, IPv4 and IPv6 targets, and Unix domain socket targets. Virtual Socket /// targets are not supported with this transport. If you use a custom target you must also provide an @@ -63,6 +63,7 @@ extension HTTP2ClientTransport { private let channel: GRPCChannel + /// The retry throttle derived from the service config, if any. public var retryThrottle: RetryThrottle? { self.channel.retryThrottle } @@ -77,8 +78,8 @@ extension HTTP2ClientTransport { /// - serviceConfig: Service config controlling how the transport should establish and /// load-balance connections. /// - eventLoopGroup: The underlying NIO `EventLoopGroup` to run connections on. This must - /// be a `MultiThreadedEventLoopGroup` or an `EventLoop` from - /// a `MultiThreadedEventLoopGroup`. + /// be a `NIOTSEventLoopGroup` or an `EventLoop` from + /// a `NIOTSEventLoopGroup`. /// - Throws: When no suitable resolver could be found for the `target`. public init( target: any ResolvableTarget, @@ -110,14 +111,17 @@ extension HTTP2ClientTransport { ) } + /// Connects to the resolved target and waits for the connection to become ready. public func connect() async throws { await self.channel.connect() } + /// Begins graceful shutdown of the underlying channel. public func beginGracefulShutdown() { self.channel.beginGracefulShutdown() } + /// Opens a stream on the channel and uses it as input to the given closure. public func withStream( descriptor: MethodDescriptor, options: CallOptions, @@ -126,6 +130,7 @@ extension HTTP2ClientTransport { try await self.channel.withStream(descriptor: descriptor, options: options, closure) } + /// Returns the method-specific configuration for the given method, if any. public func config(forMethod descriptor: MethodDescriptor) -> MethodConfig? { self.channel.config(forMethod: descriptor) } @@ -334,7 +339,7 @@ extension NIOTSConnectionBootstrap { @available(gRPCSwiftNIOTransport 2.0, *) extension ClientTransport where Self == HTTP2ClientTransport.TransportServices { - /// Create a new `TransportServices` based HTTP/2 client transport. + /// Creates a new `TransportServices` based HTTP/2 client transport. /// /// - Parameters: /// - target: A target to resolve. diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ServerTransport+TransportServices.swift b/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ServerTransport+TransportServices.swift index 874c6eff..51ef0cec 100644 --- a/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ServerTransport+TransportServices.swift +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ServerTransport+TransportServices.swift @@ -94,7 +94,7 @@ extension HTTP2ServerTransport { /// /// It is an `async` property because it will only return once the address has been successfully bound. /// - /// - Throws: A runtime error will be thrown if the address could not be bound or is not bound any + /// - Throws: A runtime error is thrown if the address could not be bound or is not bound any /// longer, because the transport isn't listening anymore. It can also throw if the transport returned an /// invalid address. public var listeningAddress: GRPCNIOTransportCore.SocketAddress { @@ -113,13 +113,13 @@ extension HTTP2ServerTransport { } } - /// Create a new `TransportServices` transport. + /// Creates a new `TransportServices` transport. /// /// - Parameters: /// - address: The address to which the server should be bound. /// - transportSecurity: The security settings applied to the transport. /// - config: The transport configuration. - /// - eventLoopGroup: The ELG from which to get ELs to run this transport. + /// - eventLoopGroup: The underlying NIO `EventLoopGroup` to run this transport on. public init( address: GRPCNIOTransportCore.SocketAddress, transportSecurity: TransportSecurity, @@ -144,10 +144,12 @@ extension HTTP2ServerTransport { ) } + /// Stores the server context, making it available to accepted connections. public func configure(context: GRPCServerContext) { self.underlyingTransport.configure(context: context) } + /// Starts serving, binding the listening address and accepting connections. public func listen( streamHandler: @escaping @Sendable ( @@ -158,6 +160,7 @@ extension HTTP2ServerTransport { try await self.underlyingTransport.listen(streamHandler: streamHandler) } + /// Begins graceful shutdown of the listening channel. public func beginGracefulShutdown() { self.underlyingTransport.beginGracefulShutdown() } @@ -183,7 +186,7 @@ extension HTTP2ServerTransport.TransportServices { /// Channel callbacks for debugging. public var channelDebuggingCallbacks: HTTP2ServerTransport.Config.ChannelDebuggingCallbacks - /// Construct a new `Config`. + /// Creates a new configuration. /// - Parameters: /// - compression: Compression configuration. /// - connection: Connection configuration. @@ -206,6 +209,7 @@ extension HTTP2ServerTransport.TransportServices { self.channelDebuggingCallbacks = channelDebuggingCallbacks } + /// Default configuration. public static var defaults: Self { Self.defaults() } @@ -255,7 +259,7 @@ extension NIOTSListenerBootstrap { @available(gRPCSwiftNIOTransport 2.0, *) extension ServerTransport where Self == HTTP2ServerTransport.TransportServices { - /// Create a new `TransportServices` based HTTP/2 server transport. + /// Creates a new `TransportServices` based HTTP/2 server transport. /// /// - Parameters: /// - address: The address to which the server should be bound. From 0c00ce7f424d9c7ebec4665629ae0064fcbc024a Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Tue, 28 Jul 2026 11:27:33 -0700 Subject: [PATCH 2/3] rework asbtracts to narrative english prose, keeping the relevant detail provided in the discussion section of for documentation comments --- .../Client/HTTP2ClientTransport.swift | 22 ++++---- .../Client/Resolver/NameResolver+DNS.swift | 12 +++-- .../Client/Resolver/NameResolver+IPv4.swift | 18 ++++--- .../Client/Resolver/NameResolver+IPv6.swift | 18 ++++--- .../Client/Resolver/NameResolver+UDS.swift | 12 +++-- .../Client/Resolver/NameResolver+VSOCK.swift | 12 +++-- .../Client/Resolver/NameResolver.swift | 24 ++++++--- .../Resolver/NameResolverRegistry.swift | 8 +-- .../Client/Resolver/SocketAddress.swift | 34 ++++++++----- .../WrappedChannel+Config.swift | 10 ++-- .../WrappedChannel/WrappedChannel.swift | 18 +++---- .../GRPCNIOTransportBytes.swift | 4 +- .../ListeningServerTransport.swift | 2 +- .../Server/CustomTransport.swift | 10 ++-- .../Server/HTTP2ServerTransport.swift | 39 +++++++++----- .../Server/ListenerFactory.swift | 2 +- Sources/GRPCNIOTransportCore/TLSConfig.swift | 22 +++++--- .../Config+TLS.swift | 51 +++++++++++-------- .../Documentation.docc/Documentation.md | 2 +- .../HTTP2ClientTransport+Posix.swift | 12 ++--- .../HTTP2ServerTransport+Posix.swift | 22 ++++---- .../Config+TLS.swift | 45 +++++++++------- .../Documentation.docc/Documentation.md | 2 +- ...TP2ClientTransport+TransportServices.swift | 12 ++--- ...TP2ServerTransport+TransportServices.swift | 9 ++-- 25 files changed, 256 insertions(+), 166 deletions(-) diff --git a/Sources/GRPCNIOTransportCore/Client/HTTP2ClientTransport.swift b/Sources/GRPCNIOTransportCore/Client/HTTP2ClientTransport.swift index e4aea749..830d4504 100644 --- a/Sources/GRPCNIOTransportCore/Client/HTTP2ClientTransport.swift +++ b/Sources/GRPCNIOTransportCore/Client/HTTP2ClientTransport.swift @@ -41,7 +41,7 @@ extension HTTP2ClientTransport.Config { /// - Note: `CompressionAlgorithm.none` is always supported, even if it isn't set here. public var enabledAlgorithms: CompressionAlgorithmSet - /// Creates a new compression configuration. + /// Creates a compression configuration. /// /// - SeeAlso: ``defaults``. public init(algorithm: CompressionAlgorithm, enabledAlgorithms: CompressionAlgorithmSet) { @@ -69,7 +69,7 @@ extension HTTP2ClientTransport.Config { /// Whether the client sends keepalive pings when there are no calls in progress. public var allowWithoutCalls: Bool - /// Creates a new keepalive configuration. + /// Creates a keepalive configuration. public init(time: Duration, timeout: Duration, allowWithoutCalls: Bool) { self.time = time self.timeout = timeout @@ -148,7 +148,7 @@ extension HTTP2ClientTransport.Config { /// The resulting backoff will therefore be between 8 seconds and 12 seconds. public var jitter: Double - /// Creates a new backoff configuration. + /// Creates a backoff configuration. public init(initial: Duration, max: Duration, multiplier: Double, jitter: Double) { self.initial = initial self.max = max @@ -156,8 +156,10 @@ extension HTTP2ClientTransport.Config { self.jitter = jitter } - /// Default values, initial backoff is one second and maximum backoff is two minutes. The - /// multiplier is `1.6` and the jitter is set to `0.2`. + /// Default values for backoff. + /// + /// The initial backoff is one second, the maximum backoff is two minutes, the multiplier + /// is `1.6`, and the jitter is `0.2`. public static var defaults: Self { Self(initial: .seconds(1), max: .seconds(120), multiplier: 1.6, jitter: 0.2) } @@ -184,7 +186,7 @@ extension HTTP2ClientTransport.Config { /// extension, if applicable. public var authority: String? - /// Creates a new HTTP/2 configuration. + /// Creates an HTTP/2 configuration. public init(maxFrameSize: Int, targetWindowSize: Int, authority: String?) { self.maxFrameSize = maxFrameSize self.targetWindowSize = targetWindowSize @@ -211,7 +213,7 @@ extension HTTP2ClientTransport.Config { /// A callback invoked with each new HTTP/2 stream. public var onCreateHTTP2Stream: (@Sendable (_ channel: any Channel) -> EventLoopFuture)? - /// Creates a new set of channel debugging callbacks. + /// Creates a set of channel debugging callbacks. public init( onCreateTCPConnection: (@Sendable (_ channel: any Channel) -> EventLoopFuture)?, onCreateHTTP2Stream: (@Sendable (_ channel: any Channel) -> EventLoopFuture)? @@ -256,7 +258,7 @@ extension HTTP2ClientTransport.Config.Connection { /// The number of bytes to buffer before a flush is emitted, regardless of the delay. public var maxBytes: Int - /// Creates a new flush coalescing configuration. + /// Creates a flush coalescing configuration. /// /// - SeeAlso: ``defaults``. public init(maxFlushDelay: Duration, maxBytes: Int) { @@ -264,7 +266,9 @@ extension HTTP2ClientTransport.Config.Connection { self.maxBytes = maxBytes } - /// Default values. The max flush delay is 100ΞΌs and the max bytes is 64KiB. + /// The default flush delay and byte count for the client transport. + /// + /// The max flush delay is 100ΞΌs and the max bytes is 64KiB. public static var defaults: Self { Self(maxFlushDelay: .microseconds(100), maxBytes: 64 * 1024) } diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+DNS.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+DNS.swift index da79acca..3edcc52f 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+DNS.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+DNS.swift @@ -31,7 +31,8 @@ extension ResolvableTargets { /// If no port is specified then 443 is used. public var port: Int? - /// Creates a new DNS target. + /// Creates a DNS target. + /// /// - Parameters: /// - host: The host to resolve via DNS. /// - port: The port to use with resolved addresses. @@ -44,7 +45,8 @@ extension ResolvableTargets { @available(gRPCSwiftNIOTransport 2.0, *) extension ResolvableTarget where Self == ResolvableTargets.DNS { - /// Creates a new resolvable DNS target. + /// Creates a resolvable DNS target. + /// /// - Parameters: /// - host: The host address to resolve. /// - port: The port to use for each resolved address. 443 will be used if unspecified. @@ -56,11 +58,13 @@ extension ResolvableTarget where Self == ResolvableTargets.DNS { @available(gRPCSwiftNIOTransport 2.0, *) extension NameResolvers { - /// A ``NameResolverFactory`` for ``ResolvableTargets/DNS`` targets. + /// A name resolver factory for DNS targets. + /// + /// Creates resolvers for ``ResolvableTargets/DNS`` targets. public struct DNS: NameResolverFactory, Sendable { public typealias Target = ResolvableTargets.DNS - /// Creates a new DNS name resolver factory. + /// Creates a DNS name resolver factory. public init() {} /// Creates a resolver for the given DNS target. diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv4.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv4.swift index 948295f6..bebfc463 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv4.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv4.swift @@ -29,7 +29,8 @@ extension ResolvableTargets { /// This array must not be empty. public var addresses: [SocketAddress.IPv4] - /// Creates a new IPv4 target. + /// Creates an IPv4 target. + /// /// - Parameter addresses: The IPv4 addresses. Must not be empty. public init(addresses: [SocketAddress.IPv4]) { debugOnly { @@ -57,7 +58,8 @@ extension ResolvableTargets { @available(gRPCSwiftNIOTransport 2.0, *) extension ResolvableTarget where Self == ResolvableTargets.IPv4 { - /// Creates a new resolvable IPv4 target for a single address. + /// Creates a resolvable IPv4 target for a single address. + /// /// - Parameters: /// - host: The resolved host address. /// - port: The port on the host. @@ -68,7 +70,8 @@ extension ResolvableTarget where Self == ResolvableTargets.IPv4 { return Self(addresses: [address]) } - /// Creates a new resolvable IPv4 target for a single address. + /// Creates a resolvable IPv4 target for a single address. + /// /// - Parameters: /// - address: The resolved host address. /// - port: The port on the host. @@ -79,7 +82,7 @@ extension ResolvableTarget where Self == ResolvableTargets.IPv4 { return Self(addresses: [address]) } - /// Creates a new resolvable IPv4 target from the provided host-port pairs. + /// Creates a resolvable IPv4 target from the provided host-port pairs. /// /// - Parameter pairs: An array of host-port pairs. /// - Returns: A ``ResolvableTarget``. @@ -91,14 +94,15 @@ extension ResolvableTarget where Self == ResolvableTargets.IPv4 { @available(gRPCSwiftNIOTransport 2.0, *) extension NameResolvers { - /// A ``NameResolverFactory`` for ``ResolvableTargets/IPv4`` targets. + /// A name resolver factory for IPv4 targets. /// - /// The name resolver for a given target always produces the same values, with one endpoint per + /// Creates resolvers for ``ResolvableTargets/IPv4`` targets. The name resolver for a given + /// target always produces the same values, with one endpoint per /// address in the target. This resolver doesn't support fetching service configuration. public struct IPv4: NameResolverFactory, Sendable { public typealias Target = ResolvableTargets.IPv4 - /// Creates a new IPv4 resolver factory. + /// Creates an IPv4 resolver factory. public init() {} /// Creates a resolver for the given IPv4 target. diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv6.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv6.swift index 32b65822..6d8e6f95 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv6.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv6.swift @@ -29,7 +29,8 @@ extension ResolvableTargets { /// This array must not be empty. public var addresses: [SocketAddress.IPv6] - /// Creates a new IPv6 target. + /// Creates an IPv6 target. + /// /// - Parameter addresses: The IPv6 addresses. Must not be empty. public init(addresses: [SocketAddress.IPv6]) { debugOnly { @@ -56,7 +57,8 @@ extension ResolvableTargets { @available(gRPCSwiftNIOTransport 2.0, *) extension ResolvableTarget where Self == ResolvableTargets.IPv6 { - /// Creates a new resolvable IPv6 target for a single address. + /// Creates a resolvable IPv6 target for a single address. + /// /// - Parameters: /// - host: The resolved host address. /// - port: The port on the host. @@ -67,7 +69,8 @@ extension ResolvableTarget where Self == ResolvableTargets.IPv6 { return Self(addresses: [address]) } - /// Creates a new resolvable IPv6 target for a single address. + /// Creates a resolvable IPv6 target for a single address. + /// /// - Parameters: /// - address: The resolved host address. /// - port: The port on the host. @@ -78,7 +81,7 @@ extension ResolvableTarget where Self == ResolvableTargets.IPv6 { return Self(addresses: [address]) } - /// Creates a new resolvable IPv6 target from the provided host-port pairs. + /// Creates a resolvable IPv6 target from the provided host-port pairs. /// /// - Parameter pairs: An array of host-port pairs. /// - Returns: A ``ResolvableTarget``. @@ -90,14 +93,15 @@ extension ResolvableTarget where Self == ResolvableTargets.IPv6 { @available(gRPCSwiftNIOTransport 2.0, *) extension NameResolvers { - /// A ``NameResolverFactory`` for ``ResolvableTargets/IPv6`` targets. + /// A name resolver factory for IPv6 targets. /// - /// The name resolver for a given target always produces the same values, with one endpoint per + /// Creates resolvers for ``ResolvableTargets/IPv6`` targets. The name resolver for a given + /// target always produces the same values, with one endpoint per /// address in the target. This resolver doesn't support fetching service configuration. public struct IPv6: NameResolverFactory, Sendable { public typealias Target = ResolvableTargets.IPv6 - /// Creates a new IPv6 resolver factory. + /// Creates an IPv6 resolver factory. public init() {} /// Creates a resolver for the given IPv6 target. diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+UDS.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+UDS.swift index 4db678a7..e551a660 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+UDS.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+UDS.swift @@ -31,7 +31,7 @@ extension ResolvableTargets { /// If unset then the path of the address will be used. public var authority: String? - /// Creates a new Unix Domain Socket target. + /// Creates a Unix Domain Socket target. public init(address: SocketAddress.UnixDomainSocket, authority: String?) { self.address = address self.authority = authority @@ -41,7 +41,8 @@ extension ResolvableTargets { @available(gRPCSwiftNIOTransport 2.0, *) extension ResolvableTarget where Self == ResolvableTargets.UnixDomainSocket { - /// Creates a new resolvable Unix Domain Socket target. + /// Creates a resolvable Unix Domain Socket target. + /// /// - Parameters: /// - path: The path of the socket. /// - authority: The service authority. @@ -58,14 +59,15 @@ extension ResolvableTarget where Self == ResolvableTargets.UnixDomainSocket { @available(gRPCSwiftNIOTransport 2.0, *) extension NameResolvers { - /// A ``NameResolverFactory`` for ``ResolvableTargets/UnixDomainSocket`` targets. + /// A name resolver factory for Unix Domain Socket targets. /// - /// The name resolver for a given target always produces the same values, with a single endpoint. + /// Creates resolvers for ``ResolvableTargets/UnixDomainSocket`` targets. The name resolver + /// for a given target always produces the same values, with a single endpoint. /// This resolver doesn't support fetching service configuration. public struct UnixDomainSocket: NameResolverFactory, Sendable { public typealias Target = ResolvableTargets.UnixDomainSocket - /// Creates a new Unix Domain Socket resolver factory. + /// Creates a Unix Domain Socket resolver factory. public init() {} /// Creates a resolver for the given Unix Domain Socket target. diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+VSOCK.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+VSOCK.swift index ddd6049f..5952b2c3 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+VSOCK.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+VSOCK.swift @@ -26,7 +26,7 @@ extension ResolvableTargets { /// The VSOCK address. public var address: SocketAddress.VirtualSocket - /// Creates a new resolvable VSOCK target. + /// Creates a resolvable VSOCK target. public init(address: SocketAddress.VirtualSocket) { self.address = address } @@ -35,7 +35,8 @@ extension ResolvableTargets { @available(gRPCSwiftNIOTransport 2.0, *) extension ResolvableTarget where Self == ResolvableTargets.VirtualSocket { - /// Creates a new resolvable Virtual Socket target. + /// Creates a resolvable Virtual Socket target. + /// /// - Parameters: /// - contextID: The context ID (`cid`) of the service. /// - port: The port to connect to. @@ -50,14 +51,15 @@ extension ResolvableTarget where Self == ResolvableTargets.VirtualSocket { @available(gRPCSwiftNIOTransport 2.0, *) extension NameResolvers { - /// A ``NameResolverFactory`` for ``ResolvableTargets/VirtualSocket`` targets. + /// A name resolver factory for Virtual Socket targets. /// - /// The name resolver for a given target always produces the same values, with a single endpoint. + /// Creates resolvers for ``ResolvableTargets/VirtualSocket`` targets. The name resolver + /// for a given target always produces the same values, with a single endpoint. /// This resolver doesn't support fetching service configuration. public struct VirtualSocket: NameResolverFactory, Sendable { public typealias Target = ResolvableTargets.VirtualSocket - /// Creates a new VSOCK resolver factory. + /// Creates a VSOCK resolver factory. public init() {} /// Creates a resolver for the given VSOCK target. diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver.swift index 287b271f..a38603a5 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver.swift @@ -117,7 +117,9 @@ public struct NameResolver: Sendable { /// error handling, empty endpoint lists, and sequence completion semantics. public var names: RPCAsyncSequence - /// How ``names`` is updated and should be consumed. + /// How the name-resolution sequence is updated and consumed. + /// + /// Describes the update semantics of ``NameResolver/names``. public let updateMode: UpdateMode /// The authority of the service. @@ -143,7 +145,7 @@ public struct NameResolver: Sendable { public static var pull: Self { Self(.pull) } } - /// Create a new name resolver. + /// Creates a name resolver. public init( names: RPCAsyncSequence, updateMode: UpdateMode, @@ -163,10 +165,11 @@ public struct NameResolutionResult: Hashable, Sendable { public var endpoints: [Endpoint] /// The service configuration reported by the resolver, or an error if it couldn't be parsed. + /// /// This value may be `nil` if the resolver doesn't support fetching service configuration. public var serviceConfig: Result? - /// Creates a new name resolution result. + /// Creates a name resolution result. public init( endpoints: [Endpoint], serviceConfig: Result? @@ -185,17 +188,22 @@ public struct Endpoint: Hashable, Sendable { /// choose to ignore the order. public var addresses: [SocketAddress] - /// Create a new ``Endpoint``. + /// Creates an endpoint. + /// /// - Parameter addresses: A list of equivalent addresses. public init(addresses: [SocketAddress]) { self.addresses = addresses } } -/// A resolver capable of resolving targets of type ``Target``. +/// A factory capable of creating resolvers for a specific target type. +/// +/// The target type is given by ``NameResolverFactory/Target``. @available(gRPCSwiftNIOTransport 2.0, *) public protocol NameResolverFactory { - /// The type of ``ResolvableTarget`` this factory makes resolvers for. + /// The type of target this factory makes resolvers for. + /// + /// Must conform to ``ResolvableTarget``. associatedtype Target: ResolvableTarget /// Creates a resolver for the given target. @@ -225,7 +233,9 @@ extension NameResolverFactory { } } -/// A target which can be resolved to a ``SocketAddress``. +/// A target which can be resolved to a socket address. +/// +/// The resolved address is represented by ``SocketAddress``. @available(gRPCSwiftNIOTransport 2.0, *) public protocol ResolvableTarget {} diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolverRegistry.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolverRegistry.swift index bebcf636..63ef15ca 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolverRegistry.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolverRegistry.swift @@ -117,7 +117,7 @@ public struct NameResolverRegistry { private var factories: [Factory] - /// Creates a new name resolver registry with no resolver factories. + /// Creates a name resolver registry with no resolver factories. public init() { self.factories = [] } @@ -160,7 +160,7 @@ public struct NameResolverRegistry { self.factories.append(Self.Factory(factory)) } - /// Removes any factories which have the given type + /// Removes any factories which have the given type. /// /// - Parameter type: The type of factory to remove. /// - Returns: Whether a factory was removed. @@ -193,10 +193,10 @@ public struct NameResolverRegistry { self.factories.contains { $0.hasTarget(target) } } - /// Makes a ``NameResolver`` for the target, if a suitable factory exists. + /// Makes a name resolver for the target, if a suitable factory exists. /// /// If multiple factories exist which are capable of resolving the target then the first - /// is used. + /// is used. The result is a ``NameResolver``. /// /// - Parameter target: The target to make a resolver for. /// - Returns: The resolver, or `nil` if no factory could make a resolver for the target. diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/SocketAddress.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/SocketAddress.swift index 3ce0f40c..9dea36b3 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/SocketAddress.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/SocketAddress.swift @@ -102,22 +102,30 @@ extension SocketAddress { @available(gRPCSwiftNIOTransport 2.0, *) extension SocketAddress { - /// Creates a socket address by wrapping a ``SocketAddress/IPv4-swift.struct``. + /// Creates a socket address from an IPv4 address. + /// + /// Wraps the given ``SocketAddress/IPv4-swift.struct``. public static func ipv4(_ address: IPv4) -> Self { return Self(.ipv4(address)) } - /// Creates a socket address by wrapping a ``SocketAddress/IPv6-swift.struct``. + /// Creates a socket address from an IPv6 address. + /// + /// Wraps the given ``SocketAddress/IPv6-swift.struct``. public static func ipv6(_ address: IPv6) -> Self { return Self(.ipv6(address)) } - /// Creates a socket address by wrapping a ``SocketAddress/UnixDomainSocket-swift.struct``. + /// Creates a socket address from a Unix domain socket address. + /// + /// Wraps the given ``SocketAddress/UnixDomainSocket-swift.struct``. public static func unixDomainSocket(_ address: UnixDomainSocket) -> Self { return Self(.unix(address)) } - /// Creates a socket address by wrapping a ``SocketAddress/VirtualSocket-swift.struct``. + /// Creates a socket address from a VSOCK address. + /// + /// Wraps the given ``SocketAddress/VirtualSocket-swift.struct``. public static func vsock(_ address: VirtualSocket) -> Self { return Self(.vsock(address)) } @@ -139,7 +147,7 @@ extension SocketAddress { return .unixDomainSocket(UnixDomainSocket(path: path)) } - /// Creates a virtual socket (`vsock`) address. + /// Creates a VSOCK address. public static func vsock(contextID: VirtualSocket.ContextID, port: VirtualSocket.Port) -> Self { return .vsock(VirtualSocket(contextID: contextID, port: port)) } @@ -170,7 +178,7 @@ extension SocketAddress { /// The port to connect to. public var port: Int - /// Creates a new IPv4 address. + /// Creates an IPv4 address. /// /// - Parameters: /// - host: Resolved host address. @@ -188,7 +196,7 @@ extension SocketAddress { /// The port to connect to. public var port: Int - /// Creates a new IPv6 address. + /// Creates an IPv6 address. /// /// - Parameters: /// - host: Resolved host address. @@ -204,7 +212,7 @@ extension SocketAddress { /// The path name of the Unix domain socket. public var path: String - /// Creates a new Unix domain socket address. + /// Creates a Unix domain socket address. /// /// - Parameter path: The path name of the Unix domain socket. public init(path: String) { @@ -222,7 +230,7 @@ extension SocketAddress { /// The port number. public var port: Port - /// Creates a new VSOCK address. + /// Creates a VSOCK address. /// /// - Parameters: /// - contextID: The context ID (or `cid`) of the address. @@ -246,7 +254,7 @@ extension SocketAddress { self.rawValue = value } - /// Creates a port from an `Int`, truncating it to fit a `UInt32`. + /// Creates a port from an integer value, truncating it if necessary. public init(_ value: Int) { self.init(rawValue: UInt32(bitPattern: Int32(truncatingIfNeeded: value))) } @@ -259,7 +267,9 @@ extension SocketAddress { } } - /// A VSOCK context ID (or `cid`), identifying a virtual machine or the host. + /// A VSOCK context ID, identifying a virtual machine or the host. + /// + /// This is also known as a `cid`. public struct ContextID: Hashable, Sendable, RawRepresentable, ExpressibleByIntegerLiteral { /// The context identifier. public var rawValue: UInt32 @@ -273,7 +283,7 @@ extension SocketAddress { self.rawValue = value } - /// Creates a context ID from an `Int`, truncating it to fit a `UInt32`. + /// Creates a context ID from an integer value, truncating it if necessary. public init(_ value: Int) { self.rawValue = UInt32(bitPattern: Int32(truncatingIfNeeded: value)) } diff --git a/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel+Config.swift b/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel+Config.swift index 12e07b0b..650f6f4a 100644 --- a/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel+Config.swift +++ b/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel+Config.swift @@ -18,7 +18,9 @@ public import NIOCore @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ClientTransport.WrappedChannel { - /// Configuration for a ``HTTP2ClientTransport/WrappedChannel``. + /// Configuration for a wrapped-channel transport. + /// + /// Used by ``HTTP2ClientTransport/WrappedChannel``. public struct Config: Sendable { /// Configuration for HTTP/2 connections. public var http2: HTTP2ClientTransport.Config.HTTP2 @@ -32,7 +34,7 @@ extension HTTP2ClientTransport.WrappedChannel { /// Channel callbacks for debugging. public var channelDebuggingCallbacks: ChannelDebuggingCallbacks - /// Creates a new connection configuration. + /// Creates a connection configuration. /// /// - Parameters: /// - http2: HTTP2 configuration. @@ -58,7 +60,7 @@ extension HTTP2ClientTransport.WrappedChannel { Self.defaults { _ in } } - /// Default values. + /// Default values, combining the defaults of each nested configuration, optionally customized by a closure. /// /// - Parameters: /// - configure: A closure which allows you to modify the defaults before returning them. @@ -88,7 +90,7 @@ extension HTTP2ClientTransport.WrappedChannel.Config { /// A callback invoked with each new HTTP/2 stream. public var onCreateHTTP2Stream: (@Sendable (_ channel: any Channel) -> EventLoopFuture)? - /// Creates a new set of channel debugging callbacks. + /// Creates a set of channel debugging callbacks. public init( onCreateHTTP2Stream: (@Sendable (_ channel: any Channel) -> EventLoopFuture)? ) { diff --git a/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel.swift b/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel.swift index acf404da..b4ccc536 100644 --- a/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel.swift +++ b/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel.swift @@ -21,7 +21,7 @@ private import Synchronization @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ClientTransport { - /// A client transport which wraps an existing SwiftNIO `Channel`. + /// A client transport which wraps an existing SwiftNIO channel. /// /// You can use this if you already have a connected `Channel` that you'd like to use as a gRPC /// client connection. This is helpful if, for example, you wish to tunnel gRPC inside another @@ -84,7 +84,7 @@ extension HTTP2ClientTransport { 4 * 1024 * 1024 } - /// Create a new wrapping client transport from an already connected NIO `Channel`. + /// Creates a wrapping client transport from an already connected NIO channel. /// /// - Parameters: /// - channel: The channel to wrap. The transport takes ownership of the lifetime of the channel @@ -361,7 +361,7 @@ extension HTTP2ClientTransport { @available(gRPCSwiftNIOTransport 2.0, *) extension ClientTransport where Self == HTTP2ClientTransport.WrappedChannel { - /// Create a new wrapping client transport from an already connected NIO `Channel`. + /// Creates a wrapping client transport from an already connected NIO channel. /// /// - Parameters: /// - channel: The channel to wrap. The transport takes ownership of the lifetime of the channel @@ -395,13 +395,13 @@ extension ClientTransport where Self == HTTP2ClientTransport.WrappedChannel { @available(gRPCSwiftNIOTransport 2.9, *) extension HTTP2ClientTransport.WrappedChannel { - /// An opaque handle representing a `Channel` whose pipeline has been configured for gRPC by - /// ``WrappedChannel/wrapping(config:serviceConfig:makeChannel:)``. + /// An opaque handle representing a channel whose pipeline has been configured for gRPC. /// /// Returned from the `configure` closure given to `makeChannel` and threaded through to the - /// closure's return value; do not construct this yourself. + /// closure's return value; do not construct this yourself. This type is produced by + /// ``WrappedChannel/wrapping(config:serviceConfig:makeChannel:)``. public struct ConfiguredChannel: Sendable { - /// The underlying NIO `Channel`. + /// The underlying NIO channel. public let channel: any Channel fileprivate let connection: NIOAsyncChannel @@ -418,7 +418,7 @@ extension HTTP2ClientTransport.WrappedChannel { } } - /// Builds a `WrappedChannel` transport, configuring the gRPC pipeline on a channel you supply. + /// Builds a wrapped-channel transport, configuring the gRPC pipeline on a channel you supply. /// /// The `makeChannel` closure is invoked with a `configure` closure. You must call /// `configure(_:)` exactly once before any inbound bytes can flow into the pipeline. In a @@ -473,7 +473,7 @@ extension HTTP2ClientTransport.WrappedChannel { @available(gRPCSwiftNIOTransport 2.0, *) extension ClientTransport where Self == HTTP2ClientTransport.WrappedChannel { - /// Builds a `WrappedChannel` transport, configuring the gRPC pipeline on a channel you supply. + /// Builds a wrapped-channel transport, configuring the gRPC pipeline on a channel you supply. /// /// See ``HTTP2ClientTransport/WrappedChannel/wrapping(config:serviceConfig:makeChannel:)`` for /// details. diff --git a/Sources/GRPCNIOTransportCore/GRPCNIOTransportBytes.swift b/Sources/GRPCNIOTransportCore/GRPCNIOTransportBytes.swift index 17bdb868..17d9e893 100644 --- a/Sources/GRPCNIOTransportCore/GRPCNIOTransportBytes.swift +++ b/Sources/GRPCNIOTransportCore/GRPCNIOTransportBytes.swift @@ -33,13 +33,13 @@ public struct GRPCNIOTransportBytes: GRPCContiguousBytes, Hashable, Sendable { self.buffer = ByteBuffer() } - /// Creates a new instance filled with the given byte, repeated `count` times. + /// Creates an instance by repeating the given byte a number of times. @inlinable public init(repeating: UInt8, count: Int) { self.buffer = ByteBuffer(repeating: repeating, count: count) } - /// Creates a new instance from a sequence of bytes. + /// Creates an instance from a sequence of bytes. @inlinable public init(_ sequence: some Sequence) { self.buffer = ByteBuffer(bytes: sequence) diff --git a/Sources/GRPCNIOTransportCore/ListeningServerTransport.swift b/Sources/GRPCNIOTransportCore/ListeningServerTransport.swift index 3bc819ea..fd5e8995 100644 --- a/Sources/GRPCNIOTransportCore/ListeningServerTransport.swift +++ b/Sources/GRPCNIOTransportCore/ListeningServerTransport.swift @@ -16,7 +16,7 @@ public import GRPCCore -/// A transport which refines `ServerTransport` to provide the socket address of a listening +/// A transport which refines a server transport to provide the socket address of a listening /// server. @available(gRPCSwiftNIOTransport 2.0, *) public protocol ListeningServerTransport: ServerTransport { diff --git a/Sources/GRPCNIOTransportCore/Server/CustomTransport.swift b/Sources/GRPCNIOTransportCore/Server/CustomTransport.swift index 3d7e61e3..0b5ba58c 100644 --- a/Sources/GRPCNIOTransportCore/Server/CustomTransport.swift +++ b/Sources/GRPCNIOTransportCore/Server/CustomTransport.swift @@ -22,8 +22,8 @@ private import Synchronization @available(gRPCSwiftNIOTransport 2.6, *) extension HTTP2ServerTransport { - /// A NIO-based server transport that handles HTTP/2 connections using a pluggable - /// ``HTTP2ServerTransport/ListenerFactory``. + /// A NIO-based server transport that handles HTTP/2 connections using a pluggable listener + /// factory. /// /// This transport provides the core functionality for accepting HTTP/2 connections and /// dispatching RPC streams. It delegates the creation of the listening channel to a @@ -63,7 +63,7 @@ extension HTTP2ServerTransport { /// Channel callbacks for debugging. public var channelDebuggingCallbacks: HTTP2ServerTransport.Config.ChannelDebuggingCallbacks - /// Creates a new configuration. + /// Creates a configuration. /// /// - Parameters: /// - compression: Compression configuration. @@ -85,7 +85,7 @@ extension HTTP2ServerTransport { self.channelDebuggingCallbacks = channelDebuggingCallbacks } - /// Default values. + /// Default values, combining the defaults of each nested configuration. /// /// - SeeAlso: ``HTTP2ServerTransport/Config/Compression/defaults`` /// - SeeAlso: ``HTTP2ServerTransport/Config/Connection/defaults`` @@ -185,7 +185,7 @@ extension HTTP2ServerTransport { } } - /// Creates a new NIO-based HTTP/2 server transport. + /// Creates a NIO-based HTTP/2 server transport. /// /// - Parameters: /// - listenerFactory: The factory responsible for creating the listening channel. diff --git a/Sources/GRPCNIOTransportCore/Server/HTTP2ServerTransport.swift b/Sources/GRPCNIOTransportCore/Server/HTTP2ServerTransport.swift index 27c599d8..53c52a1a 100644 --- a/Sources/GRPCNIOTransportCore/Server/HTTP2ServerTransport.swift +++ b/Sources/GRPCNIOTransportCore/Server/HTTP2ServerTransport.swift @@ -37,7 +37,7 @@ extension HTTP2ServerTransport.Config { /// - Note: `CompressionAlgorithm.none` is always supported, even if it isn't set here. public var enabledAlgorithms: CompressionAlgorithmSet - /// Creates a new compression configuration. + /// Creates a compression configuration. /// /// - SeeAlso: ``defaults``. public init(enabledAlgorithms: CompressionAlgorithmSet) { @@ -61,7 +61,7 @@ extension HTTP2ServerTransport.Config { /// Configuration for how the server enforces client keepalive. public var clientBehavior: ClientKeepaliveBehavior - /// Creates a new keepalive configuration. + /// Creates a keepalive configuration. public init( time: Duration, timeout: Duration, @@ -72,7 +72,9 @@ extension HTTP2ServerTransport.Config { self.clientBehavior = clientBehavior } - /// Default values. The time after reading data a ping should be sent defaults to 2 hours, the timeout for + /// The default keepalive ping interval and timeout for the server transport. + /// + /// The time after reading data a ping should be sent defaults to 2 hours, the timeout for /// keepalive pings defaults to 20 seconds, pings are not permitted when no calls are in progress, and /// the minimum allowed interval for clients to send pings defaults to 5 minutes. public static var defaults: Self { @@ -87,6 +89,7 @@ extension HTTP2ServerTransport.Config { /// Configuration for how the server enforces client keepalive. public struct ClientKeepaliveBehavior: Sendable, Hashable { /// The minimum allowed interval the client is allowed to send keep-alive pings. + /// /// Pings more frequent than this interval count as β€œstrikes” and the connection is closed if there are /// too many strikes. public var minPingIntervalWithoutCalls: Duration @@ -94,7 +97,7 @@ extension HTTP2ServerTransport.Config { /// Whether the server allows the client to send keepalive pings when there are no calls in progress. public var allowWithoutCalls: Bool - /// Creates a new configuration for permitted client keepalive behavior. + /// Creates a configuration for permitted client keepalive behavior. public init( minPingIntervalWithoutCalls: Duration, allowWithoutCalls: Bool @@ -103,7 +106,9 @@ extension HTTP2ServerTransport.Config { self.allowWithoutCalls = allowWithoutCalls } - /// Default values. The minimum allowed interval for clients to send pings without an active + /// The default policy for client keepalive pings sent without an active call. + /// + /// The minimum allowed interval for clients to send pings without an active /// call defaults to 5 minutes, and pings without an active call aren't permitted. public static var defaults: Self { Self(minPingIntervalWithoutCalls: .seconds(5 * 60), allowWithoutCalls: false) @@ -173,7 +178,9 @@ extension HTTP2ServerTransport.Config { self.flushCoalescing = flushCoalescing } - /// Default values. The max connection age, max grace time, and max idle time default to + /// The default connection lifetime and idle time limits for the server transport. + /// + /// The max connection age, max grace time, and max idle time default to /// `nil` (that is, infinite). See ``HTTP2ServerTransport/Config/Keepalive/defaults`` for keepalive /// defaults. Flush coalescing is enabled with default values. public static var defaults: Self { @@ -200,7 +207,7 @@ extension HTTP2ServerTransport.Config { /// The number of concurrent streams on the HTTP/2 connection. public var maxConcurrentStreams: Int? - /// Creates a new HTTP/2 configuration. + /// Creates an HTTP/2 configuration. public init( maxFrameSize: Int, targetWindowSize: Int, @@ -211,7 +218,9 @@ extension HTTP2ServerTransport.Config { self.maxConcurrentStreams = maxConcurrentStreams } - /// Default values. The max frame size defaults to 2^14, the target window size defaults to 2^16-1, and + /// The default HTTP/2 frame and window sizes, with unlimited concurrent streams. + /// + /// The max frame size defaults to 2^14, the target window size defaults to 2^16-1, and /// the max concurrent streams default to infinite. public static var defaults: Self { Self( @@ -227,12 +236,14 @@ extension HTTP2ServerTransport.Config { /// The maximum request payload size. public var maxRequestPayloadSize: Int - /// Creates a new RPC configuration. + /// Creates an RPC configuration. public init(maxRequestPayloadSize: Int) { self.maxRequestPayloadSize = maxRequestPayloadSize } - /// Default values. Maximum request payload size defaults to 4MiB. + /// The default maximum request payload size. + /// + /// Maximum request payload size defaults to 4MiB. public static var defaults: Self { Self(maxRequestPayloadSize: 4 * 1024 * 1024) } @@ -255,7 +266,7 @@ extension HTTP2ServerTransport.Config { /// A callback invoked with each accepted HTTP/2 stream. public var onAcceptHTTP2Stream: (@Sendable (_ channel: any Channel) -> EventLoopFuture)? - /// Creates a new set of channel debugging callbacks. + /// Creates a set of channel debugging callbacks. public init( onBindTCPListener: (@Sendable (_ channel: any Channel) -> EventLoopFuture)?, onAcceptTCPConnection: (@Sendable (_ channel: any Channel) -> EventLoopFuture)?, @@ -302,7 +313,7 @@ extension HTTP2ServerTransport.Config.Connection { /// The number of bytes to buffer before a flush is emitted, regardless of the delay. public var maxBytes: Int - /// Creates a new flush coalescing configuration. + /// Creates a flush coalescing configuration. /// /// - SeeAlso: ``defaults``. public init(maxFlushDelay: Duration, maxBytes: Int) { @@ -310,7 +321,9 @@ extension HTTP2ServerTransport.Config.Connection { self.maxBytes = maxBytes } - /// Default values. The max flush delay is 100ΞΌs and the max bytes is 64KiB. + /// The default flush delay and byte count for the server transport. + /// + /// The max flush delay is 100ΞΌs and the max bytes is 64KiB. public static var defaults: Self { Self(maxFlushDelay: .microseconds(100), maxBytes: 64 * 1024) } diff --git a/Sources/GRPCNIOTransportCore/Server/ListenerFactory.swift b/Sources/GRPCNIOTransportCore/Server/ListenerFactory.swift index e53fe1db..a25a625e 100644 --- a/Sources/GRPCNIOTransportCore/Server/ListenerFactory.swift +++ b/Sources/GRPCNIOTransportCore/Server/ListenerFactory.swift @@ -31,7 +31,7 @@ extension HTTP2ServerTransport { /// /// - SeeAlso: ``HTTP2ServerTransport/Custom`` public protocol ListenerFactory: Sendable { - /// The `EventLoopGroup` the listener uses for the connections it creates. + /// The event loop group the listener uses for the connections it creates. var eventLoopGroup: any EventLoopGroup { get } /// Creates a listening channel that produces configured HTTP/2 connection channels. diff --git a/Sources/GRPCNIOTransportCore/TLSConfig.swift b/Sources/GRPCNIOTransportCore/TLSConfig.swift index 24fda750..9cd33150 100644 --- a/Sources/GRPCNIOTransportCore/TLSConfig.swift +++ b/Sources/GRPCNIOTransportCore/TLSConfig.swift @@ -32,8 +32,10 @@ public enum TLSConfig: Sendable { public static let der = Self(wrapped: .der) } - /// A description of where a certificate is coming from: either a byte array or a file. - /// The serialization format is specified by ``TLSConfig/SerializationFormat``. + /// A description of where a certificate is coming from. + /// + /// The source is either a byte array or a file, and the serialization format is specified by + /// ``TLSConfig/SerializationFormat``. public struct CertificateSource: Sendable, Equatable { package enum Wrapped: Equatable { case file(path: String, format: SerializationFormat) @@ -44,6 +46,7 @@ public enum TLSConfig: Sendable { package let wrapped: Wrapped /// The certificate's source is a file. + /// /// - Parameters: /// - path: The file path containing the certificate. /// - format: The certificate's format, as a ``TLSConfig/SerializationFormat``. @@ -53,6 +56,7 @@ public enum TLSConfig: Sendable { } /// The certificate's source is an array of bytes. + /// /// - Parameters: /// - bytes: The array of bytes making up the certificate. /// - format: The certificate's format, as a ``TLSConfig/SerializationFormat``. @@ -62,8 +66,10 @@ public enum TLSConfig: Sendable { } } - /// A description of where the private key is coming from: either a byte array or a file. - /// The serialization format is specified by ``TLSConfig/SerializationFormat``. + /// A description of where a private key is coming from. + /// + /// The source is either a byte array or a file, and the serialization format is specified by + /// ``TLSConfig/SerializationFormat``. public struct PrivateKeySource: Sendable { package enum Wrapped { case file(path: String, format: SerializationFormat) @@ -74,6 +80,7 @@ public enum TLSConfig: Sendable { package let wrapped: Wrapped /// The private key's source is a file. + /// /// - Parameters: /// - path: The file path containing the private key. /// - format: The private key's format, as a ``TLSConfig/SerializationFormat``. @@ -83,6 +90,7 @@ public enum TLSConfig: Sendable { } /// The private key's source is an array of bytes. + /// /// - Parameters: /// - bytes: The array of bytes making up the private key. /// - format: The private key's format, as a ``TLSConfig/SerializationFormat``. @@ -104,8 +112,10 @@ public enum TLSConfig: Sendable { package let wrapped: Wrapped - /// A list of ``TLSConfig/CertificateSource``s making up the - /// chain of trust. + /// A list of certificate sources making up the chain of trust. + /// + /// Each source is a ``TLSConfig/CertificateSource``. + /// /// - Parameter certificateSources: The sources for the certificates that make up the chain of trust. /// - Returns: A trust root for the given chain of trust. public static func certificates( diff --git a/Sources/GRPCNIOTransportHTTP2Posix/Config+TLS.swift b/Sources/GRPCNIOTransportHTTP2Posix/Config+TLS.swift index 69091fde..c9110ab2 100644 --- a/Sources/GRPCNIOTransportHTTP2Posix/Config+TLS.swift +++ b/Sources/GRPCNIOTransportHTTP2Posix/Config+TLS.swift @@ -57,7 +57,7 @@ extension HTTP2ServerTransport.Posix { return .tls(tlsConfig) } - /// Creates a new TLS config using a certificate reloader to provide the certificate chain + /// Creates a TLS config using a certificate reloader to provide the certificate chain /// and private key. /// /// The reloader must provide an initial certificate chain and private key. If you already @@ -66,7 +66,7 @@ extension HTTP2ServerTransport.Posix { /// the `configure` callback. /// /// The defaults include setting: - /// - `clientCertificateVerificationMode` to `doNotVerify`, + /// - `clientCertificateVerification` to `doNotVerify`, /// - `trustRoots` to `systemDefault`, and /// - `requireALPN` to `false`. /// @@ -109,7 +109,7 @@ extension HTTP2ServerTransport.Posix { return .tls(tlsConfig) } - /// Creates a new TLS config suitable for mTLS using a certificate reloader to provide the + /// Creates a TLS config suitable for mTLS using a certificate reloader to provide the /// certificate chain and private key. /// /// The reloader must provide an initial certificate chain and private key. If you already @@ -118,7 +118,7 @@ extension HTTP2ServerTransport.Posix { /// the `configure` callback. /// /// The defaults include setting: - /// - `clientCertificateVerificationMode` to `noHostnameVerification`, + /// - `clientCertificateVerification` to `noHostnameVerification`, /// - `trustRoots` to `systemDefault`, and /// - `requireALPN` to `false`. /// @@ -146,7 +146,7 @@ extension HTTP2ServerTransport.Posix { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ServerTransport.Posix.TransportSecurity { - /// TLS configuration for the `Posix` server transport. + /// TLS configuration for the Posix server transport. public struct TLS: Sendable { /// The certificates the server will offer during negotiation. public var certificateChain: [TLSConfig.CertificateSource] @@ -181,7 +181,8 @@ extension HTTP2ServerTransport.Posix.TransportSecurity { ) -> Void )? - /// Creates a new HTTP2 NIO Posix server transport TLS config. + /// Creates an HTTP2 NIO Posix server transport TLS config. + /// /// - Parameters: /// - certificateChain: The certificates the server will offer during negotiation. /// - privateKey: The private key associated with the leaf certificate. @@ -202,8 +203,10 @@ extension HTTP2ServerTransport.Posix.TransportSecurity { self.requireALPN = requireALPN } - /// Creates a new HTTP2 NIO Posix transport TLS config, with some values defaulted: - /// - `clientCertificateVerificationMode` equals `doNotVerify` + /// Creates a server configuration for one-way TLS, with some values defaulted. + /// + /// The defaults are: + /// - `clientCertificateVerification` equals `doNotVerify` /// - `trustRoots` equals `systemDefault` /// - `requireALPN` equals `false` /// @@ -228,9 +231,10 @@ extension HTTP2ServerTransport.Posix.TransportSecurity { return config } - /// Creates a new HTTP2 NIO Posix transport TLS config, with some values defaulted to match - /// the requirements of mTLS: - /// - `clientCertificateVerificationMode` equals `noHostnameVerification` + /// Creates a server configuration for mutual TLS, with some values defaulted. + /// + /// The defaults are: + /// - `clientCertificateVerification` equals `noHostnameVerification` /// - `trustRoots` equals `systemDefault` /// - `requireALPN` equals `false` /// @@ -324,7 +328,7 @@ extension HTTP2ClientTransport.Posix { return .tls(tlsConfig) } - /// Creates a new TLS config suitable for mTLS using a certificate reloader to provide the + /// Creates a TLS config suitable for mTLS using a certificate reloader to provide the /// certificate chain and private key. /// /// The reloader must provide an initial certificate chain and private key. If you already @@ -360,7 +364,7 @@ extension HTTP2ClientTransport.Posix { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ClientTransport.Posix.TransportSecurity { - /// TLS configuration for the `Posix` client transport. + /// TLS configuration for the Posix client transport. public struct TLS: Sendable { /// The certificates the client will offer during negotiation. public var certificateChain: [TLSConfig.CertificateSource] @@ -390,7 +394,8 @@ extension HTTP2ClientTransport.Posix.TransportSecurity { /// use at that point in time. public var certificateReloader: (any CertificateReloader)? - /// Creates a new HTTP2 NIO Posix client transport TLS config. + /// Creates an HTTP2 NIO Posix client transport TLS config. + /// /// - Parameters: /// - certificateChain: The certificates the client will offer during negotiation. /// - privateKey: The private key associated with the leaf certificate. @@ -408,7 +413,9 @@ extension HTTP2ClientTransport.Posix.TransportSecurity { self.trustRoots = trustRoots } - /// Creates a new HTTP2 NIO Posix transport TLS config, with some values defaulted: + /// Creates a client configuration for one-way TLS, with some values defaulted. + /// + /// The defaults are: /// - `certificateChain` equals `[]` /// - `privateKey` equals `nil` /// - `serverCertificateVerification` equals `fullVerification` @@ -430,15 +437,18 @@ extension HTTP2ClientTransport.Posix.TransportSecurity { return config } - /// Creates a new HTTP2 NIO Posix transport TLS config, with some values defaulted: + /// The default client configuration for one-way TLS. + /// + /// The defaults are: /// - `certificateChain` equals `[]` /// - `privateKey` equals `nil` /// - `serverCertificateVerification` equals `fullVerification` /// - `trustRoots` equals `systemDefault` public static var defaults: Self { .defaults() } - /// Creates a new HTTP2 NIO Posix transport TLS config, with some values defaulted to match - /// the requirements of mTLS: + /// Creates a client configuration for mutual TLS, with some values defaulted. + /// + /// The defaults are: /// - `trustRoots` equals `systemDefault` /// - `serverCertificateVerification` equals `fullVerification` /// @@ -466,10 +476,11 @@ extension HTTP2ClientTransport.Posix.TransportSecurity { @available(gRPCSwiftNIOTransport 2.0, *) extension TLSConfig.PrivateKeySource { - /// Creates a key source from a `NIOSSLCustomPrivateKey`. + /// Creates a key source from a custom private key. /// /// This private key source is only applicable to the NIOPosix-based transports. Using one - /// with a NIOTransportServices-based transport is a programmer error. + /// with a NIOTransportServices-based transport is a programmer error. The key must conform to + /// `NIOSSLCustomPrivateKey`. /// /// - Parameter key: The custom private key. /// - Returns: A private key source wrapping the custom private key. diff --git a/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/Documentation.md b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/Documentation.md index 65fa970a..cd862593 100644 --- a/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/Documentation.md +++ b/Sources/GRPCNIOTransportHTTP2Posix/Documentation.docc/Documentation.md @@ -1,6 +1,6 @@ # ``GRPCNIOTransportHTTP2Posix`` -HTTP/2 client and server transports built on top of SwiftNIO's `NIOPosix` module. +HTTP/2 client and server transports built on top of SwiftNIO's Posix networking layer. ## Overview diff --git a/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ClientTransport+Posix.swift b/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ClientTransport+Posix.swift index 9f95cd00..78dcfbc8 100644 --- a/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ClientTransport+Posix.swift +++ b/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ClientTransport+Posix.swift @@ -22,7 +22,7 @@ private import NIOSSL @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ClientTransport { - /// A `ClientTransport` using HTTP/2 built on top of `NIOPosix`. + /// A client transport using HTTP/2 built on top of NIOPosix. /// /// This transport builds on top of SwiftNIO's Posix networking layer and is suitable for use /// on Linux and Darwin-based platforms (macOS, iOS, etc.). However, it's *strongly* recommended @@ -61,7 +61,7 @@ extension HTTP2ClientTransport { private let channel: GRPCChannel - /// Creates a new NIOPosix-based HTTP/2 client transport. + /// Creates a NIOPosix-based HTTP/2 client transport. /// /// - Parameters: /// - target: A target to resolve. @@ -231,7 +231,7 @@ extension HTTP2ClientTransport.Posix { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ClientTransport.Posix { - /// Configuration for the `Posix` client transport. + /// Configuration for the Posix client transport. public struct Config: Sendable { /// Configuration for HTTP/2 connections. public var http2: HTTP2ClientTransport.Config.HTTP2 @@ -252,7 +252,7 @@ extension HTTP2ClientTransport.Posix { /// Channel callbacks for debugging. public var channelDebuggingCallbacks: HTTP2ClientTransport.Config.ChannelDebuggingCallbacks - /// Creates a new connection configuration. + /// Creates a connection configuration. /// /// - Parameters: /// - http2: HTTP2 configuration. @@ -300,7 +300,7 @@ extension HTTP2ClientTransport.Posix { Self.defaults() } - /// Default values. + /// Default values, combining the defaults of each nested configuration, optionally customized by a closure. /// /// - Parameters: /// - configure: A closure which allows you to modify the defaults before returning them. @@ -336,7 +336,7 @@ extension GRPCChannel.Config { @available(gRPCSwiftNIOTransport 2.0, *) extension ClientTransport where Self == HTTP2ClientTransport.Posix { - /// Creates a new Posix based HTTP/2 client transport. + /// Creates a Posix based HTTP/2 client transport. /// /// - Parameters: /// - target: A target to resolve. diff --git a/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ServerTransport+Posix.swift b/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ServerTransport+Posix.swift index 2404ccbf..1cc36419 100644 --- a/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ServerTransport+Posix.swift +++ b/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ServerTransport+Posix.swift @@ -27,7 +27,7 @@ public import X509 @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ServerTransport { - /// A `ServerTransport` using HTTP/2 built on top of `NIOPosix`. + /// A server transport using HTTP/2 built on top of NIOPosix. /// /// This transport builds on top of SwiftNIO's Posix networking layer and is suitable for use /// on Linux and Darwin-based platforms (macOS, iOS, etc.). However, it's *strongly* recommended @@ -186,7 +186,7 @@ extension HTTP2ServerTransport { } } - /// Creates a new `Posix` transport. + /// Creates a Posix transport, binding to the given address. /// /// - Parameters: /// - address: The address to which the server should be bound. @@ -207,7 +207,7 @@ extension HTTP2ServerTransport { ) } - /// Creates a new `Posix` transport. + /// Creates a Posix transport from an already bound listening socket. /// /// - Parameters: /// - fileDescriptor: The file descriptor of an already bound listening socket. @@ -302,21 +302,23 @@ extension HTTP2ServerTransport { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ServerTransport.Posix { - /// The transport-specific context for the `Posix` server transport. + /// The transport-specific context for the Posix server transport. public struct Context: ServerContext.TransportSpecific { /// The peer certificate (if any) from the mTLS handshake. public var peerCertificate: Certificate? - /// The validated peer certificate chain from the mTLS handshake. This is only available when using a custom verification callback. + /// The validated peer certificate chain from the mTLS handshake. + /// + /// This is only available when using a custom verification callback. @available(gRPCSwiftNIOTransport 2.2, *) public var peerCertificateChain: X509.ValidatedCertificateChain? - /// Creates a new, empty context. + /// Creates an empty context. public init() { } } - /// Config for the `Posix` transport. + /// Configuration for the Posix transport. public struct Config: Sendable { /// Compression configuration. public var compression: HTTP2ServerTransport.Config.Compression @@ -333,7 +335,7 @@ extension HTTP2ServerTransport.Posix { /// Channel callbacks for debugging. public var channelDebuggingCallbacks: HTTP2ServerTransport.Config.ChannelDebuggingCallbacks - /// Creates a new configuration. + /// Creates a configuration. /// /// - Parameters: /// - http2: HTTP2 configuration. @@ -419,7 +421,7 @@ extension ServerBootstrap { @available(gRPCSwiftNIOTransport 2.0, *) extension ServerTransport where Self == HTTP2ServerTransport.Posix { - /// Creates a new `Posix` based HTTP/2 server transport. + /// Creates a Posix-based HTTP/2 server transport. /// /// - Parameters: /// - address: The address to which the server should be bound. @@ -445,7 +447,7 @@ extension ServerTransport where Self == HTTP2ServerTransport.Posix { @available(gRPCSwiftNIOTransport 2.6, *) extension ServerTransport where Self == HTTP2ServerTransport.Posix { - /// Creates a new `Posix` based HTTP/2 server transport. + /// Creates a Posix-based HTTP/2 server transport. /// /// - Parameters: /// - fileDescriptor: The file descriptor of an already bound listening socket. diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/Config+TLS.swift b/Sources/GRPCNIOTransportHTTP2TransportServices/Config+TLS.swift index d655928d..96241723 100644 --- a/Sources/GRPCNIOTransportHTTP2TransportServices/Config+TLS.swift +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/Config+TLS.swift @@ -77,7 +77,7 @@ extension HTTP2ServerTransport.TransportServices { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ServerTransport.TransportServices { - /// TLS configuration for the `TransportServices` server transport. + /// TLS configuration for the TransportServices server transport. public struct TLS: Sendable { /// How to verify the client certificate, if one is presented. public var clientCertificateVerification: TLSConfig.CertificateVerification @@ -90,18 +90,19 @@ extension HTTP2ServerTransport.TransportServices { /// If this is set to `true` but the client does not support ALPN, then the connection is rejected. public var requireALPN: Bool - /// A provider for the `SecIdentity` to be used when setting up TLS. + /// A provider for the identity to be used when setting up TLS. public var identityProvider: @Sendable () throws -> SecIdentity /// Additional certificates to include in the TLS handshake alongside the - /// leaf certificate from the `SecIdentity`. + /// leaf certificate from the identity. /// /// Use this to provide intermediate (and optionally root) certificates /// when the peer requires the full chain for verification. @available(gRPCSwiftNIOTransport 2.5, *) public var additionalCertificates: [SecCertificate] - /// Creates a new HTTP2 NIO Transport Services transport TLS config. + /// Creates an HTTP2 NIO Transport Services transport TLS config. + /// /// - Parameters: /// - clientCertificateVerification: How to verify the client certificate, if one is presented. /// - trustRoots: The trust roots to be used when verifying client certificates. @@ -120,8 +121,10 @@ extension HTTP2ServerTransport.TransportServices { self.additionalCertificates = [] } - /// Creates a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted: - /// - `clientCertificateVerificationMode` equals `doNotVerify` + /// Creates a server configuration for one-way TLS, with some values defaulted. + /// + /// The defaults are: + /// - `clientCertificateVerification` equals `doNotVerify` /// - `trustRoots` equals `systemDefault` /// - `requireALPN` equals `false` /// @@ -143,9 +146,10 @@ extension HTTP2ServerTransport.TransportServices { return config } - /// Creates a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted to match - /// the requirements of mTLS: - /// - `clientCertificateVerificationMode` equals `noHostnameVerification` + /// Creates a server configuration for mutual TLS, with some values defaulted. + /// + /// The defaults are: + /// - `clientCertificateVerification` equals `noHostnameVerification` /// - `trustRoots` equals `systemDefault` /// - `requireALPN` equals `false` /// @@ -238,27 +242,29 @@ extension HTTP2ClientTransport.TransportServices { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ClientTransport.TransportServices { - /// TLS configuration for the `TransportServices` client transport. + /// TLS configuration for the TransportServices client transport. public struct TLS: Sendable { /// How to verify the server certificate, if one is presented. public var serverCertificateVerification: TLSConfig.CertificateVerification /// The trust roots to be used when verifying server certificates. + /// /// - Important: If specifying custom certificates, they must be DER-encoded X509 certificates. public var trustRoots: TLSConfig.TrustRootsSource - /// An optional provider for the `SecIdentity` to be used when setting up TLS. + /// An optional provider for the identity to be used when setting up TLS. public var identityProvider: (@Sendable () throws -> SecIdentity)? /// Additional certificates to include in the TLS handshake alongside the - /// leaf certificate from the `SecIdentity`. + /// leaf certificate from the identity. /// /// Use this to provide intermediate (and optionally root) certificates /// when the peer requires the full chain for verification. @available(gRPCSwiftNIOTransport 2.5, *) public var additionalCertificates: [SecCertificate] - /// Creates a new HTTP2 NIO Transport Services transport TLS config. + /// Creates an HTTP2 NIO Transport Services transport TLS config. + /// /// - Parameters: /// - serverCertificateVerification: How to verify the server certificate, if one is presented. /// - trustRoots: The trust roots to be used when verifying server certificates. @@ -274,7 +280,9 @@ extension HTTP2ClientTransport.TransportServices { self.additionalCertificates = [] } - /// Creates a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted: + /// Creates a client configuration for one-way TLS, with some values defaulted. + /// + /// The defaults are: /// - `serverCertificateVerification` equals `fullVerification` /// - `trustRoots` equals `systemDefault` /// - `identityProvider` equals `nil` @@ -294,14 +302,17 @@ extension HTTP2ClientTransport.TransportServices { return config } - /// Creates a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted: + /// The default client configuration for one-way TLS. + /// + /// The defaults are: /// - `serverCertificateVerification` equals `fullVerification` /// - `trustRoots` equals `systemDefault` /// - `identityProvider` equals `nil` public static var defaults: Self { .defaults() } - /// Creates a new HTTP2 NIO Transport Services transport TLS config, with some values defaulted to match - /// the requirements of mTLS: + /// Creates a client configuration for mutual TLS, with some values defaulted. + /// + /// The defaults are: /// - `serverCertificateVerification` equals `fullVerification` /// - `trustRoots` equals `systemDefault` /// diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/Documentation.md b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/Documentation.md index 6d6a41ef..712e9d33 100644 --- a/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/Documentation.md +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/Documentation.docc/Documentation.md @@ -1,6 +1,6 @@ # ``GRPCNIOTransportHTTP2TransportServices`` -HTTP/2 client and server transports built on top of SwiftNIO's `NIOTransportServices` module. +HTTP/2 client and server transports built on top of SwiftNIO's Transport Services networking layer. ## Overview diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ClientTransport+TransportServices.swift b/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ClientTransport+TransportServices.swift index dc501351..51218544 100644 --- a/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ClientTransport+TransportServices.swift +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ClientTransport+TransportServices.swift @@ -24,7 +24,7 @@ private import Network @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ClientTransport { - /// A `ClientTransport` using HTTP/2 built on top of `NIOTransportServices`. + /// A client transport using HTTP/2 built on top of NIOTransportServices. /// /// This transport builds on top of SwiftNIO's Transport Services networking layer and is the recommended /// variant for use on Darwin-based platforms (macOS, iOS, etc.). @@ -68,7 +68,7 @@ extension HTTP2ClientTransport { self.channel.retryThrottle } - /// Creates a new NIOTransportServices-based HTTP/2 client transport. + /// Creates a NIOTransportServices-based HTTP/2 client transport. /// /// - Parameters: /// - target: A target to resolve. @@ -211,7 +211,7 @@ extension HTTP2ClientTransport.TransportServices { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ClientTransport.TransportServices { - /// Configuration for the `TransportServices` transport. + /// Configuration for the TransportServices transport. public struct Config: Sendable { /// Configuration for HTTP/2 connections. public var http2: HTTP2ClientTransport.Config.HTTP2 @@ -232,7 +232,7 @@ extension HTTP2ClientTransport.TransportServices { /// Channel callbacks for debugging. public var channelDebuggingCallbacks: HTTP2ClientTransport.Config.ChannelDebuggingCallbacks - /// Creates a new connection configuration. + /// Creates a connection configuration. /// /// - Parameters: /// - http2: HTTP2 configuration. @@ -280,7 +280,7 @@ extension HTTP2ClientTransport.TransportServices { Self.defaults() } - /// Default values. + /// Default values, combining the defaults of each nested configuration, optionally customized by a closure. /// /// - Parameters: /// - configure: A closure which allows you to modify the defaults before returning them. @@ -339,7 +339,7 @@ extension NIOTSConnectionBootstrap { @available(gRPCSwiftNIOTransport 2.0, *) extension ClientTransport where Self == HTTP2ClientTransport.TransportServices { - /// Creates a new `TransportServices` based HTTP/2 client transport. + /// Creates a TransportServices-based HTTP/2 client transport. /// /// - Parameters: /// - target: A target to resolve. diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ServerTransport+TransportServices.swift b/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ServerTransport+TransportServices.swift index 51ef0cec..c0bf2340 100644 --- a/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ServerTransport+TransportServices.swift +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ServerTransport+TransportServices.swift @@ -113,7 +113,7 @@ extension HTTP2ServerTransport { } } - /// Creates a new `TransportServices` transport. + /// Creates a TransportServices transport. /// /// - Parameters: /// - address: The address to which the server should be bound. @@ -169,7 +169,7 @@ extension HTTP2ServerTransport { @available(gRPCSwiftNIOTransport 2.0, *) extension HTTP2ServerTransport.TransportServices { - /// Configuration for the `TransportServices` transport. + /// Configuration for the TransportServices transport. public struct Config: Sendable { /// Compression configuration. public var compression: HTTP2ServerTransport.Config.Compression @@ -186,7 +186,8 @@ extension HTTP2ServerTransport.TransportServices { /// Channel callbacks for debugging. public var channelDebuggingCallbacks: HTTP2ServerTransport.Config.ChannelDebuggingCallbacks - /// Creates a new configuration. + /// Creates a configuration. + /// /// - Parameters: /// - compression: Compression configuration. /// - connection: Connection configuration. @@ -259,7 +260,7 @@ extension NIOTSListenerBootstrap { @available(gRPCSwiftNIOTransport 2.0, *) extension ServerTransport where Self == HTTP2ServerTransport.TransportServices { - /// Creates a new `TransportServices` based HTTP/2 server transport. + /// Creates a TransportServices-based HTTP/2 server transport. /// /// - Parameters: /// - address: The address to which the server should be bound. From 5bc5d2aa4c5c7806763060cea72b18695d19cd1c Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Wed, 29 Jul 2026 10:07:07 -0700 Subject: [PATCH 3/3] adds missing abstracts --- .../Client/Resolver/NameResolver+DNS.swift | 3 +++ .../Client/Resolver/NameResolver+IPv4.swift | 3 +++ .../Client/Resolver/NameResolver+IPv6.swift | 3 +++ .../Client/Resolver/NameResolver+UDS.swift | 3 +++ .../Client/Resolver/NameResolver+VSOCK.swift | 3 +++ .../Client/Resolver/SocketAddress.swift | 24 +++++++++++++++++++ .../WrappedChannel/WrappedChannel.swift | 3 +++ .../ListeningServerTransport.swift | 1 + .../Server/CustomTransport.swift | 1 + .../HTTP2ClientTransport+Posix.swift | 2 ++ .../HTTP2ServerTransport+Posix.swift | 3 +++ ...TP2ClientTransport+TransportServices.swift | 2 ++ ...TP2ServerTransport+TransportServices.swift | 2 ++ 13 files changed, 53 insertions(+) diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+DNS.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+DNS.swift index 3edcc52f..0d682814 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+DNS.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+DNS.swift @@ -62,6 +62,9 @@ extension NameResolvers { /// /// Creates resolvers for ``ResolvableTargets/DNS`` targets. public struct DNS: NameResolverFactory, Sendable { + /// The type of target that this factory creates resolvers for. + /// + /// For this factory, the target type is ``ResolvableTargets/DNS``. public typealias Target = ResolvableTargets.DNS /// Creates a DNS name resolver factory. diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv4.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv4.swift index bebfc463..26fec5e3 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv4.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv4.swift @@ -100,6 +100,9 @@ extension NameResolvers { /// target always produces the same values, with one endpoint per /// address in the target. This resolver doesn't support fetching service configuration. public struct IPv4: NameResolverFactory, Sendable { + /// The type of target that this factory creates resolvers for. + /// + /// For this factory, the target type is ``ResolvableTargets/IPv4``. public typealias Target = ResolvableTargets.IPv4 /// Creates an IPv4 resolver factory. diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv6.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv6.swift index 6d8e6f95..5318fb32 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv6.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv6.swift @@ -99,6 +99,9 @@ extension NameResolvers { /// target always produces the same values, with one endpoint per /// address in the target. This resolver doesn't support fetching service configuration. public struct IPv6: NameResolverFactory, Sendable { + /// The type of target that this factory creates resolvers for. + /// + /// For this factory, the target type is ``ResolvableTargets/IPv6``. public typealias Target = ResolvableTargets.IPv6 /// Creates an IPv6 resolver factory. diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+UDS.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+UDS.swift index e551a660..3d9f9e16 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+UDS.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+UDS.swift @@ -65,6 +65,9 @@ extension NameResolvers { /// for a given target always produces the same values, with a single endpoint. /// This resolver doesn't support fetching service configuration. public struct UnixDomainSocket: NameResolverFactory, Sendable { + /// The type of target that this factory creates resolvers for. + /// + /// For this factory, the target type is ``ResolvableTargets/UnixDomainSocket``. public typealias Target = ResolvableTargets.UnixDomainSocket /// Creates a Unix Domain Socket resolver factory. diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+VSOCK.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+VSOCK.swift index 5952b2c3..bb8fee03 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+VSOCK.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+VSOCK.swift @@ -57,6 +57,9 @@ extension NameResolvers { /// for a given target always produces the same values, with a single endpoint. /// This resolver doesn't support fetching service configuration. public struct VirtualSocket: NameResolverFactory, Sendable { + /// The type of target that this factory creates resolvers for. + /// + /// For this factory, the target type is ``ResolvableTargets/VirtualSocket``. public typealias Target = ResolvableTargets.VirtualSocket /// Creates a VSOCK resolver factory. diff --git a/Sources/GRPCNIOTransportCore/Client/Resolver/SocketAddress.swift b/Sources/GRPCNIOTransportCore/Client/Resolver/SocketAddress.swift index 9dea36b3..d9aede97 100644 --- a/Sources/GRPCNIOTransportCore/Client/Resolver/SocketAddress.swift +++ b/Sources/GRPCNIOTransportCore/Client/Resolver/SocketAddress.swift @@ -155,6 +155,7 @@ extension SocketAddress { @available(gRPCSwiftNIOTransport 2.0, *) extension SocketAddress: CustomStringConvertible { + /// A string representation of the address, formatted according to its underlying address kind. public var description: String { switch self.value { case .ipv4(let address): @@ -245,6 +246,7 @@ extension SocketAddress { /// The port number. public var rawValue: UInt32 + /// Creates a port from its raw numeric value. public init(rawValue: UInt32) { self.rawValue = rawValue } @@ -274,6 +276,7 @@ extension SocketAddress { /// The context identifier. public var rawValue: UInt32 + /// Creates a context ID from its raw numeric value. public init(rawValue: UInt32) { self.rawValue = rawValue } @@ -333,6 +336,10 @@ extension SocketAddress { @available(gRPCSwiftNIOTransport 2.0, *) extension SocketAddress.IPv4: CustomStringConvertible { + /// A string representation of the IPv4 address. + /// + /// The string consists of the literal prefix `[ipv4]` followed by the host and port, + /// separated by a colon. public var description: String { "[ipv4]\(self.host):\(self.port)" } @@ -340,6 +347,10 @@ extension SocketAddress.IPv4: CustomStringConvertible { @available(gRPCSwiftNIOTransport 2.0, *) extension SocketAddress.IPv6: CustomStringConvertible { + /// A string representation of the IPv6 address. + /// + /// The string consists of the literal prefix `[ipv6]` followed by the host and port, + /// separated by a colon. public var description: String { "[ipv6]\(self.host):\(self.port)" } @@ -347,6 +358,9 @@ extension SocketAddress.IPv6: CustomStringConvertible { @available(gRPCSwiftNIOTransport 2.0, *) extension SocketAddress.UnixDomainSocket: CustomStringConvertible { + /// A string representation of the Unix domain socket address. + /// + /// The string consists of the literal prefix `[unix]` followed by the path. public var description: String { "[unix]\(self.path)" } @@ -354,6 +368,10 @@ extension SocketAddress.UnixDomainSocket: CustomStringConvertible { @available(gRPCSwiftNIOTransport 2.0, *) extension SocketAddress.VirtualSocket: CustomStringConvertible { + /// A string representation of the virtual socket address. + /// + /// The string consists of the literal prefix `[vsock]` followed by the context ID and port, + /// separated by a colon. public var description: String { "[vsock]\(self.contextID):\(self.port)" } @@ -361,6 +379,9 @@ extension SocketAddress.VirtualSocket: CustomStringConvertible { @available(gRPCSwiftNIOTransport 2.0, *) extension SocketAddress.VirtualSocket.ContextID: CustomStringConvertible { + /// A string representation of the context ID. + /// + /// The value is `-1` when the context ID is ``any``, and its raw numeric value otherwise. public var description: String { self == .any ? "-1" : String(describing: self.rawValue) } @@ -368,6 +389,9 @@ extension SocketAddress.VirtualSocket.ContextID: CustomStringConvertible { @available(gRPCSwiftNIOTransport 2.0, *) extension SocketAddress.VirtualSocket.Port: CustomStringConvertible { + /// A string representation of the port. + /// + /// The value is `-1` when the port is ``any``, and its raw numeric value otherwise. public var description: String { self == .any ? "-1" : String(describing: self.rawValue) } diff --git a/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel.swift b/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel.swift index b4ccc536..7c4da1e6 100644 --- a/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel.swift +++ b/Sources/GRPCNIOTransportCore/Client/WrappedChannel/WrappedChannel.swift @@ -62,6 +62,7 @@ extension HTTP2ClientTransport { /// resumed with `unavailable`. @available(gRPCSwiftNIOTransport 2.0, *) public final class WrappedChannel: ClientTransport { + /// The concrete type of bytes this transport produces and consumes. public typealias Bytes = GRPCNIOTransportBytes private let channel: any Channel @@ -359,6 +360,7 @@ extension HTTP2ClientTransport { } } +/// Adds a factory for creating a client transport that wraps an already connected NIO channel. @available(gRPCSwiftNIOTransport 2.0, *) extension ClientTransport where Self == HTTP2ClientTransport.WrappedChannel { /// Creates a wrapping client transport from an already connected NIO channel. @@ -471,6 +473,7 @@ extension HTTP2ClientTransport.WrappedChannel { } } +/// Adds a factory for creating a client transport whose channel is configured for gRPC via a closure you supply. @available(gRPCSwiftNIOTransport 2.0, *) extension ClientTransport where Self == HTTP2ClientTransport.WrappedChannel { /// Builds a wrapped-channel transport, configuring the gRPC pipeline on a channel you supply. diff --git a/Sources/GRPCNIOTransportCore/ListeningServerTransport.swift b/Sources/GRPCNIOTransportCore/ListeningServerTransport.swift index fd5e8995..b157f01e 100644 --- a/Sources/GRPCNIOTransportCore/ListeningServerTransport.swift +++ b/Sources/GRPCNIOTransportCore/ListeningServerTransport.swift @@ -24,6 +24,7 @@ public protocol ListeningServerTransport: ServerTransport { var listeningAddress: SocketAddress { get async throws } } +/// Adds a convenience accessor for a server's listening address, for transports that provide one. @available(gRPCSwiftNIOTransport 2.0, *) extension GRPCServer { /// Returns the listening address of the server transport once it has started. diff --git a/Sources/GRPCNIOTransportCore/Server/CustomTransport.swift b/Sources/GRPCNIOTransportCore/Server/CustomTransport.swift index 0b5ba58c..e5b977dc 100644 --- a/Sources/GRPCNIOTransportCore/Server/CustomTransport.swift +++ b/Sources/GRPCNIOTransportCore/Server/CustomTransport.swift @@ -42,6 +42,7 @@ extension HTTP2ServerTransport { public final class Custom< ListenerFactory: HTTP2ServerTransport.ListenerFactory >: ServerTransport { + /// The concrete type of bytes this transport produces and consumes. public typealias Bytes = GRPCNIOTransportBytes /// Configuration for the custom HTTP/2 server transport. diff --git a/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ClientTransport+Posix.swift b/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ClientTransport+Posix.swift index 78dcfbc8..ec4385b7 100644 --- a/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ClientTransport+Posix.swift +++ b/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ClientTransport+Posix.swift @@ -57,6 +57,7 @@ extension HTTP2ClientTransport { /// } /// ``` public struct Posix: ClientTransport { + /// The concrete type of bytes this transport produces and consumes. public typealias Bytes = GRPCNIOTransportBytes private let channel: GRPCChannel @@ -334,6 +335,7 @@ extension GRPCChannel.Config { } } +/// Provides a static factory method for constructing a Posix-based HTTP/2 client transport. @available(gRPCSwiftNIOTransport 2.0, *) extension ClientTransport where Self == HTTP2ClientTransport.Posix { /// Creates a Posix based HTTP/2 client transport. diff --git a/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ServerTransport+Posix.swift b/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ServerTransport+Posix.swift index 1cc36419..2937950c 100644 --- a/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ServerTransport+Posix.swift +++ b/Sources/GRPCNIOTransportHTTP2Posix/HTTP2ServerTransport+Posix.swift @@ -55,6 +55,7 @@ extension HTTP2ServerTransport { /// } /// ``` public struct Posix: ServerTransport, ListeningServerTransport { + /// The concrete type of bytes this transport produces and consumes. public typealias Bytes = GRPCNIOTransportBytes fileprivate struct ListenerFactory: HTTP2ServerTransport.ListenerFactory { @@ -419,6 +420,7 @@ extension ServerBootstrap { } } +/// Provides a static factory method for constructing a Posix-based HTTP/2 server transport bound to a socket address. @available(gRPCSwiftNIOTransport 2.0, *) extension ServerTransport where Self == HTTP2ServerTransport.Posix { /// Creates a Posix-based HTTP/2 server transport. @@ -445,6 +447,7 @@ extension ServerTransport where Self == HTTP2ServerTransport.Posix { } } +/// Provides a static factory method for constructing a Posix-based HTTP/2 server transport from an already bound listening socket. @available(gRPCSwiftNIOTransport 2.6, *) extension ServerTransport where Self == HTTP2ServerTransport.Posix { /// Creates a Posix-based HTTP/2 server transport. diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ClientTransport+TransportServices.swift b/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ClientTransport+TransportServices.swift index 51218544..160b0bbc 100644 --- a/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ClientTransport+TransportServices.swift +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ClientTransport+TransportServices.swift @@ -59,6 +59,7 @@ extension HTTP2ClientTransport { /// } /// ``` public struct TransportServices: ClientTransport { + /// The concrete type of bytes this transport produces and consumes. public typealias Bytes = GRPCNIOTransportBytes private let channel: GRPCChannel @@ -337,6 +338,7 @@ extension NIOTSConnectionBootstrap { } } +/// Provides a static factory method for constructing a TransportServices-based HTTP/2 client transport. @available(gRPCSwiftNIOTransport 2.0, *) extension ClientTransport where Self == HTTP2ClientTransport.TransportServices { /// Creates a TransportServices-based HTTP/2 client transport. diff --git a/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ServerTransport+TransportServices.swift b/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ServerTransport+TransportServices.swift index c0bf2340..82b8be70 100644 --- a/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ServerTransport+TransportServices.swift +++ b/Sources/GRPCNIOTransportHTTP2TransportServices/HTTP2ServerTransport+TransportServices.swift @@ -30,6 +30,7 @@ private import Synchronization extension HTTP2ServerTransport { /// A NIO Transport Services-backed implementation of a server transport. public struct TransportServices: ServerTransport, ListeningServerTransport { + /// The concrete type of bytes this transport produces and consumes. public typealias Bytes = GRPCNIOTransportBytes fileprivate struct ListenerFactory: HTTP2ServerTransport.ListenerFactory { @@ -258,6 +259,7 @@ extension NIOTSListenerBootstrap { } } +/// Provides a static factory method for constructing a TransportServices-based HTTP/2 server transport. @available(gRPCSwiftNIOTransport 2.0, *) extension ServerTransport where Self == HTTP2ServerTransport.TransportServices { /// Creates a TransportServices-based HTTP/2 server transport.