WireAPI

Top

The Wire API allows clients to subscribe and publish to Volt wire resources.

PublishWire()

Establishes a client-streaming call to the wire resource.

Request: streaming PublishWireRequest
Response: streaming PublishWireResponse

SubscribeWire()

Establishes a bi-directional streaming call to the wire resource.

Although we're only really interested in receiving data from the wire, a bi-directional stream is required so that we can gracefully stop the subscription.

Request: streaming SubscribeWireRequest
Response: streaming SubscribeWireResponse

PublishWireRequest

Because the publish RPC is streaming, the policy will not be checked until the first message arrives. This can mean that the `PublishWire` call appears to succeed but then fails after the first attempt to publish a message.

To avoid this, clients can immediately send a message with the `wire_id` set and no `chunk` set. This will establish that the correct permissions are in place and fail fast if not.

FieldTypeDescription
wire_idstring

Only necessary in the first payload.

chunkbytes

The chunk of data to publish.

do_not_persistbool

Whether to persist the chunk.

This is only valid if the wire is configured to persist messages, i.e. the `volt:wire-persist` attribute is true.

PublishWireResponse

FieldTypeDescription
statusStatus

Details of any error that occurred on the call.

SubscribeWireRequest

The request must include one of the following fields.

FieldTypeDescription
wire_idstring

The wire id, only required for the first message.

stopbool

Request to stop the subscription.

SubscribeWireResponse

One of the following fields will be present in the response.

FieldTypeDescription
statusStatus

Details of any error that occured on the call.

chunkbytes

Data received from the wire.

Status

FieldTypeDescription
codeint32

A simple error code that can be easily handled by the client.

Mirrors the grpc StatusCode enum, 0 => OK

messagestring

A developer-facing human-readable error message in English. It should both explain the error and offer an actionable resolution to it.

descriptionstring

Long form error description.

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
doubledoubledoublefloatfloat64doublefloatFloat
floatfloatfloatfloatfloat32floatfloatFloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intintint32intintegerBignum or Fixnum (as required)
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/longint64longinteger/stringBignum
uint32Uses variable-length encoding.uint32intint/longuint32uintintegerBignum or Fixnum (as required)
uint64Uses variable-length encoding.uint64longint/longuint64ulonginteger/stringBignum or Fixnum (as required)
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intintint32intintegerBignum or Fixnum (as required)
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/longint64longinteger/stringBignum
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intintuint32uintintegerBignum or Fixnum (as required)
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/longuint64ulonginteger/stringBignum
sfixed32Always four bytes.int32intintint32intintegerBignum or Fixnum (as required)
sfixed64Always eight bytes.int64longint/longint64longinteger/stringBignum
boolboolbooleanbooleanboolboolbooleanTrueClass/FalseClass
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicodestringstringstringString (UTF-8)
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr[]byteByteStringstringString (ASCII-8BIT)