webpush

package
v0.0.27 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 20 Imported by: 0

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

View Source
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.

View Source
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

View Source
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.

View Source
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

func Allowed

func Allowed(host string, hosts []string) bool

Allowed reports whether host matches hosts (empty: DefaultHosts): an exact name or *.suffix; never an IP address.

func GenerateKeys

func GenerateKeys() (string, string, error)

GenerateKeys is a fresh VAPID pair.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client of one channel.

func New

func New(cfg Config, client *http.Client) *Client

New is the client of cfg (validated); client nil: the default, which follows no redirect (an endpoint must not bounce courier elsewhere) and dials only public addresses, directly (netguard.ErrForbiddenAddress).

func (*Client) Check

func (c *Client) Check(context.Context) error

Check verifies the key pair; no push service has a call to try.

func (*Client) Hosts

func (c *Client) Hosts() []string

Hosts the channel's endpoints may name.

func (*Client) PublicKey

func (c *Client) PublicKey() string

PublicKey of the channel: browsers subscribe with it.

func (*Client) Send

func (c *Client) Send(ctx context.Context, m Message) (string, error)

Send encrypts and posts m (validated) and returns the message's id — the push service's Location — or a *provider.Error: final for a gone or refused subscription, later for a rate limit.

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.

func (Config) Validate

func (c Config) Validate() error

Validate checks the key pair and the subject.

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.

func (Message) TTL

func (m Message) TTL() int

TTL of the message.

func (Message) Target

func (m Message) Target() string

Target is the subscription as audited: its push service and a hash, never the endpoint, which identifies a browser.

func (Message) Validate

func (m Message) Validate(hosts []string) error

Validate checks what a push service would refuse, and the endpoint against hosts (empty: DefaultHosts).

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL