Documentation
¶
Overview ¶
Package webpush is the built-in Web Push provider: the standard protocol every browser's push service speaks (RFC 8030), the payload encrypted to the subscription (RFC 8291) and the sender identified by its VAPID key (RFC 8292). No vendor account: a channel is a VAPID key pair and a contact; the subscription a browser hands out names its push service.
Index ¶
Constants ¶
const ( // MaxPayloadBytes is what one 4096-byte aes128gcm record holds: the // header (86), the tag (16) and the padding delimiter (1) take the rest. MaxPayloadBytes = int(wp.MaxRecordSize) - 86 - 16 - 1 // MaxTTLSeconds: push services keep a message four weeks at most. MaxTTLSeconds = 28 * 24 * 3600 // DefaultTTLSeconds is how long a message waits for an offline browser // when it names no ttl. DefaultTTLSeconds = 24 * 3600 )
Limits of the protocol.
Variables ¶
var ( ErrConfig = errors.New("webpush: invalid channel") ErrSubscription = errors.New("webpush: invalid subscription") ErrEndpoint = errors.New("webpush: endpoint is not a push service this channel allows") ErrPayload = errors.New("webpush: payload is required") ErrTooBig = errors.New("webpush: payload exceeds 3993 bytes") ErrTTL = errors.New("webpush: ttl_seconds is 0 to 2419200 (28 days)") ErrUrgency = errors.New("webpush: urgency is very-low, low, normal or high") ErrTopic = errors.New("webpush: topic is up to 32 characters of A-Z a-z 0-9 - _") )
Errors of the configuration and of Validate; every one is final.
var DefaultHosts = []string{
"fcm.googleapis.com", "*.googleapis.com", "updates.push.services.mozilla.com", "*.push.services.mozilla.com",
"*.push.apple.com", "*.notify.windows.com",
}
DefaultHosts are the push services of the browsers: Chrome and Edge (Google), Firefox (Mozilla), Safari (Apple), legacy Edge (Windows).
Functions ¶
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client of one channel.
func New ¶
New is the client of cfg (validated); client nil: the default, which follows no redirect (an endpoint must not bounce courier elsewhere).
type Config ¶
type Config struct {
// Subject: a mailto: address or an https URL push services can reach
// the sender at.
Subject string `json:"subject" schemapb:"description=mailto: address or https URL of the sender"`
// PublicKey: the VAPID public key, base64url of the uncompressed P-256
// point; browsers subscribe with it (applicationServerKey).
PublicKey string `json:"public_key" schemapb:"description=VAPID public key (base64url) browsers subscribe with"`
// PrivateKey: the VAPID private key, base64url of the P-256 scalar.
PrivateKey config.Secret `json:"private_key" schemapb:"secret=true;description=VAPID private key (base64url)"`
// Hosts the endpoints may point at: exact names or *.suffix; empty:
// DefaultHosts. Subscriptions come from browsers, so an endpoint is
// untrusted input: courier posts only to push services listed here,
// over https.
Hosts []string `json:"hosts,omitempty" schemapb:"description=Allowed push service hosts, else the browsers own"`
}
Config of a Web Push channel.
type Keys ¶
type Keys struct {
P256dh string `json:"p256dh" schemapb:"description=The browser's P-256 public key (base64url)"`
Auth string `json:"auth" schemapb:"description=The authentication secret (base64url)"`
}
Keys of a subscription.
type Message ¶
type Message struct {
Channel string `json:"channel,omitempty" schemapb:"description=Web Push channel of the installation, else the default"`
Subscription Subscription `json:"subscription"`
// Payload is what the service worker's push event gets as
// event.data.json(): any JSON — the app's own shape, or the
// declarative {"web_push": 8030, "notification": {...}} Safari shows
// without a service worker.
Payload json.RawMessage `json:"payload" schemapb:"description=JSON the service worker gets as event.data.json()"`
TTLSeconds *int64 `json:"ttl_seconds,omitempty" schemapb:"description=Seconds kept for an offline browser, else 86400"`
Urgency string `json:"urgency,omitempty" schemapb:"description=very-low, low, normal or high"`
Topic string `json:"topic,omitempty" schemapb:"description=A newer undelivered one replaces it"`
}
Message is one Web Push to one subscription.
type Subscription ¶
type Subscription struct {
Endpoint string `json:"endpoint" schemapb:"description=The push service URL of the subscription"`
Keys Keys `json:"keys"`
}
Subscription is what PushManager.subscribe() gives the browser, as its toJSON() writes it.