Protocol Buffers Payload

For communication between Avid Connector API and Secure Gateway, Google Protocol Buffers payload is used.

Protocol Buffer Message Structure

Avid Connector API Protocol buffer file is following

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
syntax = "proto3";

package protobuf;
option java_package = "com.avid.acs.ipc.protobuf";
option java_outer_classname = "BusIpcProtobufGenerated";
option csharp_namespace = "Google.Protobuf.Generated";

option optimize_for = SPEED;

enum SGVariantType { VT_UNKNOWN = 0; VT_STRING = 1; VT_BOOL = 2;
VT_INT32 = 3; VT_INT64 = 4; VT_FLOAT= 5; VT_DOUBLE = 6;
VT_BYTES = 7; VT_MAP = 8; VT_LIST = 9; }

message SGVariant {
SGVariantType type = 1;
oneof value_oneof {
string stringValue = 2;
bool boolValue = 3;
int32 intValue = 4;
int64 longValue = 5;
float floatValue = 6;
double doubleValue = 7;
bytes bytesValue = 8;
SGVariantMap mapValue = 9;
SGVariantList listValue = 10;
}
}

message SGVariantPair {
string key = 1;
SGVariant value = 2;
}

message SGVariantMap {
repeated SGVariantPair entrySet = 1;
}

message SGVariantList {
repeated SGVariant value = 1;
}

message SGPacket {
message SGHeader {
string version = 1;
string requestId = 2;
string instanceId = 3;
SGVariantMap options = 4;
}

message SGGenericData {
string action = 1;
SGVariantMap metadata = 2;
bytes body = 3;
}

// For future more specific data
// message SG{Specific}Data {
// }

SGHeader header = 1;
oneof packetData_oneof {
SGGenericData genericData = 2;
// For future more specific data
SGRequestData = 3;
}
}

This file can be used to generate stubs for any language, supported by Google Protocol Buffers compiler.

Note, that message has two fields, which returns byte arrays:

  • SGVariant→bytesValue = 8;
  • SGPacket→SGData→body = 3;

Values of these fields depends on value of SGPacket→SGData→action.

Content of the package depends on the value of the SGPacket→SGData→action field.

Messages can be sent by Avid Connector API to Secure Gateway and vise versa. Action which are sent from Avid Connector API to Secure Gateway have name prefix bal_to_sg_. Actions which are sent from Secure Gateway to Avid Connector API have name prefix sg_to_bal_.

Available Actions

The following actions can be sent by Avid Connector API, and must be handled by Secure Gateway:

  • bal_to_sg_connect - connect instance to Secure Gateway
  • bal_to_sg_disconnect - disconnect instance from Secure Gateway
  • bal_to_sg_register - register service instance
  • bal_to_sg_unregister - unregister service instance
  • bal_to_sg_request - outgoing request to service (query, send or broadcast)
  • bal_to_sg_post - posting message to channel
  • bal_to_sg_subscribe - subscribing to channel
  • bal_to_sg_unsubscribe - unsubscribing from channel(s)
  • bal_to_sg_response - deliver service response
  • bal_to_sg_ack - sends message handled acknowledgement
  • bal_to_sg_environment - request environment information
  • bal_to_sg_status - set service status

The following actions can be sent by Secure Gateway must be handled by Avid Connector API:

  • sg_to_bal_request - deliver request to service (query, send or broadcast)
  • sg_to_bal_post - deliver channel message to subscriber
  • sg_to_bal_response - deliver service response
  • sg_to_bal_configure - configure service
  • sg_to_bal_control - control service
  • sg_to_bal_environment - return environment information
  • sg_to_bal_acknowledged - acknowledgement of a completed action.
  • sg_to_bal_set_status - propagate service status changes to the API, if it was changed by Secure Gateway or from Service Manager

Actions Sent By Avid Connector API, And Handled By Secure Gateway

bal_to_sg_connect

genericData: provided

metadata:

Key Type Value Required Default
pid int32 process id required
host string host name or IP address of the connected instance required
runtime SGVariantMap

