push

Documentation

Overview

Package push sends notifications over HTTP/2 to Apple's Push Notification Service.

Index

• Constants
• Variables
• func IsDeviceTokenValid(s string) bool
• func NewClient(cert tls.Certificate) (*http.Client, error)
• type Error
  • func (e *Error) Error() string
• type Headers
• type Queue
  • func NewQueue(service *Service, workers uint) *Queue
  • func (q *Queue) Push(deviceToken string, headers *Headers, payload []byte)
  • func (q *Queue) Response() (id string, deviceToken string, err error)
  • func (q *Queue) Wait()
• type Service
  • func NewService(client *http.Client, host string) *Service
  • func (s *Service) Push(deviceToken string, headers *Headers, payload []byte) (string, error)

Constants

const (
	Development = "https://api.development.push.apple.com"
	Production  = "https://api.push.apple.com"
)

Apple host locations for configuring Service.

Variables

var (
	// These could be checked prior to sending the request to Apple.
	ErrPayloadEmpty    = errors.New("PayloadEmpty")
	ErrPayloadTooLarge = errors.New("PayloadTooLarge")

	// Device token errors.
	ErrMissingDeviceToken = errors.New("MissingDeviceToken")
	ErrBadDeviceToken     = errors.New("BadDeviceToken")
	ErrTooManyRequests    = errors.New("TooManyRequests")

	// Header errors.
	ErrBadMessageID      = errors.New("BadMessageID")
	ErrBadExpirationDate = errors.New("BadExpirationDate")
	ErrBadPriority       = errors.New("BadPriority")
	ErrBadTopic          = errors.New("BadTopic")

	// Certificate and topic errors.
	ErrBadCertificate            = errors.New("BadCertificate")
	ErrBadCertificateEnvironment = errors.New("BadCertificateEnvironment")
	ErrForbidden                 = errors.New("Forbidden")
	ErrMissingTopic              = errors.New("MissingTopic")
	ErrTopicDisallowed           = errors.New("TopicDisallowed")
	ErrUnregistered              = errors.New("Unregistered")
	ErrDeviceTokenNotForTopic    = errors.New("DeviceTokenNotForTopic")

	// These errors should never happen when using Push.
	ErrDuplicateHeaders = errors.New("DuplicateHeaders")
	ErrBadPath          = errors.New("BadPath")
	ErrMethodNotAllowed = errors.New("MethodNotAllowed")

	// Fatal server errors.
	ErrIdleTimeout         = errors.New("IdleTimeout")
	ErrShutdown            = errors.New("Shutdown")
	ErrInternalServerError = errors.New("InternalServerError")
	ErrServiceUnavailable  = errors.New("ServiceUnavailable")
)

Service error responses.

Functions

func IsDeviceTokenValid

func IsDeviceTokenValid(s string) bool

IsDeviceTokenValid checks if s is a hexadecimal token of the correct length.

func NewClient

func NewClient(cert tls.Certificate) (*http.Client, error)

NewClient sets up an HTTP/2 client for a certificate.

Types

type Error

type Error struct {
	Reason    error
	Status    int // http StatusCode
	Timestamp time.Time
}

Error responses from Apple

func (*Error) Error

func (e *Error) Error() string

type Headers

type Headers struct {
	// ID for the notification. Apple generates one if omitted.
	// This should be a UUID with 32 lowercase hexadecimal digits.
	// TODO: use a UUID type.
	ID string

	// Apple will retry delivery until this time. The default behavior only tries once.
	Expiration time.Time

	// Allow Apple to group messages together to reduce power consumption.
	// By default messages are sent immediately.
	LowPriority bool

	// Topic for certificates with multiple topics.
	Topic string
}

Headers sent with a push to control the notification (optional)

type Queue

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

Queue up notifications without waiting for the response.

func NewQueue

func NewQueue(service *Service, workers uint) *Queue

NewQueue wraps a service with a queue for sending notifications asynchronously.

func (*Queue) Push

func (q *Queue) Push(deviceToken string, headers *Headers, payload []byte)

Push queues a notification to the APN service.

func (*Queue) Response

func (q *Queue) Response() (id string, deviceToken string, err error)

Response blocks waiting for a response. Responses may be received in any order.

func (*Queue) Wait

func (q *Queue) Wait()

Wait for all responses to be handled and shutdown workers to stop accepting notifications.

type Service

type Service struct {
	Host   string
	Client *http.Client
}

Service is the Apple Push Notification Service that you send notifications to.

func NewService

func NewService(client *http.Client, host string) *Service

NewService creates a new service to connect to APN.

func (*Service) Push

func (s *Service) Push(deviceToken string, headers *Headers, payload []byte) (string, error)

Push sends a notification and waits for a response.