push

Documentation

Overview

Package push defines the provider-neutral mobile push boundary and the Expo Push Service adapter. Provider configuration is explicit: an empty provider returns a nil Transport and constructs no HTTP client.

Index

• Constants
• func DecodeSubscriptionKey(s string) ([]byte, error)
• func GenerateVAPIDKeys() (publicKey, privateKey string, err error)
• func ValidatePublicPushEndpoint(raw string) (string, error)
• type Config
• type EnvelopeData
• type InvalidTokenError
  • func (e *InvalidTokenError) Error() string
• type Message
• type Option
  • func WithHTTPClient(client httpDoer) Option
• type PayloadError
  • func (e *PayloadError) Error() string
• type PermanentError
  • func (e *PermanentError) Error() string
• type Priority
• type RateLimitedError
  • func (e *RateLimitedError) Error() string
• type Receipt
• type Ticket
• type TransientError
  • func (e *TransientError) Error() string
• type Transport
  • func New(config Config, options ...Option) (Transport, error)
• type WebPush
  • func NewWebPush(config WebPushConfig, options ...Option) (*WebPush, error)
  • func (w *WebPush) PublicKey() string
  • func (w *WebPush) Send(ctx context.Context, msg WebPushMessage) error
• type WebPushConfig
• type WebPushMessage

Constants

const (
	ProviderExpo    = "expo"
	ProviderWebPush = "webpush"

	// MaxPayloadBytes is Expo's maximum encoded notification size.
	MaxPayloadBytes        = 4096
	MaxTitleBytes          = 120
	MaxBodyBytes           = 1024
	MaxRouteBytes          = 512
	MaxNotificationIDBytes = 128
	MaxEventBytes          = 64
	MaxBindingIDBytes      = 200
	MaxCollapseBytes       = 64
	MaxTagBytes            = 64
)

Functions

func DecodeSubscriptionKey

func DecodeSubscriptionKey(s string) ([]byte, error)

func GenerateVAPIDKeys

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

GenerateVAPIDKeys mints an uncompressed P-256 point and 32-byte scalar as unpadded base64url, the encoding browsers and RFC 8292 expect.

func ValidatePublicPushEndpoint

func ValidatePublicPushEndpoint(raw string) (string, error)

Types

type Config

type Config struct {
	Provider    string
	AccessToken string
	Endpoint    string
	Timeout     time.Duration
}

Config is the complete provider configuration. Endpoint is the Expo push API base (the adapter appends /send and /getReceipts). It is primarily an integration-test/self-hosted stub seam; production should leave it empty.

type EnvelopeData

type EnvelopeData struct {
	Schema         string `json:"schema"`
	NotificationID string `json:"notificationId"`
	Event          string `json:"event"`
	Route          string `json:"route"`
	Subject        string `json:"subject"`
	WorkspaceID    string `json:"workspaceId"`
	SessionID      string `json:"sessionId"`
}

EnvelopeData is the complete closed custom-data contract understood by the native client. Keeping it typed prevents arbitrary facts or credentials from drifting into provider-visible payloads.

type InvalidTokenError

type InvalidTokenError struct {
	Code string
}

InvalidTokenError is a permanent device-token error. It intentionally does not retain the token.

func (*InvalidTokenError) Error

func (e *InvalidTokenError) Error() string

type Message

type Message struct {
	Token       string
	Title       string
	Body        string
	Data        EnvelopeData
	CollapseKey string
	Tag         string
	Priority    Priority
}

Message is deliberately narrow. Arbitrary caller data is excluded so credentials, environment values, and logs cannot accidentally become push payloads. Route is an app-internal deep link, not an arbitrary URL.

type Option

type Option func(*expoOptions)

Option customizes construction without exposing provider details through the Transport interface.

func WithHTTPClient

func WithHTTPClient(client httpDoer) Option

WithHTTPClient supplies a fake or instrumented client for tests.

type PayloadError

type PayloadError struct {
	Field  string
	Reason string
}

PayloadError is a permanent caller error. Field is a fixed schema name; the rejected value is never retained.

func (*PayloadError) Error

func (e *PayloadError) Error() string

type PermanentError

type PermanentError struct {
	Operation string
	Code      string
}

PermanentError represents other non-retryable provider rejection. Code is a provider-defined classification, never the provider's free-form message.

func (*PermanentError) Error

func (e *PermanentError) Error() string

type Priority

type Priority string

Priority is intentionally provider-neutral. Later notification policy may choose it without importing Expo vocabulary.

const (
	PriorityDefault Priority = ""
	PriorityNormal  Priority = "normal"
	PriorityHigh    Priority = "high"
)

type RateLimitedError

type RateLimitedError struct {
	Operation  string
	RetryAfter time.Duration
}

RateLimitedError represents provider throttling. RetryAfter is zero when the provider did not supply a usable delay.

func (*RateLimitedError) Error

func (e *RateLimitedError) Error() string

type Receipt

type Receipt struct {
	ID  string
	Err error
}

Receipt is the provider's terminal delivery result. Err is nil on delivery; typed errors tell the caller whether to retry or prune the device token.

type Ticket

type Ticket struct {
	ID string
}

Ticket identifies a message accepted by the provider. Acceptance is not delivery: callers must persist ID and call CheckReceipts later.

type TransientError

type TransientError struct {
	Operation string
	Detail    string
}

TransientError represents a provider/network outage that may be retried. Detail is an internal stable label and never provider text or payload data.

func (*TransientError) Error

func (e *TransientError) Error() string

type Transport

type Transport interface {
	Send(context.Context, Message) (Ticket, error)
	CheckReceipts(context.Context, []string) (map[string]Receipt, error)
}

Transport is the provider-neutral push seam used by the notifications service. CheckReceipts may omit IDs for which the provider has no result yet.

func New

func New(config Config, options ...Option) (Transport, error)

New constructs the configured transport. Empty Provider is the only disabled state and returns (nil, nil) before allocating an HTTP client or parsing any provider settings.

type WebPush

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

WebPush sends one encrypted Web Push request. It is not a push.Transport: browsers have no Expo-style receipt poll.

func NewWebPush

func NewWebPush(config WebPushConfig, options ...Option) (*WebPush, error)

NewWebPush constructs the VAPID sender. Empty config returns (nil, nil).

func (*WebPush) PublicKey

func (w *WebPush) PublicKey() string

PublicKey is the uncompressed P-256 point in unpadded base64url, the value browsers pass as applicationServerKey.

func (*WebPush) Send

func (w *WebPush) Send(ctx context.Context, msg WebPushMessage) error

Send encrypts and POSTs one notification. Ticket ID is empty: Web Push has no receipt poll. 404/410 map to InvalidTokenError so the worker prunes.

type WebPushConfig

type WebPushConfig struct {
	PublicKey  string
	PrivateKey string
	Subscriber string
	Timeout    time.Duration
}

WebPushConfig is the complete VAPID composition. All three fields empty is the only disabled state and returns (nil, nil) before allocating a client. A partial set fails closed at construction so a misconfigured replica cannot silently skip browser delivery.

type WebPushMessage

type WebPushMessage struct {
	Endpoint string
	P256dh   string
	Auth     string
	Title    string
	Body     string
	Urgency  string
	Data     EnvelopeData
}

WebPushMessage is the closed JSON body a service worker showNotification consumes. Data is the same envelope native push uses.