From 11ead62b9d67cec8eff6bfdfcd3f552314f4152e Mon Sep 17 00:00:00 2001 From: Gyuho Lee Date: Wed, 20 Jun 2018 10:28:41 -0700 Subject: [PATCH] clientv3: clarify "WithRequireLeader" for network partition Signed-off-by: Gyuho Lee --- clientv3/watch.go | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/clientv3/watch.go b/clientv3/watch.go index 39d149c530e..9c5cb5abd93 100644 --- a/clientv3/watch.go +++ b/clientv3/watch.go @@ -50,13 +50,19 @@ type Watcher interface { // and "WatchResponse" from this closed channel has zero events and nil "Err()". // The context "ctx" MUST be canceled, as soon as watcher is no longer being used, // to release the associated resources. - // If the context is "context.Background/TODO", returned "WatchChan" will not be closed - // and wait until events happen, except when server returns a non-recoverable error. - // For example, when context passed with "WithRequireLeader" and the connected server - // has no leader, error "etcdserver: no leader" is returned, and then "WatchChan" is - // closed with non-nil "Err()". - // Otherwise, as long as the context has not been canceled or timed out, watch will - // retry on other recoverable errors forever until reconnected. + // + // If the context is "context.Background/TODO", returned "WatchChan" will + // not be closed and block until event is triggered, except when server + // returns a non-recoverable error (e.g. ErrCompacted). + // For example, when context passed with "WithRequireLeader" and the + // connected server has no leader (e.g. due to network partition), + // error "etcdserver: no leader" (ErrNoLeader) will be returned, + // and then "WatchChan" is closed with non-nil "Err()". + // In order to prevent a watch stream being stuck in a partitioned node, + // make sure to wrap context with "WithRequireLeader". + // + // Otherwise, as long as the context has not been canceled or timed out, + // watch will retry on other recoverable errors forever until reconnected. // // TODO: explicitly set context error in the last "WatchResponse" message and close channel? // Currently, client contexts are overwritten with "valCtx" that never closes.