PZQ Sockets & Formats

PZQ has 3 sockets that can be accessed: a 'receive' socket where messages are added to the queue, a 'send' socket where they are sent on to the message receivers, and a 'monitor' socket that can be queried for information about the status of the PZQ instance itself.

Producers

PZQ refers to clients that add messages to the queue as 'producers'. They connect on the 'receive' PZQ socket with a ZeroMQ DEALER type socket. Messages are multipart ZeroMQ messages which consist of the following parts:

[0] - The identity of the message - this will be used to acknowledge PZQ has received it
[1] - A blank message part (length 0)
[2] - The body of the message

There may be more parts, which will be passed through PZQ unmodified. After sending, the producer should listen for a response from PZQ, which will consist of the following parts:

[0] - The identity of the message being acknowledged 
[1] - The string 'OK'

The producer should maintain a list of messages sent (if more than one) and mark off acknowledged IDs. If the second message part is 'NO' or any string other than OK, the producer should assume the message has not been registered successfully.

Consumers

Clients that accept messages from PZQ are referred to as 'consumers', and connect on the 'send' PZQ socket with a ROUTER type ZeroMQ socket. Consumers will receive a multipart ZeroMQ message with the following structure:

[0] - The identity of the PZQ instance
[1] - The identity of the message 
[2] - The time the message was sent as a microsecond timestamp
[3] - The acknowledgement timeout, in microseconds
[4] - The first part of the message body. 

More parts may be available, and should be consumed as normal and treated as part of the passed message.

Part 0 is used to allow replying to PZQ through the ROUTER socket used, and also to allow a client to consumer from multiple PZQ instances simply by connecting to each one.

Part 1 is a unique identity for the message, and should be used in the acknowledgement, and to ensure duplicate messages have not been received, if required.

Parts 2 and 3 are used to allow detection of expired messages. If the current time as a microsecond timestamp is greater than the sent time + the ack timeout, then the client can assume the message will be resent, and discard it. This may reduce instances of duplicate messages received.

On processing a message, the consumer should acknowledge it, to prevent resending and allow PZQ to remove the message from it's store. The acknowledgement should be sent back through the socket, as a ZeroMQ message with the following structure:

[0] - The PZQ identity
[1] - A blank message part
[2] - The identity of the message

If the message is not processed successfully and should be resent, the consumer simply need to not acknowledge the message, and it will be resent.

Monitoring

Monitoring code must create a REQ socket, and connect to the monitor PZQ socket. The monitor responds to a request containing the ASCII string "MONITOR" with a single part message. This will include multiple lines of monitoring information, which can be exploded by splitting field on the \n newline character, and then key from value on the colon ':'. An example response:

messages: 0
messages_in_flight: 0
db_size: 1438720
in_flightdb_size: 8390432
syncs: 16694
expired_messages: 6