aos/configuration.fbs

include "reflection/reflection.fbs";

namespace aos;

enum LoggerConfig : ubyte {
  // This data should be logged on this node.
  LOCAL_LOGGER,
  // This data should be logged on a remote node.
  REMOTE_LOGGER,
  // This data should not be logged.
  NOT_LOGGED,
  // This data should be logged both on this node and on the remote node.
  // This is useful where you want to log a message on both the sender and
  // receiver to create self-contained log files.
  LOCAL_AND_REMOTE_LOGGER
}

table Connection {
  // Node name to forward to.
  name:string (id: 0);

  // How the delivery timestamps for this connection should be logged.  Do we
  // log them with the local logger (i.e. the logger running on the node that
  // this message is delivered to)?  Do we log them on another node (a central
  // logging node)?  Do we log them in both places redundantly?
  timestamp_logger:LoggerConfig = LOCAL_LOGGER (id: 1);

  // If the corresponding delivery timestamps for this channel are logged
  // remotely, which node should be responsible for logging the data.  Note:
  // for now, this can only be the source node.  Empty implies the node this
  // connection is connecting to (i.e. name).
  timestamp_logger_nodes:[string] (id: 2);

  // Priority to forward data with.
  // The priority value in SCTP_SS_PRIO is used to determine the order in which
  // data from different streams is transmitted. Lower priority values indicate
  // higher priority in sending the data. When the SCTP stack has to choose
  // which stream's data to send next, it will select the data from the stream
  // with the highest priority (i.e., the lowest priority value). If two or
  // more streams have the same priority, SCTP_SS_PRIO falls back to a
  // round-robin scheduling between these streams. Note that this does not
  // reserve any potion of the bandwidth. It is only used to determine which
  // message to send when the system is ready to send a message.
  priority:ushort = 100 (id: 3);

  // Time to live in nanoseconds before the message is dropped.
  // A value of 0 means no timeout, i.e. reliable.  When a client connects, the
  // latest message from this channel will be sent regardless.
  // TODO(austin): We can retry more than just the last message on reconnect
  //   if we want.  This is an unlikely scenario though.
  time_to_live:uint = 0 (id: 4);
}

enum ReadMethod : ubyte {
  // Copy all the data out of shared memory into a local buffer for each reader.
  COPY,
  // Pin the data in shared memory and read directly from there.
  PIN,
}

// Table representing a channel.  Channels are where data is published and
// subscribed from.  The tuple of name, type is the identifying information.
table Channel {
  // Name of the channel.
  name:string (id: 0);
  // Type name of the flatbuffer.
  type:string (id: 1);
  // Max frequency in messages/sec of the data published on this channel.
  // The maximum number of messages that can be sent
  // in a channel_storage_duration is
  // frequency * channel_storage_duration (in seconds).
  frequency:int = 100 (id: 2);
  // Max size of the data being published.  (This will hopefully be
  // automatically computed in the future.)
  max_size:int = 1000 (id: 3);

  // Sets the maximum number of senders on a channel.
  num_senders:int = 10 (id: 4);
  // Sets the maximum number of watchers on a channel.
  num_watchers:int = 10 (id: 5);

  // The schema for the data sent on this channel.
  schema:reflection.Schema (id: 6);

  // The source node name for the data sent on this channel.
  // If nodes is populated below, this needs to also be populated.
  source_node:string (id: 7);

  // The destination nodes for data sent on this channel.
  // This only needs to be populated if this message is getting forwarded.
  destination_nodes:[Connection] (id: 8);

  // What service is responsible for logging this channel:
  logger:LoggerConfig = LOCAL_LOGGER (id: 9);
  // If the channel is logged remotely, which node should be responsible for
  // logging the data.  Note: this requires that the data is forwarded to the
  // node responsible for logging it.  Empty implies the node this connection
  // is connecting to (i.e. name).
  logger_nodes:[string] (id: 10);

  // The way messages are read from shared memory for this channel.
  read_method:ReadMethod = COPY (id: 11);

  // Sets the maximum number of senders on a channel.
  //
  // Currently, this must be set if and only if read_method is PIN.
  num_readers:int (id: 12);

  // Length of this channel in nanoseconds.  This overrides
  // channel_storage_duration below in Configuration for just this channel.
  channel_storage_duration:long = 2000000000 (id: 13);
}

