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.
const Bucket = "courier_webpush"
Bucket keeps the minted VAPID pairs, one key per channel. It holds private keys: only courier's NATS identity may use $KV.courier_webpush.>.
const CodeForbidden = "forbidden_destination"
CodeForbidden is the refusal's code for an endpoint courier does not post to: not https, a host the channel does not allow, or an internal address.
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) and, unless the channel is insecure, dials only public addresses, directly (netguard.ErrForbiddenAddress). pair is the channel's keys: deps.Static of Configured, or the minted pair.
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). Empty with
// private_key: courier mints the pair once and keeps it (README).
// Changing a pair makes every browser subscribe again.
PublicKey string `json:"public_key,omitempty" schemapb:"description=VAPID public key (base64url), empty: minted"`
// PrivateKey: the VAPID private key, base64url of the P-256 scalar.
PrivateKey config.Secret `json:"private_key,omitempty" schemapb:"secret=true;description=VAPID private key"`
// 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"`
// Insecure lets the channel post over http, to internal addresses and,
// without hosts, to any host: a push service in the installation's own
// network (a test stand), or development.
Insecure bool `json:"insecure,omitempty" schemapb:"description=Allow http, internal addresses and any host"`
}
Config of a Web Push channel.
func (Config) Configured ¶ added in v0.0.38
Configured is the pair the configuration gives, if it gives one.
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 Store ¶ added in v0.0.38
type Store struct {
// contains filtered or unexported fields
}
Store mints a channel's pair once into Bucket and keeps it there: a subscription is bound to the public key, so the pair never rotates.
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.