title: "Web Push Extension" layout: spec copyrights:
This is an experimental specification for a vendored extension.
No guarantees are made regarding the stability of this extension. Backwards-incompatible changes can be made at any time without prior notice.
Software implementing this work-in-progress specification MUST NOT use the unprefixed
webpush CAP name. Instead, implementations SHOULD use the
soju.im/webpush CAP name to be interoperable with other software implementing a compatible work-in-progress version.
Historically, IRC clients have relied on keeping a TCP connection alive to receive notifications about new events. However, this design has limitations:
To address these limitations, various push notification mechanisms have been designed. This specification standardizes an extension for Web Push.
┌────────────┐ ┌────────────┐ │ │ Subscribe │ │ │ ├─────────────►│ │ │ IRC client │ │ IRC server │ │ │ │ │ │ │ │ │ └────────────┘ └─────┬──────┘ ▲ │ │ │ Push │ │Push notification │ │notification │ ┌──────────┐ │ │ │ │ │ └───────┤ Web Push │◄──────┘ │ Server │ │ │ └──────────┘
Although Web Push has been designed for the Web, it can be used on other platforms as well. Web Push provides a vendor-neutral standard to send push notifications.
soju.im/webpush capability allows clients to subscribe to Web Push and receive notifications for messages of interest.
Once a client has subscribed, the server will send push notifications for a server-defined subset of IRC messages. Each push notification MUST contain exactly one IRC message as the payload, without the final CRLF.
The messages follow the same capabilities and the same
RPL_ISUPPORT as when the client registered for Web Push notifications.
Because of size limits on the payload of push notifications, servers MAY drop some or all message tags from the original message. Servers MUST NOT drop the
msgid tag if present.
If the server supports Voluntary Application Server Identification (VAPID) and the client has enabled the
soju.im/webpush capability, the server MUST advertise its public key in the
VAPID ISUPPORT token. This key can be used to verify notifications upon reception by the Web Push server.
The value MUST be the URL-safe base64-encoded public key usable with the Elliptic Curve Digital Signature Algorithm (ECDSA) over the P-256 curve. The value MUST NOT change over the lifetime of the connection to avoid race conditions.
WEBPUSH command is introduced. It has a case-insensitive subcommand:
WEBPUSH <subcommand> <params...>
REGISTER subcommand creates a new Web Push subscription.
WEBPUSH REGISTER <endpoint> <keys>
<endpoint> is an URL pointing to a push server, which can be used to send push messages for this particular subscription.
<keys> is a string encoded in the message-tag format. The values are URL-safe base64-encoded. For the
aes128gcm encryption algorithm, it MUST contain at least:
p256dhset to the client's P-256 ECDH public key.
authset to a 16-byte client-generated authentication secret.
If the server has advertised the
VAPID ISUPPORT token, they MUST use this VAPID public key when sending push notifications. Servers MUST replace any previous subscription with the same
If the registration is successful, the server MUST reply with a
WEBPUSH REGISTER message:
WEBPUSH REGISTER <endpoint>
On error, the server MUST reply with a
Servers MAY expire a subscription at any time.
UNREGISTER subcommand removes an existing Web Push subscription.
WEBPUSH UNREGISTER <endpoint>
Servers MUST silently ignore
UNREGISTER commands for non-existing subscriptions.
If the unregistration is successful, the server MUST echo back the
WEBPUSH UNREGISTER message. On error, the server MUST reply with a
Errors are returned using the standard replies syntax.
If the server receives a syntactically invalid
WEBPUSH command, e.g., an unknown subcommand, missing parameters, excess parameters, or parameters that cannot be parsed, the
INVALID_PARAMS error code SHOULD be returned:
FAIL WEBPUSH INVALID_PARAMS <command> <endpoint> <message>
If the server cannot fullfill a client command due to an internal error, the
INTERNAL_ERROR error code SHOULD be returned:
FAIL WEBPUSH INTERNAL_ERROR <command> <endpoint> <message>