instance runtime information

  • service.access.object
    This property is MANDATORY, it's JSON with the following fields:
    {
        "id": "String, unique UUID",
        "bal": "String, language of the Connector API, i.e. 'java' or 'node.js'",
        "host": "String, hostname or IP where service is running",
        "pid": 123, // Integer, ID of the process
        "platformId": "String, unique identifier of the box, where service is running (must be unique for each box)",
        "buildNumber": "String, build number of Avid Connector API",
        "environmentId": "String, unique identifier of the environment (can be same for different boxes)"
    }


  • websocketPingSupported
    This property must be always set to true. Custom ping message is deprecated and will be removed from the Secure Gateway in future releases.
  • connectorApiHealthCheckSupported
    if property is set to true it means that Avid Connector API is providing health check API
  • queryTimeoutByApi 
    property must be provided Avid Connector API, which monitor query timeout itself and does not rely on sg_to_bal_response payload with timeout field set to true
required
auth SGVariantMap instance identity information optional null

auth:

Key Type Value Required Default
authType string type of authentication ('serviceIdentityToken', 'ip') true
clientId string client id given to the service developer (must be passed if authType=serviceIdentityToken) false
clientSecret string client secret given to the service developer (must be passed if authType=serviceIdentityToken) false

body: NullValue

NOTE: if auth is not provided or authType is not serviceIdentyToken, approval of the connected service relies on IP address validation. In this case Secure Gateway checks if service IP address belongs to allowed by IP mask. If allowed, then application has internal access level, without restrictions. Default allowed IP mask must be 127.0.0.1/25.

Reply:

bal_to_sg_connect answers with a sg_to_bal_acknowledged message (see topic sg_to_bal_acknowledged). The acknowledged sends the runtime map back to the client. The runtime map MAY be modified by the Gateway. The Client MUST obey the runtime configuration received by the Gateway. This configuration negation allows the Gateway to enforce a configuration of the client if current situation requires it.

bal_to_sg_disconnect

genericData: NullValue

bal_to_sg_register

genericData: provided

metadata:

confluence
Key Type Value Required Default
multizone bool whether registered service is multi-zone service or not optional false

requestServiceConfiguration

bool

if property is set to true it means that Secure Gateway must request configuration from Service Manager and return it back to service. If false or not provided, then configuration won't be requested

optional true

startSuspended

bool whether to start service in suspended state initially or not optional false

manualAcknowledgement

bool provide global configuration for service behavior, whether it must acknowledge messages manually (true) or automatically (false) optional

false

numberOfConcurrentMessages

int32 maximum number of concurrent messages to the service, -1 means unlimited number of concurrent messages optional -1

body: serialized as bytes, JSON data with Service Info

bal_to_sg_unregister

genericData: NullValue

bal_to_sg_request

genericData: provided

metadata:

Key Type Value Required Default
zone string target zone ID optional 00000000-0000-0000-0000-000000000000 for local zone
anyCompatibleVersion boolean whether to send request to any compatible service version or to exact one optional true
timeout int64 timeout for query operation optional 10000
durable boolean whether message must be durable or not (not supported now) optional false
requestType string type of outgoing request ('query', 'send' or 'broadcast') optional query

body: serialized as bytes, JSON data with request message to service

NOTE: requestId passed in the header of this message must be passed as requestId in the header of sg_to_bal_response

bal_to_sg_post

genericData: provided

metadata:

Key Type Value Required Default
zone string target zone ID optional 00000000-0000-0000-0000-000000000000 for local zone

body: serialized as bytes, JSON data with channel message

bal_to_sg_subscribe

genericData: provided

metadata:

Key Type Value Is Required Default
channelName string name of the channel required
bindings SGVariantList

list of bindings

optional '#'
multizone bool whether channel must receive messages from any zone or from local zone only optional false
subscriberId string UUID v.4 of the subscriber required
sharedName string shared channel name. Channel created as shared if this key is provided, otherwise created as regular channel optional null

body: NullValue

bal_to_sg_unsubscribe

genericData: provided

metadata:

Key Type Value Is Required Default
channelName string name of the channel. If not provided, then subscriber will be unsubscribed from all channels optional null
subscriberId string

UUID v.4 of the subscriber

required
multizone bool whether subscriber was subscribed to any zone or to local zone only required
bindings SGVariantList list of bindings to unsubscribe from. If this key is provided, channelName must be provided as well. If binding are provided but channelName is not provided, secure gateway must resply with error optional

body: NullValue

bal_to_sg_response

genericData: provided

metadata:

Key Type Value Is Required Default
error string error information, in case if BAL wasn't able to return JSON message optional NullValue

body: serialized as bytes, JSON data with response message from service

header: requestId of the header must be requestId of the incoming message sg_to_bal_request

bal_to_sg_ack

