v3lock.proto

syntax = "proto3";
package v3lockpb;

import "gogoproto/gogo.proto";
import "etcd/api/etcdserverpb/rpc.proto";

// for grpc-gateway
import "google/api/annotations.proto";

option go_package = "go.etcd.io/etcd/server/v3/etcdserver/api/v3lock/v3lockpb";

option (gogoproto.marshaler_all) = true;
option (gogoproto.unmarshaler_all) = true;

// The lock service exposes client-side locking facilities as a gRPC interface.
service Lock {
  // Lock acquires a distributed shared lock on a given named lock.
  // On success, it will return a unique key that exists so long as the
  // lock is held by the caller. This key can be used in conjunction with
  // transactions to safely ensure updates to etcd only occur while holding
  // lock ownership. The lock is held until Unlock is called on the key or the
  // lease associate with the owner expires.
  rpc Lock(LockRequest) returns (LockResponse) {
      option (google.api.http) = {
        post: "/v3/lock/lock"
        body: "*"
    };
  }

  // Unlock takes a key returned by Lock and releases the hold on lock. The
  // next Lock caller waiting for the lock will then be woken up and given
  // ownership of the lock.
  rpc Unlock(UnlockRequest) returns (UnlockResponse) {
      option (google.api.http) = {
        post: "/v3/lock/unlock"
        body: "*"
    };
  }
}

message LockRequest {
  // name is the identifier for the distributed shared lock to be acquired.
  bytes name = 1;
  // lease is the ID of the lease that will be attached to ownership of the
  // lock. If the lease expires or is revoked and currently holds the lock,
  // the lock is automatically released. Calls to Lock with the same lease will
  // be treated as a single acquisition; locking twice with the same lease is a
  // no-op.
  int64 lease = 2;
}

message LockResponse {
  etcdserverpb.ResponseHeader header = 1;
  // key is a key that will exist on etcd for the duration that the Lock caller
  // owns the lock. Users should not modify this key or the lock may exhibit
  // undefined behavior.
  bytes key = 2;
}

message UnlockRequest {
  // key is the lock ownership key granted by Lock.
  bytes key = 1;
}

message UnlockResponse {
  etcdserverpb.ResponseHeader header = 1;
}