github.com/psiphon-labs/goarista@v0.0.0-20160825065156-d002785f4c67/openconfig/openconfig.proto

// Copyright 2015 Google, Inc.
//
// 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";

// Package openconfig defines the gRPC service for getting and setting the
// OpenConfig configuration and state of a network device.
//
// This package and its contents have not been ratified by OpenConfig.  It is
// a working proposal by Google.
package openconfig;

// A Type describes what format a Value's data is encoded in.
enum Type {
  JSON = 0;
  BYTES = 1;
}

// A Path represents an open config path as a list of strings, one element
// per string.
message Path {
  repeated string element = 1;
}

// A Value is either raw data or a JSON encoded value.  An enumerated value is
// of type JSON, with the numeric value in the value field and the name of the
// enumerated value in the name field.
message Value {
  bytes value = 1;
  Type type = 2;
  string name = 3;
}

// An Update maps a path to a value.
//
// In a Notification, an Update represents a new or updated value for path.  The
// absolute path name is the concatenation of the Notification prefix and the
// Update path.  Updates are only sent by the target.  Path must always specify
// a leaf node.  Value should be a scalar value (e.g., if Value is JSON encoded
// then the value 123 is acceptable, but {"x":123} is not).
//
// In a SetRequest, an Update contains a path to a read-write node and an
// optional value.  The absolute path name is the concatenation of the
// SetRequest prefix and the Update path The path may reference either a
// directory or leaf node.  If value is not present then path, and all its
// subelements, should be removed.  If value set and path references a directory
// node, the value is the JSON encoded tree of values below that node,
// otherwise, if the value is a scalar and may be encoded in JSON are as raw
// BYTES.  the value
//
// For an example of updating a directory node, consider a tree that has the
// following values:
//
//   /a/b/c: 1
//   /a/b/d: 2
//   /a/b/e: 3
//
// And an Update of
//
//   Path: /a/b
//   Value: "{c: 4, f: 5}"
//
// The result is that /a/b/d and /a/b/e are removed, /a/b/c now has the value of
// 4, and /a/b/f is added with the value of 5.
message Update {
   Path path = 1;
   Value value = 2;
}

// A Notification is a list of updates to apply.  Deletes are a list of paths to
// delete as long as their data is older than timestamp.  Deleting nodes deletes
// all values below the node that are older than timestamp.  Deletes are
// performed after updates are applied.  Delete paths are created by
// concatenating the prefix, if present, with the individual paths.
//
// Update paths are created by concatenating the prefix, if present, with the
// paths contained in the Updates.
//
// It is valid to have a path be both in an update and match a delete.  The
// deletion will only delete values that are older than this update.
//
// Each notification should contain at most a single update for a given path.
// If a nonconforming implementation does send multiple updates for a given path
// in a single notification, all but the final update should be ignored.
//
// The prefix should normally be the longest common prefix to all the individual
// update and delete path.  This reduces the repetition of the common prefix in
// each update and/or delete.  The individual updates and deletes also are a
// Path (repeated list of elements), allowing a notification such as:
//
//   prefix: /a/b/c
//   update: {
//     path: d
//     value: x
//   }
//   update: {
//     path: e/f
//     value: y
//   }
//   update: {
//     path: e/g
//     value: z
//   }
//
// The prefix may begin with an alias.  An alias is a Path with 1 or more
// elements, which maps to another Path.  Aliases may be defined by either the
// target or the client.  Target defined aliases are limited to a single
// element.  Aliases are client specific (though a target may define the same
// alias for multiple clients).
//
// The target defines an alias by sending a Notification that has alias set and
// a non-empty prefix. When alias is set, a Notification need not provide
// updates or deletes.  If the alias was previously defined, it is over ridden
// with the new definition.  Once defined, the target may send the value of
// alias as the first element of a prefix.  A target must not send target
// defined aliases to clients that do not specify the use_aliases option in the
// initial SubscriptionList message.  A target does not need to define aliases
// even if the client does specify the use_aliases option in the initial
// SubscriptionLlist message.
//
// Clients define aliases by sending a SubscriptionRequest with aliases set.
//
// A target should use a define alias when possible, but is not required to.  A
// target may ignore client defined aliases.
//
// Clients should not define aliases that valid paths in the data tree.  The
// target must not define aliases that valid paths in the dat tree.
//
// If a target sends a notification with alias set, but not prefix, then it is
// indicating it will no longer use this alias.  The client may delete this
// alias from its list of aliases.  A target may not delete an alias defined by
// the client.  It is implementation dependent on what happens if the client
// defines an alias that is also defined by the target.
//
// Aliases must not be used in UDP packets.
//
// If a client sets the use_aliases option, or defines aliases, in the initial
// SubscriptionList message, then it must always check the initial elements of a
// prefix against the list of known aliases, expanding the prefix as needed.
// Aliases must always be defined as fully expanded prefixes.  Only single alias
// lookup is needed per Notification.
//
// Target defined aliases may be any unique string.  A target may choose to use
// a unique prefix for aliases to make them visually distinct.  For example, a
// target might construct all aliases as an @ character followed by a decimal or
// hexadecimal number (perhaps a hashed address in memory).
//
// Example:
//
// Define @42 as an alias:
//
//   timestamp: 1439416376123456789
//   prefix: "this_is"
//   prefix: "a_long"
//   prefix: "prefix"
//   alias: "@42
//
// Use @42 as an alias to set /this_is/a_long/prefix/Ethernet0/0/1/in-octets to
// 17:
//
//   timestamp: 1439416376456456456
//   prefix: "@42"
//   prefix: "Ethernet0/0/1"
//   update: {
//     path: {
//       element: "in-octets"
//     }
//     value: 17
//   }
//
// Delete the alias @42:
//
//   timestamp: 1439416376987654321
//   alias: @42
message Notification {
  int64 timestamp = 1;
  Path prefix = 2;
  string alias = 3;
  repeated Update update = 4;
  repeated Path delete = 5;
}

