Updated RFC links to be easier to read

dimitribouniol · dimitribouniol · commit 63c37c332e24 · 2024-12-25T14:34:31.000-08:00
diff --git a/README.md b/README.md
@@ -416,13 +416,13 @@ import WebPushTesting
 
 ## Specifications
 
-- [RFC 6454 The Web Origin Concept](https://datatracker.ietf.org/doc/html/rfc6454)
-- [RFC 7515 JSON Web Signature (JWS)](https://datatracker.ietf.org/doc/html/rfc7515)
-- [RFC 7519 JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)
-- [RFC 8030 Generic Event Delivery Using HTTP Push](https://datatracker.ietf.org/doc/html/rfc8030)
-- [RFC 8188 Encrypted Content-Encoding for HTTP](https://datatracker.ietf.org/doc/html/rfc8188)
-- [RFC 8291 Message Encryption for Web Push](https://datatracker.ietf.org/doc/html/rfc8291)
-- [RFC 8292 Voluntary Application Server Identification (VAPID) for Web Push](https://datatracker.ietf.org/doc/html/rfc8292)
+- [RFC 6454 — The Web Origin Concept](https://datatracker.ietf.org/doc/html/rfc6454)
+- [RFC 7515 — JSON Web Signature (JWS)](https://datatracker.ietf.org/doc/html/rfc7515)
+- [RFC 7519 — JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)
+- [RFC 8030 — Generic Event Delivery Using HTTP Push](https://datatracker.ietf.org/doc/html/rfc8030)
+- [RFC 8188 — Encrypted Content-Encoding for HTTP](https://datatracker.ietf.org/doc/html/rfc8188)
+- [RFC 8291 — Message Encryption for Web Push](https://datatracker.ietf.org/doc/html/rfc8291)
+- [RFC 8292 — Voluntary Application Server Identification (VAPID) for Web Push](https://datatracker.ietf.org/doc/html/rfc8292)
 
 
 - [Push API Working Draft](https://www.w3.org/TR/push-api/)
diff --git a/Sources/WebPush/Errors/PushServiceError.swift b/Sources/WebPush/Errors/PushServiceError.swift
@@ -11,8 +11,8 @@ import Foundation
 
 /// An unknown Push Service error was encountered.
 ///
-/// - SeeAlso: [RFC 8030 Generic Event Delivery Using HTTP Push](https://datatracker.ietf.org/doc/html/rfc8030)
-/// - SeeAlso: [RFC 8292 Voluntary Application Server Identification (VAPID) for Web Push](https://datatracker.ietf.org/doc/html/rfc8292)
+/// - SeeAlso: [RFC 8030 — Generic Event Delivery Using HTTP Push](https://datatracker.ietf.org/doc/html/rfc8030)
+/// - SeeAlso: [RFC 8292 — Voluntary Application Server Identification (VAPID) for Web Push](https://datatracker.ietf.org/doc/html/rfc8292)
 /// - SeeAlso: [Sending web push notifications in web apps and browsers — Review responses for push notification errors](https://developer.apple.com/documentation/usernotifications/sending-web-push-notifications-in-web-apps-and-browsers#Review-responses-for-push-notification-errors)
 public struct PushServiceError: LocalizedError, Sendable {
     /// The HTTP response that was returned from the push service..
diff --git a/Sources/WebPush/Helpers/URL+Origin.swift b/Sources/WebPush/Helpers/URL+Origin.swift
@@ -13,8 +13,8 @@ extension URL {
     ///
     /// This implementation is similar to the [WHATWG Standard](https://url.spec.whatwg.org/#concept-url-origin), except that it uses the unicode form of the host, and is limited to HTTP and HTTPS schemas.
     ///
-    /// - SeeAlso: [RFC 8292 Voluntary Application Server Identification (VAPID) for Web Push §2. Application Server Self-Identification](https://datatracker.ietf.org/doc/html/rfc8292#section-2)
-    /// - SeeAlso: [RFC6454 The Web Origin Concept §6.1. Unicode Serialization of an Origin](https://datatracker.ietf.org/doc/html/rfc6454#section-6.1)
+    /// - SeeAlso: [RFC 8292 — Voluntary Application Server Identification (VAPID) for Web Push §2. Application Server Self-Identification](https://datatracker.ietf.org/doc/html/rfc8292#section-2)
+    /// - SeeAlso: [RFC 6454 — The Web Origin Concept §6.1. Unicode Serialization of an Origin](https://datatracker.ietf.org/doc/html/rfc6454#section-6.1)
     var origin: String {
         /// Note that we need the unicode variant, which only URLComponents provides.
         let components = URLComponents(url: self, resolvingAgainstBaseURL: true)
diff --git a/Sources/WebPush/Subscriber.swift b/Sources/WebPush/Subscriber.swift
@@ -31,7 +31,7 @@ public protocol SubscriberProtocol: Sendable {
 
 /// The set of cryptographic secrets shared by the browser (is. user agent) along with a subscription.
 /// 
-/// - SeeAlso: [RFC 8291 Message Encryption for Web Push §2.1. Key and Secret Distribution](https://datatracker.ietf.org/doc/html/rfc8291#section-2.1)
+/// - SeeAlso: [RFC 8291 — Message Encryption for Web Push §2.1. Key and Secret Distribution](https://datatracker.ietf.org/doc/html/rfc8291#section-2.1)
 public struct UserAgentKeyMaterial: Sendable {
     /// The underlying type of an authentication secret.
     public typealias Salt = Data
diff --git a/Sources/WebPush/Topic.swift b/Sources/WebPush/Topic.swift
@@ -15,7 +15,7 @@ import Foundation
 ///
 /// - Important: Since topics are sent in the clear to push services, they must be securely hashed. You must use a stable random value for this, such as the subscriber's ``UserAgentKeyMaterial/authenticationSecret``. This is fine for most applications, though you may wish to use a different key if your application requires it.
 ///
-/// - SeeAlso: [RFC 8030 Generic Event Delivery Using HTTP §5.4. Replacing Push Messages](https://datatracker.ietf.org/doc/html/rfc8030#section-5.4)
+/// - SeeAlso: [RFC 8030 — Generic Event Delivery Using HTTP §5.4. Replacing Push Messages](https://datatracker.ietf.org/doc/html/rfc8030#section-5.4)
 public struct Topic: Hashable, Sendable, CustomStringConvertible {
     /// The topic value to use.
     public let topic: String
diff --git a/Sources/WebPush/VAPID/VAPID.swift b/Sources/WebPush/VAPID/VAPID.swift
@@ -13,5 +13,5 @@ public typealias VoluntaryApplicationServerIdentification = VAPID
 
 /// A set of types for Voluntary Application Server Identification, also known as VAPID.
 ///
-/// - SeeAlso: [RFC 8292 Voluntary Application Server Identification (VAPID) for Web Push](https://datatracker.ietf.org/doc/html/rfc8292)
+/// - SeeAlso: [RFC 8292 — Voluntary Application Server Identification (VAPID) for Web Push](https://datatracker.ietf.org/doc/html/rfc8292)
 public enum VAPID: Sendable {}
diff --git a/Sources/WebPush/VAPID/VAPIDConfiguration.swift b/Sources/WebPush/VAPID/VAPIDConfiguration.swift
@@ -214,7 +214,7 @@ extension VAPID.Configuration {
     /// This allows administrators of push services to contact you should an issue arise with your application server.
     ///
     /// - Note: Although the specification notes that this field is optional, some push services may refuse connection from serers without contact information.
-    /// - SeeAlso: [RFC 8292 Voluntary Application Server Identification (VAPID) for Web Push §2.1. Application Server Contact Information](https://datatracker.ietf.org/doc/html/rfc8292#section-2.1)
+    /// - SeeAlso: [RFC 8292 — Voluntary Application Server Identification (VAPID) for Web Push §2.1. Application Server Contact Information](https://datatracker.ietf.org/doc/html/rfc8292#section-2.1)
     public enum ContactInformation: Hashable, Codable, Sendable {
         /// A URL-based contact method, such as a support page on your website.
         case url(URL)
diff --git a/Sources/WebPush/VAPID/VAPIDKey.swift b/Sources/WebPush/VAPID/VAPIDKey.swift
@@ -98,7 +98,7 @@ extension VAPID.Key: Identifiable {
     /// The public key component in a format suitable for user agents to consume.
     ///
     /// - SeeAlso: [Push API Working Draft §7.2. `PushSubscriptionOptions` Interface](https://www.w3.org/TR/push-api/#dom-pushsubscriptionoptions-applicationserverkey)
-    /// - SeeAlso: [RFC 8292 Voluntary Application Server Identification (VAPID) for Web Push §3.2. Public Key Parameter ("k")](https://datatracker.ietf.org/doc/html/rfc8292#section-3.2)
+    /// - SeeAlso: [RFC 8292 — Voluntary Application Server Identification (VAPID) for Web Push §3.2. Public Key Parameter ("k")](https://datatracker.ietf.org/doc/html/rfc8292#section-3.2)
     public var id: ID {
         ID(privateKey.publicKey.x963Representation.base64URLEncodedString())
     }
diff --git a/Sources/WebPush/VAPID/VAPIDToken.swift b/Sources/WebPush/VAPID/VAPIDToken.swift
@@ -12,9 +12,9 @@ import Foundation
 extension VAPID {
     /// An internal representation the token and authorization headers used self-identification.
     ///
-    /// - SeeAlso: [RFC 8292 Voluntary Application Server Identification (VAPID) for Web Push §2. Application Server Self-Identification](https://datatracker.ietf.org/doc/html/rfc8292#section-2)
-    /// - SeeAlso: [RFC 7515 JSON Web Signature (JWS)](https://datatracker.ietf.org/doc/html/rfc7515)
-    ///- SeeAlso: [RFC 7519 JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)
+    /// - SeeAlso: [RFC 8292 — Voluntary Application Server Identification (VAPID) for Web Push §2. Application Server Self-Identification](https://datatracker.ietf.org/doc/html/rfc8292#section-2)
+    /// - SeeAlso: [RFC 7515 — JSON Web Signature (JWS)](https://datatracker.ietf.org/doc/html/rfc7515)
+    ///- SeeAlso: [RFC 7519 — JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)
     struct Token: Hashable, Codable, Sendable {
         /// The coding keys used to encode the token.
         enum CodingKeys: String, CodingKey {
@@ -26,25 +26,25 @@ extension VAPID {
         /// The audience claim, which encodes the origin of the ``Subscriber/endpoint``
         ///
         /// - SeeAlso: ``/Foundation/URL/origin``
-        /// - SeeAlso: [RFC 7519 JSON Web Token (JWT) §4.1.3. "aud" (Audience) Claim](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3)
-        /// - SeeAlso: [RFC 8292 Voluntary Application Server Identification (VAPID) for Web Push §2. Application Server Self-Identification](https://datatracker.ietf.org/doc/html/rfc8292#section-2)
+        /// - SeeAlso: [RFC 7519 — JSON Web Token (JWT) §4.1.3. "aud" (Audience) Claim](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3)
+        /// - SeeAlso: [RFC 8292 — Voluntary Application Server Identification (VAPID) for Web Push §2. Application Server Self-Identification](https://datatracker.ietf.org/doc/html/rfc8292#section-2)
         var audience: String
         
         /// The subject claim, which encodes contact information for the application server.
         ///
-        /// - SeeAlso: [RFC 7519 JSON Web Token (JWT) §4.1.2. "sub" (Subject) Claim](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2)
-        /// - SeeAlso: [RFC 8292 Voluntary Application Server Identification (VAPID) for Web Push §2.1. Application Server Contact Information](https://datatracker.ietf.org/doc/html/rfc8292#section-2.1)
+        /// - SeeAlso: [RFC 7519 — JSON Web Token (JWT) §4.1.2. "sub" (Subject) Claim](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2)
+        /// - SeeAlso: [RFC 8292 — Voluntary Application Server Identification (VAPID) for Web Push §2.1. Application Server Contact Information](https://datatracker.ietf.org/doc/html/rfc8292#section-2.1)
         var subject: Configuration.ContactInformation
         
         /// The expiry claim, which encodes the number of seconds after 1970/01/01 when the token expires.
         ///
-        /// - SeeAlso: [RFC 7519 JSON Web Token (JWT) §4.1.4. "exp" (Expiration Time) Claim](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4)
-        /// - SeeAlso: [RFC 8292 Voluntary Application Server Identification (VAPID) for Web Push §2. Application Server Self-Identification](https://datatracker.ietf.org/doc/html/rfc8292#section-2)
+        /// - SeeAlso: [RFC 7519 — JSON Web Token (JWT) §4.1.4. "exp" (Expiration Time) Claim](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4)
+        /// - SeeAlso: [RFC 8292 — Voluntary Application Server Identification (VAPID) for Web Push §2. Application Server Self-Identification](https://datatracker.ietf.org/doc/html/rfc8292#section-2)
         var expiration: Int
         
         /// The standard header including the type and algorithm.
         ///
-        /// - SeeAlso: [RFC 8292 Voluntary Application Server Identification (VAPID) for Web Push §2. Application Server Self-Identification](https://datatracker.ietf.org/doc/html/rfc8292#section-2)
+        /// - SeeAlso: [RFC 8292 — Voluntary Application Server Identification (VAPID) for Web Push §2. Application Server Self-Identification](https://datatracker.ietf.org/doc/html/rfc8292#section-2)
         static let jwtHeader = Array(#"{"typ":"JWT","alg":"ES256"}"#.utf8).base64URLEncodedString()
         
         /// Initialize a token with the specified claims.
@@ -93,7 +93,7 @@ extension VAPID {
             self = token
         }
         
-        /// - SeeAlso: [RFC 7515 JSON Web Signature (JWS) §3. JSON Web Signature (JWS) Overview](https://datatracker.ietf.org/doc/html/rfc7515#section-3)
+        /// - SeeAlso: [RFC 7515 — JSON Web Signature (JWS) §3. JSON Web Signature (JWS) Overview](https://datatracker.ietf.org/doc/html/rfc7515#section-3)
         func generateJWT(signedBy signingKey: some VAPIDKeyProtocol) throws -> String {
             let header = Self.jwtHeader
             
@@ -108,7 +108,7 @@ extension VAPID {
         
         /// Generate an `Authorization` header.
         ///
-        /// - SeeAlso: [RFC 8292 Voluntary Application Server Identification (VAPID) for Web Push §3. VAPID Authentication Scheme](https://datatracker.ietf.org/doc/html/rfc8292#section-3)
+        /// - SeeAlso: [RFC 8292 — Voluntary Application Server Identification (VAPID) for Web Push §3. VAPID Authentication Scheme](https://datatracker.ietf.org/doc/html/rfc8292#section-3)
         func generateAuthorization(signedBy signingKey: some VAPIDKeyProtocol) throws -> String {
             let token = try generateJWT(signedBy: signingKey)
             let key = signingKey.id
@@ -123,6 +123,6 @@ protocol VAPIDKeyProtocol: Identifiable, Sendable {
     associatedtype Signature: ContiguousBytes
     
     /// Returns a JWS signature for the message.
-    /// - SeeAlso: [RFC 7515 JSON Web Signature (JWS)](https://datatracker.ietf.org/doc/html/rfc7515)
+    /// - SeeAlso: [RFC 7515 — JSON Web Signature (JWS)](https://datatracker.ietf.org/doc/html/rfc7515)
     func signature(for message: some DataProtocol) throws -> Signature
 }
diff --git a/Sources/WebPush/WebPushManager.swift b/Sources/WebPush/WebPushManager.swift
@@ -637,7 +637,7 @@ public actor WebPushManager: Sendable {
             .withUnsafeBytes(AES.GCM.Nonce.init(data:))
         
         /// Encrypt the padded payload into a single record.
-        /// - SeeAlso: [RFC 8188 Encrypted Content-Encoding for HTTP](https://datatracker.ietf.org/doc/html/rfc8188)
+        /// - SeeAlso: [RFC 8188 — Encrypted Content-Encoding for HTTP](https://datatracker.ietf.org/doc/html/rfc8188)
         let encryptedRecord = try AES.GCM.seal(paddedPayload, using: contentEncryptionKey, nonce: nonce)
         
         /// Attach the header with our public key and salt, along with the authentication tag.
@@ -784,7 +784,7 @@ extension WebPushManager: Service {
 extension WebPushManager {
     /// A duration in seconds used to express when push messages will expire.
     ///
-    /// - SeeAlso: [RFC 8030 Generic Event Delivery Using HTTP §5.2. Push Message Time-To-Live](https://datatracker.ietf.org/doc/html/rfc8030#section-5.2)
+    /// - SeeAlso: [RFC 8030 — Generic Event Delivery Using HTTP §5.2. Push Message Time-To-Live](https://datatracker.ietf.org/doc/html/rfc8030#section-5.2)
     public struct Expiration: Hashable, Comparable, Codable, ExpressibleByIntegerLiteral, AdditiveArithmetic, Sendable {
         /// The number of seconds represented by this expiration.
         public let seconds: Int
@@ -800,7 +800,7 @@ extension WebPushManager {
         ///
         /// If the user agent is unavailable, a push message with a zero TTL expires and is never delivered.
         ///
-        /// - SeeAlso: [RFC 8030 Generic Event Delivery Using HTTP §5.2. Push Message Time-To-Live](https://datatracker.ietf.org/doc/html/rfc8030#section-5.2)
+        /// - SeeAlso: [RFC 8030 — Generic Event Delivery Using HTTP §5.2. Push Message Time-To-Live](https://datatracker.ietf.org/doc/html/rfc8030#section-5.2)
         public static let dropIfUndeliverable: Self = .zero
         
         /// Initialize an expiration with a number of seconds.
@@ -868,7 +868,7 @@ extension WebPushManager {
 extension WebPushManager {
     /// The urgency with which to deliver a push message.
     ///
-    /// - SeeAlso: [RFC 8030 Generic Event Delivery Using HTTP §5.3. Push Message Urgency](https://datatracker.ietf.org/doc/html/rfc8030#section-5.3)
+    /// - SeeAlso: [RFC 8030 — Generic Event Delivery Using HTTP §5.3. Push Message Urgency](https://datatracker.ietf.org/doc/html/rfc8030#section-5.3)
     public struct Urgency: Hashable, Comparable, Sendable, CustomStringConvertible {
         /// The internal raw value that is encoded in this type's place when calling ``description``.
         let rawValue: String

Original file line number	Diff line number	Diff line change
`@@ -98,7 +98,7 @@ extension VAPID.Key: Identifiable {`
`98`	`98`	`/// The public key component in a format suitable for user agents to consume.`
`99`	`99`	`///`
`100`	`100`	/// - SeeAlso: [Push API Working Draft §7.2. `PushSubscriptionOptions` Interface](https://www.w3.org/TR/push-api/#dom-pushsubscriptionoptions-applicationserverkey)
`101`		`- /// - SeeAlso: [RFC 8292 Voluntary Application Server Identification (VAPID) for Web Push §3.2. Public Key Parameter ("k")](https://datatracker.ietf.org/doc/html/rfc8292#section-3.2)`
	`101`	`+ /// - SeeAlso: [RFC 8292 — Voluntary Application Server Identification (VAPID) for Web Push §3.2. Public Key Parameter ("k")](https://datatracker.ietf.org/doc/html/rfc8292#section-3.2)`
`102`	`102`	`public var id: ID {`
`103`	`103`	`ID(privateKey.publicKey.x963Representation.base64URLEncodedString())`
`104`	`104`	`}`