data.proto

// Copyright 2024 Nokia
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

import "google/protobuf/any.proto";
import "google/protobuf/empty.proto";
import "options.proto";
import "schema.proto";

package data;

option go_package = "github.com/sdcio/sdc-protos/sdcpb;sdcpb";

service DataServer {
  // datastore
  rpc ListDataStore(ListDataStoreRequest) returns (ListDataStoreResponse);
  // return a datastore details
  rpc GetDataStore(GetDataStoreRequest) returns (GetDataStoreResponse);
  // creates a new datastore, either a MAIN or a CANDIDATE datastore
  rpc CreateDataStore(CreateDataStoreRequest) returns (CreateDataStoreResponse);
  // deletes a datastore, either a MAIN or a CANDIDATE datastore
  rpc DeleteDataStore(DeleteDataStoreRequest) returns (DeleteDataStoreResponse);

  // Start a transaction
  rpc TransactionSet(TransactionSetRequest) returns (TransactionSetResponse);
  // Confirm the transaction
  rpc TransactionConfirm(TransactionConfirmRequest)
      returns (TransactionConfirmResponse);
  // Cancel and thereby rollback the transaction
  rpc TransactionCancel(TransactionCancelRequest)
      returns (TransactionCancelResponse);

  // list intents for a given datastore (name and priority)
  rpc ListIntent(ListIntentRequest) returns (ListIntentResponse);

  rpc GetIntent(GetIntentRequest) returns (GetIntentResponse);

  rpc WatchDeviations(WatchDeviationRequest)
      returns (stream WatchDeviationResponse);

  rpc BlameConfig(BlameConfigRequest) returns (BlameConfigResponse);
}

// messages
message GetDataRequest {
  // data store name
  string name               = 1;
  // data store type
  DataStore datastore       = 2;
  // path list
  repeated schema.Path path = 3;
  // dataType config, state
  schema.DataType data_type = 4;
  // data encoding
  Encoding encoding         = 5;
}

message GetDataResponse {
  // list of paths and values
  repeated Notification notification = 1;
}

message SetDataRequest {
  // datastore name
  string name                 = 1;
  // datastore type and name
  DataStore datastore         = 2;
  // list of updates
  repeated Update update      = 10;
  // list of replaces
  repeated Update replace     = 11;
  // list of deletes
  repeated schema.Path delete = 12;
}
message SetDataResponse {
  // A set of responses specifying the result of the operations specified in
  // the SetRequest.
  repeated UpdateResult response = 2;
  // e.g. netconf rpc-errors with severity warning
  repeated string warnings       = 3;
  // Timestamp of transaction (ns since epoch).
  int64 timestamp                = 4;
}

// DS
message ListDataStoreRequest {}
message ListDataStoreResponse { repeated GetDataStoreResponse datastores = 1; }

message GetDataStoreRequest {
  // datastore name
  string datastore_name = 1;
}
message GetDataStoreResponse {
  // datastore name
  string datastore_name   = 1;
  // list of intents in this datastore
  repeated string intents = 2;
  // the schema this datastore should comply with
  schema.Schema schema    = 3;
  // south bound interface target of this datastore
  Target target           = 4;
}

message CreateDataStoreRequest {
  // datastore name
  string datastore_name = 1;
  // the schema this datastore should comply with
  schema.Schema schema  = 3;
  // south bound interface target of this datastore
  Target target         = 4;
  // datastore sync strategy
  Sync sync             = 5;
}

message CreateDataStoreResponse {}

message DeleteDataStoreRequest {
  // datastore name
  string name = 1;
}
message DeleteDataStoreResponse {}

message GetIntentRequest {
  // datastore name
  string datastore_name = 1;
  // intent name
  string intent         = 2;
  // format
  Format format         = 3;
}

enum Format {
  Intent_Format_JSON      = 0;
  Intent_Format_JSON_IETF = 1;
  Intent_Format_XML       = 2;
  Intent_Format_PROTO     = 3;
  Intent_Format_XPATH     = 4;
}

message GetIntentResponse {
  // datastore name
  string datastore_name = 1;
  // format
  Format format         = 2;
  // intent details
  oneof intent {
    Intent proto = 3;
    bytes  blob  = 4;
  }
  // name of the intent
  string intent_name           = 5;
  // intent priority
  int32 priority               = 6;
  // delete only from intended store
  // basically keeping the config on the device but unmanaged
  bool orphan                  = 7;
  // non_revertive is set to true if changes in running config should not
  // automatically be reverted.
  bool non_revertive           = 8;
  // explicit deletes that remain as part of the intent
  repeated schema.Path deletes = 9;
}

message TransactionSetRequest {
  // Transaction ID
  string transaction_id                     = 1;
  // datastore name
  string datastore_name                     = 2;
  // dry run indicator
  bool dry_run                              = 3;
  // optional timeout, seconds how long Transaction remains active
  // before being auto-canceled if not commited before
  optional int32 timeout                    = 4;
  // list of intents that make up the transaction
  repeated TransactionIntent intents        = 5;
  TransactionIntent          replace_intent = 6;
}

