apns2

README

APNS/2

APNS/2 is a go package designed for simple, flexible and fast Apple Push Notifications on iOS, OSX and Safari using the new HTTP/2 Push provider API.

Features

• Uses new Apple APNs HTTP/2 connection
• Fast - See notes on speed
• Works with go 1.7 and later
• Supports new Apple Token Based Authentication (JWT)
• Supports new iOS 10 features such as Collapse IDs, Subtitles and Mutable Notifications
• Supports persistent connections to APNs
• Supports VoIP/PushKit notifications (iOS 8 and later)
• Modular & easy to use
• Tested and working in APNs production environment

Install

• Make sure you have Go installed and have set your GOPATH.
• Install apns2:

go get -u github.com/sideshow/apns2

If you are running the test suite you will also need to install testify:

go get -u github.com/stretchr/testify

Example

package main

import (
  "log"
  "fmt"

  "github.com/sideshow/apns2"
  "github.com/sideshow/apns2/certificate"
)

func main() {

  cert, err := certificate.FromP12File("../cert.p12", "")
  if err != nil {
    log.Fatal("Cert Error:", err)
  }

  notification := &apns2.Notification{}
  notification.DeviceToken = "11aa01229f15f0f0c52029d8cf8cd0aeaf2365fe4cebc4af26cd6d76b7919ef7"
  notification.Topic = "com.sideshow.Apns2"
  notification.Payload = []byte(`{"aps":{"alert":"Hello!"}}`) // See Payload section below

  client := apns2.NewClient(cert).Production()
  res, err := client.Push(notification)

  if err != nil {
    log.Fatal("Error:", err)
  }

  fmt.Printf("%v %v %v\n", res.StatusCode, res.ApnsID, res.Reason)
}

JWT Token Example

Instead of using a .p12 or .pem certificate as above, you can optionally use APNs JWT Provider Authentication Tokens. First you will need a signing key (.p8 file), Key ID and Team ID from Apple. Once you have these details, you can create a new client:

authKey, err := token.AuthKeyFromFile("../AuthKey_XXX.p8")
if err != nil {
  log.Fatal("token error:", err)
}

token := &token.Token{
  AuthKey: authKey,
  // KeyID from developer account (Certificates, Identifiers & Profiles -> Keys)
  KeyID:   "ABC123DEFG",
  // TeamID from developer account (View Account -> Membership)
  TeamID:  "DEF123GHIJ",
}
...

client := apns2.NewTokenClient(token)
res, err := client.Push(notification)

• You can use one APNs signing key to authenticate tokens for multiple apps.
• A signing key works for both the development and production environments.
• A signing key doesn’t expire but can be revoked.

Notification

At a minimum, a Notification needs a DeviceToken, a Topic and a Payload.

notification := &apns2.Notification{
  DeviceToken: "11aa01229f15f0f0c52029d8cf8cd0aeaf2365fe4cebc4af26cd6d76b7919ef7",
  Topic: "com.sideshow.Apns2",
  Payload: []byte(`{"aps":{"alert":"Hello!"}}`),
}

You can also set an optional ApnsID, Expiration or Priority.

notification.ApnsID =  "40636A2C-C093-493E-936A-2A4333C06DEA"
notification.Expiration = time.Now()
notification.Priority = apns2.PriorityLow

Payload

You can use raw bytes for the notification.Payload as above, or you can use the payload builder package which makes it easy to construct APNs payloads.

// {"aps":{"alert":"hello","badge":1},"key":"val"}

payload := payload.NewPayload().Alert("hello").Badge(1).Custom("key", "val")

notification.Payload = payload
client.Push(notification)

Refer to the payload docs for more info.

Response, Error handling

APNS/2 draws the distinction between a valid response from Apple indicating whether or not the Notification was sent or not, and an unrecoverable or unexpected Error;

• An Error is returned if a non-recoverable error occurs, i.e. if there is a problem with the underlying http.Client connection or Certificate, the payload was not sent, or a valid Response was not received.
• A Response is returned if the payload was successfully sent to Apple and a documented response was received. This struct will contain more information about whether or not the push notification succeeded, its apns-id and if applicable, more information around why it did not succeed.

To check if a Notification was successfully sent;

res, err := client.Push(notification)
if err != nil {
  log.Println("There was an error", err)
  return
}

if res.Sent() {
  log.Println("Sent:", res.ApnsID)
} else {
  fmt.Printf("Not Sent: %v %v %v\n", res.StatusCode, res.ApnsID, res.Reason)
}

Context & Timeouts

