Order of watch events happening in the same revision in the same watcher is not documented

[socketpair]

It's not clear which order of watch events is guaranteed (or not guaranteed) in the same revision in the same watcher.

Support I watch prefix /prefix. Single TXN happened which adds /prefix/a, removes /prefix/b and changes /profix/c. So, watcher will notice these changes as changes in the same revision. Yes, but in what order ? Does etcd give any guarantees on that? Please do not confuse with order of events happening in different revisions (here etcd states about the order).

EDIT: Experiment says, that the order of watched events is the same as it was in TXN block. But if it is not said in the docs then it may be changed in the future (i.e. implementation specific). Strictly speaking, since keys in TXN success (or TXN failure) block can not intersect, order of operations does not have any meaning. I don't know, possibly order of records in watcher may be changed after compaction.

[siyuanfoundation]

/cc @fuweid

[serathius]

Experiment says, that the order of watched events is the same as it was in TXN block. But if it is not said in the docs then it may be changed in the future (i.e. implementation specific). Strictly speaking, since keys in TXN success (or TXN failure) block can not intersect, order of operations does not have any meaning.

You are exactly right. Order is based on order of operation in TXN and it should not matter due to lack of intersection.

I don't know, possibly order of records in watcher may be changed after compaction.

After compaction it should not matter as you no longer can access/watch from this revision. Still if you looked under the hood, you would find that etcd assigns TXN operations a sequence number called subrevision. This should ensure that etcd always maintains order of operations in TXN

[socketpair]

Okay, but it is not documented. It's impossible to get it reading documentation. I would add that the order of operations in TXN is preserved and makes sense for watching them.

[siyuanfoundation]

@socketpair
Feel free to raise an PR in https://github.com/etcd-io/website for https://etcd.io/docs/v3.5/learning/api_guarantees/#watch-apis to improve the documentation.

Thanks!

[socketpair]

@siyuanfoundation @serathius https://github.com/etcd-io/website/pull/984/files