Draft: draft-thomson-webpush-protocol

Commentary: This is the initial iteration on the changes to the receipt design that were discussed today . I 'm not made changes related to conditional DELETE . Those should be incorporated into the collapsing design if pursued ? The number of resources is beginning to make the section of capability URL a bit unwieldy . Definitely in need of an edit to streamline and simplify . This 
 This is likely straightforward , but it will require different amounts of machinery depending on the outcome of . Application servers need to be told when their messages arrived . The basic mechanism as described has the user agent send a conditional DELETE to the resource generated by each push message . Tagging each message with an ETag would allow this to work without requiring too much extra state on the server ( in essence , the ETag could carry that state ) . The application server would get something like a push notification ( hanging get , etc ... ) to inform it of delivery . If we choose to disaggregate with , we should disaggregate here too . Otherwise , we can just require that the application server register . The disaggregation option has a small race condition that we would have to resolve if we were interested in efficiency for receipts , where the delivery receipt arrives at the resource while the hanging get from the application server has n't yet made it to the server . That could force the delivery receipts to be buffered in the same way that push messages are , which is definitely suboptimal . In my opinion , we should treat all receipts as messages with TTL=0 . The aggregated solution might benefit from additional information being surfaced in the subscription , or maybe an application server could learn where to register for receipts when it pushes a message . The former increases the surface area of the API , the latter potentially adds some latency . We could also resurrect 200/202 for direct delivery in addition to either of these options . Note that the reasons for dropping 202 were largely driven by privacy needs that are n't valid in this context , so returning it should be OK . 
 This was addressed in . 
 I need to click the right link ; this is clearly NOT resolved . 
 The associated pull request should also update Implications for Application Reliability .