For better control over request cancellations and timeouts APNS/2 supports contexts. Using a context can be helpful if you want to cancel all pushes when the parent process is cancelled, or need finer grained control over individual push timeouts. See the Google post for more information on contexts.

ctx, cancel = context.WithTimeout(context.Background(), 10 * time.Second)
res, err := client.PushWithContext(ctx, notification)
defer cancel()

Speed & Performance

Also see the wiki page on APNS HTTP 2 Push Speed.

For best performance, you should hold on to an apns2.Client instance and not re-create it every push. The underlying TLS connection itself can take a few seconds to connect and negotiate, so if you are setting up an apns2.Client and tearing it down every push, then this will greatly affect performance. (Apple suggest keeping the connection open all the time).

You should also limit the amount of apns2.Client instances. The underlying transport has a http connection pool itself, so a single client instance will be enough for most users (One instance can potentially do 4,000+ pushes per second). If you need more than this then one instance per CPU core is a good starting point.

Speed is greatly affected by the location of your server and the quality of your network connection. If you're just testing locally, behind a proxy or if your server is outside USA then you're not going to get great performance. With a good server located in AWS, you should be able to get decent throughput.

Command line tool

APNS/2 has a command line tool that can be installed with go get github.com/sideshow/apns2/apns2. Usage:

apns2 --help
usage: apns2 --certificate-path=CERTIFICATE-PATH --topic=TOPIC [<flags>]

Listens to STDIN to send notifications and writes APNS response code and reason to STDOUT.

The expected format is: <DeviceToken> <APNS Payload>
Example: aff0c63d9eaa63ad161bafee732d5bc2c31f66d552054718ff19ce314371e5d0 {"aps": {"alert": "hi"}}
Flags:
      --help               Show context-sensitive help (also try --help-long and --help-man).
  -c, --certificate-path=CERTIFICATE-PATH
                           Path to certificate file.
  -t, --topic=TOPIC        The topic of the remote notification, which is typically the bundle ID for your app
  -m, --mode="production"  APNS server to send notifications to. `production` or `development`. Defaults to `production`
      --version            Show application version.

License

The MIT License (MIT)

Copyright (c) 2016 Adam Jones

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation

Overview

Package apns2 is a go Apple Push Notification Service (APNs) provider that allows you to send remote notifications to your iOS, tvOS, and OS X apps, using the new APNs HTTP/2 network protocol.

Index

• Constants
• Variables
• type Client
  • func NewClient(certificate tls.Certificate) *Client
  • func NewTokenClient(token *token.Token) *Client
  • func (c *Client) CloseIdleConnections()
  • func (c *Client) Development() *Client
  • func (c *Client) Production() *Client
  • func (c *Client) Push(n *Notification) (*Response, error)
  • func (c *Client) PushWithContext(ctx Context, n *Notification) (*Response, error)
• type ClientManager
  • func NewClientManager() *ClientManager
  • func (m *ClientManager) Add(client *Client)
  • func (m *ClientManager) Get(certificate tls.Certificate) *Client
  • func (m *ClientManager) Len() int
• type Context
• type EPushType
• type Notification
  • func (n *Notification) MarshalJSON() ([]byte, error)
• type Response
  • func (c *Response) Sent() bool
• type Time
  • func (t *Time) UnmarshalJSON(b []byte) error

Constants

const (
	HostDevelopment = "https://api.sandbox.push.apple.com"
	HostProduction  = "https://api.push.apple.com"
)

Apple HTTP/2 Development & Production urls

const (
	// PriorityLow will tell APNs to send the push message at a time that takes
	// into account power considerations for the device. Notifications with this
	// priority might be grouped and delivered in bursts. They are throttled,
	// and in some cases are not delivered.
	PriorityLow = 5

	// PriorityHigh will tell APNs to send the push message immediately.
	// Notifications with this priority must trigger an alert, sound, or badge
	// on the target device. It is an error to use this priority for a push
	// notification that contains only the content-available key.
	PriorityHigh = 10
)

