.. contents:: Table of Contents :depth: 3 .. _ref_transport.proto: 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 .. index:: PatchSetWriteRequest .. _ref_market.mass.PatchSetWriteRequest: PatchSetWriteRequest ------------------------------------------------------------------ Used by authenticated clients to write events to the relay. Requires prior successful authentication. .. csv-table:: PatchSetWriteRequest type fields :header: "Field", "Type", "Label", "Description" :widths: auto "patch_set", ":ref:`ref_bytes`", "", "CBOR encoded" .. index:: SyncStatusRequest .. _ref_market.mass.SyncStatusRequest: SyncStatusRequest ------------------------------------------------------------------ Sent by the relay to signal the number of unpushed patches per subscription. .. csv-table:: SyncStatusRequest type fields :header: "Field", "Type", "Label", "Description" :widths: auto "subscription_id", ":ref:`ref_uint64`", "", "" "unpushed_patches", ":ref:`ref_uint64`", "", "" .. index:: PingRequest .. _ref_market.mass.PingRequest: 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 .. _ref_scala_types: Scalar Value Types ~~~~~~~~~~~~~~~~~~ .. _ref_double: double ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. csv-table:: double language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "double", "double", "double", "float", "float64", "double", "float", "Float" .. _ref_float: float ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. csv-table:: float language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "float", "float", "float", "float", "float32", "float", "float", "Float" .. _ref_int32: int32 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. .. csv-table:: int32 language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "int32", "int32", "int", "int", "int32", "int", "integer", "Bignum or Fixnum (as required)" .. _ref_int64: int64 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. .. csv-table:: int64 language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "int64", "int64", "long", "int/long", "int64", "long", "integer/string", "Bignum" .. _ref_uint32: uint32 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Uses variable-length encoding. .. csv-table:: uint32 language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "uint32", "uint32", "int", "int/long", "uint32", "uint", "integer", "Bignum or Fixnum (as required)" .. _ref_uint64: uint64 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Uses variable-length encoding. .. csv-table:: uint64 language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "uint64", "uint64", "long", "int/long", "uint64", "ulong", "integer/string", "Bignum or Fixnum (as required)" .. _ref_sint32: sint32 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. .. csv-table:: sint32 language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "sint32", "int32", "int", "int", "int32", "int", "integer", "Bignum or Fixnum (as required)" .. _ref_sint64: sint64 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. .. csv-table:: sint64 language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "sint64", "int64", "long", "int/long", "int64", "long", "integer/string", "Bignum" .. _ref_fixed32: fixed32 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Always four bytes. More efficient than uint32 if values are often greater than 2^28. .. csv-table:: fixed32 language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "fixed32", "uint32", "int", "int", "uint32", "uint", "integer", "Bignum or Fixnum (as required)" .. _ref_fixed64: fixed64 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Always eight bytes. More efficient than uint64 if values are often greater than 2^56. .. csv-table:: fixed64 language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "fixed64", "uint64", "long", "int/long", "uint64", "ulong", "integer/string", "Bignum" .. _ref_sfixed32: sfixed32 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Always four bytes. .. csv-table:: sfixed32 language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "sfixed32", "int32", "int", "int", "int32", "int", "integer", "Bignum or Fixnum (as required)" .. _ref_sfixed64: sfixed64 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Always eight bytes. .. csv-table:: sfixed64 language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "sfixed64", "int64", "long", "int/long", "int64", "long", "integer/string", "Bignum" .. _ref_bool: bool ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. csv-table:: bool language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "bool", "bool", "boolean", "boolean", "bool", "bool", "boolean", "TrueClass/FalseClass" .. _ref_string: string ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A string must always contain UTF-8 encoded or 7-bit ASCII text. .. csv-table:: string language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "string", "string", "String", "str/unicode", "string", "string", "string", "String (UTF-8)" .. _ref_bytes: bytes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ May contain any arbitrary sequence of bytes. .. csv-table:: bytes language representation :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" :widths: auto "bytes", "string", "ByteString", "str", "[]byte", "ByteString", "string", "String (ASCII-8BIT)"