Paragraph (version A):
A message, sent from an application server to a user agent via a
push service.
Paragraph (version A):
A message delivery context that is established between the user
agent and the push service and shared with applications.  All push
messages are associated with a subscription.
Paragraph (version B):
A message sent from an application server to a user agent via a
push service.
Paragraph (version B):
A message delivery context that is established between the user
agent and the push service and shared with the application server.
All push messages are associated with a message subscription.
Paragraph (version B):
A message delivery confirmation sent from the push server to the
application server.
Paragraph (version A):
At the very beginning of the process, a new subscription is created
by the user agent and then distributed to its application server.
The subscription is the basis of all future interactions between the
actors.
Paragraph (version B):
At the very beginning of the process, a new message subscription is
created by the user agent and then distributed to its application
server.  This subscription is the basis of all future interactions
between the actors.
Paragraph (version A):
This resource is used in subscribe.  It is configured into user
agents.
Paragraph (version A):
A link relation of type "urn:ietf:params:push:subscription" refers
to a resource with read and delete access to a subscription.  A
user agent monitor using this resource.
Paragraph (version A):
A link relation of type "urn:ietf:params:push" refers to a
resource with write access to a subscription.  An application
server send using this resource.
Paragraph (version A):
A user agent sends a POST request to its configured push service
resource to create a new subscription.  If successful, the push
service MUST return new "subscription" and "push" resources in
response to this request.  URIs for these resources are included in
Link header fields in the response.
Paragraph (version B):
This resource is used to subscribe message_subscription.  It is
configured into user agents.
Paragraph (version B):
A link relation of type
"urn:ietf:params:push:message:subscription" refers to a resource
with read and delete access to a message subscription.  A user
agent monitor using this resource.
Paragraph (version B):
A link relation of type "urn:ietf:params:push:message" refers to a
resource with write access to a message subscription.  An
application server send using this resource.
Paragraph (version B):
A link relation of type "urn:ietf:params:push:receipt:subscribe"
refers to a resource used to subscribe for receipt_subscription.
An application server creates a receipt subscription using this
resource.
Paragraph (version B):
A link relation of type
"urn:ietf:params:push:receipt:subscription" refers to a resource
with read access to a receipt subscription.  An application server
request_receipt for push messages using this resource.
Paragraph (version B):
A user agent sends a POST request to its configured push service
resource to create a new subscription.  If successful, the push
service MUST return new "subscription", "push", and "receipt
subscribe" resources in response to this request.  URIs for these
resources are included in Link header fields in the response.
Paragraph (version B):
The user agent should securely distribute both the "push" and
"receipt subscribe" resources to its application server.  Details are
outside the scope of this document.
Paragraph (version B):
An application server creates a new subscription for push message
receipts by sending a HTTP POST request to the "receipt subscribe"
resource distributed by its user agent.  If successful, the push
service MUST return a new "receipt" resource in response to this
request.  The URI for this resource is included in a Link header
field in the response.
Paragraph (version B):
A response with a 201 (Created) status code includes a URI for the
"receipt" resource in the Location header field.
Paragraph (version B):
An application server can use the Push-Receipt header field to
request a confirmation from the push server when a push message is
delivered and acknowledged by the user agent.  The Push-Receipt
header field is a URI-Reference as defined in Section 2.7 of RFC7230.
Its value is the "receipt" URI returned from the push server in
response to the receipt subscription request (receipt_subscription)
from the application server.
Paragraph (version A):
Each push message is pushed in response to a synthesized GET request.
The GET request is made to the same "push" resource that is used by
the application server to send the message.  The response body is the
entity body from the most recent request sent to the "push" resource.
Paragraph (version B):
Each push message is pushed in response to a synthesized GET request.
The GET request is made to the same "push message" resource that was
created by the push server when the application server requested
message delivery.  The response body is the entity body from the most
recent request sent to the "push" resource.
Paragraph (version B):
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 a HTTP DELETE on the push message resource.
Paragraph (version B):
If the application has requested a delivery receipt, the push server
MUST deliver a response to the application server monitoring the
"receipt" resource.
Paragraph (version B):
The application server requests the delivery of receipts from the
push server by making a HTTP GET request to the "receipt" resource.
The push service does not respond to this request, it instead uses I-
D.ietf-httpbis-http2 to send push receipts when messages are
acknowledged (acknowledge_message) by the user agent.
Paragraph (version B):
Each receipt is pushed in response to a synthesized GET request.  The
GET request is made to the same "push message" resource that was
created by the push server when the application server requested
message delivery.  A successful response includes a 410 (GONE) status
code with no data.
Paragraph (version A):
An application developer might find it tempting to create alternative
mechanisms for message delivery in case the push service fails to
deliver a critical message.  Setting up a polling mechanism or a
backup messaging channel in order to compensate for these
shortcomings negates almost all of the advantages a push service
provides.
Paragraph (version A):
Applications are encouraged to instead provide a means to detect
situations where push messages were not delivered and recover
gracefully.  For instance, an application server might include a
sequence number in push messages; a gap in the sequence can then be
used to trigger some form of state resynchronization.  For instance,
the missing messages might be requested from the application server
directly.  Push service failures are expected to be rare, therefore
performance optimization of any recovery mechanism might be
unnecessary.
Paragraph (version B):
A push server that does not support reliable delivery over
intermittent network connections or failing applications on devices,
forces the device to acknowledge receipt directly to the application
server, incurring additional power drain in order to establish
(usually secure) connections to the individual application servers.
Paragraph (version B):
While reliability is not required for messages that expire in few
seconds (e.g. an incoming call) or collapsible ones (e.g. the current
number of unread emails), it is more important when messages contain
information that is longer lasting, e.g. a command to update a
configuration value, or the acknowledgement of a financial
transaction or workflow step.  In particular, in the case of power-
constrained devices, it is preferable to transmit the actual
information in the "pushed" message reliably, instead of forcing them
to reconnect periodically to get the current state.
Paragraph (version B):
The availability of push message delivery receipts in the protocol
ensures that the application developer is not tempted to create
alternative mechanisms for message delivery in case the push service
fails to deliver a critical message.  Setting up a polling mechanism
or a backup messaging channel in order to compensate for these
shortcomings negates almost all of the advantages a push service
provides.
Paragraph (version B):
The URIs provided for "push" resources MUST NOT provide any basis to
correlate communications for a given user agent.  It MUST NOT be
possible to correlate any two "push" URIs based solely on their
contents.  This allows a user agent to control correlation across
different applications, or over time.
Paragraph (version B):
Similarly, the URIs provided by the push service to identify a push
message MUST NOT provide any information that allows for correlation
across subscriptions.  Push message URIs for the same subscription
MAY contain information that would allow correlation with the
associated subscription or other push messages for that subscription.
Paragraph (version B):
User and device information MUST NOT be exposed through a "push" or
push message URI.
Paragraph (version B):
In addition, "push" URIs established by the same user agent or push
message URIs for the same subscription MUST NOT include any
information that allows them to be correlated with the user agent.
Paragraph (version B):
Authorization is managed using "subscription", "push", "receipt", and
"receipt subcribe" capability URLs (see CAP-URI).  A capability URL
grants access to a resource based solely on knowledge of the URL.
Paragraph (version B):
Capability URLs are used for their "easy onward sharing" and "easy
client API" properties.  These make it possible to avoid relying on
relationships between push services and application servers, with the
protocols necessary to build and support those relationships.
Paragraph (version B):
A "subscription", "push", "receipt", "receipt subcribe", or push
message URI acts as a bearer token.  Knowledge of a "subscription"
URI implies authorization to either receive push messages or delete
the subscription.  Knowledge of a "push" URI implies authorization to
send push messages.  Knowledge of a "receipt" URI implies
authorization to receive push receipts.  Knowledge of a "receipt
subscribe" URI implies authorization to create subscriptions for
receipts.  Knowledge of a push message URI allows for reading and
acknowledging that specific message.
Paragraph (version B):
Encoding a large amount of random entropy (at least 120 bits) in the
path component ensures that it is difficult to successfully guess a
valid capability URL.
Paragraph (version B):
Server request logs can reveal subscription-related URIs.  Acquiring
a "subscription" URI enables the receipt of messages or deletion of
the subscription.  Acquiring a "push" URI permits the sending of push
messages.  Logging could also reveal relationships between different
subscription-related URIs for the same user agent.  Encrypted message
contents are not revealed to the push service.
Paragraph (version A):
This document registers three URNs for use in identifying link
relation types.  These are added to a new "Web Push Identifiers"
registry according to the procedures in Section 4 of RFC3553; the
corresponding "push" sub-namespace is entered in the "IETF URN Sub-
namespace for Registered Protocol Parameter Identifiers" registry.
Paragraph (version B):
This document registers URNs for use in identifying link relation
types.  These are added to a new "Web Push Identifiers" registry
according to the procedures in Section 4 of RFC3553; the
corresponding "push" sub-namespace is entered in the "IETF URN Sub-
namespace for Registered Protocol Parameter Identifiers" registry.
Paragraph (version A):
Two values are entered as the initial content of the "Web Push
Identifiers" registry.
Paragraph (version B):
These values are entered as the initial content of the "Web Push
Identifiers" registry.
Paragraph (version A):
This link relation type is used to identify a resource for
receiving push messages and deleting a subscription.
Paragraph (version B):
This link relation type is used to identify a resource for
subscribing to push messages.
Paragraph (version B):
This link relation type is used to identify a resource for
subscribing for delivery confirmations for push messages.
Paragraph (version B):
This link relation type is used to identify a resource for
creating new push message receipt subscriptions.