const (
	// 400 The collapse identifier exceeds the maximum allowed size
	ReasonBadCollapseID = "BadCollapseId"

	// 400 The specified device token was bad. Verify that the request contains a
	// valid token and that the token matches the environment.
	ReasonBadDeviceToken = "BadDeviceToken"

	// 400 The apns-expiration value is bad.
	ReasonBadExpirationDate = "BadExpirationDate"

	// 400 The apns-id value is bad.
	ReasonBadMessageID = "BadMessageId"

	// 400 The apns-priority value is bad.
	ReasonBadPriority = "BadPriority"

	// 400 The apns-topic was invalid.
	ReasonBadTopic = "BadTopic"

	// 400 The device token does not match the specified topic.
	ReasonDeviceTokenNotForTopic = "DeviceTokenNotForTopic"

	// 400 One or more headers were repeated.
	ReasonDuplicateHeaders = "DuplicateHeaders"

	// 400 Idle time out.
	ReasonIdleTimeout = "IdleTimeout"

	// 400 The device token is not specified in the request :path. Verify that the
	// :path header contains the device token.
	ReasonMissingDeviceToken = "MissingDeviceToken"

	// 400 The apns-topic header of the request was not specified and was
	// required. The apns-topic header is mandatory when the client is connected
	// using a certificate that supports multiple topics.
	ReasonMissingTopic = "MissingTopic"

	// 400 The message payload was empty.
	ReasonPayloadEmpty = "PayloadEmpty"

	// 400 Pushing to this topic is not allowed.
	ReasonTopicDisallowed = "TopicDisallowed"

	// 403 The certificate was bad.
	ReasonBadCertificate = "BadCertificate"

	// 403 The client certificate was for the wrong environment.
	ReasonBadCertificateEnvironment = "BadCertificateEnvironment"

	// 403 The provider token is stale and a new token should be generated.
	ReasonExpiredProviderToken = "ExpiredProviderToken"

	// 403 The specified action is not allowed.
	ReasonForbidden = "Forbidden"

	// 403 The provider token is not valid or the token signature could not be
	// verified.
	ReasonInvalidProviderToken = "InvalidProviderToken"

	// 403 No provider certificate was used to connect to APNs and Authorization
	// header was missing or no provider token was specified.
	ReasonMissingProviderToken = "MissingProviderToken"

	// 404 The request contained a bad :path value.
	ReasonBadPath = "BadPath"

	// 405 The specified :method was not POST.
	ReasonMethodNotAllowed = "MethodNotAllowed"

	// 410 The device token is inactive for the specified topic.
	ReasonUnregistered = "Unregistered"

	// 413 The message payload was too large. See Creating the Remote Notification
	// Payload in the Apple Local and Remote Notification Programming Guide for
	// details on maximum payload size.
	ReasonPayloadTooLarge = "PayloadTooLarge"

	// 429 The provider token is being updated too often.
	ReasonTooManyProviderTokenUpdates = "TooManyProviderTokenUpdates"

	// 429 Too many requests were made consecutively to the same device token.
	ReasonTooManyRequests = "TooManyRequests"

	// 500 An internal server error occurred.
	ReasonInternalServerError = "InternalServerError"

	// 503 The service is unavailable.
	ReasonServiceUnavailable = "ServiceUnavailable"

	// 503 The server is shutting down.
	ReasonShutdown = "Shutdown"
)

The possible Reason error codes returned from APNs. From table 8-6 in the Apple Local and Remote Notification Programming Guide.

const StatusSent = http.StatusOK

StatusSent is a 200 response.

Variables

var (
	// TLSDialTimeout is the maximum amount of time a dial will wait for a connect
	// to complete.
	TLSDialTimeout = 20 * time.Second
	// HTTPClientTimeout specifies a time limit for requests made by the
	// HTTPClient. The timeout includes connection time, any redirects,
	// and reading the response body.
	HTTPClientTimeout = 60 * time.Second
	// TCPKeepAlive specifies the keep-alive period for an active network
	// connection. If zero, keep-alives are not enabled.
	TCPKeepAlive = 60 * time.Second
)

var DefaultHost = HostDevelopment

DefaultHost is a mutable var for testing purposes

var DialTLS = func(network, addr string, cfg *tls.Config) (net.Conn, error) {
	dialer := &net.Dialer{
		Timeout:   TLSDialTimeout,
		KeepAlive: TCPKeepAlive,
	}
	return tls.DialWithDialer(dialer, network, addr, cfg)
}

DialTLS is the default dial function for creating TLS connections for non-proxied HTTPS requests.

Types

type Client

type Client struct {
	Host        string
	Certificate tls.Certificate
	Token       *token.Token
	HTTPClient  *http.Client
}

Client represents a connection with the APNs

func NewClient

func NewClient(certificate tls.Certificate) *Client

NewClient returns a new Client with an underlying http.Client configured with the correct APNs HTTP/2 transport settings. It does not connect to the APNs until the first Notification is sent via the Push method.

As per the Apple APNs Provider API, you should keep a handle on this client so that you can keep your connections with APNs open across multiple notifications; don’t repeatedly open and close connections. APNs treats rapid connection and disconnection as a denial-of-service attack.

If your use case involves multiple long-lived connections, consider using the ClientManager, which manages clients for you.

func NewTokenClient

func NewTokenClient(token *token.Token) *Client

