Network.Apns.Types

Public types for using the APNs integration.

Documentation

data ApnsPushData

Data for an APNs push message, consisting of its target device token, information that gets sent as headers with the push request such as expiration and topic, and the payload itself.

Constructors

ApnsPushData

Fields

• _apnsPushData_deviceToken :: ByteString

  The target device token, as its raw binary self. This value will be base16 encoded when sending the push message.

• _apnsPushData_expiration :: UTCTime

  When the push should expire at APNs if it hasn't been delivered yet.

• _apnsPushData_priority :: Maybe Int

  What priority the push should have at APNs, with 10 being immediately and must have a alert, sound or badge, and 5 being possibly deferred due to battery conservation and other factors.

• _apnsPushData_topic :: Text

  The topic (usually app bundle ID) that this push is being sent for.

• _apnsPushData_collapseId :: Maybe ByteString

  An optional identifier that the target device can use to consolidate a series of updates to the same notification.

• _apnsPushData_payload :: ByteString

  The payload data, usually formatted as JSON.

Instances

Show ApnsPushData

Defined in Network.Apns.Types

Methods

showsPrec :: Int -> ApnsPushData -> ShowS

show :: ApnsPushData -> String

showList :: [ApnsPushData] -> ShowS

apnsPushData_deviceToken :: Lens' ApnsPushData ByteString

apnsPushData_expiration :: Lens' ApnsPushData UTCTime

apnsPushData_priority :: Lens' ApnsPushData (Maybe Int)

apnsPushData_topic :: Lens' ApnsPushData Text

apnsPushData_collapseId :: Lens' ApnsPushData (Maybe ByteString)

apnsPushData_payload :: Lens' ApnsPushData ByteString

data ApnsErrorReason

Various error codes reported by APNs in response to a push or on the connection as a whole. See APNs documentation for meanings.

Constructors

ApnsErrorBadCollapseId

ApnsErrorBadDeviceToken

ApnsErrorBadExpirationDate

ApnsErrorBadMessageId

ApnsErrorBadPriority

ApnsErrorBadTopic

ApnsErrorDeviceTokenNotForTopic

ApnsErrorDuplicateHeaders

ApnsErrorIdleTimeout

ApnsErrorMissingDeviceToken

ApnsErrorMissingTopic

ApnsErrorPayloadEmpty

ApnsErrorTopicDisallowed

ApnsErrorBadCertificate

ApnsErrorBadCertificateEnvironment

ApnsErrorExpiredProviderToken

ApnsErrorForbidden

ApnsErrorInvalidProviderToken

ApnsErrorMissingProviderToken

ApnsErrorBadPath

ApnsErrorMethodNotAllowed

ApnsErrorUnregistered

ApnsErrorPayloadTooLarge

ApnsErrorTooManyProviderTokenUpdates

ApnsErrorTooManyRequests

ApnsErrorInternalServerError

ApnsErrorServiceUnavailable

ApnsErrorShutdown

Instances

Bounded ApnsErrorReason

Defined in Network.Apns.Types

Methods

minBound :: ApnsErrorReason

maxBound :: ApnsErrorReason

Enum ApnsErrorReason

Defined in Network.Apns.Types

Methods

succ :: ApnsErrorReason -> ApnsErrorReason

pred :: ApnsErrorReason -> ApnsErrorReason

toEnum :: Int -> ApnsErrorReason

fromEnum :: ApnsErrorReason -> Int

enumFrom :: ApnsErrorReason -> [ApnsErrorReason]

enumFromThen :: ApnsErrorReason -> ApnsErrorReason -> [ApnsErrorReason]

enumFromTo :: ApnsErrorReason -> ApnsErrorReason -> [ApnsErrorReason]

enumFromThenTo :: ApnsErrorReason -> ApnsErrorReason -> ApnsErrorReason -> [ApnsErrorReason]

Eq ApnsErrorReason

Defined in Network.Apns.Types

Methods

(==) :: ApnsErrorReason -> ApnsErrorReason -> Bool

(/=) :: ApnsErrorReason -> ApnsErrorReason -> Bool

Ord ApnsErrorReason

Defined in Network.Apns.Types

Methods

compare :: ApnsErrorReason -> ApnsErrorReason -> Ordering

(<) :: ApnsErrorReason -> ApnsErrorReason -> Bool

