| Network Working Group | D. Turner |
| Internet-Draft | J. Conlin |
| Intended status: Standards Track | N. Marathe |
| Expires: November 15, 2014 | Mozilla |
| May 14, 2014 |
WebPush Protocol
draft-turner-push-proto-latest
This page describes the protocol used for communication by the WebPushServer and the UserAgent.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 15, 2014.
Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English.
WebPush is a simple notification and small data delievery system designed to be easy to implement, scalable, and robust. The WebPush protocol enables application servers to delivery guarantees, minimal server state, and client driven recovery. It is a signaling and data carrying system.
[todo] integrate auth
AppServer : The third-party server or application which will generate a Push Event by accessing the Endpoint.
[todo] Complete description of Application below
Application : A program which requires access to push notifications. The UserAgent acts on
Channel : The flow of information from AppServer through WebPushServer to UserAgent.
ChannelID : Unique identifier for a Channel. Generated by UserAgent for a particular application. Opaque identifier for both UserAgent and WebPushServer. This MUST NOT be exposed to an application.
Endpoint : A REST-ful HTTPS URL uniquely associated to a channel. Requests to this URL should update the WebPushServer state for the channel. MUST be exposed to third-party applications.
UAID : A globally unique UserAgent ID. Used by the WebPushServer to associate channelIDs with a client. Stored by the UserAgent, but opaque to it.
UserAgent : A device or program that implements the client side of the WebPush Protocol.
Version : Monotonically increasing 64-bit integer describing the application state. This holds meaning as a primary key or similar only to the AppServer. The WebPushServer and UserAgent and App should use this only for detecting changes. MUST be exposed to applications.
WebPushServer : A publicly accessible server that implements the server side of the WebPush Protocol and exposes an HTTPS API for AppServer’s to notify it.
The WebPush protocol defines how UserAgents and WebPushServers communicate to ensure reliable delivery of the latest version of a channel from the WebPushServer to the UserAgent.
The WebPush communication channel is WebSockets, and the wire protocol is JSON, with messages defined below. The WebSocket specific HTTP header Sec-WebSocket-Protocol MUST be set to push-notification by the UserAgent. The WebPushServer SHOULD reject the connection if the header is not set.
All messages MUST use TLS (wss:// protocol for WebSockets). In addition, Endpoints generated by WebPushServer’s MUST use HTTPS URLs.
All messages are encoded as JSON. All messages MUST have the following fields:
After the WebSocket is established, including whatever optional WebPushServer authentication is required, the UserAgent begins communication by sending a hello message. The hello message contains the UAID of the UserAgent has one or returned by the server from an earlier handshake. The UserAgent may also transmit the channelIDs it knows so the server may synchronize its state.
The server MAY respect this UAID, but it is at liberty to ask the UserAgent to change its UAID in the response.
If the UserAgent receives a new UAID in the hello response, it MUST delete all existing channelIDs and their associated versions. It MAY then wake up all registered applications immediately or at a later date by sending them a push-register message.
The handshake is considered ‘‘complete’’, once the UserAgent has received a reply.
An UserAgent MUST transmit a hello message only once on its WebSocket. If the handshake is not completed in the first try, it MUST disconnect the WebSocket and begin a new connection.
NOTE: Applications may request registrations or unregistrations from the UserAgent, before or when the handshake is in progress. The UserAgent MAY buffer these or report errors to the application. But it MUST NOT send these requests to the WebPushServer until the handshake is completed.
Extra fields: The UserAgent MAY pass any extra JSON data to the WebPushServer. For example, this data may include information required to wake up the UserAgent using out-of-band, proprietary methods, or contain the last time the UserAgent successfully connected. Fields prefixed by “wp-“ are reserved for future WebPush use. The WebPushServer MAY ignore this data.
{
"messageType": "hello",
"uaid": "fd52438f-1c49-41e0-a2e4-98e49833cc9c",
"channelIDs": ["431b4391-c78f-429a-a134-f890b5adc0bb",
"a7695fa0-9623-4890-9c08-cce0231e4b36"],
"lastAccess": 1399049780
}
WebPushServers MUST only respond to a hello once. UserAgents MUST ignore multiple hello replies.
Extra fields: The WebPushServer MAY pass any extra JSON data back to the UserAgent. Fields prefixed by “wp-“ are reserved for future WebPush use. The UserAgent MAY ignore this data.
[todo] what kind of restrictions do we want to put on the redirect
{
"messageType": "hello",
"status": 200,
"uaid": "fd52438f-1c49-41e0-a2e4-98e49833cc9c",
"connected": 1399049780
}
The Register message is used by the UserAgent to request that the WebPushServer notify it when a channel changes. Since channelIDs are associated with only one UAID, this effectively creates the channel, while unregister destroys the channel.
The channelID is chosen by the UserAgent because it also acts like a nonce for the Register message itself. Because of this WebPushServers MAY respond out of order to multiple register messages or messages may be lost without compromising correctness of the protocol.
The request is considered successful only after a response is received with a status code of 200.
On success the UserAgent MUST:
NOTE: The register call is made by the UserAgent on behalf of an application. The UserAgent SHOULD have reasonable timeouts in place so that the application is not kept waiting for too long if the server does not respond or the UserAgent has to retry the connection.
#### Example
{
"messageType": "register",
"channelID": "d9b74644-4f97-46aa-b8fa-9393985cd6cd"
}
{
"messageType": "register",
"channelID": "d9b74644-4f97-46aa-b8fa-9393985cd6cd",
"status": 200,
"pushEndpoint": "http://pushserver.example.org/d9b74644"
}
Unregistration is an optional procedure.
The unregister is required only between the App and the UserAgent, so that the UserAgent stops notifying the App when the App is no longer interested in a pushEndpoint.
The unregister is also useful to the AppServer, because it should stop sending notifications to an endpoint the App is no longer monitoring. Even then, it is really an optimization so that the AppServer need not have some sort of automatic deletion mechanism to clean up endpoints at later intervals of time.
Well-behaved AppServers will stop notifying it of unregistered endpoints automatically. Well behaved UserAgents won’t notify their apps of unregistered updates either. So the WebPushServer can continue to process notifications and pass them on to UserAgents, when it has not been told about the unregistration.
When an App calls unregister(endpoint) it is RECOMMENDED that the UserAgent follow these steps:
{
"messageType": "unregister",
"channelID": "d9b74644-4f97-46aa-b8fa-9393985cd6cd"
}
{
"messageType": "unregister",
"channelID": "d9b74644-4f97-46aa-b8fa-9393985cd6cd",
"status": 200
}
The connection to the WebPush Server may be lost due to network issues. When the UserAgent detects loss of network, it should reconnect. There are situations in which the TCP connection dies without either end discovering it immediately. The UserAgent should send a ping approximately every 30 minutes and expect a reply from the server in a reasonable time (The Mozilla UserAgent uses 10 seconds). If no data is received, the connection should be presumed closed and a new connection started.
The UserAgent should consider normal communications as an indication that the socket is working properly. It SHOULD send the ping packet only if no activity has occurred in the past 30 minutes.
An empty JSON object (The 2-character string {}) is sent. This object requires no alternative processing on the server, keeping transmission size small.
The WebPushServer may reply with any data. The UserAgent is only concerned about the state of the connection. It is RECOMMENDED that the WebPushServer either deliver pending notifications or an empty JSON object ({}).
[todo] the push protocol needs to support data. We also need to talk about the lifetime of this data.
The AppServer MUST make a HTTP PUT request to the Endpoint received from the App.
If no request body is present, the server MAY presume the version to be the current server UTC.
If the request body is present, the Content-Type MUST be application/x-www-form-urlencoded and the request body MUST contain the string “version=N”.
Authentication is optional and left to the WebPushServer provider.
curl -X PUT -H "Content-Type: application/x-www-form-urlencoded" -d "version=123" "https://push.example.com/endpoint/123abcd"
The HTTP response status code indicates if the request was successful.
Additional status codes may be returned based on requirements of the WebPushServer provider. Please refer to the provider documentation.
The HTTP response body SHOULD be empty.
Notifications are acknowledged by the UserAgent. WebPushServers should retry unacknowledged notifications every 60 seconds. If the version of an unacknowledged notification is updated, the WebPushServer MAY queue up a new notification for this channelID and the new version, and remove the old notification from the pending queue.
The Notification message may contain additional data specific to the WebPushServer provider. This data may be safely ignored by the UserAgent. Please refer to the WebPushServer provider documentation for details regarding this data. Please note that fields prefixed by “wp-“ are considered reserved for future use by WebPush.
{
"messageType": "notification",
"updates": [
{ "channelID": "431b4391-c78f-429a-a134-f890b5adc0bb",
"version": 23,
"data": "" },
{ "channelID": "a7695fa0-9623-4890-9c08-cce0231e4b36",
"version": 42,
"data": "Make the Internet work better" } ]
}
It is RECOMMENDED that the UserAgent try to batch all pending acknowledgments into fewer messages. ACK messages do not require a response from the WebPushServer.
[TODO] – ack does not require DATA response!
{
"messageType": "ack",
"updates": [
{ "channelID": "431b4391-c78f-429a-a134-f890b5adc0bb",
"version": 23 },
{ "channelID": "a7695fa0-9623-4890-9c08-cce0231e4b36",
"version": 42 } ]
}
At any time, if the WebPushServer reaches an inconsistent condition, due to database failure, network failure, or any other reason, it MAY drop all state. It MUST then disconnect all active clients, forcing them to reconnect and begin a handshake to get synchronized.
The Data Retention policy of the WebPushServer is determined by the provider of the service. It is RECOMMENDED that when data for a given UAID is expired without access, the UAID is marked as invalid, resulting in the UserAgent re-registering channels.
In environments or devices where maintaining an always alive WebSocket is difficult, UserAgents and WebPushServers MAY implement alternative means to notify UserAgents about updates. This out of band notification SHOULD be restricted to request the UserAgent to establish the WebSocket. WebPush state SHOULD NOT be transmitted out of band, since reliable delivery may not be guaranteed.
[TODO]
[TODO]
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |