Design Document Protocol Buffers Interface

The current backend implementation suffers from two serious problems:

1. NAT/Firewall Issue: Clients of a testbed must be capable to open a world-wide accessible Web Service endpoint which uses a publicly accessible IP-Address and Port.
2. Performance: Web Service Calls are pretty slow if for every message the clients' Controller Web Service must be called.

This document describes an alternative interface between client and testbed backend that is based upon a plain TCP/IP connection and the Google Protocol Buffers middleware solution.

How does it work?

1. The client opens a TCP connection to a special Protocol Buffers socket of the testbed.
2. The client sends his secret reservation keys to connect to the running experiment.

• If the keys are invalid the backend will close the TCP connection.
• If the client sends any unexpected data (other than one-time secret reservation keys at the beginning of the session) the backend will close the TCP connection.
• If the keys are valid the backend will add this TCP connection to the list of controllers, thereby from now on delivering all node output and asynchronous status updates over this TCP connection.

3. If the connection dies away or is closed by the client the backend will automatically remove the client from the list of controllers.

Messages

Envelope

All messages that are sent are wrapped in an envelope message as to allow the recipient to decide what type of message to parse.

message Envelope {

  enum BodyType {
    MESSAGE = 1;
    REQUEST_STATUS = 2;
    SECRET_RESERVATION_KEYS = 3;
  }

  required BodyType body_type = 1;

  optional Message message = 2;
  optional RequestStatus requestStatus = 3;
  optional SecretReservationKeys secretReservationKeys = 4;

}

SecretReservationKeys

message SecretReservationKeys {

  message SecretReservationKey {
    required string urn_prefix = 1;
    required string key = 2;
  }

  repeated SecretReservationKey keys = 1;
}

Message

message Message {

  enum Type {
    NODE_TEXT = 1;
    NODE_BINARY = 2;
    BACKEND = 3;
  }

  enum Level {
    TRACE = 1;
    DEBUG = 2;
    INFO = 3;
    WARN = 4;
    ERROR = 5;
    FATAL = 6;
  }

  message NodeText {
    required string source_node_urn = 1;
    required Level level = 2;
    required string text = 3;
  }

  message NodeBinary {
    required string source_node_urn = 1;
    required uint32 type = 2;
    required bytes data = 3;
  }

  message Backend {
    required Level level = 1;
    required string text = 2;
  }

  required Type type = 1;
  required string timestamp = 2;
  optional NodeBinary node_binary = 3;
  optional NodeText node_text = 4;
  optional Backend backend = 5;
}

RequestStatus

message RequestStatus {

  message Status {
    required string node_urn = 1;
    required int32 value = 2;
    optional string message = 3;
  }

  required string request_id = 1;
  repeated Status status = 2;

}