apple-crates

@@ -17,7 +17,8 @@ let device_data = grandslam::DeviceData {

 connection.set_topics(&["com.apple.idmsauth"]).await?;

 loop {

     let notification = connection.receive().await?;

-    // Interpret notification.payload according to its topic.

+    // Accept or store notification.payload according to its topic.

+    connection.acknowledge(&notification).await?;

 }

 ```

@@ -39,13 +40,15 @@ signer uses embedded constants and Rust cryptography.

 ## Connection lifetime and persistence

-`receive` handles notification acknowledgements and ping/pong traffic. Keep it

-running while expecting pushes. There are no hidden background tasks or retry

+`receive` returns notifications and handles ping/pong traffic. Call `acknowledge`

+after accepting or storing each notification; it borrows the notification, so

+an acknowledgement error leaves it available to the caller. Keep calling

+`receive` while expecting pushes. There are no hidden background tasks or retry

 loops. Call `reconnect` after transport failure; it reuses the identity/token

 and restores the enabled topics. Use `close` to shut down deliberately. A

 token's existence does not mean a connection is currently reachable.

-If cancelling `receive` during an acknowledgement or keepalive write, reconnect

-before continuing.

+If cancelling `acknowledge` during its write, or `receive` during a keepalive

+write, reconnect before continuing.

 Persist the device certificate, private key, and latest token together.

 `PushIdentity::certificate` returns DER bytes; `private_key` exposes the RSA key

@@ -186,8 +186,9 @@ impl PushConnection {

         Ok(())

     }

-    /// Receives and acknowledges the next notification, driving keepalive while

-    /// waiting. Reconnect after errors or cancellation during a protocol write.

+    /// Receives the next notification, driving keepalive while waiting.

+    /// Call `acknowledge` once the notification is accepted or stored.

+    /// Reconnect after errors or cancellation during a keepalive write.

     pub async fn receive(&mut self) -> Result<Notification, CourierError> {

         loop {

             let deadline = self.pong_deadline.unwrap_or(self.next_ping);

@@ -216,14 +217,6 @@ impl PushConnection {

                     if token != self.token.as_bytes() {

                         return Err(CourierError::TokenMismatch);

                     }

-                    // Validate the payload before acknowledging it.

-                    frame.required(3)?;

-                    Message::Ack {

-                        token: &self.token,

-                        id,

-                    }

-                    .write(&mut self.stream)

-                    .await?;

                     return Ok(Notification {

                         id,

                         topic,

@@ -240,6 +233,17 @@ impl PushConnection {

         }

     }

+    /// Acknowledges receipt of a notification returned by this connection.

+    /// Reconnect after errors or cancellation during the write.

+    pub async fn acknowledge(&mut self, notification: &Notification) -> Result<(), CourierError> {

+        Message::Ack {

+            token: &self.token,

+            id: notification.id,

+        }

+        .write(&mut self.stream)

+        .await

+    }

+

     pub async fn close(mut self) -> io::Result<()> {

         timeout(TIMEOUT, self.stream.shutdown())

             .await