Finesse @available guards: document rationale and relax over-annota…#8
Open
rnro wants to merge 1 commit into
Open
Finesse @available guards: document rationale and relax over-annota…#8rnro wants to merge 1 commit into
@available guards: document rationale and relax over-annota…#8rnro wants to merge 1 commit into
Conversation
…tions
Every `@available` annotation in `Sources/` and `Tests/` now carries a
`// Availability due to ...` comment naming the underlying type or feature
that drives the OS floor (e.g. `Swift`'s `RawSpan`, `os.log`'s `Logger`,
`CryptoKit`'s `P256.Signing.PublicKey`, `CryptoKit`'s `MLKEM768`). Reading
the source no longer requires inferring why each guard is there.
Use the actual binding type's availability instead of `SwiftTLS 0.1.0`
(= macOS 26+) where it's lower:
* Types whose only OS-bound dependency is `P256.Signing.{PublicKey,
PrivateKey}` — `PrivateKey`, `PublicKey`, their conformance extensions,
`BackingPrivateKey`, `SwiftTLSOpaqueReferenceKey` — drop to
`macOS 11, iOS 14, tvOS 14, watchOS 7, *` (the P256 Apple-CryptoKit
floor).
* `struct Curve25519EphemeralKey` in `KeyExchange.swift` drops to
`macOS 10.15, iOS 13, tvOS 13, watchOS 6, *` — its body only references
`Curve25519`, available at those versions since CryptoKit shipped.
Drop the `@available` entirely on declarations that have no OS-bound
dependency:
* `enum LatestError` and `func errorCodeFromLatestError` in
`SwiftTLSProtocol.swift` — both reference only stdlib types.
* `public typealias SwiftTLSSignatureScheme` (a `UInt16` alias) and
`public typealias SwiftTLSRefKeySignCallback` (a closure over stdlib
`Data` and the alias above) in `PrivateKey.swift` — neither references
an OS-bound type.
* Various other declarations whose bodies only touch stdlib / NIO core /
always-available APIs.
rnro
requested review from
agnosticdev,
baumanl,
ekinnear,
kpodosin and
tfpauly
as code owners
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
…tions
Every
@availableannotation inSources/andTests/now carries a// Availability due to ...comment naming the underlying type or feature that drives the OS floor (e.g.Swift'sRawSpan,os.log'sLogger,CryptoKit'sP256.Signing.PublicKey,CryptoKit'sMLKEM768). Reading the source no longer requires inferring why each guard is there.Use the actual binding type's availability instead of
SwiftTLS 0.1.0(= macOS 26+) where it's lower:P256.Signing.{PublicKey, PrivateKey}—PrivateKey,PublicKey, their conformance extensions,BackingPrivateKey,SwiftTLSOpaqueReferenceKey— drop tomacOS 11, iOS 14, tvOS 14, watchOS 7, *(the P256 Apple-CryptoKit floor).struct Curve25519EphemeralKeyinKeyExchange.swiftdrops tomacOS 10.15, iOS 13, tvOS 13, watchOS 6, *— its body only referencesCurve25519, available at those versions since CryptoKit shipped.Drop the
@availableentirely on declarations that have no OS-bound dependency:enum LatestErrorandfunc errorCodeFromLatestErrorinSwiftTLSProtocol.swift— both reference only stdlib types.public typealias SwiftTLSSignatureScheme(aUInt16alias) andpublic typealias SwiftTLSRefKeySignCallback(a closure over stdlibDataand the alias above) inPrivateKey.swift— neither references an OS-bound type.