Add semantic safe API for FileProvider notifications (#149)

# Motivation
We want to provide new APIs that are semantically safe when sending FileProvider notifications to APNs.

# Modification
The PR adds new types for the FileProvider notification and a convenience method to send it notifications with the APNSClient.

# Result
We can now send FileProvider notifications.

Author: FranzBusch

Sources/APNSwift/FileProvider/APNSClient+FileProvider.swift

@@ -0,0 +1,50 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the APNSwift open source project
+//
+// Copyright (c) 2022 the APNSwift project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of APNSwift project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import Logging
+import NIOCore
+
+extension APNSClient {
+    /// Sends a file provider notification to APNs.
+    ///
+    /// - Parameters:
+    ///   - notification: The notification to send.
+    ///
+    ///   - deviceToken: The hexadecimal bytes that identify the user’s device. Your app receives the bytes for this device token
+    ///    when registering for remote notifications.
+    ///
+    ///   - deadline: Point in time by which sending the notification to APNs must complete.
+    ///
+    ///   - logger: The logger to use for sending this notification.
+    @discardableResult
+    @inlinable
+    public func sendFileProviderNotification<Payload: Encodable>(
+        _ notification: APNSFileProviderNotification<Payload>,
+        deviceToken: String,
+        deadline: NIODeadline,
+        logger: Logger = _noOpLogger
+    ) async throws -> APNSResponse {
+        try await self.send(
+            payload: notification.payload,
+            deviceToken: deviceToken,
+            pushType: .fileprovider,
+            expiration: notification.expiration,
+            // This always needs to be consideringDevicePower otherwise APNs returns an error
+            priority: .consideringDevicePower,
+            topic: notification.topic,
+            deadline: deadline,
+            logger: logger
+        )
+    }
+}

Sources/APNSwift/FileProvider/APNSFileProviderNotification.swift

@@ -0,0 +1,84 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the APNSwift open source project
+//
+// Copyright (c) 2022 the APNSwift project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of APNSwift project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import struct Foundation.UUID
+
+/// A file provider notification.
+public struct APNSFileProviderNotification<Payload: Encodable> {
+    /// A canonical UUID that identifies the notification. If there is an error sending the notification,
+    /// APNs uses this value to identify the notification to your server. The canonical form is 32 lowercase hexadecimal digits,
+    /// displayed in five groups separated by hyphens in the form 8-4-4-4-12. An example UUID is as follows:
+    /// `123e4567-e89b-12d3-a456-42665544000`.
+    ///
+    /// If you omit this, a new UUID is created by APNs and returned in the response.
+    public var apnsID: UUID?
+
+    /// The topic for the notification. In general, the topic is your app’s bundle ID/app ID suffixed with `.voip`.
+    public var topic: String
+
+    /// The date when the notification is no longer valid and can be discarded. If this value is not `none`,
+    /// APNs stores the notification and tries to deliver it at least once,
+    /// repeating the attempt as needed if it is unable to deliver the notification the first time.
+    /// If the value is `immediately`, APNs treats the notification as if it expires immediately
+    /// and does not store the notification or attempt to redeliver it.
+    public var expiration: APNSNotificationExpiration
+
+    /// Your custom payload.
+    public var payload: Payload
+
+    /// Initializes a new ``APNSFileProviderNotification``.
+    ///
+    /// - Parameters:
+    ///   - expiration: The date when the notification is no longer valid and can be discarded
+    ///   - appID: Your app’s bundle ID/app ID. This will be suffixed with `.pushkit.fileprovider`.
+    ///   - payload: Your custom payload.
+    ///   - apnsID: A canonical UUID that identifies the notification.
+    @inlinable
+    public init(
+        expiration: APNSNotificationExpiration,
+        appID: String,
+        payload: Payload,
+        apnsID: UUID? = nil
+    ) {
+        self.init(
+            expiration: expiration,
+            topic: appID + ".pushkit.fileprovider",
+            payload: payload,
+            apnsID: apnsID
+        )
+    }
+
+    /// Initializes a new ``APNSFileProviderNotification``.
+    ///
+    /// - Important: Your dynamic payload will get encoded to the root of the JSON payload that is send to APNs.
+    /// It is **important** that you do not encode anything with the key `aps`
+    ///
+    /// - Parameters:
+    ///   - expiration: The date when the notification is no longer valid and can be discarded
+    ///   - topic: The topic for the notification. In general, the topic is your app’s bundle ID/app ID suffixed with `.pushkit.fileprovider`.
+    ///   - payload: Your custom payload.
+    ///   - apnsID: A canonical UUID that identifies the notification.
+    @inlinable
+    public init(
+        expiration: APNSNotificationExpiration,
+        topic: String,
+        payload: Payload,
+        apnsID: UUID? = nil
+    ) {
+        self.expiration = expiration
+        self.topic = topic
+        self.payload = payload
+        self.apnsID = apnsID
+    }
+}

Sources/APNSwiftExample/Program.swift

@@ -30,6 +30,7 @@ struct Main {
     /// To use this example app please provide proper values for variable below.
     static let deviceToken = ""
     static let pushKitDeviceToken = ""
+    static let fileProviderDeviceToken = ""
     static let appBundleID = ""
     static let privateKey = """
     -----BEGIN PRIVATE KEY-----
@@ -68,6 +69,7 @@ struct Main {
             try await Self.sendMutableContentAlert(with: client)
             try await Self.sendBackground(with: client)
             try await Self.sendVoIP(with: client)
+            try await Self.sendFileProvider(with: client)
         } catch {
             self.logger.error("Failed sending push", metadata: ["error": "\(error)"])
         }
@@ -218,3 +220,21 @@ extension Main {
         )
     }
 }
+
+// MARK: FileProvider
+
+@available(macOS 11.0, *)
+extension Main {
+    static func sendFileProvider(with client: APNSClient<JSONDecoder, JSONEncoder>) async throws {
+        try await client.sendFileProviderNotification(
+            .init(
+                expiration: .immediately,
+                appID: self.appBundleID,
+                payload: Payload()
+            ),
+            deviceToken: self.fileProviderDeviceToken,
+            deadline: .distantFuture,
+            logger: self.logger
+        )
+    }
+}

Tests/APNSwiftTests/FileProvider/APNSFileProviderNotificationTests.swift

@@ -0,0 +1,31 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the APNSwift open source project
+//
+// Copyright (c) 2022 the APNSwift project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of APNSwift project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import APNSwift
+import XCTest
+
+final class APNSFileProviderNotificationTests: XCTestCase {
+    func testAppID() {
+        struct Payload: Encodable {
+            let foo = "bar"
+        }
+        let fileProviderNotification = APNSFileProviderNotification(
+            expiration: .immediately,
+            appID: "com.example.app",
+            payload: Payload()
+        )
+
+        XCTAssertEqual(fileProviderNotification.topic, "com.example.app.pushkit.fileprovider")
+    }
+}