NewTokenClient returns a new Client with an underlying http.Client configured with the correct APNs HTTP/2 transport settings. It does not connect to the APNs until the first Notification is sent via the Push method.

As per the Apple APNs Provider API, you should keep a handle on this client so that you can keep your connections with APNs open across multiple notifications; don’t repeatedly open and close connections. APNs treats rapid connection and disconnection as a denial-of-service attack.

func (*Client) CloseIdleConnections

func (c *Client) CloseIdleConnections()

CloseIdleConnections closes any underlying connections which were previously connected from previous requests but are now sitting idle. It will not interrupt any connections currently in use.

func (*Client) Development

func (c *Client) Development() *Client

Development sets the Client to use the APNs development push endpoint.

func (*Client) Production

func (c *Client) Production() *Client

Production sets the Client to use the APNs production push endpoint.

func (*Client) Push

func (c *Client) Push(n *Notification) (*Response, error)

Push sends a Notification to the APNs gateway. If the underlying http.Client is not currently connected, this method will attempt to reconnect transparently before sending the notification. It will return a Response indicating whether the notification was accepted or rejected by the APNs gateway, or an error if something goes wrong.

Use PushWithContext if you need better cancellation and timeout control.

func (*Client) PushWithContext

func (c *Client) PushWithContext(ctx Context, n *Notification) (*Response, error)

PushWithContext sends a Notification to the APNs gateway. Context carries a deadline and a cancellation signal and allows you to close long running requests when the context timeout is exceeded. Context can be nil, for backwards compatibility.

If the underlying http.Client is not currently connected, this method will attempt to reconnect transparently before sending the notification. It will return a Response indicating whether the notification was accepted or rejected by the APNs gateway, or an error if something goes wrong.

type ClientManager

type ClientManager struct {
	// MaxSize is the maximum number of clients allowed in the manager. When
	// this limit is reached, the least recently used client is evicted. Set
	// zero for no limit.
	MaxSize int

	// MaxAge is the maximum age of clients in the manager. Upon retrieval, if
	// a client has remained unused in the manager for this duration or longer,
	// it is evicted and nil is returned. Set zero to disable this
	// functionality.
	MaxAge time.Duration

	// Factory is the function which constructs clients if not found in the
	// manager.
	Factory func(certificate tls.Certificate) *Client
	// contains filtered or unexported fields
}

ClientManager is a way to manage multiple connections to the APNs.

func NewClientManager

func NewClientManager() *ClientManager

NewClientManager returns a new ClientManager for prolonged, concurrent usage of multiple APNs clients. ClientManager is flexible enough to work best for your use case. When a client is not found in the manager, Get will return the result of calling Factory, which can be a Client or nil.

Having multiple clients per certificate in the manager is not allowed.

By default, MaxSize is 64, MaxAge is 10 minutes, and Factory always returns a Client with default options.

func (*ClientManager) Add

func (m *ClientManager) Add(client *Client)

Add adds a Client to the manager. You can use this to individually configure Clients in the manager.

func (*ClientManager) Get

func (m *ClientManager) Get(certificate tls.Certificate) *Client

Get gets a Client from the manager. If a Client is not found in the manager or if a Client has remained in the manager longer than MaxAge, Get will call the ClientManager's Factory function, store the result in the manager if non-nil, and return it.

func (*ClientManager) Len

func (m *ClientManager) Len() int

Len returns the current size of the ClientManager.

type Context

type Context interface {
	context.Context
}

A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Context's methods may be called by multiple goroutines simultaneously.

type EPushType

type EPushType string

EPushType defines the value for the apns-push-type header

