Development notes

Open questions

HTTP/2

• What's the deal with the content-length header? HTTP/2 frames already include a length header, and the max size of an APNs payload (4kB) is already much smaller than the lower bound for a maximum frame size (16kB). It sounds like APNs payloads are always expected to be sent in a single DATA frame, but a content-length header would be most useful if splitting the content across multiple frames.
  • It sounds like the content-length header requirement might go away in the near future.
• Why is the apns-id header needed? It sounds like each notification should receive a reply on the stream on which it was sent, so it seems like responses should already be associated with requests. It seems like the apns-id would mostly be useful if responses were sent asynchronously, or on different streams. I think we can ignore this if it's not useful to us, but I'm worried that I could be misunderstanding the model.
  • Is the apns-id only sent in error responses?
    • No—it appears that the apns-id header is sent with all responses.

Binary APNs protocol

• Apple's docs say: "If you need to send a large number of push notifications, spread them out over connections to several different gateways." The docs only list one gateway address (gateway.push.apple.com) and that's presumably a load balancer(?), but it would be nice to confirm that's actually what's happening.
  • It does not appear that any automatic load balancing is actually happening. We may need to do this ourselves (see #62).
• Are any of the "items" in the binary notification format optional? It definitely doesn't make sense to leave out a device token, payload, or sequence number, but can we leave out an expiration date or priority?
  • Experimentally, yes, it appears that at least the expiration time and delivery priority can be omitted. No experiments were run for the sequence number, token, or payload because it wouldn't really make sense to omit them. It's also not clear if it will ALWAYS be safe to omit the "optional" fields (Apple may change their minds in the future) or what the defaults are when those frame items are omitted. That said, delivery priority probably defaults to IMMEDIATE (because that's what happens in legacy formats) and the expiration timestamp probably defaults to 0 (because sure why not).
• "[When using the IMMEDIATE delivery priority] the push notification must trigger an alert, sound, or badge on the device. It is an error to use this priority for a push that contains only the content-available key." Does that mean the notification will be rejected by the gateway? If so, what will the error code be? This is even more confusing because the docs for the legacy protocols say: "These formats do not include a priority; a priority of 10 is assumed."
  • In experiments, the gateway does not complain about sending a content-available-only notification with an IMMEDIATE priority. Looks like this one is up to the sender.
• Using the binary notification format, it seems like it's much more likely that a notification will be rejected before a sequence number is sent. Can we reduce the risk by sending the sequence number as early in the frame as possible? If not, what sequence number will the APNs gateway send when in doubt?
  • If something goes wrong before the sequence number of a notification has been processed, the gateway will always send 0 as the ID of the rejected notification. If something goes wrong after the sequence number has been sent (i.e. bad payload length after a good sequence number), the correct sequence number will be sent in the rejection notification.