push

Documentation

Overview

Package push sends Web Push notifications to browsers using the Web Push protocol (RFC 8291, RFC 8292). It handles VAPID JWT signing and payload encryption so the caller only needs a Sender and a subscription.

Use GenerateVAPIDKeys once during initial setup to create a key pair. Create a Sender with NewSender and pass it to [tether.PushConfig]. When a subscription arrives, call Sender.Send to deliver notifications.

Index

• Variables
• func GenerateVAPIDKeys() (publicKey, privateKey string, err error)
• type Config
• type Notification
• type NotificationAction
• type Sender
  • func NewSender(cfg Config) *Sender
  • func (s *Sender) PublicKey() string
  • func (s *Sender) Send(sub Subscription, n Notification) error
• type Subscription
  • func (s Subscription) Validate() error
• type SubscriptionKeys

Variables

var ErrSubscriptionExpired = errors.New("push: subscription expired (410 Gone)")

ErrSubscriptionExpired is returned by [Send] when the push service responds with HTTP 410 Gone, indicating the subscription is no longer valid and should be removed from storage.

Functions

func GenerateVAPIDKeys

func GenerateVAPIDKeys() (publicKey, privateKey string, err error)

GenerateVAPIDKeys generates a new ECDSA P-256 key pair for VAPID authentication. Returns base64url-encoded public and private keys. Call this once during initial setup and store the keys securely.

Types

type Config

type Config struct {
	// VAPIDPublicKey is the base64url-encoded ECDSA P-256 public key.
	VAPIDPublicKey string

	// VAPIDPrivateKey is the base64url-encoded ECDSA P-256 private key.
	VAPIDPrivateKey string

	// Subject identifies the application server. Must be a mailto: or
	// https: URI (e.g. "mailto:admin@example.com").
	Subject string

	// HTTPClient is the HTTP client used to send push requests. When
	// nil, http.DefaultClient is used.
	HTTPClient *http.Client
}

Config holds application-level VAPID credentials for push delivery. Create a Sender from a Config to send notifications.

type Notification

type Notification struct {
	Title    string               `json:"title"`
	Body     string               `json:"body,omitempty"`
	Icon     string               `json:"icon,omitempty"`
	Badge    string               `json:"badge,omitempty"`
	URL      string               `json:"url,omitempty"`
	Tag      string               `json:"tag,omitempty"`      // Groups related notifications; replaces previous with same tag.
	Renotify bool                 `json:"renotify,omitempty"` // Re-alert (vibration/sound) when replacing a tagged notification.
	Silent   bool                 `json:"silent,omitempty"`   // Suppress vibration and sound.
	Actions  []NotificationAction `json:"actions,omitempty"`  // Up to two action buttons shown on the notification.
}

Notification is the payload sent to the service worker's push event. The fields map to the Notification API options that the service worker passes to showNotification().

type NotificationAction

type NotificationAction struct {
	Action string `json:"action"`         // Identifier sent in the notificationclick event.
	Title  string `json:"title"`          // Button label.
	Icon   string `json:"icon,omitempty"` // Optional button icon URL.
	URL    string `json:"url,omitempty"`  // URL to open when this action is clicked.
}

NotificationAction is a button displayed on a push notification. Browsers typically show at most two actions. Each action can navigate to its own URL when clicked; if URL is empty, the notification's top-level URL is used.

type Sender

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

Sender delivers Web Push notifications using pre-configured VAPID credentials. Create one at startup with NewSender and reuse it for all push calls.

func NewSender

func NewSender(cfg Config) *Sender

NewSender creates a Sender from the given configuration.

func (*Sender) PublicKey

func (s *Sender) PublicKey() string

PublicKey returns the VAPID public key for client-side push subscription. Pass this to [tether.PushConfig] so the browser can subscribe to notifications.

func (*Sender) Send

func (s *Sender) Send(sub Subscription, n Notification) error

Send delivers a push notification to a single subscriber. It encrypts the payload, signs the request with a VAPID JWT, and POSTs to the push service endpoint. Returns nil on success (HTTP 201).

Returns ErrSubscriptionExpired when the push service responds with HTTP 410 Gone. Other non-2xx responses are returned as errors with the status code in the message.

type Subscription

type Subscription struct {
	Endpoint string           `json:"endpoint"`
	Keys     SubscriptionKeys `json:"keys"`
}

Subscription holds the endpoint and encryption keys the browser provides after a successful PushManager.subscribe() call. Store this server-side to send notifications later via [Send].

func (Subscription) Validate

func (s Subscription) Validate() error

Validate checks that the subscription has a valid endpoint URL, a 65-byte uncompressed P-256 public key, and a 16-byte auth secret. Call this before storing a subscription to catch malformed data early rather than hitting opaque crypto errors during [Send].

type SubscriptionKeys

type SubscriptionKeys struct {
	P256dh string `json:"p256dh"`
	Auth   string `json:"auth"`
}

SubscriptionKeys holds the client-side ECDH public key and authentication secret needed to encrypt push message payloads.