const (
	// PushTypeAlert is used for notifications that trigger a user interaction —
	// for example, an alert, badge, or sound. If you set this push type, the
	// apns-topic header field must use your app’s bundle ID as the topic. The
	// alert push type is required on watchOS 6 and later. It is recommended on
	// macOS, iOS, tvOS, and iPadOS.
	PushTypeAlert EPushType = "alert"

	// PushTypeBackground is used for notifications that deliver content in the
	// background, and don’t trigger any user interactions. If you set this push
	// type, the apns-topic header field must use your app’s bundle ID as the
	// topic. The background push type is required on watchOS 6 and later. It is
	// recommended on macOS, iOS, tvOS, and iPadOS.
	PushTypeBackground EPushType = "background"

	// PushTypeVOIP is used for notifications that provide information about an
	// incoming Voice-over-IP (VoIP) call. If you set this push type, the
	// apns-topic header field must use your app’s bundle ID with .voip appended
	// to the end. If you’re using certificate-based authentication, you must
	// also register the certificate for VoIP services. The voip push type is
	// not available on watchOS. It is recommended on macOS, iOS, tvOS, and
	// iPadOS.
	PushTypeVOIP EPushType = "voip"

	// PushTypeComplication is used for notifications that contain update
	// information for a watchOS app’s complications. If you set this push type,
	// the apns-topic header field must use your app’s bundle ID with
	// .complication appended to the end. If you’re using certificate-based
	// authentication, you must also register the certificate for WatchKit
	// services. The complication push type is recommended for watchOS and iOS.
	// It is not available on macOS, tvOS, and iPadOS.
	PushTypeComplication EPushType = "complication"

	// PushTypeFileProvider is used to signal changes to a File Provider
	// extension. If you set this push type, the apns-topic header field must
	// use your app’s bundle ID with .pushkit.fileprovider appended to the end.
	// The fileprovider push type is not available on watchOS. It is recommended
	// on macOS, iOS, tvOS, and iPadOS.
	PushTypeFileProvider EPushType = "fileprovider"

	// PushTypeMDM is used for notifications that tell managed devices to
	// contact the MDM server. If you set this push type, you must use the topic
	// from the UID attribute in the subject of your MDM push certificate.
	PushTypeMDM EPushType = "mdm"
)

type Notification

type Notification struct {

	// An optional canonical UUID that identifies the notification. The
	// canonical form is 32 lowercase hexadecimal digits, displayed in five
	// groups separated by hyphens in the form 8-4-4-4-12. An example UUID is as
	// follows:
	//
	//  123e4567-e89b-12d3-a456-42665544000
	//
	// If you don't set this, a new UUID is created by APNs and returned in the
	// response.
	ApnsID string

	// A string which allows multiple notifications with the same collapse
	// identifier to be displayed to the user as a single notification. The
	// value should not exceed 64 bytes.
	CollapseID string

	// A string containing hexadecimal bytes of the device token for the target
	// device.
	DeviceToken string

	// The topic of the remote notification, which is typically the bundle ID
	// for your app. The certificate you create in the Apple Developer Member
	// Center must include the capability for this topic. If your certificate
	// includes multiple topics, you must specify a value for this header. If
	// you omit this header and your APNs certificate does not specify multiple
	// topics, the APNs server uses the certificate’s Subject as the default
	// topic.
	Topic string

	// An optional time at which the notification is no longer valid and can be
	// discarded by APNs. If this value is in the past, APNs treats the
	// notification as if it expires immediately and does not store the
	// notification or attempt to redeliver it. If this value is left as the
	// default (ie, Expiration.IsZero()) an expiration header will not added to
	// the http request.
	Expiration time.Time

	// The priority of the notification. Specify ether apns.PriorityHigh (10) or
	// apns.PriorityLow (5) If you don't set this, the APNs server will set the
	// priority to 10.
	Priority int

	// A byte array containing the JSON-encoded payload of this push notification.
	// Refer to "The Remote Notification Payload" section in the Apple Local and
	// Remote Notification Programming Guide for more info.
	Payload interface{}

	// The pushtype of the push notification. If this values is left as the
	// default an apns-push-type header with value 'alert' will be added to the
	// http request.
	PushType EPushType
}

Notification represents the the data and metadata for a APNs Remote Notification.

func (*Notification) MarshalJSON

func (n *Notification) MarshalJSON() ([]byte, error)

MarshalJSON converts the notification payload to JSON.

type Response

type Response struct {

	// The HTTP status code returned by APNs.
	// A 200 value indicates that the notification was successfully sent.
	// For a list of other possible status codes, see table 6-4 in the Apple Local
	// and Remote Notification Programming Guide.
	StatusCode int

	// The APNs error string indicating the reason for the notification failure (if
	// any). The error code is specified as a string. For a list of possible
	// values, see the Reason constants above.
	// If the notification was accepted, this value will be "".
	Reason string

	// The APNs ApnsID value from the Notification. If you didn't set an ApnsID on the
	// Notification, this will be a new unique UUID which has been created by APNs.
	ApnsID string

	// If the value of StatusCode is 410, this is the last time at which APNs
	// confirmed that the device token was no longer valid for the topic.
	Timestamp Time
}

Response represents a result from the APNs gateway indicating whether a notification was accepted or rejected and (if applicable) the metadata surrounding the rejection.

func (*Response) Sent

func (c *Response) Sent() bool

Sent returns whether or not the notification was successfully sent. This is the same as checking if the StatusCode == 200.

type Time

type Time struct {
	time.Time
}

Time represents a device uninstall time

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(b []byte) error

UnmarshalJSON converts an epoch date into a Time struct.