Websocket protocol

All messages are encoded as a space separated list. The first part of a message is always a numeric message type followed by message specific fields.

Message id

Most messages require a message_id to be sent. Both server and client must implement it as a counter without gaps starting at 1. It is used to match match request and response messages together and provide reliable messaging even in case of a unexpected connection timeout.

Message types

The following message types are supported:

CodeMessage type
0Heartbeat
1Notification
2Request
3Response
4Error response
-1Disconnect

Heartbeat

The heartbeat is used by the client and server to acknowledge messages and keep the connection alive if there has been no traffic for a given amount of time. For transports that do not keep the connection open for an unlimited amount of time this is used for polling.

FieldTypeDescription
message_typeIntegerConstant 0
last_message_idIntegerThe last message id of the remote side that has been received.

Example:

0 42

Notification

Send a notification to the remote side and do not expect a response. This message type is especially useful to implement broadcasts from the server to the client where no response is expected. Implementations of webwire MUST NOT expect a response to a notification.

Fields:

FieldTypeDescription
message_typeIntegerConstant 1
message_idIntegerThe id of the message.
methodFQMNThe fully qualified method name of the method to be called.
dataBinaryThe data field captures the rest of the frame and is treated as binary.

Example:

1 43 example.hello peter

Request

Send a request to the remote side and expect a response.

FieldTypeDescription
message_typeIntegerConstant 2
message_idIntegerThe id of the message.
methodFQMNThe fully qualified method name of the method to be called.
dataBinaryThe data field captures the rest of the frame and is treated as binary.

Example:

2 44 example.get_version

Response

This message is sent in response to a request if the remote method could be called successfully.

FieldTypeDescription
message_typeIntegerConstant 3
message_idIntegerThe id of the message.
request_message_idIntegerThe id of the message that started the request.
dataBinaryThe data field captures the rest of the frame and is treated as binary.

Example:

3 7 44 "1.4.9"

Error response

This message is sent in response to a request if the remote side encountered an error while processing the request. Please note that this message type MUST NOT be used to encode application level errors. This is only meant to be used for errors which are outside of the application scope. e.g. parser errors, data validation, internal server errors, etc.

FieldTypeDescription
message_typeIntegerConstant 4
message_idIntegerThe id of the message.
request_message_idIntegerThe id of the message that started the request.
error_codeBinaryThe data field captures the rest of the frame and is treated as binary.
error_messageStringOptional error message.

Example:

4 7 44 MethodNotFound

Disconnect

Terminate the current connection. The remote side should respond with a -1 and close the connection.

FieldTypeDescription
message_typeIntegerConstant -1

Example:

-1

Example communication

Assuming the connection has been up for a while and the server has now reached message id 117. The client has sent 5 messages so far and the next message id is 5.

  1. Heartbeat (client to server):

    0 117
    
  2. Heartbeat (server to client):

    0 4
    
  3. Notification (client to server):

    1 5 Player.ready true
    
  4. Request (client to server):

    2 6 get_time
    
  5. Response (server to client):

    3 118 6 1342106240