Idempotent publishing doesn't describe idempotent realtime publishing

[paddybyers]

See https://ably.com/docs/channels?lang=javascript#idempotency

This text was written before idempotentRestPublishing defaulted to true, and so it reads as if you need to enable this option if you want library-provided ids for REST idempotency. Instead it should say that the library will do this automatically, except on older libraries with API version < 1.2.

The key omission here though is that it does not mention that you can also have idempotent realtime publishing via a client-provided id.

I think this needs a bit if a rewrite, and the narrative should be:

• idempotent publishing is supported by Ably, both for REST and realtime publishing;
• idempotent publishing is achieved by associating a unique id with a message; that id is processed by the system, and the system ensures that a published message is not processed/forwarded again if it is a duplicate of one already processed;
• client libraries ensure that message IDs are added to messages so that they are handled idempotently. This is the case both for REST and Realtime. (For library versions older than 1.2, this was not the default for REST, but it could be enabled with the idempotentRestPublishing client option. For library versions >= 1.2 it is the default.
• there are often use-cases for using a client-supplied ID to achieve idempotency. This can either be because:
  • you want idempotency to be supported when you can't rely on there being a single continuously active client instance; eg you want idempotency even if a publisher is restarted;
  • you have an upstream system that is using message IDs, and you want to ensure that idempotency applies to a whole message processing pipeline.
• in these cases, both for REST and realtime publishing, you can specify your own message ID, and that will be used for idempotency;
• beware of the restrictions on the form of the ID in the case that you are attempting to publish multiple messages atomically, also with idempotency (see the FAQ).

┆Issue is synchronized with this Jira Task by Unito

[sync-by-unito]

➤ Francis Roberts commented:

New structure:

1. Defined Idempotent Publishing
2. Mechanism of Action
3. Role of Client Libraries
4. Custom Message IDs
5. Important Considerations 
6. Practical Example
7. FAQ and Restrictions