// UDPWrapper adds metadata necessary for encapsulating a list of notifications
// into a UDP packet.  It adds the ability to identify the agent that originated
// the Notifications, detect packet loss, and identify latency introduced by
// the target wrapping notifications.
//
// The target should keep the total size of a serialized UDPWrapper message
// small enough to not cause IP packet fragmentation.
message UDPWrapper {
  // ID Identifies the device (e.g., Loopback IP address, linecard, ...)
  // TODO(borman): Add examples.  Perhaps Agent/module/submodule for juniper.
  Path id = 1;

  // Optional Epoch time of when the message is queued for transmit.
  // Useful to quantify delay between message generation and transmission.
  uint64 transmit_timestamp = 2;

  // The sequence_number must start at 1 and increment by 1 for each new packet
  // sent.  A client may use this to determine if a packet was lost.
  uint64 sequence_number = 3;

  repeated Notification notification = 4;
}

service OpenConfig {
  // Subscribe subscribes for streaming updates.  Streaming updates are provided
  // as a series of Notifications, each of which update a portion of the tree.
  // The target must send the current values of all subscribed paths at the
  // start of the stream, followed by a sync_response of 0.
  //
  // A Subscription operates in one of three modes.
  //
  // Streaming:  This is the default mode.  The target sends continual updates
  // of each value as specified by each subscription's coalesce_interval.  The
  // client may request the target to resend the current value of a set of paths
  // by sending a SyncRequest.
  //
  // Once: This mode is specified by setting once to true in the
  // SubscriptionRequest.  The target must close the stream after sending
  // the sync_response of 0.  The target should only send each value once.
  //
  // Poll: This mode is the equivalent of periodic Once requests but sent over a
  // single stream.  Polling is specified by setting poll_interval in the
  // SubscriptionRequest to the expected number of nanoseconds between polls.
  // The target stops sending updates after sending the sync_response of 0.
  // After the polling interval, the client sends a new SubscriptionRequest with
  // only the poll_interval set.  The target must respond by sending the current
  // values of all subscribed paths, once again followed with a sync_response of
  // 0.  This process then repeats until the client closes the request stream.
  rpc Subscribe(stream SubscribeRequest) returns (stream SubscribeResponse);

  // Get requests a single snapshot of the requested data.  A Get request may
  // contain a hint that the request will be repeated (i.e., polling).  A Get is
  // the equivalent of a Subscribe with once set, with the exception that all
  // the key value pairs will be returned in a single response.
  rpc Get(GetRequest) returns (GetResponse);

  // Set sets the paths contained in the SetRequest to the values If a path does
  // not exist, or is read-only the SetResponse will return an error.  All paths
  // in the SetRequest must be valid or the entire request must be rejected.  If
  // a path specifies a node, rather than the leaf, then the value must be the
  // values of the node's children encoded in JSON.  Binary data in the tree
  // must be base64 encoded.
  rpc Set(stream SetRequest) returns (stream SetResponse);
}

// An Error contains information about why a particular request failed.
//
// The canonical error codes are defined for each language.
//
//   Go:   import "google.golang.org/grpc/codes"
//   C++:  #include <grpc++/status_code_enum.h>
//   Java: import static io.grpc.Status.Code;
//   C:    #include <grpc/status.h>
//   C#:   using Grpc.Core;
message Error {
  uint32 code = 1;                // Canonical grpc error code
  string message = 2;             // Human readable error
  google.protobuf.Any data = 3;   // optional additional information
}

// A SubscribeRequest is either a subscription request, a change to the
// heartbeat rate, or a request for resynchronization of data.  It is always
// sent from the client to the target.
//
// Proxy is a list of proxies to use to get to the target.  The first proxy
// listed is the address of the next hop.  Targets ignore the proxy field (it
// should not be set).
message SubscribeRequest {
  oneof request {
    SubscriptionList subscribe = 1;
    Heartbeat heartbeat = 2;         // See description for Heartbeat
    SyncRequest sync = 3;            // See description for SyncRequest
    AliasList aliases = 4;
  }
  repeated string proxy = 5;
}

