Pubkeeper Protocol V1.1

Client - Server Protocol

Framing

The Pubkeeper Protocol uses a framed packet to transmit data between client and server. The frame header is in Little-Endian order, and is 8 bytes long, not including payload.

2 bytes - Packet Type
2 bytes - Low Payload Length [in v1.0 - this was total length]
1 byte  - Flags [Introduced in v1.1]
2 bytes - High Payload Length [Introduced in v1.1]
1 byte  - Padding
N bytes - Payload

ChangeLog

  • v1.1 - v1.0 of the protocol had a small bug where packet frames were packed with only 2 bytes to denote frame length. This limited packets to being only 65536 bytes long. This version expands the length to 4 bytes. The rest of the protocol is untouched.

Client - Client Protocol

Framing

The Pubkeeper Protocol also dictates how clients communicate with each other once matched by a server. The data brewed to patrons is also framed to allow structured communication. The header is also in Little-Endian format and is 88 bytes in length, not including payload.

1 byte   - Major Version
1 byte   - Minor Version
32 bytes - Topic String
16 bytes - Brewer ID
34 bytes - Padding
4 bytes  - Payload Length
N bytes  - Payload

Protocol Packets

Client authenticate

token—token for authentication

{
    token: 'your_pk_token'
}

This method should be the first packet to the Pubkeeper server from a client. You provide the server a token which will have been issued to you by the administrator of the server. The token should have an issuer and audience of Pubkeeper, and the subject should be your client. The token will also contain an array of rights associated with this token. The client will receive a client_authenticated packet back from the server in response to a valid token.

Client authenticated

authenticated—Your authenticated status

{
    authenticated: True
}

In response to every client_authenticate packet, you will receive this packet back which informs you of the current authentication status with the Pubkeeper server.

Brewer register

topic—Topic of publication, this may not contain a wildcard brewer_id—UUID of the brewer brews—List of the brews supported and specific information about each brew

{
    topic: 'test.topic',
    brewer_id: 'xxxxxxxxxxxxxxxxxxxx',
    brews: [
        {
            name: 'websocket',
            hostname: 'localhost',
            port: 9899
        }
    ]
}

This method registers a single brewer with the network. A set of brews signifies the multiple different protocols this brewer can support and how to acquire the data being produced. This action will trigger the sending of brewer_notify packets to subscribed patrons.

Brewer unregister

topic—Topic you are unregistering from brewer_id—UUID of the Brewer

{
    topic: 'test.topic',
    brewer_id: 'xxxxxxxxxxxxxxxxxxxx'
}

This method is the inverse of brewer_register, and will instruct the Pubkeeper server to remove the listed brewer for the topic.

Brewer notify

patron_id—UUID of the client's patron brewers—List of remote brewers publishing to this patron's topic

  • topic—Topic brewer is publishing to
  • brewer_id—UUID of the remote brewer
  • brewer_config—Configuration of the remote brewer
  • brew—The brewer's brew configuration options
{
    patron_id: 'xxxxxxxxxxxxxxxxxxxx',
    brewers: [
        {
            topic: 'test.topic',
            brewer_id: 'xxxxxxxxxxxxxxxxxxxx',
            brewer_config: {
                'crypto': {
                    'cipher_key': 'xxxxxxxxxx',
                    'cipher_mode': x
                }
            },
            brew: {
                name: 'websocket',
                hostname: 'localhost',
                port: 9899
            }
        }
    ]
}

This method is sent to the client from the Pubkeeper server to inform them of new brewer(s) on the network. The provided configuration is from the registration of the brewer. This is passed to the client so it can correctly find the produced data. After a patron_register packet is sent, the server will respond with a set of all the currently matched brewers for the topic. This may include an empty set of brewers, alerting the client that there are currently no brewers for that topic. The full topic is included with each brewer since the patron may have subscribed to a topic that contains a wildcard.

Brewer removed

topic—Topic of new brewer patron_id—UUID of the client's patron brewer_id—UUID of the remote brewer

{
    topic: 'test.topic',
    patron_id: 'xxxxxxxxxxxxxxxxxxxx'
    brewer_id: 'xxxxxxxxxxxxxxxxxxxx'
}

This method, the inverse of brewer_notify, will be sent out to clients who are subscribed to this brewer to inform them the brewer is no longer on the network.

Patron register

topic—Topic you are registering to patron_id—UUID of the patron brews—Array of the brews supported and specific information about the brew

{
    topic: 'test.topic',
    patron_id: 'xxxxxxxxxxxxxxxxxxxx',
    brews: [
        {
            name: 'websocket'
        }
    ]
}

This method registerers a single patron with the network. A set of brews signifies the multiple different protocols this patron can support. Any additional information provided will be given to the brewers this patron will patronize. This action will trigger the sending of patron_notify packets to subscribed brewers.

Patron unregister

topic—Topic you are unregistering from patron_id—UUID of the patron

{
    topic: 'test.topic',
    patron_id: 'xxxxxxxxxxxxxxxxxxxx'
}

This method is the inverse of patron_register, and will instruct the Pubkeeper server to remove the listed patron for the topic. This action, will trigger the sending of a patron_removed packet to brewers who were publishing to this patron.

Patron notify