(<=) :: ApnsErrorReason -> ApnsErrorReason -> Bool

(>) :: ApnsErrorReason -> ApnsErrorReason -> Bool

(>=) :: ApnsErrorReason -> ApnsErrorReason -> Bool

max :: ApnsErrorReason -> ApnsErrorReason -> ApnsErrorReason

min :: ApnsErrorReason -> ApnsErrorReason -> ApnsErrorReason

Show ApnsErrorReason

Defined in Network.Apns.Types

Methods

showsPrec :: Int -> ApnsErrorReason -> ShowS

show :: ApnsErrorReason -> String

showList :: [ApnsErrorReason] -> ShowS

apnsErrorReasonToText :: ApnsErrorReason -> Text

Convert an ApnsErrorReason to its text equivalent.

apnsErrorReasonFromText :: Text -> Maybe ApnsErrorReason

Convert a text value to a Just ApnsErrorReason if the text value is a valid error reason, Nothing if it's invalid.

apnsErrorReasonFromTextMap :: Map Text ApnsErrorReason

Mapping of ApnsErrorReason text forms to values.

data ApnsError

Structure carrying error information returned by APNs in response to a push.

Constructors

ApnsError

Fields

• _apnsError_apnsId :: ByteString

  The unique identifier assigned by APNs for the push.

• _apnsError_status :: Int

  The HTTP status code returned. Should never be in the 2xx range.

• _apnsError_reason :: Either Text ApnsErrorReason

  The reason for failure given by APNs (Right) or the raw value of the reason field if its value is unrecognized (Left).

• _apnsError_timestamp :: Maybe UTCTime

  For status 410, the last time APNs confirmed that the device token was invalid. No pushes should be sent for this device token.

Instances

Show ApnsError

Defined in Network.Apns.Types

Methods

showsPrec :: Int -> ApnsError -> ShowS

show :: ApnsError -> String

showList :: [ApnsError] -> ShowS

apnsError_apnsId :: Lens' ApnsError ByteString

apnsError_status :: Lens' ApnsError Int

apnsError_reason :: Lens' ApnsError (Either Text ApnsErrorReason)

apnsError_timestamp :: Lens' ApnsError (Maybe UTCTime)

data ApnsPushResult

The result of a push delivery attempt.

Constructors

ApnsPushDelivered ByteString

The push was successfully delivered to APNs along with its assigned apns-id. It may or may not be delivered to the target device, at the discretion of APNs.

ApnsPushErrored ApnsError

APNs rejected the push notification. See the ApnsError for more detail.

ApnsPushStreamError ErrorCodeId ByteString

APNs reset the HTTP2 stream before delivery could be completed. The push was most likely not accepted by APNs. The HTTP2 ErrorCodeId and error data are given.

ApnsPushResponseParseError Text

APNs gave an error response but it could not be parsed as JSON. The JSON parsing error is given.

ApnsPushDropped

APNs closed the HTTP/2 connection and indicated it did not process the push. It should be resubmitted on a new connection.

ApnsPushConnectionClosed

The connection to APNs was already closed by the time the push was requested. It should be resubmitted on a new connection.

ApnsPushStreamsExhausted

The HTTP/2 connection cannot allocate any more new streams. The connection should be closed and the push resubmitted on a new connection.

Instances

Show ApnsPushResult

Defined in Network.Apns.Types

Methods

showsPrec :: Int -> ApnsPushResult -> ShowS

show :: ApnsPushResult -> String

showList :: [ApnsPushResult] -> ShowS

_ApnsPushDelivered :: Prism' ApnsPushResult ByteString

_ApnsPushErrored :: Prism' ApnsPushResult ApnsError

_ApnsPushStreamError :: Prism' ApnsPushResult (ErrorCodeId, ByteString)

_ApnsPushResponseParseError :: Prism' ApnsPushResult Text

_ApnsPushDropped :: Prism' ApnsPushResult ()

_ApnsPushConnectionClosed :: Prism' ApnsPushResult ()

_ApnsPushStreamsExhausted :: Prism' ApnsPushResult ()

data ApnsPush

Push notification data along with a callback that's invoked with the disposition of the push as soon as it's known.

Constructors

ApnsPush

Fields

• _apnsPush_data :: ApnsPushData

  What data to send for the push.

• _apnsPush_callback :: ApnsPushResult -> IO ()

  What callback to invoke when the push result is known. Exceptions thrown by the callback will be silently ignored.

