@@ -225,11 +225,6 @@ out be acknowledged by the client, and will eventually close the channel if
225enough unacknowledged events accumulate. The `Urbit` object handles event
225enough unacknowledged events accumulate. The `Urbit` object handles event
226acknowledgement automatically, so you don't need to worry about this.
226acknowledgement automatically, so you don't need to worry about this.
228−Since the `Urbit` object handles channels internally, you don't typically need
229−to deal with them at all. There is, however, the [`delete()`](#delete-channel)
230−function if you want to close the whole channel and end all subscriptions at
233Eyre automatically creates a channel when a poke or subscription request is
228Eyre automatically creates a channel when a poke or subscription request is
234first sent to `/~/channel/[a new channel ID]`. If your web app is served
229first sent to `/~/channel/[a new channel ID]`. If your web app is served
235external to the ship and you use the `authenticate` function [described
230external to the ship and you use the `authenticate` function [described
@@ -238,6 +233,41 @@ the channel. If your web app is served directly from the ship and you use
238`Urbit` class constructor, it won't open the channel right away. Instead, the
233`Urbit` class constructor, it won't open the channel right away. Instead, the
239channel will be opened whenever you first send a poke or subscription request.
234channel will be opened whenever you first send a poke or subscription request.
238+`Urbit` class includes three optional callbacks that fire when the SSE
239+connection state changes:
241+| Callback | Description |
242+| `Urbit.onOpen` | Called when an SSE channel connection is successfully established. |
243+| `Urbit.onRetry` | This is called whenever a reconnection attempt is made due to an interruption, for example if there are network problems. |
244+| `Urbit.onError` | This is called when there is an unrecoverable error, for example after enough reconnection attemps have failed. |
246+As mentioned in the previous section, typically a channel will be opened and an
247+SSE connection established after you first poke the ship or make a subscription
248+request. If successful, whatever function you provided to `onOpen` will be
249+called. If at some point the connection is interrupted, a reconnection attempt will be made three times:
252+2. 750ms after the first.
253+3. 3000ms after the second.
255+Each attempt will call the function you provided to `onRetry`, if any. If all
256+three reconnection attempts failed, or if a fatal error occurred, the function
257+you provided `onError` will be called with an `Error` object containing an error
258+message as its argument.
260+How you use these (if you do at all) is up to you and depends on the nature of
261+your app. If you want to try reconnecting when `onError` fires, note that Eyre
262+will delete a channel if it's had no messages from the client in the last 12
263+hours. The timeout is reset whenever it receives a message, including the acks
264+that are automatically sent by the `Urbit` object in response to subscription
267+If you don't want to account for the possibility of the channel having been
268+deleted in your app's logic, you can also just call the [`reset()`](#reset)
269+function before you try reconnecting and consequently open a brand new channel.
241### Authentication
271### Authentication
243**If your front-end is served directly from the Urbit ship, this step can be
273**If your front-end is served directly from the Urbit ship, this step can be