Protobuf Protocol

Description

The protobuf protocol provides an interface to the Gemfire Cache Server using Google Protocol Buffers.  The exact specification of the interface can be found in the *.proto files included with the product release (packaged in $GEODE_HOME/tools/ClientProtocol/v1/geode-protobuf-definitions-{versionNumber}.zip), but the message format is also detailed in the Message Structure and Definition page.

Creating a Protobuf Connection

There are a few steps that need to be followed when connecting a client to server running the protobuf interface.

Binary Negotiation

After connecting to the server (and doing any socket level security negotiation such as SSL), the client will need to send a single byte to identify the protocol they are using.  For the protobuf protocol this byte should be 110.  Additionally once the client has identified that they'll be communicating via protobuf, they'll need to send one more byte describing the major version of the protobuf protocol they'll be speaking.  This will provide the server with enough information to exchange a protobuf handshake message with the client.

Handshake

The handshake message is used to fully establish the major and minor version of the protocol in use on the connection. The first message sent from a client to a server must be a handshake. Once the server accepts the client's handshake, it will guarantee that it's response messages match the client's protocol version, regardless of the version of protobuf being run on the server.

Authentication

If a server is set to require client authentication, the next message after handshake must be an authentication message. The exact requirements of this message may vary according to the security manager implemented on the server, but the message will always take the client credentials as a series of key, value string pairs.  Authentication is done at a connection level and once it succeeds, all future messages handled by that connection will be authorized against the credentials provided at authentication.

If a server does not require authentication, the client can immediately start sending region operations and is assumed to be authorized for any operation.  If the client tries to authenticate on such a server, it will respond with a AUTHENTICATION_NOT_SUPPORTED error.