brewer_id—UUID of the brewer patrons—List of patrons the client is being notified of

  • patron_id—UUID of the network brewer
  • brew—The patron brew configuration options
{
    brewer_id: 'xxxxxxxxxxxxxxxxxxxx',
    patrons: [
        {
            patron_id: 'xxxxxxxxxxxxxxxxxxxx',
            brew: {
                name: 'websocket'
            }
        }
    ]
}

This method is sent to the client from the Pubkeeper server to inform them of a new patron on the network. The provided configuration is from the registration of the patron. This information is passed to brewers of the given topic, so they know who is consuming their topic. The goal is for brewers with no subscribers to conserve resources and not attempt to publish information if no one is reading.

Patron removed

topic—Topic of new brewer brewer_id—UUID of the client brewer patron_id—UUID of the remote patron

{
    topic: 'test.topic',
    brewer_id: 'xxxxxxxxxxxxxxxxxxxx'
    patron_id: 'xxxxxxxxxxxxxxxxxxxx'
}

This method, the inverse of patron_notify, will be sent out to brewers alerting them that this patron has left the network and is no longer subscribed to them.

Brews register

brews—Set of brews to register bridge_mode—Is this client able to be a bridge

{
    brews: [
        'websocket',
        'zmq'
    ],
    bridge_mode: True
}

This method registers the brews a client has registered and if these brews may be used to bridge data.

Brew state

brew_name—Brew name to alter state state—A brew's current state

{
    brew: 'websocket',
    state: 0
}

Update the state of a given brew with the server. Depending on the state, the Pubkeeper server may act on the brew differently. For instance, a brew in an error state will not be used for matching or bridging purposes. The value of state may be 0: Operational, 1: Error

Segment create

segment_id—UUID of the segment being created patron_details—Information for a patron to be created by this segment brewer_details—Information for a brewer to be created by this segment

{
    segment_id: 'xxxxxxxxxxxxxxxxxxxx',
    patron_details: {
        patron_id: 'xxxxxxxxxxxxxxxxxxxx',
        brewer_id: 'xxxxxxxxxxxxxxxxxxxx',
        topic: 'test.topic',
        brew: {
            name: 'websocket',
            hostname: 'localhost',
            port: 9899
        }
    }
    brewer_details: {
        brewer_id: 'xxxxxxxxxxxxxxxxxxxx',
        topic: 'segment.topic',
        brew: {
            name: 'zmq'
        }
    }
}

[info] note

The segment packet documentation is describing what packets would look like for a single segment created bridging a WebSocket brewer and a ZMQ patron.

This packet, only sent when a client is acting in bridge_mode, will instruct the client to create a segment for a server-determined bridge. The client will receive instruction to create a patron and to create a brewer. The server will determine the patron and brewer IDs that will be created by this client. The server may also use randomly generated topics between segment links. The client will act upon this message by creating a patron with the provided patronid for the provided brewer information. It will also create a brewer with the given brewer_id publishing on the provided topic on the given brew type. The client should then directly link the callback of the patron to the output of the brewer in order to translate the incoming messages out to the next protocol. After set up, the client _must respond back to the server with a segment_register packet.

Segment register

segment_id—UUID of the segment brewer_brew—Brewer configured as result of a segment_create patron_brew—Patron configured as result of a segment_create

{
    segment_id: 'xxxxxxxxxxxxxxxxxxxx',
    brewer_brew: {
        name: 'zmq',
        publisher_url: 'tcp://x.x.x.x:xxxx',
    }
    patron_brew: {
        name: 'websocket'
    }
}

[info] note

The segment packet documentation is describing what packets would look like for a single segment created bridging a WebSocket brewer and a ZMQ patron.

This is the response of the segment_create. As you can see, the brewer_brew response here is the parity of the brewer from segment_create and the patron_brew is the parity of the patron from segment_create. The server will relay necessary information to previous—or subsequent—segments or to the actual brewer and patron.

Segment connect brewer

segment_id—UUID of the segment patron_id—UUID of the patron to your brewer in the segment patron_brew—Actual patron brew your segment is brewing to

{
    segment_id: 'xxxxxxxxxxxxxxxxxxxx',
    patron_id: 'xxxxxxxxxxxxxxxxxxxx',
    patron_brew: {
        name: 'zmq'
    }
}

[info] note

The segment packet documentation is describing what packets would look like for a single segment created bridging a WebSocket brewer and a ZMQ patron.

After the server handles the segment_register packet, it will respond to the segment providing its brewer with the patron information about who they are brewing to. For this example, the real ZMQ patron has already informed the server that its patron brew details are only a name element. However, since we do not know how many segments may be in a bridge, they all follow the same pattern, by providing the patron details through this packet.

Segment destroy

segment_id—UUID of the segment being destroyed

{
    segment_id: 'xxxxxxxxxxxxxxxxxxxx',
}

When the server sends this packet, the bridge is no longer deemed necessary. This might be because a segment of the bridge has been disconnected and we'll have to rebuild, or, the brewer or patron of the bridge no longer subscribe to each other. Regardless, the client is to tear down all resources managed for the segment.

Error

message—Message of the error

{
    message: 'Something bad happened',
}

This method sends an error message to the other end of the connection. This is generally useful for alerting when a non-connection-terminating problem is encountered. An example would be when a client attempts to access a method when it doesn't have rights, so it receives an error message.

results matching ""

    No results matching ""