genericData: NullValue

header: requestId of the header must be requestId of the incoming message sg_to_bal_request

bal_to_sg_environment

genericData: provided

metadata:

Key Type Value Is Required Default
zone string target zone ID optional 00000000-0000-0000-0000-000000000000 for local zone

body: NullValue

bal_to_sg_status

genericData: provided

metadata:

Key Type Value Is Required Default
status string ok | warning | error | offline | suspended required
info string Additional information for the status optional NullValue

Actions Sent by Secure Gateway, and Handled By Avid Connector API

sg_to_bal_request

genericData: provided

metadata:

Key Type Value Required Default
sendResponseToSG bool whether to send response back to SG or not (legacy, we should remove it and always send response back) optional true

body: serialized as bytes, JSON data with request message to service

NOTE: requestId received in the header of this message must be used as requestId of the header in the response message bal_to_sg_response

sg_to_bal_post

genericData: provided

metadata:

Key Type Value Required Default
subscriberId string

UUID v.4 of the subscriber

required


body: serialized as bytes, JSON data with channel message

sg_to_bal_response

genericData: provided

metadata:

Key Type Value Is Required Default
error string error information, in case if BAL wasn't able to return JSON message optional NullValue
errorType string

forbiddenByPolicies - if registration of the service is forbidden according to policies, provided to service identity token

internal - internal error

optional NullValue

body: serialized as bytes, JSON data with response message from service

header: requestId of the header must be requestId of the incoming message bal_to_sg_request

sg_to_bal_configure

genericData: provided

metadata:

Key Type Value Is Required Default
type

string

Type of configuration ('proxy' or 'service') true
proxyConfiguration SGVariantMap Proxy configuration data, must be provided if type is 'proxy' false NullValue

errorType

string

internal - internal error

false NullValue

error

string error information, in case if failed to receive configuration false NullValue

configurationUpdate

boolean false - if configuration is initially requested by the service; true - if configuration update was received. If this field is missing treat incoming update as initial update true false

body: serialized as bytes, JSON data with service configuration if configuration type is 'service', or registry information (structre described in sg_to_bal_environment) if configuration type is 'proxy'.

sg_to_bal_control

genericData: provided

metadata:

Key Type Value Is Required Default
type

string

Type of control command ('start', 'stop', 'suspend' or 'resume') true

body: NullValue

sg_to_bal_environment

genericData: provided

metadata:

Key Type Value Is Required Default
runtime SGVariantMap Runtime map can be provided by some commands. Please see command details optional NullValue

body: JSON with the 'simple' format of the registry. Additional information other than registry could be added to this JSON in the future:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
{
"registry": {
"local": {
"lastUpdated": "2015-12-08T16:19:50.849Z",
"zone": {
"id": "aaaaaaaa-1aaa-4aaa-8aaa-aaaaaaaaaaaa",
"ums": {
"host": "localhost"
}
},
"services": {
"avid.acs.registry": {
"versions": {
"3": {
"description": "Tracks living service instances.",
"realms": {
"global": {
"status": "ok",
"scope": "zone",
"instances": {
"eb97b755-a88e-418c-a550-52545110ddc4": {
"status": "ok",
"scope": "zone",
"access": "698e74fc-b152-47cc-b87d-c34df910e7fa"
}
}
}
}
},
"earliestVersions": {
"realms": {
"global": 3
}
},
"latestVersions": {
"realms": {
"global": 3
}
}
},
"avid.acs.attributes": {
"versions": {
"0": {
"description": "Storage and Retrieval of Attributes and Attribute Trees",
"realms": {
"global": {
"status": "ok",
"scope": "zone"
}
}
}
},
"earliestVersions": {
"realms": {
"global": 0
}
},
"latestVersions": {
"realms": {
"global": 0
}
}
},
"avid.acs.federation": {
"versions": {
"3": {
"description": "Federating and Un-Federating w/ Other ICS Zones",
"realms": {
"global": {
"status": "ok",
"scope": "zone"
}
}
}
},
"earliestVersions": {
"realms": {
"global": 3
}
},
"latestVersions": {
"realms": {
"global": 3
}
}
},
"avid.acs.infrastructure": {
"versions": {
"0": {
"description": "Provides information about the infrastructure of the zone.",
"realms": {
"global": {
"status": "ok",
"scope": "zone"
}
}
}
},
"earliestVersions": {
"realms": {
"global": 0
}
},
"latestVersions": {
"realms": {
"global": 0
}
}
},
"avid.acs.gateway": {
"versions": {
"3": {
"description": "Avid ACS Gateway Service.",
"realms": {
"global": {
"status": "ok",
"scope": "zone"
}
}
}
},
"earliestVersions": {
"realms": {
"global": 3
}
},
"latestVersions": {
"realms": {
"global": 3
}
}
},
"avid.acs.service.manager": {
"versions": {
"3": {
"description": "Bus Services Manager",
"realms": {
"global": {
"status": "ok",
"scope": "zone"
}
}
}
},
"earliestVersions": {
"realms": {
"global": 3
}
},
"latestVersions": {
"realms": {
"global": 3
}
}
}
}
},
"remote": {
"aaaaaaaa-2aaa-4aaa-8aaa-aaaaaaaaaaaa": {
"lastUpdated": "2015-12-08T16:19:43.578Z",
"zone": {
"id": "aaaaaaaa-2aaa-4aaa-8aaa-aaaaaaaaaaaa",
"ums": {
"host": "localhost"
}
},
"services": {}
},
"aaaaaaaa-4aaa-4aaa-8aaa-aaaaaaaaaaaa": {
"lastUpdated": "2015-12-08T16:19:48.390Z",
"zone": {
"id": "aaaaaaaa-4aaa-4aaa-8aaa-aaaaaaaaaaaa",
"ums": {
"host": "localhost"
}
},
"services": {}
},
"aaaaaaaa-3aaa-4aaa-8aaa-aaaaaaaaaaaa": {
"lastUpdated": "2015-12-08T16:19:47.011Z",
"zone": {
"id": "aaaaaaaa-3aaa-4aaa-8aaa-aaaaaaaaaaaa",
"ums": {
"host": "localhost"
}
},
"services": {}
}
}
}
}
}

