Implement and provide message protocols for communication between Bokeh Servers and clients.
Protocol
Provide a message factory for a given version of the Bokeh Server message protocol.
version (str) – a string identifying a protocol version, e.g. “1.0”
assemble
Create a Message instance assembled from json fragments.
header_json (JSON) –
JSON
metadata_json (JSON) –
content_json (JSON) –
message
create
Create a new Message instance for the given type.
msgtype (str) –
Provide named exceptions having to do with handling Bokeh Protocol messages.
MessageError
Indicate an error in constructing a Bokeh Message object.
This exception usually indicates that the JSON fragments of a message cannot be decoded at all.
ProtocolError
Indicate an error in processing wire protocol fragments.
This exception indicates that decoded message fragments cannot be properly assembled.
ValidationError
Indicate an error validating wire protocol fragments.
This exception typically indicates that a binary message fragment was received when a text fragment was expected, or vice-versa.
Provide a base class for all Bokeh Server Protocol message types.
Boker messages are comprised of a sequence of JSON fragments. Specified as Python JSON-like data, messages have the general form:
[ # these are required b'{header}', # serialized header dict b'{metadata}', # serialized metadata dict b'{content}, # serialized content dict # these are optional, and come in pairs; header contains num_buffers b'{buf_header}', # serialized buffer header dict b'array' # raw buffer payload data ... ]
The header fragment will have the form:
header
header = { # these are required 'msgid' : <str> # a unique id for the message 'msgtype' : <str> # a message type, e.g. 'ACK', 'PATCH-DOC', etc # these are optional 'num_buffers' : <int> # the number of additional buffers, if any }
The metadata fragment may contain any arbitrary information. It is not processed by Bokeh for any purpose, but may be useful for external monitoring or instrumentation tools.
metadata
The content fragment is defined by the specific message type.
content
Message
The Message base class encapsulates creating, assembling, and validating the integrity of Bokeh Server messages. Additionally, it provide hooks
__init__
Initialize a new message from header, metadata, and content dictionaries.
To assemble a message from existing JSON fragments, use the assemble method.
To create new messages with automatically generated headers, use subclass create methods.
header (JSON-like) –
metadata (JSON-like) –
content (JSON-like) –
add_buffer
Associate a buffer header and payload with this message.
buf_header (JSON) – a buffer header
buf_payload (JSON or bytes) – a buffer payload
None
MessageError –
Creates a new message, assembled from JSON fragments.
Message subclass
assemble_buffer
Add a buffer header and payload that we read from the socket.
This differs from add_buffer() because we’re validating vs. the header’s num_buffers, instead of filling in the header.
ProtocolError –
create_header
Return a message header fragment dict.
request_id (str or None) – Message ID of the message this message replies to
a message header
dict
send
Send the message on the given connection.
conn (WebSocketHandler) – a WebSocketHandler to send messages
number of bytes sent
int
write_buffers
Write any buffer headers and payloads to the given connection.
conn (object) – May be any object with a write_message method. Typically, a Tornado WSHandler or WebSocketClientConnection
write_message
WSHandler
WebSocketClientConnection
locked (bool) –
complete
Returns whether all required parts of a message are present.
True if the message is complete, False otherwise
bool
register
Decorator to add a Message (and its revision) to the Protocol index.
Example
@register class some_msg_1(Message): msgtype = 'SOME-MSG' revision = 1 @classmethod def create(cls, **metadata): header = cls.create_header() content = {} return cls(header, metadata, content)
ACK
ack_1
Define the ACK message (revision 1) for acknowledging successful client connection to a Bokeh server.
The content fragment of for this message is empty.
Create an ACK message
Any keyword arguments will be put into the message metadata fragment as-is.
EVENT
event_1
Define the EVENT message (revision 1) for sending events between a Bokeh server and clients.
This message is currently only generated by clients.
notify_event
ERROR
error_1
Define the ERROR message (revision 1) for reporting error conditions back to a Bokeh server.
The content fragment of for this message is has the form:
{ 'text' : <error message text> # this is optional 'traceback' : <traceback text> }
Create an ERROR message
request_id (str) – The message ID for the message the precipitated the error.
text (str) – The text of any error message or traceback, etc.
Any additional keyword arguments will be put into the message metadata fragment as-is.
OK
ok_1
Define the OK message (revision 1) for acknowledging successful handling of a previous message.
Create an OK message
request_id (str) – The message ID for the message the precipitated the OK.
PATCH-DOC
patch_doc_1
Define the PATCH-DOC message (revision 1) for sending Document patch events between remote documents.
{ 'events' : <protocol document events> 'references' : <model references> }
apply_to_document
Create a PATCH-DOC message
events (list) – A list of patch events to apply to a document
process_document_events
Create a JSON string describing a patch to be applied as well as any optional buffers.
events – list of events to be translated into patches
JSON string which can be applied to make the given updates to obj as well as any optional buffers
str, list
PULL-DOC-REPLY
pull_doc_reply_1
Define the PULL-DOC-REPLY message (revision 1) for replying to Document pull requests from clients
{ 'doc' : <Document JSON> }
Create an PULL-DOC-REPLY message
request_id (str) – The message ID for the message that issues the pull request
document (Document) – The Document to reply with
PULL-DOC-REQ
pull_doc_req_1
Define the PULL-DOC-REQ message (revision 1) for requesting a Bokeh server reply with a new Bokeh Document.
Create an PULL-DOC-REQ message
PUSH-DOC
push_doc_1
Define the PUSH-DOC message (revision 1) for pushing Documents from clients to a Bokeh server.
push_to_document
SERVER-INFO-REPLY
server_info_reply_1
Define the SERVER-INFO-REPLY message (revision 1) for replying to Server info requests from clients.
{ 'version_info' : { 'bokeh' : <bokeh library version> 'server' : <bokeh server version> } }
Create an SERVER-INFO-REPLY message
request_id (str) – The message ID for the message that issues the info request
SERVER-INFO-REQ
server_info_req_1
Define the SERVER-INFO-REQ message (revision 1) for requesting a Bokeh server provide information about itself.
Create an SERVER-INFO-REQ message
Assemble WebSocket wire message fragments into complete Bokeh Server message objects that can be processed.
Receiver
Receive wire message fragments and assemble complete Bokeh server message objects.
On MessageError or ValidationError, the receiver will reset its state and attempt to consume a new message.
The fragment received can be either bytes or unicode, depending on the transport’s semantics (WebSocket allows both).
Configure a Receiver with a specific Bokeh protocol version.
protocol (Protocol) – A Bokeh protocol object to use to assemble collected message fragments.
consume
Consume individual protocol message fragments.
fragment (JSON) – A message fragment to assemble. When a complete message is assembled, the receiver state will reset to begin consuming a new message.
Provide definitions for Bokeh WebSocket protocol versions.
A protocol specification is a sequence of tuples of the form:
( (<message_type>, <revision>), (<message_type>, <revision>), ... )
Where <message_type> is string that identifies a message type, e.g, 'ACK', 'SERVER-INFO-REQ', etc. and <revision> is an integer that identifies what revision of the message this version of the protocol uses.
<message_type>
'ACK'
'SERVER-INFO-REQ'
<revision>
A protocol version is a string of the form '<major>.<minor>'. The guidelines for updating the major or minor version are:
'<major>.<minor>'
<major>
bump when new messages are added or deleted (and reset minor version to zero)
<minor>
bump when existing message revisions change
spec
A mapping of protocol versions to protocol specifications.
{ "1.0" : ( ("ACK", 1), ("OK", 1), ("ERROR", 1), ("EVENT", 1), ('SERVER-INFO-REPLY', 1), ('SERVER-INFO-REQ', 1), ('PULL-DOC-REQ', 1), ('PULL-DOC-REPLY', 1), ('PUSH-DOC', 1), ('PATCH-DOC', 1) ), }