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

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
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

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

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:

{
  "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

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_unregister, bal_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