If internal error occurred during getting environment information, runtime object must provide following fields:

Key Type Value
errorType string internal - internal error
errorMessage string additional error message, with more details

sg_to_bal_acknowledged

genericData: provided

metadata:

Key Type Value Is Required Default
error string error information, in case SG encountered a error while processing the message optional NullValue
requestedAction string

the action being acknowledged, which may be any one of:
bal_to_sg_connect
bal_to_sg_disconnect
bal_to_sg_register
bal_to_sg_unregister
bal_to_sg_request (send and broadcast)
bal_to_sg_post
bal_to_sg_subscribe
bal_to_sg_unsubscribe
bal_to_sg_status

required
runtime SGVariantMap Runtime map can be provided by some commands. Please see command details optional NullValue

header: requestId of the header must be the requestId of the message that is being acknowledged i.e. bal_to_sg_XXX.

Acknowledgement of the bal_to_sg_connect returns following fileds in the runtime:

Key Type Value
gatewayJarVersion string Version of the BAL, retrieved from the JAR file definition
gatewayRpmVersion string Version of the RPM, retrieved from the ACS_SERVICE_BUILD_NUMBER environment variable
sgFeatureUnsubscribeFromBindings string true if unsubscribe from bindings is supported by Secure Gateway, false or field is not available if unsubscribe from bindings is not supported by Secure Gateway

If bal_to_sg_connect failed, runtime has also the following fields:

Key Type Value
errorType string

connection - if Secure Gateway failed to connect to RMQ
authentication - if authentication failed on Secure Gateway 
internal - internal error 

errorMessage string

additional error message, with more details

If bal_to_sg_register failed, runtime has following fields:

Key Type Value
errorType string

forbiddenByPolicies - if registration of the service is forbidden according to policies, provided to service identity token

forbiddenMultiple - if trying to register multiple service with same connected instance

internal - internal error

errorMessage string additional error message, with more details

If bal_to_sg_request (send and broadcast), bal_to_sg_post or bal_to_sg_subscribe failed, runtime has following fields:

Key Type Value
errorType string forbiddenByPolicies - if registration of the service is forbidden according to policies, provided to service identity token
internal - internal error
errorMessage string additional error message, with more details

If bal_to_sg_unregisterbal_to_sg_unsubscribe or bal_to_sg_status failed, runtime has following fields:

Key Type Value
errorType string internal - internal error
errorMessage string additional error message, with more details

sg_to_bal_set_status

genericData: provided

metadata:

Key Type Value Is Required Default
statusCode string Service status code required
statusDetails string Service status details optional NullValue