Added Bad Subscriber and HTTP Error types

Author: dimitribouniol

Sources/WebPush/Errors/BadSubscriberError.swift

@@ -0,0 +1,20 @@
+//
+//  BadSubscriberError.swift
+//  swift-webpush
+//
+//  Created by Dimitri Bouniol on 2024-12-13.
+//  Copyright © 2024 Mochi Development, Inc. All rights reserved.
+//
+
+import Foundation
+
+/// The subscription is no longer valid and should be removed and re-registered.
+///
+/// - Warning: Do not continue to send notifications to invalid subscriptions or you'll risk being rate limited by push services.
+public struct BadSubscriberError: LocalizedError, Hashable {
+    public init() {}
+    
+    public var errorDescription: String? {
+        "The subscription is no longer valid."
+    }
+}

Sources/WebPush/Errors/HTTPError.swift

@@ -0,0 +1,27 @@
+//
+//  HTTPError.swift
+//  swift-webpush
+//
+//  Created by Dimitri Bouniol on 2024-12-13.
+//  Copyright © 2024 Mochi Development, Inc. All rights reserved.
+//
+
+import AsyncHTTPClient
+import Foundation
+
+/// An unknown HTTP error was encountered.
+///
+/// - SeeAlso: [RFC8030 Generic Event Delivery Using HTTP Push](https://datatracker.ietf.org/doc/html/rfc8030)
+/// - SeeAlso: [RFC8292 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 HTTPError: LocalizedError {
+    let response: HTTPClientResponse
+    
+    init(response: HTTPClientResponse) {
+        self.response = response
+    }
+    
+    public var errorDescription: String? {
+        "A \(response.status) HTTP error was encountered: \(response)."
+    }
+}

Sources/WebPush/Errors/VAPIDConfigurationError.swift

@@ -13,17 +13,23 @@ extension VAPID {
     public struct ConfigurationError: LocalizedError, Hashable {
         enum Kind {
             case keysNotProvided
+            case matchingKeyNotFound
         }
 
         var kind: Kind
 
         /// VAPID keys not found during initialization.
         public static let keysNotProvided = Self(kind: .keysNotProvided)
 
+        /// A VAPID key for the subscriber was not found.
+        public static let matchingKeyNotFound = Self(kind: .matchingKeyNotFound)
+        
         public var errorDescription: String? {
             switch kind {
             case .keysNotProvided:
                 "VAPID keys not found during initialization."
+            case .matchingKeyNotFound:
+                "A VAPID key for the subscriber was not found."
             }
         }
     }

Sources/WebPush/WebPushManager.swift

@@ -296,7 +296,12 @@ public actor WebPushManager: Sendable {
         urgency: Urgency
     ) async throws {
         guard let signingKey = vapidKeyLookup[subscriber.vapidKeyID]
-        else { throw CancellationError() } // throw key not found error
+        else {
+            logger.warning("A key was not found for this subscriber.", metadata: [
+                "vapidKeyID": "\(subscriber.vapidKeyID)"
+            ])
+            throw VAPID.ConfigurationError.matchingKeyNotFound
+        }
 
         /// Prepare authorization, private keys, and payload ahead of time to bail early if they can't be created.
         let authorization = try loadCurrentVAPIDAuthorizationHeader(endpoint: subscriber.endpoint, signingKey: signingKey)
@@ -305,7 +310,7 @@ public actor WebPushManager: Sendable {
         /// Perform key exchange between the user agent's public key and our private key, deriving a shared secret.
         let userAgent = subscriber.userAgentKeyMaterial
         guard let sharedSecret = try? applicationServerECDHPrivateKey.sharedSecretFromKeyAgreement(with: userAgent.publicKey)
-        else { throw CancellationError() } // throw bad subscription
+        else { throw BadSubscriberError() }
 
         /// Generate a 16-byte salt.
         var salt: [UInt8] = Array(repeating: 0, count: 16)
@@ -376,8 +381,10 @@ public actor WebPushManager: Sendable {
         /// Check the response and determine if the subscription should be removed from our records, or if the notification should just be skipped.
         switch response.status {
         case .created: break
-        case .notFound, .gone: throw CancellationError() // throw bad subscription
-        default: throw CancellationError() //Abort(response.status, headers: response.headers, reason: response.description)
+        case .notFound, .gone: throw BadSubscriberError()
+        // TODO: 413 payload too large - warn and throw error
+        // TODO: 429 too many requests, 500 internal server error, 503 server shutting down - check config and perform a retry after a delay?
+        default: throw HTTPError(response: response)
         }
         logger.trace("Sent \(message) notification to \(subscriber): \(response)")
     }