lease_status.proto

// Copyright 2017 The Cockroach Authors.
//
// Use of this software is governed by the Business Source License
// included in the file licenses/BSL.txt.
//
// As of the Change Date specified in that file, in accordance with
// the Business Source License, use of this software will be governed
// by the Apache License, Version 2.0, included in the file
// licenses/APL.txt.

syntax = "proto3";
package cockroach.kv.kvserver.storagepb;
option go_package = "kvserverpb";

import "roachpb/data.proto";
import "kv/kvserver/liveness/livenesspb/liveness.proto";
import "util/hlc/timestamp.proto";

import "gogoproto/gogo.proto";

enum LeaseState {
  // ERROR indicates that the lease can't be used or acquired.
  ERROR = 0;
  // VALID indicates that the lease is not expired at the current clock
  // time and can be used to serve a given request.
  VALID = 1;
  // UNUSABLE indicates that a lease has not expired at the current clock
  // time, but cannot be used to serve a given request. A lease may be
  // unusable for one of two reasons.
  //
  // First, if the request operates at a timestamp in the future, it is
  // possible for the request's timestamp to fall outside of the lease's
  // validity window, even if the lease is not yet expired at the current
  // clock time. In such cases, the lease must be extended past the
  // request's timestamp before the request can be served under the lease.
  //
  // Second, even if the request does not operate at a timestamp in the
  // future and operates fully within the lease's validity window, it may
  // operate at a time too close to the lease's expiration to be served
  // safely due to clock uncertainty. We refer to the period at the end of
  // each lease, immediately before its expiration, as its stasis period.
  //
  // The point of the stasis period is to prevent reads on the old
  // leaseholder (the one whose stasis we're talking about) from missing
  // to see writes performed under the next lease (held by someone else)
  // when these writes should fall in the uncertainty window. Even without
  // the stasis, writes performed by the new leaseholder are guaranteed to
  // have higher timestamps than any reads served by the old leaseholder.
  // However, a read at timestamp T needs to observe all writes at
  // timestamps [T, T+maxOffset] and so, without the stasis, only the new
  // leaseholder might have some of these writes. In other words, without
  // the stasis, a new leaseholder with a fast clock could start
  // performing writes ordered in real time before the old leaseholder
  // considers its lease to have expired.
  //
  // An UNUSABLE lease may become VALID for the same leaseholder after a
  // successful RequestLease (for expiration-based leases) or Heartbeat
  // (for epoch-based leases), each of which serve as forms of "lease
  // extension".
  UNUSABLE = 2;
  // EXPIRED indicates that the current clock time is past the lease's
  // expiration time. An expired lease may become VALID for the same
  // leaseholder on RequestLease or Heartbeat, or it may be replaced by a
  // new leaseholder with a RequestLease (for expiration-based leases) or
  // IncrementEpoch+RequestLease (for epoch-based leases).
  //
  // Only an EXPIRED lease may change hands non-cooperatively.
  EXPIRED = 3;
  // PROSCRIBED indicates that the lease's proposed timestamp is earlier
  // than allowed and can't be used to serve a request. This is used to
  // detect node restarts: a node that has restarted will see its former
  // incarnation's leases as PROSCRIBED so it will renew them before using
  // them. This state also used during a lease transfer, to prevent the
  // outgoing leaseholder from serving any other requests under its old
  // lease. Note that the PROSCRIBED state is only visible to the
  // leaseholder; other nodes may see this as a VALID lease.
  PROSCRIBED = 4;
}

// LeaseStatus holds the lease state, the current clock time at which the
// state is accurate, the request time at which the status is accurate, the
// lease iself, and optionally the liveness if the lease is epoch-based.
message LeaseStatus {
  // Lease which this status describes.
  roachpb.Lease lease = 1 [(gogoproto.nullable) = false];
  // Clock timestamp that the lease was evaluated at.
  util.hlc.Timestamp now = 2 [(gogoproto.nullable) = false,
    (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/util/hlc.ClockTimestamp"];
  // Timestamp for the request operating under the lease.
  util.hlc.Timestamp request_time = 5 [(gogoproto.nullable) = false];
  // State of the lease at now for a request at request_time.
  LeaseState state = 3;
  // If state == ERROR, this provides more info about the error.
  string err_info = 6;
  // Liveness if this is an epoch-based lease.
  kv.kvserver.liveness.livenesspb.Liveness liveness = 4 [(gogoproto.nullable) = false];
  // The minimum observed timestamp on a transaction that is respected by this lease.
  util.hlc.Timestamp min_valid_observed_timestamp = 7 [(gogoproto.nullable) = false,
    (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/util/hlc.ClockTimestamp"];
}