Network.Apns.Internal

Documentation

data ReaderEvent

Event emitted by the reader thread.

Constructors

ReadFrame Frame

Reader read a well formed and not obviously wrong HTTP2 frame which is not a SETTINGS frame.

ReadSettingsUpdate Settings

Reader encountered a SETTINGS frame and updated its internal settings. The SETTINGS frame still needs to be adopted by the processor and acknowledged.

ReadH2Error ErrorCodeId ByteString ApnsTerminationReason

Reader failed to process incoming data due to some catastrophic protocol error.

Instances

Show ReaderEvent

Defined in Network.Apns.Internal

Methods

showsPrec :: Int -> ReaderEvent -> ShowS

show :: ReaderEvent -> String

showList :: [ReaderEvent] -> ShowS

data Context

Environmental context for the processing system, passed around as a ReaderT.

Constructors

Context

Fields

• _context_params :: ApnsConnectionParams

  The ApnsConnectionParams used to open the connection.

• _context_authority :: ByteString

  The cached HTTP authority value sent with each request.

• _context_closingTv :: TVar (Maybe ApnsTerminationReason)

  TVar that is Just when the connection is being closed due to local or remote action but not all streams have been processed yet.

• _context_pushQueue :: TBMQueue ApnsPush

  The TBMQueue that _apnsConnection_submitPush enqueues using. If this queue is closed, then the connection is closed and can't deliver any more push notifications.

• _context_read :: STM (Either ApnsTerminationReason ReaderEvent)

  STM action which dequeues either a reader failure or reader event from the read queue.

• _context_write :: EncodeInfo -> FramePayload -> STM (Either ApnsTerminationReason ())

  STM action which enqueues an HTTP/2 frame to write.

• _context_encodingTable :: DynamicTable

  The HPACK dynamic table for encoding.

• _context_decodingTable :: DynamicTable

  The HPACK dynamic table for decoding.

data State

The dynamic state of the processing system, passed around as a StateT.

Constructors

State

Fields

• _state_nextStreamId :: StreamId

  The next stream ID to assign to a new push.

• _state_settings :: Settings

  The current settings as accepted and acknowledged by the processor.

• _state_connectionWindow :: WindowSize

  How many DATA payload bytes can be written to the connection for any stream before a WINDOW_UPDATE frame from the server is required.

• _state_writableStreams :: IntMap WritableStream

  Streams that are currently writing out their payload data but have had their headers already sent along. Streams will be written out as quickly as flow-control windows allow.

• _state_readableStreams :: IntMap (ApnsPush, ReadableStream)

  Streams whose request bodies have been fully transmitted via DATA frames and now are waiting for server frames to complete the response.

data WritableStream

Data associated with a single push stream which is in the process of being written to the server as DATA frames. Streams are written as fast as flow-control windows allow, so this structure is mostly concerned with tracking that.

Constructors

WritableStream

Fields

• _writableStream_push :: ApnsPush

  The ApnsPush that this stream is associated with.

• _writableStream_windowSize :: WindowSize

  The remaining bytes of payload that can be sent for this stream, assuming the connection flow-control window allows for it. Each DATA frame that goes out will decrement this by the size of its payload.

• _writableStream_remaining :: ByteString

  The request body content still to be written. Each DATA frame that goes out will drop the sent bytes from the front of this bytestring.

data ReadableStream

Data associated with a stream which the processor is waiting for server frames to move along.

Constructors

StreamWaiting

So far nothing has been received from the server for the stream.

StreamReadingHeaderContinuation ByteString

A HEADERS frame without the END_HEADERS or END_STREAM flags was received, so the processor is expecting one or more CONTINUATION frames.

StreamReadingBody HeaderList ByteString

A HEADERS/CONTINUATION with END_HEADERS set but END_STREAM not set was received, so the processor is expecting zero or more DATA frames constituting the response body.

StreamReadingTrailerContinuation HeaderList ByteString ByteString

A HEADERS frame after the initial HEADERS frame and zero or more DATA frames was received with the END_STREAM flag but not the END_HEADERS flag, so the processor is expecting one or more CONTINUATION frames, the last of which will finish the stream.

context_write :: Lens' Context (EncodeInfo -> FramePayload -> STM (Either ApnsTerminationReason ()))

context_read :: Lens' Context (STM (Either ApnsTerminationReason ReaderEvent))

context_pushQueue :: Lens' Context (TBMQueue ApnsPush)

context_params :: Lens' Context ApnsConnectionParams

context_encodingTable :: Lens' Context DynamicTable

context_decodingTable :: Lens' Context DynamicTable

context_closingTv :: Lens' Context (TVar (Maybe ApnsTerminationReason))

context_authority :: Lens' Context ByteString

state_writableStreams :: Lens' State (IntMap WritableStream)

state_settings :: Lens' State Settings

state_readableStreams :: Lens' State (IntMap (ApnsPush, ReadableStream))

state_nextStreamId :: Lens' State StreamId

state_connectionWindow :: Lens' State WindowSize

