Skip to content

Commit 96ee205

Browse files
franrob-projectsfranrob-projects
committed
Rebase: Aligns with latest main branch changes
EDU-1469: Update idempotent publishing section for clarity
1 parent d0dfbdc commit 96ee205

File tree

1 file changed

+147
-22
lines changed

1 file changed

+147
-22
lines changed

‎content/channels/index.textile

Lines changed: 147 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -753,56 +753,181 @@ channel.Publish(context.Background(), "action", "boom!")
753753

754754
h3(#idempotency). Idempotent publish
755755

756-
Idempotency ensures that multiple publishes of the same message cannot result in duplicate messages.
756+
Idempotent publishing ensures that multiple attempts to publish the same message do not result in duplicate messages. This feature is essential when network issues may cause a client to reattempt message publication without knowing if the initial attempt succeeded.
757757

758-
It is possible that a client publishing a message using the REST interface may not receive acknowledgement of receipt from Ably, due to issues such as network failure outside of Ably's control. Clients will internally attempt to re-publish messages in these instances.
758+
h4. Automatic idempotency
759759

760-
When idempotent publishing is enabled, the Ably SDK will internally assign a unique ID to each message which ensures that subsequent retry attempts cannot result in duplicate messages. Idempotent publishing is enabled by default in all latest Ably SDKs. It can be disabled by setting the @idempotentRestPublishing@ "@ClientOptions@":/api/rest-sdk#client-options to @false@.
760+
For versions 1.2 and later of the Ably library, idempotent publishing is enabled by default. This means the Ably SDK automatically assigns a unique ID to each message to prevent duplicates during retries. This functionality applies to both REST and realtime publishing.
761+
For older versions (before 1.2), this feature was not enabled by default for publishing. However, it could be activated using @idempotentRestPublishing@ in "@ClientOptions@":/api/rest-sdk#client-optionsidempotentRestPublishing.
761762

762-
Note that Ably can only detect duplicate messages within a 2-minute window after the original message, with the same ID, is published. If a message with the same ID is published after this 2-minute window, it will be treated as a new message.
763+
h4. Client ID idempotency
763764

764-
You can also specify message IDs externally. The following is an example of how you might do this:
765+
There are scenarios where specifying a client-supplied ID to achieve idempotency are necessary, such as:
765766

766-
```[rest_javascript]
767-
const rest = new Ably.Rest('{{API_KEY}}');
768-
const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}');
769-
await channel.publish([{data: 'payload', id: 'unique123'}]);
767+
* Ensuring idempotency when a publisher instance might be restarted, and continuous activity cannot be guaranteed.
768+
* Integrating with an upstream system that uses its message IDs, ensuring idempotency across an entire message processing pipeline.
769+
770+
In these cases, you can manually specify the message ID for REST and realtime publishing.
771+
772+
The following example manually specifies a message ID:
773+
774+
```[realtime_javascript]
775+
const realtime = new Ably.Realtime = '{{API_KEY}}';
776+
const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
777+
const message = [{ data: 'payload', id: 'unique123' }];
770778
```
771779

772-
```[rest_go]
773-
rest, err := ably.NewREST(
780+
```[realtime_nodejs]
781+
const realtime = new Ably.Realtime = '{{API_KEY}}';
782+
const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
783+
const message = [{ data: 'payload', id: 'unique123' }];
784+
```
785+
786+
```[realtime_ruby]
787+
realtime = Ably::Realtime.new(key: '{{API_KEY}}')
788+
channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
789+
channel.publish(name: 'example', data: 'payload', id: 'unique123')
790+
```
791+
792+
```[realtime_python]
793+
realtime = AblyRealtime('{{API_KEY}}')
794+
channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
795+
await channel.publish([{data: 'payload', id: 'unique123'}])
796+
```
797+
798+
```[realtime_java]
799+
ClientOptions options = new ClientOptions('{{API_KEY}}');
800+
AblyRealtime ably = new AblyRealtime(options);
801+
Channel channel = ably.channels.get('{{RANDOM_CHANNEL_NAME}}');
802+
803+
Message message = new Message();
804+
message.data = "payload";
805+
message.id = "unique123";
806+
```
807+
808+
```[realtime_csharp]
809+
ARTRealtime *realtime = [[ARTRealtime alloc] initWithKey:@"{{API_KEY}}"];
810+
ARTRealtimeChannel *channel = [realtime.channels get:@"{{RANDOM_CHANNEL_NAME}}"];
811+
channel publish:@"example" data:@"payload" id:@"unique123" callback:^(ARTErrorInfo *error)
812+
```
813+
814+
```[realtime_swift]
815+
let realtime = ARTRealtime(key: "{{API_KEY}}")
816+
let channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}")
817+
channel.publish("example", data: "message data", id: "unique123")
818+
```
819+
820+
```[realtime_objc]
821+
ARTRealtime *realtime = [[ARTRealtime alloc] initWithKey:("{{API_KEY}}"));
822+
ARTRealtimeChannel *channel = [realtime.channels get:("{{RANDOM_CHANNEL_NAME}}");
823+
[channel.publish("example", data: "message data", id: "unique123")];
824+
```
825+
826+
```[realtime_flutter]
827+
final clientOptions = ably.ClientOptions(key: '{{API_KEY}}');
828+
final realtime = ably.Realtime(options: clientOptions);
829+
final channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
830+
await message = ably.Message(data: 'payload', id: 'unique123');
831+
```
832+
833+
```[realtime_go]
834+
realtime, err := ably.NewRealtime(
774835
ably.WithKey("{{API_KEY}}"))
775836
if err != nil {
776837
log.Fatalf("Error creating Ably client: %v", err)
777838
}
778839

779-
channel := rest.Channels.Get("{{RANDOM_CHANNEL_NAME}}")
840+
channel := realtime.Channels.Get("{{RANDOM_CHANNEL_NAME}}")
780841

781842
message := &ably.Message{
782843
Data: "payload",
783844
ID: "unique123",
784845
}
846+
```
785847

786-
// Publish the message to the channel
787-
err = channel.Publish(context.Background(), "eventName", message)
788-
if err != nil {
789-
log.Fatalf("Error publishing message: %v", err)
790-
}
848+
```[rest_javascript]
849+
const rest = new Ably.Rest = '{{API_KEY}}';
850+
const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}');
851+
const message = [{ data: 'payload', id: 'unique123' }];
852+
```
853+
854+
```[rest_nodejs]
855+
const rest = new Ably.Rest = '{{API_KEY}}';
856+
const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}');
857+
const message = [{ data: 'payload', id: 'unique123' }];
858+
```
859+
860+
```[rest_ruby]
861+
rest = Ably::Rest.new(key: '{{API_KEY}}')
862+
channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}')
863+
channel.publish(name: 'example', data: 'payload', id: 'unique123')
864+
```
865+
866+
```[rest_python]
867+
rest = AblyRest('{{API_KEY}}')
868+
channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}')
869+
await channel.publish([{data: 'payload', id: 'unique123'}])
870+
```
871+
872+
```[rest_php]
873+
$rest = new Ably\AblyRest('{{API_KEY}}');
874+
$channel = $rest->channels->get('{{RANDOM_CHANNEL_NAME}}')
875+
$channel->publish([{data: 'payload', id: 'unique123'}]);
791876
```
792877

793878
```[rest_java]
794-
ClientOptions options = new ClientOptions("{{API_KEY}}");
795-
AblyRealtime ably = new AblyRealtime(options);
796-
Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
879+
ClientOptions options = new ClientOptions('{{API_KEY}}');
880+
AblyRest ably = new AblyRest(options);
881+
Channel channel = ably.channels.get('{{RANDOM_CHANNEL_NAME}}');
797882

798883
Message message = new Message();
799884
message.data = "payload";
800885
message.id = "unique123";
886+
```
801887

802-
channel.publish(new Message[]{message});
888+
```[rest_csharp]
889+
ARTRealtime *rest = [[ARTRealtime alloc] initWithKey:@"{{API_KEY}}"];
890+
ARTRealtimeChannel *channel = [rest.channels get:@"{{RANDOM_CHANNEL_NAME}}"];
891+
channel publish:@"example" data:@"payload" id:@"unique123" callback:^(ARTErrorInfo *error)
803892
```
804893

805-
If manually specifying message IDs, it is important to be aware of how messages are published when calling the "publish()":/api/rest-sdk/channels#publish method with an array of messages. See this "FAQ":https://faqs.ably.com/client-specified-message-id-restrictions-for-multiple-messages-published-atomically for further information.
894+
```[rest_swift]
895+
let rest = ARTRest(key: "{{API_KEY}}")
896+
var channel = rest.channels.get("{{RANDOM_CHANNEL_NAME}}")
897+
channel.publish("example", data: "message data", id: "unique123")
898+
```
899+
900+
```[rest_objc]
901+
ARTRest *rest = [[ARTRest alloc] initWithKey:("{{API_KEY}}"));
902+
ARTRestChannel *channel = [rest.channels get:("{{RANDOM_CHANNEL_NAME}}");
903+
[channel.publish("example", data: "message data", id: "unique123")];
904+
```
905+
906+
```[rest_flutter]
907+
final clientOptions = ably.ClientOptions(key: '{{API_KEY}}');
908+
final rest = ably.Rest(options: clientOptions);
909+
final channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}');
910+
await message = ably.Message(data: 'payload', id: 'unique123');
911+
```
912+
913+
```[rest_go]
914+
rest, err := ably.NewREST(
915+
ably.WithKey("{{API_KEY}}"))
916+
if err != nil {
917+
log.Fatalf("Error creating Ably client: %v", err)
918+
}
919+
920+
channel := rest.Channels.Get("{{RANDOM_CHANNEL_NAME}}")
921+
922+
message := &ably.Message{
923+
Data: "payload",
924+
ID: "unique123",
925+
}
926+
```
927+
928+
h4. Restrictions and considerations
929+
930+
When specifying custom message IDs, particularly when attempting to "@publish()@":/api/rest-sdk/channels#publish multiple messages atomically with idempotency, ensure that the IDs adhere to the format restrictions. For more details on these restrictions, refer to the "FAQ":https://faqs.ably.com/client-specified-message-id-restrictions-for-multiple-messages-published-atomically.
806931

807932
h3(#publish-on-behalf). Use the REST interface to publish on behalf of a realtime connection
808933

0 commit comments

Comments
 (0)