// Table to support renaming channel names.
table Map {
  // Channel to match with.  If the name in here matches, the name is replaced
  // with the name in rename.  If the name ends in *, it will be treated like a
  // wildcard.  Anything with the same prefix will match, and anything matching
  // the * will get preserved on rename.  This supports moving subfolders.
  // Node specific matches are also supported.
  match:Channel (id: 0);
  // The channel to merge in.
  rename:Channel (id: 1);
}

// Application specific information.
table Application {
  // Name of the application.
  name:string (id: 0);

  // Path of the executable relative to starter. If this field is unset, use
  // name as the path. Not permitted to change while starter is running.
  executable_name:string (id: 5);

  // List of maps to apply for this specific application.  Application specific
  // maps are applied in reverse order, and before the global maps.
  // For example
  //   "maps": [ { "match": { "name": "/foo" }, "rename": { "name": "/bar" } } ]
  // will make it so any channels named "/foo" actually go to "/bar" for just
  // this application.  This is super handy for running an application twice
  // publishing to different channels, or for injecting a little application
  // to modify messages live for testing.
  //
  //   "maps": [
  //     { "match": { "name": "/foo" }, "rename": { "name": "/bar" } },
  //     { "match": { "name": "/foo" }, "rename": { "name": "/baz" } }
  //   ]
  //
  // will map "/foo" to "/baz", even if there is a global list of maps.
  maps:[Map] (id: 1);

  // The node that this application will be started on.
  // TODO(austin): Teach starter how to use this for starting applications.
  nodes:[string] (id: 2);

  // The user to run this application as. If this field is unset, run it as
  // the current user of the application starter.
  user:string (id: 3);

  // List of arguments to be passed to application
  args:[string] (id: 4);

  // Indicates that application should be executed on boot.
  autostart:bool = true (id: 6);

  // Indicates that application should automatically restart on failure.
  autorestart:bool = true (id: 7);

  // If set, this is the memory limit to enforce in bytes for the application
  // (and it's children)
  memory_limit:uint64 = 0 (id: 8);
}

// Per node data and connection information.
table Node {
  // Short name for the node.  This provides a short hand to make it easy to
  // setup forwarding rules as part of the channel setup.
  name:string (id: 0);

  // Hostname used to identify and connect to the node.
  hostname:string (id: 1);
  // Port to serve forwarded data from.
  port:ushort = 9971 (id: 2);

  // An alternative to hostname which allows specifying multiple hostnames,
  // any of which will match this node.
  //
  // Don't specify a hostname in multiple nodes in the same configuration.
  hostnames:[string] (id: 3);

  // An arbitrary list of strings representing properties of each node.  These
  // can be used to store information about roles.
  tags:[string] (id: 4);
}

// Overall configuration datastructure for the pubsub.
table Configuration {
  // List of channels.
  channels:[Channel] (id: 0);
  // List of global maps.  These are applied in reverse order.
  maps:[Map] (id: 1);

  // If present, this is the list of nodes in the system.  If this is not
  // present, AOS will be running in a single node configuration.
  nodes:[Node] (id: 4);

  // List of applications.
  applications:[Application] (id: 2);
  // List of imports.  Imports are loaded first, and then this configuration
  // is merged into them.
  imports:[string] (id: 3);

  // Length of the channels in nanoseconds.  Every channel will have enough
  // data allocated so that if data is published at the configured frequency,
  // at least this many nanoseconds of messages will be available for fetchers.
  channel_storage_duration:long = 2000000000 (id: 5);
}

root_type Configuration;