apnsPush_data :: Lens' ApnsPush ApnsPushData

apnsPush_callback :: Lens' ApnsPush (ApnsPushResult -> IO ())

data ApnsTerminationReason

The reason an APNs connection was terminated.

Constructors

ApnsTerminatedLocally

The APNs connection was locally closed using _apnsConnection_close.

ApnsTerminatedRemotely (Either ByteString ApnsErrorReason)

The APNs connection was remotely closed by APNs. The APNs error reason is given as Right if available, otherwise some other error string given as Left.

ApnsTerminatedHttp2Error HTTP2Error

The APNs connection was terminated due to an HTTP/2 protocol error.

ApnsTerminatedSilentlyClosed

The APNs connection was terminated because a foreign entity closed the TCP stream and no reason was provided.

ApnsTerminatedInsufficientHeaderBytes

The APNs connection was terminated because the TCP stream ended before being able to read all the header bytes for an HTTP/2 frame.

ApnsTerminatedInsufficientPayloadBytes FrameTypeId

The APNs connection was terminated because the TCP stream ended before being able to read all the payload bytes for an HTTP/2 frame.

ApnsTerminatedOversizedPayload

The APNs connection was terminated because the server send a frame with a purported payload size larger than the currently negotiated MAX_FRAME_SIZE.

ApnsTerminatedReadError SomeException

The APNs connection was terminated by an I/O error while reading.

ApnsTerminatedWriteError SomeException

The APNs connection was terminated by an I/O error while writing.

ApnsTerminatedProcessingException SomeException

The processing thread died due to some unexpected exception. Pushes currently in transit might or might not be delivered.

Instances

Show ApnsTerminationReason

Defined in Network.Apns.Types

Methods

showsPrec :: Int -> ApnsTerminationReason -> ShowS

show :: ApnsTerminationReason -> String

showList :: [ApnsTerminationReason] -> ShowS

_ApnsTerminatedLocally :: Prism' ApnsTerminationReason ()

_ApnsTerminatedRemotely :: Prism' ApnsTerminationReason (Either ByteString ApnsErrorReason)

_ApnsTerminatedHttp2Error :: Prism' ApnsTerminationReason HTTP2Error

_ApnsTerminatedInsufficientHeaderBytes :: Prism' ApnsTerminationReason ()

_ApnsTerminatedInsufficientPayloadBytes :: Prism' ApnsTerminationReason FrameTypeId

_ApnsTerminatedReadError :: Prism' ApnsTerminationReason SomeException

_ApnsTerminatedWriteError :: Prism' ApnsTerminationReason SomeException

_ApnsTerminatedProcessingException :: Prism' ApnsTerminationReason SomeException

data ApnsConnectionParams

Parameters for establishing an APNs connection.

Constructors

ApnsConnectionParams

Fields

• _apnsConnectionParams_hostName :: HostName

  The host name of APNs. Usually api.development.push.apple.com or api.push.apple.com.

• _apnsConnectionParams_portNumber :: PortNumber

  The port number of APNs. Usually 443.

• _apnsConnectionParams_clientCertificateChain :: CertificateChain

  The client TLS certificate and chain to send to APNs to authenticate. Usually generated by the Apple developer portal.

  See credentialLoadX509Chain for one way to provide this value.

• _apnsConnectionParams_clientCertificateKey :: PrivKey

  The client TLS private key to use when authenticating with APNs. Usually generated locally and used to generate a certificate signing request which is then submitted to the Apple developer portal.

  See credentialLoadX509Chain for one way to provide this value.

• _apnsConnectionParams_serverCertificateStore :: Maybe CertificateStore

  The certificate store to use when validating the server certificate, typically the system's trusted CA store.

  See getSystemCertificateStore from the x509-system package for a method to load the system's trusted CA store, or readCertificateStore from x509-store for a way to load a custom trusted CA store.

• _apnsConnectionParams_onDebugLog :: Text -> IO ()

  A callback invoked by the APNs library to report debugging information. Set to _ -> pure () for no debug log. Take care to prevent any exceptions from being thrown as they will likely leave the APNs connection in an undefined state.

  WARNING: this will be both verbose and contain potentially sensitive information as it includes all traffic exchanged with APNs, including payloads and headers. The TLS certificate or key will not be included however.

