Add broadcast push send support

Author: kylebrowning

Sources/APNS/APNSBroadcastClient.swift

@@ -75,14 +75,16 @@ public final class APNSBroadcastClient<Decoder: APNSJSONDecoder & Sendable, Enco
     ///   - responseDecoder: The decoder for the responses from APNs.
     ///   - requestEncoder: The encoder for the requests to APNs.
     ///   - byteBufferAllocator: The `ByteBufferAllocator`.
+    ///   - proxy: Upstream proxy, defaults to no proxy.
     public init(
         authenticationMethod: APNSClientConfiguration.AuthenticationMethod,
         environment: APNSBroadcastEnvironment,
         bundleID: String,
         eventLoopGroupProvider: NIOEventLoopGroupProvider,
         responseDecoder: Decoder,
         requestEncoder: Encoder,
-        byteBufferAllocator: ByteBufferAllocator = .init()
+        byteBufferAllocator: ByteBufferAllocator = .init(),
+        proxy: HTTPClient.Configuration.Proxy? = nil
     ) {
         self.environment = environment
         self.bundleID = bundleID
@@ -108,6 +110,7 @@ public final class APNSBroadcastClient<Decoder: APNSJSONDecoder & Sendable, Enco
         var httpClientConfiguration = HTTPClient.Configuration()
         httpClientConfiguration.tlsConfiguration = tlsConfiguration
         httpClientConfiguration.httpVersion = .automatic
+        httpClientConfiguration.proxy = proxy
 
         switch eventLoopGroupProvider {
         case .shared(let eventLoopGroup):

Sources/APNS/APNSClient.swift

@@ -200,4 +200,91 @@ extension APNSClient {
 
         throw error
     }
+
+    /// Publishes a broadcast push notification.
+    ///
+    /// Broadcast pushes are sent to the regular device-push host (``APNSCore/APNSEnvironment``), not the
+    /// channel-management host, and are Live Activities only.
+    ///
+    /// - Parameter request: The broadcast send request.
+    public func sendBroadcast<Message: APNSCore.APNSMessage>(
+        _ request: APNSCore.APNSBroadcastSendRequest<Message>
+    ) async throws -> APNSCore.APNSBroadcastSendResponse {
+        var headers = self.defaultRequestHeaders
+
+        // Broadcast headers (apns-channel-id, apns-push-type, apns-expiration, apns-priority, apns-request-id)
+        for (name, value) in request.headers {
+            headers.add(name: name, value: value)
+        }
+
+        // Authorization token
+        if let authenticationTokenManager = self.authenticationTokenManager {
+            let token = try await authenticationTokenManager.nextValidToken
+            headers.add(name: "authorization", value: token)
+        }
+
+        let requestURL = self.configuration.environment.broadcastSendURL(bundleID: request.bundleID)
+        var byteBuffer = self.byteBufferAllocator.buffer(capacity: 0)
+
+        try self.requestEncoder.encode(request.message, into: &byteBuffer)
+
+        var httpClientRequest = HTTPClientRequest(url: requestURL)
+        httpClientRequest.method = .POST
+        httpClientRequest.headers = headers
+        httpClientRequest.body = .bytes(byteBuffer)
+
+        let response = try await self.httpClient.execute(httpClientRequest, deadline: .distantFuture)
+
+        let apnsRequestID = response.headers.first(name: "apns-request-id").flatMap { UUID(uuidString: $0) }
+        let apnsUniqueID = response.headers.first(name: "apns-unique-id").flatMap { UUID(uuidString: $0) }
+
+        if response.status == .ok {
+            return APNSBroadcastSendResponse(apnsRequestID: apnsRequestID, apnsUniqueID: apnsUniqueID)
+        }
+
+        let body = try await response.body.collect(upTo: 1024)
+        let errorResponse = try responseDecoder.decode(APNSErrorResponse.self, from: body)
+
+        let error = APNSError(
+            responseStatus: Int(response.status.code),
+            apnsID: nil,
+            apnsUniqueID: apnsUniqueID,
+            apnsResponse: errorResponse,
+            timestamp: errorResponse.timestampInSeconds.flatMap { Date(timeIntervalSince1970: $0) }
+        )
+
+        throw error
+    }
+}
+
+// MARK: - Broadcast convenience
+
+extension APNSClient {
+
+    /// Publishes a broadcast Live Activity update (or end) notification.
+    ///
+    /// - Important: Broadcast is Live Activities only and cannot be used to *start* an activity.
+    ///
+    /// - Parameters:
+    ///   - notification: The Live Activity notification to broadcast.
+    ///   - channelID: The base64-encoded channel ID to publish the broadcast on.
+    ///   - bundleID: The app's bundle identifier used in the API path.
+    ///   - apnsRequestID: An optional request ID for tracking.
+    @discardableResult
+    public func sendBroadcastLiveActivityNotification<ContentState: Encodable & Sendable>(
+        _ notification: APNSCore.APNSLiveActivityNotification<ContentState>,
+        channelID: String,
+        bundleID: String,
+        apnsRequestID: UUID? = nil
+    ) async throws -> APNSCore.APNSBroadcastSendResponse {
+        let request = APNSCore.APNSBroadcastSendRequest(
+            message: notification,
+            channelID: channelID,
+            bundleID: bundleID,
+            expiration: notification.expiration,
+            priority: notification.priority,
+            apnsRequestID: apnsRequestID
+        )
+        return try await sendBroadcast(request)
+    }
 }

Sources/APNSCore/APNSEnvironment.swift

@@ -41,6 +41,13 @@ public struct APNSEnvironment: Sendable {
     public var absoluteURL: String {
         "\(url):\(port)/3/device"
     }
-    
-    
+
+    /// The fully constructed URL for publishing a broadcast push notification.
+    ///
+    /// Broadcast pushes are sent to the regular device-push host, not the channel-management host.
+    ///
+    /// - Parameter bundleID: The app's bundle identifier.
+    public func broadcastSendURL(bundleID: String) -> String {
+        "\(url):\(port)/4/broadcasts/apps/\(bundleID)"
+    }
 }

Sources/APNSCore/Broadcast/APNSBroadcastSendRequest.swift

@@ -0,0 +1,98 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the APNSwift open source project
+//
+// Copyright (c) 2025 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
+//
+//===----------------------------------------------------------------------===//
+
+#if canImport(FoundationEssentials)
+import struct FoundationEssentials.UUID
+#else
+import struct Foundation.UUID
+#endif
+
+/// Represents a request to publish a broadcast push notification.
+///
+/// Broadcast pushes are sent to the regular device-push host (``APNSEnvironment``), not the
+/// channel-management host, at `POST /4/broadcasts/apps/<bundle ID>`. They are Live Activities only
+/// and cannot be used to start an activity.
+///
+/// See: https://developer.apple.com/documentation/usernotifications/sending-broadcast-push-notification-requests-to-apns
+public struct APNSBroadcastSendRequest<Message: APNSMessage>: Sendable {
+    /// The message payload to broadcast.
+    public let message: Message
+
+    /// The base64-encoded channel ID to publish the broadcast on.
+    public let channelID: String
+
+    /// The app's bundle identifier used in the API path.
+    public let bundleID: String
+
+    /// The date when the notification is no longer valid and can be discarded.
+    public let expiration: APNSNotificationExpiration
+
+    /// The priority of the notification.
+    public let priority: APNSPriority
+
+    /// An optional request ID for tracking. If you omit this, APNs creates a new UUID and returns it in the response.
+    public let apnsRequestID: UUID?
+
+    /// Creates a broadcast send request.
+    ///
+    /// - Parameters:
+    ///   - message: The message payload to broadcast.
+    ///   - channelID: The base64-encoded channel ID to publish the broadcast on.
+    ///   - bundleID: The app's bundle identifier used in the API path.
+    ///   - expiration: The date when the notification is no longer valid and can be discarded.
+    ///   - priority: The priority of the notification.
+    ///   - apnsRequestID: An optional request ID for tracking.
+    public init(
+        message: Message,
+        channelID: String,
+        bundleID: String,
+        expiration: APNSNotificationExpiration,
+        priority: APNSPriority,
+        apnsRequestID: UUID? = nil
+    ) {
+        self.message = message
+        self.channelID = channelID
+        self.bundleID = bundleID
+        self.expiration = expiration
+        self.priority = priority
+        self.apnsRequestID = apnsRequestID
+    }
+
+    /// The HTTP headers required (and optional) by APNs for a broadcast send request.
+    ///
+    /// - Note: Unlike a regular device push, `apns-expiration` and `apns-priority` are always emitted
+    /// since Apple requires both headers on broadcast requests.
+    public var headers: [(String, String)] {
+        var computedHeaders: [(String, String)] = []
+
+        /// Channel ID
+        computedHeaders.append(("apns-channel-id", channelID))
+
+        /// Push type — broadcast only supports `liveactivity`.
+        computedHeaders.append(("apns-push-type", "liveactivity"))
+
+        /// Expiration — required by Apple, so `.none` is sent as `0`.
+        computedHeaders.append(("apns-expiration", "\(expiration.expiration ?? 0)"))
+
+        /// Priority — required by Apple.
+        computedHeaders.append(("apns-priority", "\(priority.rawValue)"))
+
+        /// Request ID
+        if let apnsRequestID {
+            computedHeaders.append(("apns-request-id", apnsRequestID.uuidString.lowercased()))
+        }
+
+        return computedHeaders
+    }
+}

Sources/APNSCore/Broadcast/APNSBroadcastSendResponse.swift

@@ -0,0 +1,33 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the APNSwift open source project
+//
+// Copyright (c) 2025 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
+//
+//===----------------------------------------------------------------------===//
+
+#if canImport(FoundationEssentials)
+import struct FoundationEssentials.UUID
+#else
+import struct Foundation.UUID
+#endif
+
+/// Represents a response from publishing a broadcast push notification.
+public struct APNSBroadcastSendResponse: Sendable, Hashable {
+    /// The request ID returned by APNs, either echoing the one sent in the request or a newly generated one.
+    public let apnsRequestID: UUID?
+
+    /// A unique ID for the broadcast notification, as determined by the APNs servers.
+    public let apnsUniqueID: UUID?
+
+    public init(apnsRequestID: UUID?, apnsUniqueID: UUID?) {
+        self.apnsRequestID = apnsRequestID
+        self.apnsUniqueID = apnsUniqueID
+    }
+}