Document realtime idempotent publishing via user-supplied ids

[SimonWoolf]

Realtime idempotent publishing via user-supplied ids is a fairly niche feature. The usual behaviour -- for a given connection, you get idempotency automatically for free via the msgSerial (i.e. the client library, if it does not get an ack, could retry a message itself, specifying the same msgSerial) -- is enough for most use-cases, which is why we thought of idempotency as a REST feature.

But for the very few usecases who want idempotency across connections, we now support idempotency via user-supplied Message.ids. They are subject to the same constraints as the REST feature (in particular, if you are publishing multiple Messages in a single ProtocolMessage then the ids must be of the form :0, :1, ..., in order, with the same base for all the messages; the derived ProtocolMessage id is then ; this is to make clear that the individual messages aren't independently idempotent, they are treated atomically. If you are only publishing one Message, this requirement is dropped and the id can be any string).

TBH this might be a sufficiently niche feature that it's not worth complicating the main docs up with it. Might be worth relegating to a support article. Or maybe a single 'Are Ably publishes idempotent?' article, with 'REST' and 'Realtime' headings, explaining the situation for each one?

┆Issue is synchronized with this Jira Task by Unito