6. Receiving Push Messages for a Subscription

A user agent requests the delivery of new push messages by making a GET request to a push message subscription resource. The push service does not respond to this request; instead, it uses HTTP/2 server push [RFC7540] to send the contents of push messages as they are sent by application servers.

A user agent MAY include an Urgency header field in its request. The push service MUST NOT deliver messages with lower urgency than the value of the header field as defined in Table 1 (Illustrative Urgency Values).

Each push message is pushed as the response to a synthesized GET request sent in a PUSH_PROMISE. This GET request is made to the push message resource that was created by the push service when the application server requested message delivery. The response headers SHOULD provide a URI for the push resource corresponding to the push message subscription in a link relation of type urn:ietf:params:push. The response body is the entity body from the most recent request sent to the push resource by the application server.

The following example request is made over HTTP/2:

HEADERS      [stream 7] +END_STREAM +END_HEADERS
  :method        = GET
  :path          = /subscription/LBhhw0OohO-Wl4Oi971UG
  :authority     = push.example.net

The push service permits the request to remain outstanding. When a push message is sent by an application server, a server push is generated in association with the initial request. The response for the server push includes the push message.

PUSH_PROMISE [stream 7; promised stream 4] +END_HEADERS
  :method        = GET
  :path          = /message/qDIYHNcfAIPP_5ITvURr-d6BGt
  :authority     = push.example.net

HEADERS      [stream 4] +END_HEADERS
  :status        = 200
  date           = Thu, 11 Dec 2014 23:56:56 GMT
  last-modified  = Thu, 11 Dec 2014 23:56:55 GMT
  cache-control  = private
  link           = </push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV>;
                    rel="urn:ietf:params:push"
  content-type   = text/plain;charset=utf8
  content-length = 36

DATA         [stream 4] +END_STREAM
  iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB

HEADERS      [stream 7] +END_STREAM +END_HEADERS
  :status        = 200

A user agent can also request the contents of the push message subscription resource immediately by including a Prefer header field [RFC7240] with a wait preference set to 0. In response to this request, the push service MUST generate a server push for all push messages that have not yet been delivered.

A 204 (No Content) status code with no associated server pushes indicates that no messages are presently available. This could be because push messages have expired.

6.1. Receiving Push Messages for a Subscription Set

There are minor differences between receiving push messages for a subscription and a subscription set. If a subscription set is available, the user agent SHOULD use the subscription set to monitor for push messages rather than individual push message subscriptions.

A user agent requests the delivery of new push messages for a collection of push message subscriptions by making a GET request to a push message subscription set resource. The push service does not respond to this request; instead, it uses HTTP/2 server push [RFC7540] to send the contents of push messages as they are sent by application servers.

Each push message is pushed as the response to a synthesized GET request sent in a PUSH_PROMISE. This GET request is made to the push message resource that was created by the push service when the application server requested message delivery. The synthetic request MUST provide a URI for the push resource corresponding to the push message subscription in a link relation of type urn:ietf:params:push. This enables the user agent to differentiate the source of the message. The response body is the entity body from the most recent request sent to the push resource by an application server.

The following example request is made over HTTP/2.

HEADERS      [stream 7] +END_STREAM +END_HEADERS
  :method        = GET
  :path          = /subscription-set/4UXwi2Rd7jGS7gp5cuutF8ZldnEuvbOy
  :authority     = push.example.net

PUSH_PROMISE [stream 7; promised stream 4] +END_HEADERS
  :method        = GET
  :path          = /message/qDIYHNcfAIPP_5ITvURr-d6BGt
  :authority     = push.example.net

HEADERS      [stream 4] +END_HEADERS
  :status        = 200
  date           = Thu, 11 Dec 2014 23:56:56 GMT
  last-modified  = Thu, 11 Dec 2014 23:56:55 GMT
  link           = </push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV>;
                    rel="urn:ietf:params:push"
  cache-control  = private
  content-type   = text/plain;charset=utf8
  content-length = 36

DATA         [stream 4] +END_STREAM
  iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB

HEADERS      [stream 7] +END_STREAM +END_HEADERS
  :status        = 200

A user agent can request the contents of the push message subscription set resource immediately by including a Prefer header field [RFC7240] with a wait preference set to 0. In response to this request, the push service MUST generate a server push for all push messages that have not yet been delivered.

A 204 (No Content) status code with no associated server pushes indicates that no messages are presently available. This could be because push messages have expired.

6.2. Acknowledging Push Messages

To ensure that a push message is properly delivered to the user agent at least once, the user agent MUST acknowledge receipt of the message by performing an HTTP DELETE on the push message resource.

DELETE /message/qDIYHNcfAIPP_5ITvURr-d6BGt HTTP/1.1
Host: push.example.net

If the push service receives the acknowledgement and the application has requested a delivery receipt, the push service MUST return a 204 (No Content) response to the application server monitoring the receipt subscription.

If the push service does not receive the acknowledgement within a reasonable amount of time, then the message is considered to be not yet delivered. The push service SHOULD continue to retry delivery of the message until its advertised expiration.

The push service MAY cease to retry delivery of the message prior to its advertised expiration due to scenarios such as an unresponsive user agent or operational constraints. If the application has requested a delivery receipt, then the push service MUST return a 410 (Gone) response to the application server monitoring the receipt subscription.

6.3. Receiving Push Message Receipts

The application server requests the delivery of receipts from the push service by making an HTTP GET request to the receipt subscription resource. The push service does not respond to this request; instead, it uses HTTP/2 server push [RFC7540] to send push receipts when messages are acknowledged (Section 6.2) by the user agent.

Each receipt is pushed as the response to a synthesized GET request sent in a PUSH_PROMISE. This GET request is made to the same push message resource that was created by the push service when the application server requested message delivery. The response includes a status code indicating the result of the message delivery and carries no data.

The following example request is made over HTTP/2.

HEADERS      [stream 13] +END_STREAM +END_HEADERS
  :method        = GET
  :path          = /receipt-subscription/3ZtI4YVNBnUUZhuoChl6omUvG4ZM
  :authority     = push.example.net

The push service permits the request to remain outstanding. When the user agent acknowledges the message, the push service pushes a delivery receipt to the application server. A 204 (No Content) status code confirms that the message was delivered and acknowledged.

PUSH_PROMISE [stream 13; promised stream 82] +END_HEADERS
  :method        = GET
  :path          = /message/qDIYHNcfAIPP_5ITvURr-d6BGt
  :authority     = push.example.net

HEADERS      [stream 82] +END_STREAM
                        +END_HEADERS
  :status        = 204
  date           = Thu, 11 Dec 2014 23:56:56 GMT

If the user agent fails to acknowledge the receipt of the push message and the push service ceases to retry delivery of the message prior to its advertised expiration, then the push service MUST push a failure response with a status code of 410 (Gone).