holo.proto

//
// Copyright (c) The Holo Core Contributors
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
//

syntax = "proto3";

package holo;

// Service specification for the Holo northbound interface.
service Northbound {
  // Retrieve the capabilities supported by the target.
  rpc Capabilities(CapabilitiesRequest) returns (CapabilitiesResponse) {}

  // Retrieve the specified schema data from the target.
  rpc GetSchema(GetSchemaRequest) returns (GetSchemaResponse) {}

  // Retrieve configuration data, state data or both from the target.
  rpc Get(GetRequest) returns (GetResponse) {}

  // Validate the configuration without committing it.
  rpc Validate(ValidateRequest) returns (ValidateResponse) {}

  // Create a new configuration transaction using a two-phase commit protocol.
  rpc Commit(CommitRequest) returns (CommitResponse) {}

  // Execute a YANG RPC/Action.
  rpc Execute(ExecuteRequest) returns (ExecuteResponse) {}

  // Get the list of transactions recorded in the rollback log.
  rpc ListTransactions(ListTransactionsRequest) returns (stream ListTransactionsResponse) {}

  // Retrieve configuration data from the rollback log.
  rpc GetTransaction(GetTransactionRequest) returns (GetTransactionResponse) {}
}

// ----------------------- Parameters and return types -------------------------

//
// RPC: Capabilities()
//
message CapabilitiesRequest {
  // Empty.
}

message CapabilitiesResponse {
  // Return values:
  // - grpc::StatusCode::OK: Success.

  // Holo version.
  string version = 1;

  // Supported schema modules.
  repeated ModuleData supported_modules = 2;

  // Supported encodings.
  repeated Encoding supported_encodings = 3;
}

//
// RPC: GetSchema()
//
message GetSchemaRequest {
  // The name of the module to retrieve.
  string module_name = 1;

  // The specific revision of the module (optional).
  string module_revision = 2;

  // The name of the submodule to retrieve (optional).
  string submodule_name = 3;

  // The specific revision of the submodule (optional).
  string submodule_revision = 4;

  // The desired format of the schema output (optional).
  SchemaFormat format = 5;
}

message GetSchemaResponse {
  // - grpc::StatusCode::OK: Success.
  // - grpc::StatusCode::NOT_FOUND: Schema module not found.

  // The requested schema data.
  string data = 1;
}

//
// RPC: Get()
//
message GetRequest {
  // Type of elements within the data tree.
  enum DataType {
    // All data elements.
    ALL = 0;

    // Config elements.
    CONFIG = 1;

    // State elements.
    STATE = 2;
  }

  // The type of data being requested.
  DataType type = 1;

  // Encoding to be used.
  Encoding encoding = 2;

  // Include implicit default nodes.
  bool with_defaults = 3;

  // Requested YANG path.
  string path = 4;
}

message GetResponse {
  // Return values:
  // - grpc::StatusCode::OK: Success.
  // - grpc::StatusCode::INVALID_ARGUMENT: Invalid YANG data path.

  // Timestamp in nanoseconds since Epoch.
  int64 timestamp = 1;

  // The requested data.
  DataTree data = 2;
}

//
// RPC: Validate()
//
message ValidateRequest {
  // Configuration data.
  DataTree config = 1;
}

message ValidateResponse {
  // Return values:
  // - grpc::StatusCode::OK: Success.
  // - grpc::StatusCode::INVALID_ARGUMENT: Validation error.
}

//
// RPC: Commit()
//
message CommitRequest {
  enum Operation {
    // Merge the provided data tree into the running configuration.
    MERGE = 0;

    // Replace the running configuration by the provided data tree.
    REPLACE = 1;

    // Apply the provided configuration changes in the YANG PATCH format.
    CHANGE = 2;
  }

  // Commit operation.
  Operation operation = 1;

  // Configuration data.
  DataTree config = 2;

  // Optional comment describing the configuration changes.
  string comment = 3;

  // Confirmed commit timeout (in minutes).
  uint32 confirmed_timeout = 4;
}

message CommitResponse {
  // Return values:
  // - grpc::StatusCode::OK: Success.
  // - grpc::StatusCode::INVALID_ARGUMENT: Validation error.
  // - grpc::StatusCode::RESOURCE_EXHAUSTED: Failure to allocate resource.

  // ID of the created configuration transaction.
  uint32 transaction_id = 1;
}

//
// RPC: Execute()
//
message ExecuteRequest {
  // Data tree containing a single YANG RPC/Action (plus input parameters).
  DataTree data = 1;
}

message ExecuteResponse {
  // Return values:
  // - grpc::StatusCode::OK: Success.

  // The original data tree plus output parameters.
  DataTree data = 1;
}

//
// RPC: ListTransactions()
//
message ListTransactionsRequest {
}

message ListTransactionsResponse {
  // Return values:
  // - grpc::StatusCode::OK: Success.

  // Transaction ID.
  uint32 id = 1;

  // Date and time the transaction was committed.
  string date = 2;

  // Comment assigned to the transaction.
  string comment = 3;
}

//
// RPC: GetTransaction()
//
message GetTransactionRequest {
  // Transaction to retrieve.
  uint32 transaction_id = 1;

  // Encoding to be used.
  Encoding encoding = 2;
}

message GetTransactionResponse {
  // Return values:
  // - grpc::StatusCode::OK: Success.
  // - grpc::StatusCode::NOT_FOUND: Transaction ID wasn't found in the rollback log.

  DataTree config = 1;
}

// -------------------------------- Definitions --------------------------------

// YANG module.
message ModuleData {
  // Name of the YANG module;
  string name = 1;

  // Organization publishing the module.
  string organization = 2;

  // Latest revision of the module;
  string revision = 3;

  // Supported features.
  repeated string supported_features = 4;
}

// Supported encodings for YANG instance data.
enum Encoding {
  JSON = 0;
  XML = 1;
  LYB = 2;
}

// Supported schema formats.
enum SchemaFormat {
  YANG = 0;
  YIN = 1;
}

// YANG instance data.
message DataTree {
  // The encoding format of the data.
  Encoding encoding = 1;

  oneof data {
    // Data in string format, used for JSON or XML encodings.
    string data_string = 2;
    // Data in binary format, used for LYB encoding.
    bytes data_bytes = 3;
  }
}