consul/proto/pbcommon/common.proto

syntax = "proto3";

package common;

import "google/protobuf/duration.proto";

// RaftIndex is used to track the index used while creating
// or modifying a given struct type.
//
// mog annotation:
//
// target=github.com/hashicorp/consul/agent/structs.RaftIndex
// output=common.gen.go
// name=Structs
// ignore-fields=state,sizeCache,unknownFields
message RaftIndex {
  // @gotags: bexpr:"-"
  uint64 CreateIndex = 1;
  // @gotags: bexpr:"-"
  uint64 ModifyIndex = 2;
}

// TargetDatacenter is intended to be used within other messages used for RPC routing
// amongst the various Consul datacenters
message TargetDatacenter {
  string Datacenter = 1;
}

// mog annotation:
//
// target=github.com/hashicorp/consul/agent/structs.WriteRequest
// output=common.gen.go
// name=Structs
// ignore-fields=state,sizeCache,unknownFields
message WriteRequest {
  // Token is the ACL token ID. If not provided, the 'anonymous'
  // token is assumed for backwards compatibility.
  string Token = 1;
}

// ReadRequest is a type that may be embedded into any requests for read
// operations.
// It is a replacement for QueryOptions now that we no longer need any of those
// fields because we are moving away from using blocking queries.
// It is also similar to WriteRequest. It is a separate type so that in the
// future we can introduce fields that may only be relevant for reads.
message ReadRequest {
  // Token is the ACL token ID. If not provided, the 'anonymous'
  // token is assumed for backwards compatibility.
  string Token = 1;

  // RequireConsistent indicates that the request must be sent to the leader.
  bool RequireConsistent = 2;
}

// QueryOptions is used to specify various flags for read queries
//
// mog annotation:
//
// target=github.com/hashicorp/consul/agent/structs.QueryOptions
// output=common.gen.go
// name=Structs
// ignore-fields=StaleIfError,AllowNotModifiedResponse,state,sizeCache,unknownFields
message QueryOptions {
  // Token is the ACL token ID. If not provided, the 'anonymous'
  // token is assumed for backwards compatibility.
  string Token = 1;

  // If set, wait until query exceeds given index. Must be provided
  // with MaxQueryTime.
  uint64 MinQueryIndex = 2;

  // Provided with MinQueryIndex to wait for change.
  // mog: func-to=structs.DurationFromProto func-from=structs.DurationToProto
  google.protobuf.Duration MaxQueryTime = 3;

  // If set, any follower can service the request. Results
  // may be arbitrarily stale.
  bool AllowStale = 4;

  // If set, the leader must verify leadership prior to
  // servicing the request. Prevents a stale read.
  bool RequireConsistent = 5;

  // If set, the local agent may respond with an arbitrarily stale locally
  // cached response. The semantics differ from AllowStale since the agent may
  // be entirely partitioned from the servers and still considered "healthy" by
  // operators. Stale responses from Servers are also arbitrarily stale, but can
  // provide additional bounds on the last contact time from the leader. It's
  // expected that servers that are partitioned are noticed and replaced in a
  // timely way by operators while the same may not be true for client agents.
  bool UseCache = 6;

  // If set and AllowStale is true, will try first a stale
  // read, and then will perform a consistent read if stale
  // read is older than value.
  // mog: func-to=structs.DurationFromProto func-from=structs.DurationToProto
  google.protobuf.Duration MaxStaleDuration = 7;

  // MaxAge limits how old a cached value will be returned if UseCache is true.
  // If there is a cached response that is older than the MaxAge, it is treated
  // as a cache miss and a new fetch invoked. If the fetch fails, the error is
  // returned. Clients that wish to allow for stale results on error can set
  // StaleIfError to a longer duration to change this behavior. It is ignored
  // if the endpoint supports background refresh caching. See
  // https://www.consul.io/api/index.html#agent-caching for more details.
  // mog: func-to=structs.DurationFromProto func-from=structs.DurationToProto
  google.protobuf.Duration MaxAge = 8;

  // MustRevalidate forces the agent to fetch a fresh version of a cached
  // resource or at least validate that the cached version is still fresh. It is
  // implied by either max-age=0 or must-revalidate Cache-Control headers. It
  // only makes sense when UseCache is true. We store it since MaxAge = 0 is the
  // default unset value.
  bool MustRevalidate = 9;

  // StaleIfError specifies how stale the client will accept a cached response
  // if the servers are unavailable to fetch a fresh one. Only makes sense when
  // UseCache is true and MaxAge is set to a lower, non-zero value. It is
  // ignored if the endpoint supports background refresh caching. See
  // https://www.consul.io/api/index.html#agent-caching for more details.
  google.protobuf.Duration StaleIfError = 10;

  // Filter specifies the go-bexpr filter expression to be used for
  // filtering the data prior to returning a response
  string Filter = 11;
}

// QueryMeta allows a query response to include potentially
// useful metadata about a query
//
// mog annotation:
//
// target=github.com/hashicorp/consul/agent/structs.QueryMeta
// output=common.gen.go
// name=Structs
// ignore-fields=NotModified,Backend,state,sizeCache,unknownFields
message QueryMeta {
  // This is the index associated with the read
  uint64 Index = 1;

  // If AllowStale is used, this is time elapsed since
  // last contact between the follower and leader. This
  // can be used to gauge staleness.
  // mog: func-to=structs.DurationFromProto func-from=structs.DurationToProto
  google.protobuf.Duration LastContact = 2;

  // Used to indicate if there is a known leader node
  bool KnownLeader = 3;

  // Consistencylevel returns the consistency used to serve the query
  // Having `discovery_max_stale` on the agent can affect whether
  // the request was served by a leader.
  string ConsistencyLevel = 4;

  // Reserved for NotModified and Backend.
  reserved 5, 6;

  // ResultsFilteredByACLs is true when some of the query's results were
  // filtered out by enforcing ACLs. It may be false because nothing was
  // removed, or because the endpoint does not yet support this flag.
  bool ResultsFilteredByACLs = 7;
}

// EnterpriseMeta contains metadata that is only used by the Enterprise version
// of Consul.
message EnterpriseMeta {
  // Namespace in which the entity exists.
  string Namespace = 1;
  // Partition in which the entity exists.
  string Partition = 2;
}