// A SubscribeResponse is always sent from the target to the client.
message SubscribeResponse {
  oneof response {
    Notification update = 1;
    Heartbeat heartbeat = 2;  // See description for Heartbeat
    uint64 sync_response = 3; // See description for SyncRequest
  }
}

// SubscriptionList contains the list of individual subscriptions.  A
// SubscriptionList is only valid if all of the contained subscriptions are
// valid.  Setting once to false or poll_interval to 0 is the equivalent of the
// mode not being set (i.e., streaming).
//
// If prefix is set then all subscriptions in the list and all notifications
// generated are relative to prefix.
//
// If poll_interval is not set, then a SubscriptionList must only be sent once.
// If poll_interval is set, the SubscriptionLists following the initial
// SubscriptionList must only contain a poll_interval.
message SubscriptionList {
  oneof mode {
    bool once = 10;
    uint64 poll_interval = 11;
  }
  repeated Subscription subscription = 1;
  Path prefix = 2;
  message Options {
    bool use_aliases = 1;  // client accepts target defined aliases.
  }
  Options options = 3;
}

// Subscription contains a path as well as the target side coalesce_interval for
// aggregating values, typically counters.  If the target cannot support the
// interval the subscription must be rejected.  The coalesce_interval is only
// used for subscriptions in streaming mode.  If the coalesce_interval is 0 then
// the coalesce_interval is target specified.
message Subscription {
  Path path = 1;
  uint64 coalesce_interval = 2; // nanoseconds between updates
}

// An AliasList represents a list of aliases.
message AliasList {
  repeated Alias alias = 1;
}

// An Alias specifies a preferred client defined alias for a specified path.  An
// Alias is only sent from the client to the target.  An alias is typically one
// element and is much shorter than the provided path.  A target should
// substitute alias for path in Notifications.  Targets may ignore Alias
// messages.
//
// The path must be fully expanded and not use an alias.
//
// If alias is set and path is not then the alias must no longer be used by the
// target, once received.  A client may still see Notifications using the alias
// that were generated prior to the target receiving the request to stop using
// the alias.
message Alias {
  Path path = 1;
  Path alias = 2;
}

// A Heartbeat requests a (possibly repeated) response from the remote side.
message Heartbeat {
  // interval is the maximum amount of time, in nanoseconds, between subsequent
  // messages from the remote side.  An empty message may be sent if no other
  // messages are pending.  If interval is 0 then the remote must immediately
  // respond with a (possibly empty) message.
  uint64 interval = 1;
}

// A SyncRequest requests that all values identified by path be resent.  The
// target should respond with a series of updates and then a sync_response with
// the provided id, which should not be zero.
//
// A target is suggested to keep a timestamp of when the SyncRequest starts,
// followed by notifications, all of which are past the starting timestamp.
// Before sending the sync_response, a delete for each of the paths should be
// made with the starting timestamp.  This will assure the client removes all
// stale data that was not part of the update.
//
// If prefix is set, each path is relative to prefix.
message SyncRequest {
   uint64 id = 1;
   Path prefix = 2;
   repeated Path path = 3;
}

message GetRequest {
  Path prefix = 1;          // If set, each path is realitve to prefix
  repeated Path path = 2;   // List of paths to return information for

  // If cache_interval is provided and is non-zero number of nanoseconds, it is
  // a hint of when this get request will be repeated in the future.
  int64 cache_interval = 3;
 }

message GetResponse {
  repeated Notification notification = 1;
}

// A SetRequest contains an optional prefix, a list of zero or more Paths to
// delete and a list of zero or more Updates.  The delete and update paths are
// relative to prefix.  Deletes should appear to happen prior to updates being
// applied.  This supports delete, update, and replace:
//
//   delete - a path is listed in the delete field
//   update - a path is listed in the update field
//   replace - a path is listed in both the delete field and the update field.
//
// The target must either apply all the deletes and updates or return an error.
// The deletes and updates should appear to be atomically applied.
message SetRequest {
  Path prefix = 1;
  repeated Path delete = 2;
  repeated Update update = 3;
}

// A SetResponse contains responses to a SetRequest.  The optional prefix is
// applied to all paths in response.  Each path provided by a SetRequest needs a
// response, but there need not be a 1:1 correspondence between SetRequests and
// SetResponses (e.g., the target may issue a single response to multiple
// requests, or multiple responses to a single request).
message SetResponse {
  Path prefix = 1;
  repeated UpdateResponse response = 2;
}

// An UpdateResponse contains the response for a single path Update.
message UpdateResponse {
  Path path = 1;       // path provided in SetRequest.
  Error error = 2;     // optional error, if set, timestamp is optional
  // The timestamp is the time, in nanoseconds since the epoch, that a Set was
  // accepted (i.e., the request was valid).  It does not imply the value was
  // actually propagated to an underlying datastore.
  int64 timestamp = 3;
}