| Authors: | Joe Gregorio |
|---|---|
| Version: | 2.0 - May 2010 |
This whitepaper is part of a series. All of the whitepapers can be found on Google Wave Federation Protocol site.
To provide feedback on this draft join the wave-protocol mailing list at http://groups.google.com/group/wave-protocol
This current draft only covers a small subset of the functionality that is required to build a full client. Future drafts will expand to cover more functionality.
This document describes the protocol by which a wave client communicates with a wave server in order to create, read, and modify waves. The protocol is defined in terms of JSON messages exchanged over WebSockets.
There is already a protocol being defined to handle the federation of Waves, however it was designed as a server-to-server protocol and is not well suited for clients. What is needed is a lighter weight protocol that only captures the needs of a client-server communication channel. The WebSockets protocol was chosen because it provides the two-way communication channel needed to efficiently handle wave messages, while being light weight and targeted to browsers, which are considered a primary platform for client developers.
This specification only covers the rudiments of the communication between a client and a server. There are many things that are not covered by this specification at this time, such as authentication, authorization, how a client determines which server to talk to, or which port to use. This protocol is a very simple client/server protocol implementation, and does not reflect the Google Wave web client protocol used in production today.
It is important to understand the Wave Federation Protocol and Conversation Model as a prerequisite to this specification.
The following terminology is used by this specification:
Wave messages do not include the WebSocket opening handshake messages.
This section assumes an elementary understanding of the theory of Operational Transforms.
In the current implementation the version of the protocol is carried in each message and if the server does not understand the version sent it closes the connection. Future revisions may have the client and server negotiate for an agreed upon protocol version.
The version of the protocol used is 1.
The protocol begins when a Wave client connects with a Wave server. The connection is handled by the WebSockets protocol. After the connection is initiated Wave messages are sent between the client and server encapsulated in WebSocket frames. Each message occupies a single frame.
There are two kinds of Wave requests, ProtocolOpenRequest and ProtocolSubmitRequest. Communication begins when a client sends a ProtocolOpenRequest to the server with the id of a Wave it wishes to monitor and/or mutate. After opening a wave the client may send ProtocolSubmitRequests to the server to manipulate the wave. The server will send ProtocolWaveletUpdates to the client as the server representation of the wave changes.
Any error messages related to the opening of a wave are sent back from the server in a ProtocolWaveletUpdate.
A client may send more than one ProtocolOpenRequest, one for each wave that the client is interested in.
The client MUST send a ProtocolOpenRequest for each wave that the client is interested in. A client MUST NOT send mutations for a wave id that it has not issued a ProtocolOpenRequest for. The client must wait for the server to acknowledge the ProtocolOpenRequest before sending ProtocolSubmitRequests for the given wave as it needs to include the document hash with each ProtocolSubmitRequest.
The ProtocolOpenRequest contains a wave id and a wavelet_id_prefix. Those two determine the set of wavelets that the client will be notified of changes to.
The wavelet_id_prefix may be shortened to match a larger subset of wavelets, with the empty string matching all wavelets in the given wave.
The client can indicate if it supports snapshots when it sends a ProtocolOpenRequest.
It also contains the protocol version number, which is defined as 1, per the previous section on Protocol Version.
In response to a ProtocolOpenRequest the server may send any number of ProtocolWaveletUpdate messages. The ProtocolWaveletUpdate may contain a snapshot of the current wave state or it will contain one or more ProtocolWaveletDelta messages that represent deltas to be applied to wavelets that the client is monitoring. The inclusion of the snapshot is determined by the server, it will only be sent on the first ProtocolWaveletUpdate, and will only be sent if the client has indicated in its ProtocolOpenRequest that it supports receiving snapshots.
ProtocolWaveletUpdate messages will only be sent for wavelets that the client is an explicit participant in.
This message contains a ProtocolWaveletDelta which the client requests the server to apply to a wave. Only one submit per wavelet may be outstanding at any one time.
The client specifies which version to apply the delta at, and the client is expected to transform deltas pending for submission against deltas received in ProtocolWaveletUpdates from the server.
ProtocolWaveletDelta's are applied atomically and either fully succeed, or the whole delta will fail.
The ProtocolSubmitResponse acknowledges the ProtocolSubmitRequest and if the delta was successfully applied it also supplies the ProtocolHashedVersion of the wavelet after the delta, which the client will need to successfully submit future deltas to the wavelet.
TBD
TBD
Creating a new wave is different from other flows since neither the client nor the server have the wave id. The client must generate a unique id for the wave and send a ProtocolOpenRequest for that wave id.
There is no standard serialization of Protocol Buffers into JSON. This section will define the serialization that is used to construct Wave Messages from the protocol buffers included in this specification.
Protocol buffer messages may be nested, so this serialization algorithm must be applied recursively.
The root level message is emitted as a JSON object. Each member of the message will be emitted as a key-value pair in the JSON object. Each member's key name in the JSON serialization is set to normalize(key), where normalize is a function that takes in the protocol buffer member key name and returns a JSON utf-8 string.
TBD
The serialization of a value for the key is dependent on the type and modifiers of that member. If the member is flagged as 'repeated' then the serialized value will be a JSON array. The array will be filled with the serialized values of the repeated members.
The following modifiers can be applied to message values and they alter how the values are serialized.
For each repeated member value, serialize it as JSON according to the following rules and add the serialization to the JSON array.
Required parameters are always serialized into JSON.
Optional parameters are only serialized if they appear in the protocol buffer.
A string member of a protocol buffer message is serialized as a JSON string.
An int32 or int64 member of a protocol buffer message is serialized as a JSON number.
A bool value is serialized as a JSON number with a value of 1 for true and 0 for false.
An enum value is serialized as a JSON string for the enumeration's value.
A bytes value is hex encoded and serialized as a JSON string.
A protocol buffer message is serialized by recursively applying the rules in this section.
Authorization is covered in the Access Control Whitepaper.
While the client server protocol is implemented as JSON over WebSockets, each Wave message is a JSON serialization of a protocol buffer. The protocol buffer definitions are defined as:
TBD
The current open source implementation of the client-server protocol begins with the client opening the wave "indexwave!indexwave". That is currently an implementation detail and is not documented.