Etcd: Watches which begin at revision 0 actually start later

[aphyr]

This might be a bug, but I think it could also be undocumented or intended behavior in 3.4.3.

etcd's data model docs and
glossary say that revisions are monotonically increasing 64-bit integers, but don't specify what the first revision in the history is. If users want to watch all changes to a key from the beginning of time, they might begin a watch with revision 0. However, such a watch returns changes not from revision 0 (if that exists) or 1, but from some later revision--possibly the current revision on whatever node the client's talking to? Beginning with revision 1 does appear to capture all changes.

I suggest that etcd document the initial behavior around revisions: what is the first revision in etcd? Is the empty, initial state revision 0, and later revisions 1, 2, 3, ...? If so, should passing revision 0 for a watch return all changes? Or, if 0 is intended to be a special value in the watch API, meaning "the current revision", could this behavior be documented?

[spzala]

I see this behavior and that current revision is incremented by 1 when revision 0 is used (same as not specifying/default, which watches future changes) https://github.com/etcd-io/etcd/blob/master/etcdserver/api/v3rpc/watch.go#L271
@xiang90 @gyuho documenting it as @aphyr suggested should be good to address this issue? Thanks!

[jingyih]

In proto3, default value (which is 0 in this case) can indicate non-presence or presence and that the value was set to the default. So the watch starts with current store revision. Improving doc sounds good to me.

[xiang90]

@jingyih can you send a PR to improve the documentation? thanks!

[aphyr]

You may still want to document that explicitly passing 0 for watches means "the current server revision, plus one".