writableStream_windowSize :: Lens' WritableStream WindowSize

writableStream_remaining :: Lens' WritableStream ByteString

writableStream_push :: Lens' WritableStream ApnsPush

_StreamReadingTrailerContinuation :: Prism' ReadableStream (HeaderList, ByteString, ByteString)

_StreamReadingBody :: Prism' ReadableStream (HeaderList, ByteString)

_StreamReadingHeaderContinuation :: Prism' ReadableStream ByteString

_StreamWaiting :: Prism' ReadableStream ()

type ProcessorM = ExceptT ApnsTerminationReason (StateT State (ReaderT Context IO))

The monad stack used within the processing system.

processorDebug :: (MonadReader Context m, MonadIO m) => Text -> m ()

Emit some debug log message.

processorWrite :: EncodeInfo -> FramePayload -> ProcessorM ()

Enqueue a HTTP2 frame to be written. Not appropriate for HEADERSCONTINUATION as there's no guarantee of atomicity for a series of writes.

processorWriteMany :: [(EncodeInfo, FramePayload)] -> ProcessorM ()

Enqueue many frames to be Written as one contiguous block with no gaps, e.g. as for HEADERS/CONTINUATION sequences.

invokeWithoutException :: MonadIO m => IO () -> m ()

Invoke some callback function in IO where we don't care at all about exceptions.

connectApns :: forall m. MonadIO m => ApnsConnectionParams -> m (Either ApnsConnectionError ApnsConnection)

Establish a single connection to APNs, yielding Right ApnsConnection on success, Left ApnsConnectionError otherwise.

processor :: ApnsConnectionParams -> Context -> Socket -> IO (Either ApnsConnectionError ApnsConnection)

Main processing for an APNs connection which sets up the reading and writing threads for exchanging HTTP/2 frames over an established TLS connection, finishes the HTTP/2 connection initiation, and then forks off the asynchronous processing.

writePhase :: ProcessorM ()

Perform the write phase, writing as many DATA frames as the flow-control windows will allow us

postWritePhase :: Bool -> ProcessorM ()

Perform the post-write phase, where incoming messages, work, and other state changes are processed prior to returning to the write phase

at this point one of the following conditions is true: the connection flow control window has been exhausted, all stream flow-control windows have been exhausted, all streams have been written out and are waiting for a server response, or there are no pending pushes so now we wait for one of the following things to happen: an incoming SETTINGS frame, which we need to adopt and might change the initial window size and thus all flow-control windows an incoming WINDOW_UPDATE frame, which expands one of the flow-control windows a PING frame which we respond to immediately a PRIORITY frame which we ignore a PUSH_PROMISE frame which we complain about mightily a HEADERSCONTINUATIONDATA/RST_STREAM frame which advances the read state of some stream a GOAWAY frame which causes us to go into the closing state and signal any dropped pushes as dropped

The Bool argument indicates whether this postWritePhase follows another post write phase which either adjusted flow-control windows or added streams and thus controls whether this should block waiting for more to do or can immediately enter a write phase as soon as other work has been handled.

processReaderEvent :: Bool -> ReaderEvent -> ProcessorM ()

Process a reader event in the postWritePhase. This boils down to propagating a failure if the reader failed, adopting and acknowleding new settings if the reader received and processed a SETTINGS frame, or case switching on the received frame and doing various state things based on the frame.

The Bool is the haveUpdatedWindowsOrStreams flag propagating for this postWritePhase

processUpdatedSettings :: Settings -> ProcessorM Bool

Do the work required when receiving new settings from the server, such as acknowledging the update. This is a separate function since it's used both by the preface and the receive frame processing. Yields True iff the window sizes were updated.

processReadFrame :: Bool -> Frame -> ProcessorM ()

Process an incoming frame which is not a SETTINGS frame.

processNewPush :: Bool -> ApnsPush -> ProcessorM ()

Process a new ApnsPush by allocating a stream for it, sending its headers, and preparing to write the body data for it, then continuing on with the postWritePhase in progress.

headersForPush :: ByteString -> ApnsPush -> HeaderList

Given an ApnsPush, compose the list of headers that should be sent for it.

encodeHeaderBlockFragments :: Int -> DynamicTable -> HeaderList -> IO [HeaderBlockFragment]

Given the maximum frame size, a HeaderList, and the DynamicTable for encoding, encode a list of headers into a list of header block fragments. The first such fragment gets sent in a HEADERS frame while the subsequent ones if any get sent in a CONTINUATION frame.

reader :: (Text -> IO ()) -> Context -> Socket -> TBMQueue ReaderEvent -> IO ()

Reader thread. Before this exits, some debug log will be emitted, the socket will be shut down for reads, and the reader queue will be closed.

writer :: (Text -> IO ()) -> Context -> Socket -> TBMQueue (EncodeInfo, FramePayload) -> IO ()

Writer thread. Before this exits, some debug log will be emitted, the socket will be shut down for writes, and the writer queue will be closed.