sdv_databroker_v1.proto

/********************************************************************************
 * Copyright (c) 2022 Contributors to the Eclipse Foundation
 *
 * See the NOTICE file(s) distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Apache License 2.0 which is available at
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * SPDX-License-Identifier: Apache-2.0
 ********************************************************************************/

syntax = "proto3";

package sdv.databroker.v1;

import "google/protobuf/timestamp.proto";

// Data type of a signal
//
// Protobuf doesn't support int8, int16, uint8 or uint16.
// These are mapped to sint32 and uint32 respectively.
//
enum DataType {
  STRING          = 0;
  BOOL            = 1;
  INT8            = 2;
  INT16           = 3;
  INT32           = 4;
  INT64           = 5;
  UINT8           = 6;
  UINT16          = 7;
  UINT32          = 8;
  UINT64          = 9;
  FLOAT           = 10;
  DOUBLE          = 11;
  TIMESTAMP       = 12;
  STRING_ARRAY    = 20;
  BOOL_ARRAY      = 21;
  INT8_ARRAY      = 22;
  INT16_ARRAY     = 23;
  INT32_ARRAY     = 24;
  INT64_ARRAY     = 25;
  UINT8_ARRAY     = 26;
  UINT16_ARRAY    = 27;
  UINT32_ARRAY    = 28;
  UINT64_ARRAY    = 29;
  FLOAT_ARRAY     = 30;
  DOUBLE_ARRAY    = 31;
  TIMESTAMP_ARRAY = 32;
}

enum DatapointError {
  UNKNOWN_DATAPOINT = 0;
  INVALID_TYPE      = 1;
  ACCESS_DENIED     = 2;
  INTERNAL_ERROR    = 3;
  OUT_OF_BOUNDS     = 4;
}

enum EntryType {
  ENTRY_TYPE_UNSPECIFIED = 0;
  ENTRY_TYPE_SENSOR      = 1;
  ENTRY_TYPE_ACTUATOR    = 2;
  ENTRY_TYPE_ATTRIBUTE   = 3;
}

enum ChangeType {
  STATIC    = 0;   // Value never changes
  ON_CHANGE = 1;   // Updates are provided every time the value changes (i.e.
                   // window is open / closed)
  CONTINUOUS = 2;  // Value is updated continuously. Broker needs to tell
                   // provider the preferred (update) frequency.
}

message StringArray {
  repeated string values = 1;
}

message BoolArray {
  repeated bool values = 1;
}

message Int32Array {
  repeated sint32 values = 1;
}

message Int64Array {
  repeated sint64 values = 1;
}

message Uint32Array {
  repeated uint32 values = 1;
}

message Uint64Array {
  repeated uint64 values = 1;
}

message FloatArray {
  repeated float values = 1;
}

message DoubleArray {
  repeated double values = 1;
}

message Datapoint {
  // Timestamp of the value
  google.protobuf.Timestamp timestamp = 1;

  // values
  oneof value {
    Failure failure_value    = 10;
    string string_value      = 11;
    bool bool_value          = 12;
    sint32 int32_value       = 13;
    sint64 int64_value       = 14;
    uint32 uint32_value      = 15;
    uint64 uint64_value      = 16;
    float float_value        = 17;
    double double_value      = 18;
    StringArray string_array = 21;
    BoolArray bool_array     = 22;
    Int32Array int32_array   = 23;
    Int64Array int64_array   = 24;
    Uint32Array uint32_array = 25;
    Uint64Array uint64_array = 26;
    FloatArray float_array   = 27;
    DoubleArray double_array = 28;
  }

  enum Failure {
    // The data point is known, but doesn't have a valid value
    INVALID_VALUE = 0;
    // The data point is known, but no value is available
    NOT_AVAILABLE = 1;
    // Unknown datapoint
    UNKNOWN_DATAPOINT = 2;
    // Access denied
    ACCESS_DENIED = 3;
    // Unexpected internal error
    INTERNAL_ERROR = 4;
  }
}

message Metadata {
  // Id to be used in "get" and "subscribe" requests. Ids stay valid during
  // one power cycle, only.
  int32 id               = 1;
  EntryType entry_type   = 2;
  string name            = 4;
  DataType data_type     = 5;
  ChangeType change_type = 6;  // CONTINUOUS or STATIC or ON_CHANGE
  string description     = 7;

  // int32             min_update_hz       = 10; // Only for CONTINUOUS
  // int32             max_update_hz       = 11; // Only for CONTINUOUS
}

service Broker {
  // Request a set of datapoints (values)
  //
  // Returns a list of requested data points.
  //
  // InvalidArgument is returned if the request is malformed.
  rpc GetDatapoints(GetDatapointsRequest) returns (GetDatapointsReply);

  // Set a datapoint (values)
  rpc SetDatapoints(SetDatapointsRequest) returns (SetDatapointsReply);

  // Subscribe to a set of data points or conditional expressions
  // using the Data Broker Query Syntax (described in QUERY.md)
  //
  // Returns a stream of replies.
  //
  // InvalidArgument is returned if the request is malformed.
  rpc Subscribe(SubscribeRequest) returns (stream SubscribeReply);

  // Request the metadata of a set of datapoints
  //
  // Returns metadata of the requested data points that exist.
  rpc GetMetadata(GetMetadataRequest) returns (GetMetadataReply);
}

