From da3e3b7240d214b124023d9796b03d1228256911 Mon Sep 17 00:00:00 2001 From: Anthony Romano Date: Tue, 4 Apr 2017 11:05:19 -0700 Subject: [PATCH 1/3] clientv3: document from "don't halt lease client if there is a lease error" From https://github.com/coreos/etcd/pull/7866. --- clientv3/lease.go | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/clientv3/lease.go b/clientv3/lease.go index d9059022094..e94fce2adda 100644 --- a/clientv3/lease.go +++ b/clientv3/lease.go @@ -114,10 +114,27 @@ type Lease interface { Leases(ctx context.Context) (*LeaseLeasesResponse, error) // KeepAlive keeps the given lease alive forever. + // + // KeepAlive keeps the given lease alive forever. If the keepalive response posted to + // the channel is not consumed immediately, the lease client will continue sending keep alive requests + // to the etcd server at least every second until latest response is consumed. + // + // The KeepAlive channel closes if the underlying keep alive stream is interrupted in some + // way the client cannot handle itself; the error will be posted in the last keep + // alive message before closing. If there is no keepalive response within the + // lease's time-out, the channel will close with no error. In most cases calling + // KeepAlive again will re-establish keepalives with the target lease if it has not + // expired. KeepAlive(ctx context.Context, id LeaseID) (<-chan *LeaseKeepAliveResponse, error) // KeepAliveOnce renews the lease once. In most of the cases, KeepAlive // should be used instead of KeepAliveOnce. + // + // KeepAliveOnce renews the lease once. The response corresponds to the + // first message from calling KeepAlive. If the response has a recoverable + // error, KeepAliveOnce will retry the RPC with a new keep alive message. + // + // In most of the cases, Keepalive should be used instead of KeepAliveOnce. KeepAliveOnce(ctx context.Context, id LeaseID) (*LeaseKeepAliveResponse, error) // Close releases all resources Lease keeps for efficient communication From 3e58dd707f668b48956571f22ed7583bc5afd320 Mon Sep 17 00:00:00 2001 From: Gyuho Lee Date: Mon, 18 Dec 2017 10:19:41 -0800 Subject: [PATCH 2/3] clientv3: document lease KeepAlive streaming errors Signed-off-by: Gyuho Lee --- clientv3/lease.go | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/clientv3/lease.go b/clientv3/lease.go index e94fce2adda..229e8cd66ba 100644 --- a/clientv3/lease.go +++ b/clientv3/lease.go @@ -113,23 +113,24 @@ type Lease interface { // Leases retrieves all leases. Leases(ctx context.Context) (*LeaseLeasesResponse, error) - // KeepAlive keeps the given lease alive forever. + // KeepAlive keeps the given lease alive forever. If the keepalive response + // posted to the channel is not consumed immediately, the lease client will + // continue sending keep alive requests to the etcd server at least every + // second until latest response is consumed. // - // KeepAlive keeps the given lease alive forever. If the keepalive response posted to - // the channel is not consumed immediately, the lease client will continue sending keep alive requests - // to the etcd server at least every second until latest response is consumed. + // The returned "LeaseKeepAliveResponse" channel closes if underlying keep + // alive stream is interrupted in some way the client cannot handle itself; + // given context "ctx" is canceled or timed out. "LeaseKeepAliveResponse" + // from this closed channel is nil. // - // The KeepAlive channel closes if the underlying keep alive stream is interrupted in some - // way the client cannot handle itself; the error will be posted in the last keep - // alive message before closing. If there is no keepalive response within the - // lease's time-out, the channel will close with no error. In most cases calling - // KeepAlive again will re-establish keepalives with the target lease if it has not - // expired. + // If client keep alive loop halts with an unexpected error (e.g. "etcdserver: + // no leader") or canceled by the caller (e.g. context.Canceled), the error + // is returned. Otherwise, it retries. + // + // TODO(v4.0): post errors to last keep alive message before closing + // (see https://github.com/coreos/etcd/pull/7866) KeepAlive(ctx context.Context, id LeaseID) (<-chan *LeaseKeepAliveResponse, error) - // KeepAliveOnce renews the lease once. In most of the cases, KeepAlive - // should be used instead of KeepAliveOnce. - // // KeepAliveOnce renews the lease once. The response corresponds to the // first message from calling KeepAlive. If the response has a recoverable // error, KeepAliveOnce will retry the RPC with a new keep alive message. From fffb26596c7bdf7edd3816ab1bbc5022dc22b588 Mon Sep 17 00:00:00 2001 From: Gyuho Lee Date: Mon, 18 Dec 2017 10:34:43 -0800 Subject: [PATCH 3/3] words: whitelist "KeepAlive" Signed-off-by: Gyuho Lee --- .words | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.words b/.words index 561453ce956..7ca7100bdcb 100644 --- a/.words +++ b/.words @@ -1,6 +1,8 @@ ErrCodeEnhanceYourCalm ErrTimeout GoAway +KeepAlive +Keepalive RPC RPCs TODO