Update replication stream docs to better describe role of `POSITION`

matrix-org / synapse

Synapse: Matrix homeserver written in Python/Twisted.

https://matrix-org.github.io/synapse

Apache License 2.0

11.83k stars 2.13k forks source link

Update replication stream docs to better describe role of `POSITION` #16560

Open erikjohnston opened 1 year ago

erikjohnston commented 1 year ago

c.f. https://github.com/matrix-org/synapse/pull/16555#discussion_r1374439569

DMRobertson commented 1 year ago

Examples are the key here, I think.

An incoming POSITION sends two numbers prev < next. (I assume that prev = next or next < prev are invalid?) The worker processing the POSITION has its own position "current". There are then five cases to illustrate:

current < prev < next
current = prev < next
prev < current < next
prev < current = next
prev < next < current

(The invariant we apparently want is prev <= current <= next, i.e. the middle three bullets.)