message GetDatapointsRequest {
  // A list of requested data points.
  repeated string datapoints = 1;
}

message GetDatapointsReply {
  // Contains the values of the requested data points.
  // If a requested data point is not available, the corresponding Datapoint
  // will have the respective failure value set.
  map<string, Datapoint> datapoints = 1;
}

message SetDatapointsRequest {
  // A map of data points to set
  map<string, Datapoint> datapoints = 1;
}

message SetDatapointsReply {
  // A map of errors (if any)
  map<string, DatapointError> errors = 1;
}

message SubscribeRequest {
  // Subscribe to a set of data points (or expressions) described
  // by the provided query.
  // The query syntax is a subset of SQL and is described in more
  // detail in the QUERY.md file.
  string query = 2;
}

message SubscribeReply {
  // Contains the fields specified by the query.
  // If a requested data point value is not available, the corresponding
  // Datapoint will have it's respective failure value set.
  map<string, Datapoint> fields = 1;
}

message GetMetadataRequest {
  // Request metadata for a list of data points referenced by their names.
  // e.g. "Vehicle.Cabin.Seat.Row1.Pos1.Position" or "Vehicle.Speed".
  //
  // If no names are provided, metadata for all known data points will be
  // returned.
  repeated string names = 1;
}

message GetMetadataReply {
  // Contains metadata of the requested data points. If a data point
  // doesn't exist (i.e. not known to the Data Broker) the corresponding
  // Metadata isn't part of the returned list.
  repeated Metadata list = 1;
}

service Collector {
  // Register new datapoint (metadata)
  //
  // If the registration of at least one of the passed data point fails, the overall registration
  // is rejected and the gRPC status code ABORTED is returned (to indicate the "aborted" registration).
  // The details, which data point(s) caused the failure and the reason, is passed in back in human-
  // readable form in the status message. Possible failure resaons are:
  //  * PERMISSION_DENIED - Not allowed to register this name
  //  * ALREADY_REGISTERED - The data point is already registered by some other feeder
  //  * RE_REGISTRATION_MISMATCH - Already registered by this feeder but with differing metadata
  //  * INVALID_NAME - The passed name of the datapoint has an invalid structure
  //  * INVALID_VALUE_TYPE - The passed ValueType is not supported
  //  * INVALID_CHANGE_TYPE - The passed ChangeType is not supported
  rpc RegisterDatapoints(RegisterDatapointsRequest) returns (RegisterDatapointsReply);

  // Provide a set of updated datapoint values to the broker.
  // This is the unary equivalent of `StreamDatapoints` below and is better suited for cases
  // where the frequency of updates is rather low.
  //
  // NOTE: The values provided in a single request are handled as a single update in the
  // data broker. This ensures that any clients requesting (or subscribing to) a set of
  // datapoints will get a consistent update, i.e. that either all values are updated or
  // none are.
  //
  // Returns: any errors encountered updating the datapoints
  //
  rpc UpdateDatapoints(UpdateDatapointsRequest) returns (UpdateDatapointsReply);

  // Provide a stream with updated datapoint values to the broker.
  // This is the streaming equivalent of `UpdateDatapoints` above and is better suited for
  // cases where the frequency of updates is high.
  //
  // NOTE: The values provided in a single request are handled as a single update in the
  // data broker. This ensures that any clients requesting (or subscribing to) a set of
  // datapoints will get a consistent update, i.e. that either all values are updated or
  // none are.
  //
  // Returns: any errors encountered updating the datapoints
  //
  rpc StreamDatapoints(stream StreamDatapointsRequest) returns (stream StreamDatapointsReply);
}

message UpdateDatapointsRequest {
  map<int32, Datapoint> datapoints = 1;
}

message UpdateDatapointsReply {
  map<int32, DatapointError> errors = 1;  // If empty, everything went well
}

message StreamDatapointsRequest {
  map<int32, Datapoint> datapoints = 1;
}

message StreamDatapointsReply {
  map<int32, DatapointError> errors = 1;  // If empty, everything went well
}

message RegisterDatapointsRequest {
  repeated RegistrationMetadata list = 1;
}

message RegistrationMetadata {
  // Name of the data point
  // (e.g. "Vehicle.Cabin.Seat.Row1.Pos1.Position" or "Vehicle.Speed")
  string name            = 1;
  DataType data_type     = 2;
  string description     = 3;
  ChangeType change_type = 4;

  // int32             min_update_hz       = 10; // Only for CONTINUOUS
  // int32             max_update_hz       = 11; // Only for CONTINUOUS
};

message RegisterDatapointsReply {
  // Maps each data point name passed in RegisterDatapointsRequest to a data point id
  map<string, int32> results = 1;
}