Web Push Server

This is a Node Web Push server implementation.

Getting Started

The server is distributed as an npm module. You'll need Node >= 0.10.32 and npm installed on your machine; instructions and screencasts are available here. To install the server, run:

$ npm install -g webpush-server

This installs a webpush-server executable that can be used to start the server. webpush-server requires the following flags:

• --port (Number): The port on which to listen (e.g., 8080).
• --key (String): The path to a PEM-encoded TLS certificate.
• --cert (String): The private key for the given certificate.
• --pfx (String): The combined certificate, private key, and CA certs in PFX format. Mutually exclusive with --key and --cert.

Example usage:

$ webpush-server --port 8080 --key keys/key.pem --cert keys/cert.pem

The Node HTTP/2 library does not currently implement the Upgrade mechanism for HTTP/2, so TLS keys must be provided.

API

POST /devices

This is the push service resource specified by draft-02, or the push server URL from draft-01. A client registers itself with the server by requesting this resource. The server allocates "registration" (urn:ietf:params:push:reg) and "subscribe" (urn:ietf:params:push:sub) resources, and includes them in the response as link relations.

The "registration" and "subscribe" resources were called "monitor" (...:push:monitor) and "channel" (...:push:channel), respectively, in draft-01.

GET /devices/{regId}

This is the registration resource specified by draft-02, or the monitor resource from draft-01. A client requests this resource to receive push messages. Messages sent by the application server are serialized as HTTP/2 PUSH_PROMISE frames for GET requests to the associated "subscription" resource.

POST /devices/{regId}/channels

This is the subscribe resource specified by draft-02, or the channel resource from draft-01. A registered client creates a new subscription by requesting this resource. The server allocates a "subscription" (urn:ietf:params:push) resource, and includes it in the response as a link relation. The Location header contains the channel URI for the application server.

Note that draft-02 subsumes the subscription and channel URIs under the "subscription" resource, while this implementation provides a separate channel URI. In draft-02, the URIs included in the Link: <...>; rel="urn:ietf:params:push" and Location headers are equivalent.

GET /devices/{regId}/channels/{subId}

This is the subscription resource specified by draft-02. A client can fetch the last message sent by an application server for a subscription by requesting this resource. If the server does not store messages, a 204 (No Content) response is returned.

This implementation does not currently store messages; incoming messages will be dropped if the client is not holding open a request to the registration resource.

DELETE /devices/{regId}/channels/{subId}

This deletes an active subscription. Since messages are not currently stored, requesting this resource is a no-op.

PUT /updates/{key}

This is the resource allocated by the subscribe resource for the application server. The registration and subscription information is encoded into the opaque key to prevent application servers from correlating subscriptions for a client.

License

MPL 2.0.