api.proto

syntax = "proto3";

import "common.proto";

package telegraph.api;

// to be converted to json
// for both the javascript/c++ server/client code

message ParamsEntry {
    string key = 1;
    Params value = 2;
}

message ParamsMap {
    repeated ParamsEntry entries = 1;
}

message ParamsList {
    repeated Params elements = 1;
}

// json-like structure, as a protobuffer
// if all are unset, equivalent to null
message Params {
    oneof content {
        Node tree = 1;
        string uuid = 2;
        bool b = 3;
        float number = 4;
        string str = 5;
        ParamsMap object = 6;
        ParamsList array = 7;
        Empty none = 8;
    }
}

message Context {
    string uuid = 1;
    bool headless = 2;
    string name = 3;
    string type = 4;
    Params params = 5;
}

// creation options
message Create {
    string name = 1;
    string type = 2;
    Params params = 3;
}

message Request {
    string uuid = 1;
    Params params = 2;
}

message Namespace {
    repeated Context contexts = 1;
}

// tree operations

message Subscription {
    string uuid = 1; // context uuid
    repeated string variable = 2;
    float debounce = 3;
    float refresh = 4;
    float timeout = 5;
}

message Call {
    string uuid = 1; // context uuid
    repeated string action = 2; // path to action, specified the children indices
    Value value = 3;
    float timeout = 4;
}

message DataWrite {
    string uuid = 1; // context uuid
    repeated string path = 2;
    repeated Datapoint data = 3;
}

message DataQuery {
    string uuid = 1;
    repeated string path = 2;
}

message DataPacket {
    repeated Datapoint data = 1;
}

message Packet {
    sint32 req_id = 1;
    oneof payload {
        float cancel = 2; // timeout for sub cancel response from board, ignored for queries
        string error = 3;
        bool success = 4;

        // every server/client can only have a
        // single associated namespace uuid that cannot change
        // this can also be used as a heartbeat packet since it has no sideaffects
        Empty query_ns = 5;
        Namespace ns = 6;

        Context added = 7;
        string removed = 8;

        Create create = 9;
        string created = 10; // uuid of created context
        string destroy = 11;

        Request request = 12;
        Params request_update = 13;

        // tree operations:
        string fetch_tree = 14; // context uuid to fetch tree
        Node fetched_tree = 15; // response to a context fetch

        Subscription sub_change = 16;
        Empty sub_poll = 17;
        Empty sub_reset = 18;
        Type sub_type = 19;
        Datapoint sub_update = 20; // keep receiving until the original request id is cancelled

        Call call_action = 21;
        Datapoint call_return = 22;

        // archive operations:
        DataWrite data_write = 23;

        DataQuery data_query = 24;
        DataPacket archive_data = 25; // initial response to a query
        DataPacket archive_update = 26; // any archive updates
    }
}