message TransactionIntent {
  // intent name
  string intent                     = 1;
  // intent priority
  int32 priority                    = 2;
  // list of updates
  repeated Update update            = 3;
  // delete indicator
  bool delete                       = 4;
  // delete only from intended store
  // basically keeping the config on the device but unmanaged
  bool orphan                       = 5;
  // non_revertive is set to true if changes in running config should not
  // automatically be reverted.
  bool non_revertive                = 6;
  // indicates this intent was previously applied; for non_revertive intents,
  // changes in the running config on the device should remain untouched during
  // reconciliation when this non_revertive intent shows up for the first time
  // again
  bool previously_applied           = 9;
  // indicate that if the intent is marked for deletion but does not exist, no
  // error is returned
  bool delete_ignore_no_exist       = 7;
  // explicit deletes that remain as part of the intent
  repeated schema.Path deletes      = 8;
  // paths that are meant to be reverted
  repeated schema.Path revert_paths = 10;
}

message TransactionSetResponse {
  repeated Update                           update             = 1;
  repeated                                  schema.Path delete = 2;
  map<string, TransactionSetResponseIntent> intents            = 3;
  repeated string                           warnings           = 4;
}

message TransactionSetResponseIntent {
  repeated string warnings = 1;
  repeated string errors   = 2;
}

message TransactionCancelRequest {
  // datastore name
  string datastore_name = 1;
  // Transaction ID
  string transaction_id = 2;
}
message TransactionCancelResponse {}

message TransactionConfirmRequest {
  // datastore name
  string datastore_name = 1;
  // Transaction ID
  string transaction_id = 2;
}
message TransactionConfirmResponse {}

message ListIntentRequest {
  // datastore name
  string datastore_name = 1;
}
message ListIntentResponse {
  string datastore_name  = 1;
  // list of intents without updates
  repeated string intent = 2;
}

message WatchDeviationRequest {
  // datastore name
  repeated string name = 1;
}

message WatchDeviationResponse {
  // datastore name
  string          name           = 1;
  string          intent         = 2;
  DeviationEvent  event          = 3;
  DeviationReason reason         = 4;
  schema.Path     path           = 5;
  TypedValue      expected_value = 6;
  TypedValue      current_value  = 7;
}

enum DeviationEvent {
  DE_UNKNOWN = 0;
  START      = 1;
  END        = 2;
  UPDATE     = 3;
  CLEAR      = 4;
}

enum DeviationReason {
  DR_UNKNOWN    = 0;
  UNHANDLED     = 1;
  NOT_APPLIED   = 2;
  OVERRULED     = 3;
  INTENT_EXISTS = 4;
}

// sub messages
message Update {
  schema.Path path  = 1;
  TypedValue  value = 2;
}

message DiffUpdate {
  schema.Path path            = 1;
  TypedValue  main_value      = 2;
  TypedValue  candidate_value = 3;
}

message TypedValue {
  uint64 timestamp = 1;
  oneof  value {
    string                string_val      = 2;
    int64                 int_val         = 3;
    uint64                uint_val        = 4;
    bool                  bool_val        = 5;
    bytes                 bytes_val       = 6;
    float                 float_val       = 7;
    Decimal64             decimal_val     = 8;
    double                Double_val      = 9;
    ScalarArray           leaflist_val    = 10;
    google.protobuf.Any   any_val         = 11;
    bytes                 json_val        = 12;
    bytes                 json_ietf_val   = 13;
    string                ascii_val       = 14;
    bytes                 proto_bytes     = 15;
    google.protobuf.Empty empty_val       = 16;
    IdentityRef           identityref_val = 17;
  }
}

message IdentityRef {
  string value  = 1;
  string prefix = 2;
  string module = 3;
}

message UpdateResult {
  // The operation that was associated with the schema.Path specified.
  enum Operation {
    INVALID = 0;
    DELETE  = 1; // The result relates to a delete of  schema.Path.
    REPLACE = 2; // The result relates to a replace of schema.Path.
    UPDATE  = 3; // The result relates to an update of schema.Path.
  }
  schema.Path path = 2; // schema.Path associated with the update.
  Operation   op   = 4; // Update operation type.
}

message Notification {
  // Timestamp in nanoseconds since Epoch.
  int64 timestamp             = 1;
  // Data elements that have changed values.
  repeated Update update      = 4;
  // Data elements that have been deleted.
  repeated schema.Path delete = 5;
}

message DataStore {
  // name of the datastore (candidate)
  string name    = 2;
  // candidate datastore owner
  string owner   = 3;
  // candidate datastore priority
  int32 priority = 4;
}

