From 0ada723a21cfca16c909df8ecd4d94ad7b886e3d Mon Sep 17 00:00:00 2001 From: sacOO7 Date: Sun, 27 Nov 2022 20:04:07 +0530 Subject: [PATCH 1/8] Updated migration section in README, added error handling specific migration --- README.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5c466c8..e9a7689 100644 --- a/README.md +++ b/README.md @@ -131,8 +131,10 @@ npm run dev ## Migrating from pusher/pusher-compatible broadcasters -- The current Ably broadcaster is fully compatible with the [pusher](https://laravel.com/docs/9.x/broadcasting#pusher-channels), [old Ably Broadcaster](https://laravel.com/docs/9.x/broadcasting#ably) and [pusher compatible open source broadcasters](https://laravel.com/docs/9.x/broadcasting#open-source-alternatives). -- The only difference is for **Leaving the channel** on client side, you should use [Ably Channel Namespaces](https://ably.com/docs/general/channel-rules-namespaces) conventions. +The current Ably broadcaster is fully compatible with the [pusher](https://laravel.com/docs/9.x/broadcasting#pusher-channels), [old Ably Broadcaster](https://laravel.com/docs/9.x/broadcasting#ably) and [pusher compatible open source broadcasters](https://laravel.com/docs/9.x/broadcasting#open-source-alternatives). Please follow below steps to migrate properly from other broadcasters. + +**1. Leaving the channel** +- For **Leaving the channel** on client side, you should use [Ably Channel Namespaces](https://ably.com/docs/general/channel-rules-namespaces) conventions. ```js // public channel Echo.channel('channel1'); @@ -157,6 +159,13 @@ Echo.join('channel3'); Echo.leaveChannel("presence-channel3") ``` +**2. Error Handling** +- Ably echo client emits [ably specific errors with proper error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json) instead of [pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes). +- Aim is to make sure error details are as much descriptive as possible, so it's easy to understand and correct action can be taken. +- Those errors are built using [ErrorInfo object](https://ably.com/docs/api/realtime-sdk/types#error-info) with proper error context. +- Care needs to be taken while checking on the error object and mapping needs to be done from `pusher error codes` to `ably error codes`. + + ## Addtional Documentation - Current README covers basic ably broadcaster+echo configuration for setting up laravel app and getting it running. - Please take a look at [Laravel Broadcasting Doc](https://laravel.com/docs/broadcasting) for more information on broadcasting and receiving events. From 564a2f4c1fa1f8f20e2334322471365c20ffbfe7 Mon Sep 17 00:00:00 2001 From: sacOO7 Date: Sun, 27 Nov 2022 22:20:59 +0530 Subject: [PATCH 2/8] Refactored error handling under migration section --- README.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index e9a7689..14ad74b 100644 --- a/README.md +++ b/README.md @@ -134,7 +134,8 @@ npm run dev The current Ably broadcaster is fully compatible with the [pusher](https://laravel.com/docs/9.x/broadcasting#pusher-channels), [old Ably Broadcaster](https://laravel.com/docs/9.x/broadcasting#ably) and [pusher compatible open source broadcasters](https://laravel.com/docs/9.x/broadcasting#open-source-alternatives). Please follow below steps to migrate properly from other broadcasters. **1. Leaving the channel** -- For **Leaving the channel** on client side, you should use [Ably Channel Namespaces](https://ably.com/docs/general/channel-rules-namespaces) conventions. + +For Leaving the channel on client side, you should use [Ably Channel Namespaces](https://ably.com/docs/general/channel-rules-namespaces) conventions. ```js // public channel Echo.channel('channel1'); @@ -146,7 +147,7 @@ Echo.leaveChannel("private:channel2") Echo.join('channel3'); Echo.leaveChannel("presence:channel3") ``` -instead of [Pusher Channel Conventions](https://pusher.com/docs/channels/using_channels/channels/#channel-types) +instead of [Pusher Channel Conventions](https://pusher.com/docs/channels/using_channels/channels/#channel-types). ```js // public channel Echo.channel('channel1'); @@ -160,11 +161,19 @@ Echo.leaveChannel("presence-channel3") ``` **2. Error Handling** -- Ably echo client emits [ably specific errors with proper error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json) instead of [pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes). -- Aim is to make sure error details are as much descriptive as possible, so it's easy to understand and correct action can be taken. -- Those errors are built using [ErrorInfo object](https://ably.com/docs/api/realtime-sdk/types#error-info) with proper error context. -- Care needs to be taken while checking on the error object and mapping needs to be done from `pusher error codes` to `ably error codes`. +- [Ably echo client](https://github.com/ably-forks/laravel-echo) emit [ably specific error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json) instead of [pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes). +- Aim is to make sure error details are as descriptive as possible, so that it's easy to understand and corrective action can be taken ( Pusher errors lack error context, mostly emitted as integer error codes ). +- Ably errors are provided as a [errorInfo object](https://ably.com/docs/api/realtime-sdk/types#error-info) with proper error context. +- Care needs to be taken while checking on the errorInfo object and mapping needs to be done from [pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes) to [ably error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json). +```js + channel.error(error => { + if (error && error.code === 40142) { // ably token expired + console.error(error); + // take corrective action on UI + } + }) +``` ## Addtional Documentation - Current README covers basic ably broadcaster+echo configuration for setting up laravel app and getting it running. From a7c5696ed8b34aaee1aab2a4ccdc547b6592f6f5 Mon Sep 17 00:00:00 2001 From: sacOO7 Date: Sun, 27 Nov 2022 22:34:08 +0530 Subject: [PATCH 3/8] Added note for AblyPresenceChannel here method --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 14ad74b..865ea94 100644 --- a/README.md +++ b/README.md @@ -160,7 +160,7 @@ Echo.join('channel3'); Echo.leaveChannel("presence-channel3") ``` -**2. Error Handling** +**2. Error handling** - [Ably echo client](https://github.com/ably-forks/laravel-echo) emit [ably specific error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json) instead of [pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes). - Aim is to make sure error details are as descriptive as possible, so that it's easy to understand and corrective action can be taken ( Pusher errors lack error context, mostly emitted as integer error codes ). - Ably errors are provided as a [errorInfo object](https://ably.com/docs/api/realtime-sdk/types#error-info) with proper error context. @@ -174,6 +174,9 @@ Echo.leaveChannel("presence-channel3") } }) ``` +**Note :** +- AblyPresenceChannel -> `here` method gets called everytime client **joins, updates or leaves** the channel unlike pusher client. +- This is perfectly in sync with interface method [**here** provided under **presence-channel.ts**](https://github.com/laravel/echo/blob/master/src/channel/presence-channel.ts#L10). ## Addtional Documentation - Current README covers basic ably broadcaster+echo configuration for setting up laravel app and getting it running. From 58825f589d2223417deed8f5c00a7ff6d6f06ff1 Mon Sep 17 00:00:00 2001 From: sacOO7 Date: Wed, 30 Nov 2022 18:22:57 +0530 Subject: [PATCH 4/8] updated readme, refactored pusher to ably migration error handling --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 865ea94..c737b2a 100644 --- a/README.md +++ b/README.md @@ -162,7 +162,7 @@ Echo.leaveChannel("presence-channel3") **2. Error handling** - [Ably echo client](https://github.com/ably-forks/laravel-echo) emit [ably specific error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json) instead of [pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes). -- Aim is to make sure error details are as descriptive as possible, so that it's easy to understand and corrective action can be taken ( Pusher errors lack error context, mostly emitted as integer error codes ). +- Aim is to make sure error details are descriptive and easy to understand, so it's more effective to take a corrective action ( Pusher errors lack error context, mostly emitted as integer error codes ). - Ably errors are provided as a [errorInfo object](https://ably.com/docs/api/realtime-sdk/types#error-info) with proper error context. - Care needs to be taken while checking on the errorInfo object and mapping needs to be done from [pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes) to [ably error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json). @@ -175,7 +175,7 @@ Echo.leaveChannel("presence-channel3") }) ``` **Note :** -- AblyPresenceChannel -> `here` method gets called everytime client **joins, updates or leaves** the channel unlike pusher client. +- AblyPresenceChannel -> `here` method gets called everytime client **joins, updates or leaves** the channel unlike pusher client (gets called only for the first time). - This is perfectly in sync with interface method [**here** provided under **presence-channel.ts**](https://github.com/laravel/echo/blob/master/src/channel/presence-channel.ts#L10). ## Addtional Documentation From cf414931ebcd62e3bdf95ed1644abb60276cc166 Mon Sep 17 00:00:00 2001 From: sacOO7 Date: Mon, 5 Dec 2022 23:44:56 +0530 Subject: [PATCH 5/8] Updated README, refactored migrating section as per review comments --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c737b2a..33f3941 100644 --- a/README.md +++ b/README.md @@ -131,11 +131,12 @@ npm run dev ## Migrating from pusher/pusher-compatible broadcasters -The current Ably broadcaster is fully compatible with the [pusher](https://laravel.com/docs/9.x/broadcasting#pusher-channels), [old Ably Broadcaster](https://laravel.com/docs/9.x/broadcasting#ably) and [pusher compatible open source broadcasters](https://laravel.com/docs/9.x/broadcasting#open-source-alternatives). Please follow below steps to migrate properly from other broadcasters. +The Ably Laravel broadcaster is designed to be compatible with all Laravel broadcasting providers, such as [Pusher](https://laravel.com/docs/9.x/broadcasting#pusher-channels), [Ably with the Pusher adapter](https://laravel.com/docs/9.x/broadcasting#ably), and all [Pusher compatible open source broadcasters](https://laravel.com/docs/9.x/broadcasting#open-source-alternatives). Follow the below steps to migrate from other broadcasters. **1. Leaving the channel** -For Leaving the channel on client side, you should use [Ably Channel Namespaces](https://ably.com/docs/general/channel-rules-namespaces) conventions. +To leave channel on the client side, use [Ably Channel Namespaces](https://ably.com/docs/general/channel-rules-namespaces) conventions => + ```js // public channel Echo.channel('channel1'); @@ -147,7 +148,8 @@ Echo.leaveChannel("private:channel2") Echo.join('channel3'); Echo.leaveChannel("presence:channel3") ``` -instead of [Pusher Channel Conventions](https://pusher.com/docs/channels/using_channels/channels/#channel-types). +instead of [Pusher Channel Conventions](https://pusher.com/docs/channels/using_channels/channels/#channel-types) => + ```js // public channel Echo.channel('channel1'); From c3e657c6e0a425c555475908413a465d92a52f78 Mon Sep 17 00:00:00 2001 From: sacOO7 Date: Tue, 6 Dec 2022 00:49:11 +0530 Subject: [PATCH 6/8] Updated leaving a channel section as per review suggestions --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 33f3941..10fe31b 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,7 @@ npm run dev ## Migrating from pusher/pusher-compatible broadcasters The Ably Laravel broadcaster is designed to be compatible with all Laravel broadcasting providers, such as [Pusher](https://laravel.com/docs/9.x/broadcasting#pusher-channels), [Ably with the Pusher adapter](https://laravel.com/docs/9.x/broadcasting#ably), and all [Pusher compatible open source broadcasters](https://laravel.com/docs/9.x/broadcasting#open-source-alternatives). Follow the below steps to migrate from other broadcasters. -**1. Leaving the channel** +**1. Leaving a channel** To leave channel on the client side, use [Ably Channel Namespaces](https://ably.com/docs/general/channel-rules-namespaces) conventions => @@ -163,10 +163,11 @@ Echo.leaveChannel("presence-channel3") ``` **2. Error handling** -- [Ably echo client](https://github.com/ably-forks/laravel-echo) emit [ably specific error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json) instead of [pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes). +- Please note that the [Ably laravel-echo client](https://github.com/ably-forks/laravel-echo) emits [Ably specific error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json) instead of [Pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes). - Aim is to make sure error details are descriptive and easy to understand, so it's more effective to take a corrective action ( Pusher errors lack error context, mostly emitted as integer error codes ). -- Ably errors are provided as a [errorInfo object](https://ably.com/docs/api/realtime-sdk/types#error-info) with proper error context. -- Care needs to be taken while checking on the errorInfo object and mapping needs to be done from [pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes) to [ably error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json). +- Ably errors are provided as an [ErrorInfo object](https://ably.com/docs/api/realtime-sdk/types#error-info) with full error context. +- If you are interacting with pusher errors in your project, be sure to update your code accordingly. +i.e. update from [pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes) to [ably error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json). ```js channel.error(error => { From 87df49b72aa8eef8b199f5b8fe6191a2e5980cd5 Mon Sep 17 00:00:00 2001 From: sacOO7 Date: Tue, 6 Dec 2022 00:55:16 +0530 Subject: [PATCH 7/8] Updated readme, refactored pusher migration error handling note --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 10fe31b..ee6db6c 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,7 @@ Echo.leaveChannel("presence-channel3") **2. Error handling** - Please note that the [Ably laravel-echo client](https://github.com/ably-forks/laravel-echo) emits [Ably specific error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json) instead of [Pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes). -- Aim is to make sure error details are descriptive and easy to understand, so it's more effective to take a corrective action ( Pusher errors lack error context, mostly emitted as integer error codes ). +- Ably emitted errors are descriptive and easy to understand, so it's more effective to take a corrective action ( Pusher errors mostly emitted as integer error codes ). - Ably errors are provided as an [ErrorInfo object](https://ably.com/docs/api/realtime-sdk/types#error-info) with full error context. - If you are interacting with pusher errors in your project, be sure to update your code accordingly. i.e. update from [pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes) to [ably error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json). From 02a1bbb43c8f67f15a5aecc7082ca39b681ef8ea Mon Sep 17 00:00:00 2001 From: sacOO7 Date: Tue, 6 Dec 2022 19:51:00 +0530 Subject: [PATCH 8/8] updated README as per review comments --- README.md | 42 ++++++++++++++++++++---------------------- 1 file changed, 20 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index ee6db6c..015fc86 100644 --- a/README.md +++ b/README.md @@ -135,36 +135,34 @@ The Ably Laravel broadcaster is designed to be compatible with all Laravel broad **1. Leaving a channel** -To leave channel on the client side, use [Ably Channel Namespaces](https://ably.com/docs/general/channel-rules-namespaces) conventions => +To leave channel on the client side, use [Ably Channel Namespaces](https://ably.com/docs/general/channel-rules-namespaces) conventions, instead of [Pusher Channel Conventions](https://pusher.com/docs/channels/using_channels/channels/#channel-types). ```js // public channel -Echo.channel('channel1'); -Echo.leaveChannel("public:channel1"); -// private channel -Echo.private('channel2'); -Echo.leaveChannel("private:channel2") -// presence channel -Echo.join('channel3'); -Echo.leaveChannel("presence:channel3") -``` -instead of [Pusher Channel Conventions](https://pusher.com/docs/channels/using_channels/channels/#channel-types) => +Echo.channel('channel1'); // subscribe to a public channel +// use this +Echo.leaveChannel("public:channel1"); // ably convention for leaving public channel +// instead of +Echo.leaveChannel("channel1"); // pusher convention for leaving public channel -```js - // public channel -Echo.channel('channel1'); -Echo.leaveChannel("channel1"); // private channel -Echo.private('channel2'); -Echo.leaveChannel("private-channel2") +Echo.private('channel2'); // subscribe to a private channel +// use this +Echo.leaveChannel("private:channel2"); // ably convention for leaving private channel +// instead of +Echo.leaveChannel("private-channel2"); // pusher convention for leaving private channel + // presence channel -Echo.join('channel3'); -Echo.leaveChannel("presence-channel3") +Echo.join('channel3'); // subscribe to a presence channel +// use this +Echo.leaveChannel("presence:channel3"); // ably convention for leaving presence channel +// instead of +Echo.leaveChannel("presence-channel3"); // pusher convention for leaving presence channel ``` **2. Error handling** - Please note that the [Ably laravel-echo client](https://github.com/ably-forks/laravel-echo) emits [Ably specific error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json) instead of [Pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes). -- Ably emitted errors are descriptive and easy to understand, so it's more effective to take a corrective action ( Pusher errors mostly emitted as integer error codes ). +- Ably emitted errors are descriptive and easy to understand, so it's more effective to take a corrective action. - Ably errors are provided as an [ErrorInfo object](https://ably.com/docs/api/realtime-sdk/types#error-info) with full error context. - If you are interacting with pusher errors in your project, be sure to update your code accordingly. i.e. update from [pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes) to [ably error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json). @@ -178,8 +176,8 @@ i.e. update from [pusher error codes](https://pusher.com/docs/channels/library_a }) ``` **Note :** -- AblyPresenceChannel -> `here` method gets called everytime client **joins, updates or leaves** the channel unlike pusher client (gets called only for the first time). -- This is perfectly in sync with interface method [**here** provided under **presence-channel.ts**](https://github.com/laravel/echo/blob/master/src/channel/presence-channel.ts#L10). +- AblyPresenceChannel -> `here` method gets called every time a client **joins, updates or leaves** the channel, whereas when using Pusher this is only called once for first client entering the channel. +- This behaviour follows implementation as per standard [PresenceChannel Interface](https://github.com/laravel/echo/blob/master/src/channel/presence-channel.ts#L10). ## Addtional Documentation - Current README covers basic ably broadcaster+echo configuration for setting up laravel app and getting it running.