transport.proto

This file defines the transport protocol between relays and clients. Its main purpose is transfer of events of the higher application levels. It is orthogonal to the Shop Registry and other smart contracts.

Messages must be prefixed with their accompanying encoding number as a single byte. encoding.txt defines the number for each message.

Furthermore, we expect only one message per write/binary frame. This means no buffering of multiple messages into a single write. The protocol offers repeated fields where appropriate for higher throughput. A suggested transport is WebSocket over HTTPS, but the protocol is agnostic, as long as the transport used can handle binary data and keeps the framing intact. This design, specifically the push from the relay to client, assumes the transport does not produce backpressure. No further pushes are sent until they are acknowledged by the client.

For upgrades there exists a VERSION file in the root of the repository. The VERSION is a single unsigned integer, incremented for each change. The client and relay must agree on the VERSION before starting the protocol. In the case of WebSocket, the VERSION can be compared via the URL. The relay must close the connection if the VERSION isn't supported.

As of this version, the protocol is grouped into 4 areas: 1) the transport (this file) 2) authentication for establishing access rights 3) shop specific request 4) shop events

PatchSetWriteRequest

Used by authenticated clients to write events to the relay. Requires prior successful authentication.

PatchSetWriteRequest type fields

Field	Type	Label	Description
patch_set	bytes		CBOR encoded

SyncStatusRequest

Sent by the relay to signal the number of unpushed patches per subscription.

SyncStatusRequest type fields

Field	Type	Label	Description
subscription_id	uint64
unpushed_patches	uint64

PingRequest

Sent by the relay to check for the client's liveness. The client needs to respond with a PingResponse. The relay will close the connection if the client doesn't respond 3 times.

empty

Scalar Value Types

double

double language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
double	double	double	float	float64	double	float	Float

float

float language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
float	float	float	float	float32	float	float	Float

int32

Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.

int32 language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
int32	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)

int64

Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.

int64 language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
int64	int64	long	int/long	int64	long	integer/string	Bignum

uint32

Uses variable-length encoding.

uint32 language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
uint32	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)

uint64

Uses variable-length encoding.

uint64 language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
uint64	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)

sint32

Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.

sint32 language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
sint32	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)

sint64

Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.

sint64 language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
sint64	int64	long	int/long	int64	long	integer/string	Bignum

fixed32

Always four bytes. More efficient than uint32 if values are often greater than 2^28.

fixed32 language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
fixed32	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)

fixed64

Always eight bytes. More efficient than uint64 if values are often greater than 2^56.

fixed64 language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
fixed64	uint64	long	int/long	uint64	ulong	integer/string	Bignum

sfixed32

Always four bytes.

sfixed32 language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
sfixed32	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)

sfixed64

Always eight bytes.

sfixed64 language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
sfixed64	int64	long	int/long	int64	long	integer/string	Bignum

bool

bool language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
bool	bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass

string

A string must always contain UTF-8 encoded or 7-bit ASCII text.

string language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
string	string	String	str/unicode	string	string	string	String (UTF-8)

bytes

May contain any arbitrary sequence of bytes.

bytes language representation

.proto Type	C++	Java	Python	Go	C#	PHP	Ruby
bytes	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)