// Decimal64 is used to encode a fixed precision decimal number. The value
// is expressed as a set of digits with the precision specifying the
// number of digits following the decimal point in the digit set.
message Decimal64 {
  int64  digits    = 1; // Set of digits.
  uint32 precision = 2; // Number of digits following the decimal point.
}

// GetDataRequest encoding
enum Encoding {
  STRING    = 0;
  JSON      = 1;
  JSON_IETF = 2;
  PROTO     = 3;
}

// ScalarArray is used to encode a mixed-type array of values.
message ScalarArray {
  // The set of elements within the array. Each TypedValue message should
  // specify only elements that have a field identifier of 1-7 (i.e., the
  // values are scalar values).
  repeated TypedValue element = 1;
}

message NetconfOptions {
  // for netconf targets:
  // include namespace if a prefix is present
  // in the path elements.
  bool include_ns                  = 5;
  // for netconf targets:
  // add base1.0 as ns for operation attribute.
  bool operation_with_ns           = 6;
  // for netconf targets:
  // use operation remove instead of delete when deleting.
  bool use_operation_remove        = 7;
  // for netconf type, specifies which datastore to commit.
  // Can be either `candidate` or `running`.
  CommitCandidate commit_candidate = 8;
}

message GnmiOptions {
  // for gnmi targets
  string encoding    = 11;
  // xpath target
  string target_name = 12;
}

// Southbound interface of the datastore
message Target {
  // target type: gnmi or netconf
  string type             = 1;
  // target address
  string address          = 2;
  // per protocol ports
  uint32 port             = 12;
  // tls client certs, ca cert or skip_verify
  TLS tls                 = 3;
  // target credentials
  Credentials credentials = 4;
  // protocol options
  oneof protocolOptions {
    GnmiOptions    gnmi_opts    = 5;
    NetconfOptions netconf_opts = 6;
  }
  // reflects the target connection status
  TargetStatus status   = 9;
  // if the status is NOT_CONNECTED, this fields might
  // more details about the reason.
  string status_details = 10;
}

enum TargetStatus {
  UNKNOWN       = 0;
  CONNECTED     = 1;
  NOT_CONNECTED = 2;
}

enum CommitCandidate {
  COMMIT_CANDIDATE = 0;
  COMMIT_RUNNING   = 1;
}

// TLS Config
message TLS {
  string ca   = 1;
  string cert = 2;
  string key  = 3 [ (sdc.options.secret_field) = true, debug_redact = true ];
  bool   skip_verify = 4;
}

// Target Credentials
message Credentials {
  option (sdc.options.secret) = true;

  string username             = 1 [ (sdc.options.secret_field) = false ];
  string password             = 2 [ debug_redact = true ];
  string token                = 3 [ debug_redact = true ];
}

message Sync {
  // if true, all received notifications
  // are validated agains the schema
  bool validate              = 1;
  // number of notification to buffer while writing
  // to cache
  int64 buffer               = 2;
  // number of cache writers
  int64 write_workers        = 3;
  // list of sync strategies
  repeated SyncConfig config = 4;
}

message SyncConfig {
  // sync routing name
  string name          = 1;
  Target target        = 2;
  // paths to subscribe to
  repeated string path = 3;
  // gnmi only: mode, on-change, sample, or once
  SyncMode mode        = 4;
  // interval for gNMI mode sample or once
  // as well for netconf
  uint64 interval      = 5;
}

enum SyncMode {
  SM_ON_CHANGE = 0;
  SM_SAMPLE    = 1;
  SM_ONCE      = 2;
  SM_GET       = 3;
}

message Subscription {
  // objects to subscribe to
  repeated schema.Path path = 1;
  // data type config, state
  schema.DataType data_type = 2;
  // sample interval
  uint64 sample_interval    = 3;
  // suppress redandant.. this is probably not needed
  bool suppress_redundant   = 4;
}

message Watch {
  // objects to watch, identified by a path.
  repeated schema.Path path = 1;
  // data type config, state
  schema.DataType data_type = 2;
  // heartbeat interval after which the object
  // data is sent to the watcher even if it did not change.
  uint64 heartbeat_interval = 3;
}

message Intent {
  // intent name
  string intent          = 1;
  // intent priority
  int32 priority         = 2;
  // list of updates
  repeated Update update = 3;
}

message BlameConfigRequest {
  // datastore name
  string datastore_name   = 1;
  bool   include_defaults = 5;
}

message BlameConfigResponse { BlameTreeElement config_tree = 1; }

message BlameTreeElement {
  string     name                    = 1;
  string     owner                   = 2;
  TypedValue value                   = 3;
  TypedValue deviation_value         = 4;
  // key_name is set in case the level in the tree is a key level of a list.
  string                    key_name = 5;
  repeated BlameTreeElement childs   = 10;
}

message PathValue {
  schema.Path path  = 1;
  TypedValue  value = 2;
}

message PathValues { repeated PathValue path_values = 1; }