Is there any guarantee that messages received from the history API will be in order?

It depends what you mean by 'in order'.


There is the order that the messages will have been received by a realtime client. But that will vary depending on what region the client is in. We preserve ordering for a given publisher on a given channel, but for example if two publishers in regions A and B publish messages 'a' and 'b' (respectively) approximately simultaneously, it's quite likely that a subscriber in region A will see 'a' before 'b', and one in region B will see 'b' before 'a'.


The ordering that history results are returned in is the ordering defined by the message timestamp which is assigned by the channel in the region that the message was published in. This means that history results - unlike realtime messages - are in the same order no matter where in the world you query them from. But that order (which we call the canonical global order) may not be the same order as any client in any region actually received them in real time if they were subscribed to the channel.

There are exceptions to that. One is recent messages (retrieved from live ephemeral storage rather than persisted); they will be in regional ordering, and then will mesh back into canonical global ordering from persisted storage (with a mechanism that prevents duplication & missing messages) when you paginate further back.

Another exception is untilAttach, which is a point in a regional message stream, so results returned from an untilAttach query do not satisfy this.

Additionally, using untilAttach can be an issue when the client region is really far away from the publishing region, as well.

So when using untilAttach the messages will be in the regional order of the region the client is in, because they have to mesh forwards into the live message stream at that point. We intend to eventually send them in CGO order and filter, but that's pending on completely moving away from serially-incrementing channelSerials to a channelTimeserial to mark the point of attachment.