• _apnsConnectionParams_onServerCertificate :: Maybe (CertificateStore -> ValidationCache -> ServiceID -> CertificateChain -> IO [FailedReason])

  A callback invoked by the TLS library to validate the server's presented certificate. Nothing means use validateDefault, which uses _apnsConnectionParams_serverCertificateStore to validate the certificate in the usual way.

• _apnsConnectionParams_onTermination :: ApnsTerminationReason -> IO ()

  A callback invokved by the APNs library when the APNs connection terminates with the reason why it was terminated.

• _apnsConnectionParams_readQueueSize :: Int

  How many HTTP/2 frames to queue. Usually a small number is appropriate as the processing thread does no major blocking.

• _apnsConnectionParams_writeQueueSize :: Int

  How many HTTP/2 frames to queue. Usually a small number is appropriate as the server should direct flow control.

• _apnsConnectionParams_pushQueueSize :: Int

  How many ApnsPush requests to queue. Usually a small number is appropriate.

apnsConnectionParams_hostName :: Lens' ApnsConnectionParams HostName

apnsConnectionParams_portNumber :: Lens' ApnsConnectionParams PortNumber

apnsConnectionParams_clientCertificateChain :: Lens' ApnsConnectionParams CertificateChain

apnsConnectionParams_clientCertificateKey :: Lens' ApnsConnectionParams PrivKey

apnsConnectionParams_serverCertificateStore :: Lens' ApnsConnectionParams (Maybe CertificateStore)

apnsConnectionParams_onDebugLog :: Lens' ApnsConnectionParams (Text -> IO ())

apnsConnectionParams_onServerCertificate :: Lens' ApnsConnectionParams (Maybe (CertificateStore -> ValidationCache -> ServiceID -> CertificateChain -> IO [FailedReason]))

apnsConnectionParams_onTermination :: Lens' ApnsConnectionParams (ApnsTerminationReason -> IO ())

apnsConnectionParams_readQueueSize :: Lens' ApnsConnectionParams Int

apnsConnectionParams_writeQueueSize :: Lens' ApnsConnectionParams Int

apnsConnectionParams_pushQueueSize :: Lens' ApnsConnectionParams Int

data ApnsConnectionError

Indication of reason for an APNs connection attempt failing before the main asynchronous processing could begin.

Constructors

ApnsConnectionErrorInvalidHostName HostName

The host name given as _apnsConnectionParams_hostName was not resolvable.

ApnsConnectionErrorConnectFailed HostName [IOException]

The host name and port given as _apnsConnectionParams_hostName and _apnsConnectionParams_portNumber could not be connected to on any of the resolved addresses. The exceptions generated when connections were attempted are given.

ApnsConnectionErrorInvalidServerPreface

The server did not initiate with a valid HTTP/2 server preface, defined as a SETTINGS frame. Typically this indicates that the host was not APNs, APNs is catastrophically down, or something along those lines.

ApnsConnectionErrorException SomeException

An unexpected error occurred while waiting for the server to complete the HTTP/2 handshake.

Instances

Show ApnsConnectionError

Defined in Network.Apns.Types

Methods

showsPrec :: Int -> ApnsConnectionError -> ShowS

show :: ApnsConnectionError -> String

showList :: [ApnsConnectionError] -> ShowS

_ApnsConnectionErrorInvalidHostName :: Prism' ApnsConnectionError HostName

_ApnsConnectionErrorConnectFailed :: Prism' ApnsConnectionError (HostName, [IOException])

_ApnsConnectionErrorInvalidServerPreface :: Prism' ApnsConnectionError ()

_ApnsConnectionErrorException :: Prism' ApnsConnectionError SomeException

data ApnsConnection

An established APNs connection. In the future this should get metric and status reporting functions.

Constructors

ApnsConnection

Fields

• _apnsConnection_submitPush :: ApnsPush -> IO ()

  Submit a push message. This should never fail immediately and any result of the push attempt should be reported via the _apnsPush_callback

• _apnsConnection_close :: IO ()

  Close the APNs connection in an orderly fashion. The _apnsConnectionParams_onTermination callback will be triggered with ApnsTerminatedLocally if the connection closes correctly.

apnsConnection_submitPush :: Lens' ApnsConnection (ApnsPush -> IO ())

apnsConnection_close :: Lens' ApnsConnection (IO ())