Merge pull request #142 from vrtmrz/prevent-reconnection

A new option or function to stay offline when disconnected during specific situations

Author: dmotz

README.md

@@ -35,24 +35,30 @@ You can see what people are building with Trystero [here](https://github.com/jer
 
 ## Contents
 
-- [How it works](#how-it-works)
-- [Get started](#get-started)
-- [Listen for events](#listen-for-events)
-- [Broadcast events](#broadcast-events)
-- [Audio and video](#audio-and-video)
-- [Advanced](#advanced)
-  - [Binary metadata](#binary-metadata)
-  - [Action promises](#action-promises)
-  - [Progress updates](#progress-updates)
-  - [Encryption](#encryption)
-  - [React hooks](#react-hooks)
-  - [Connection issues](#connection-issues)
-  - [Running server-side (Node, Deno, Bun)](#running-server-side-node-deno-bun)
-  - [Supabase setup](#supabase-setup)
-  - [Firebase setup](#firebase-setup)
-- [API](#api)
-- [Strategy comparison](#strategy-comparison)
-  - [How to choose](#how-to-choose)
+- [✨🤝✨ Trystero](#-trystero)
+  - [Contents](#contents)
+  - [How it works](#how-it-works)
+  - [Get started](#get-started)
+  - [Listen for events](#listen-for-events)
+  - [Broadcast events](#broadcast-events)
+  - [Audio and video](#audio-and-video)
+  - [Advanced](#advanced)
+    - [Binary metadata](#binary-metadata)
+    - [Action promises](#action-promises)
+    - [Progress updates](#progress-updates)
+    - [Encryption](#encryption)
+    - [React hooks](#react-hooks)
+    - [Connection issues](#connection-issues)
+    - [Running server-side (Node, Deno, Bun)](#running-server-side-node-deno-bun)
+    - [Supabase setup](#supabase-setup)
+    - [Firebase setup](#firebase-setup)
+  - [API](#api)
+    - [`joinRoom(config, roomId, [onJoinError])`](#joinroomconfig-roomid-onjoinerror)
+    - [`selfId`](#selfid)
+    - [`getRelaySockets()`](#getrelaysockets)
+    - [`getOccupants(config, roomId)`](#getoccupantsconfig-roomid)
+  - [Strategy comparison](#strategy-comparison)
+    - [How to choose](#how-to-choose)
 
 ---
 
@@ -649,6 +655,12 @@ the same namespace will return the same room instance.
     [`Libp2pOptions`](https://libp2p.github.io/js-libp2p/types/libp2p.index.Libp2pOptions.html)
     where you can specify a list of static peers for bootstrapping.
 
+  - `manualRelayReconnection` - **(optional, 🐦 Nostr and 🌊 BitTorrent only)**
+    Boolean (default: `false`) that when set to `true` disables
+    automatically pausing and resuming reconnection attempts when the browser
+    goes offline and comes back online. This is useful if you want to manage
+    this behavior yourself.
+
 - `roomId` - A string to namespace peers and events within a room.
 
 - `onJoinError(details)` - **(optional)** A callback function that will be
@@ -893,6 +905,18 @@ console.log(trystero.getRelaySockets())
 //  }
 ```
 
+### `pauseRelayReconnection()`
+
+**(🐦 Nostr, 🌊 BitTorrent only)** Normally Trystero will try to automatically
+reconnect to relay sockets unless `manualRelayReconnection: true` is set in
+the room config. Calling this function stops relay reconnection attempts until
+`resumeRelayReconnection()` is called.
+
+### `resumeRelayReconnection()`
+
+**(🐦 Nostr, 🌊 BitTorrent, only)** Allows relay reconnection attempts to resume.
+(See `pauseRelayReconnection()` above).
+
 ### `getOccupants(config, roomId)`
 
 **(🔥 Firebase only)** Returns a promise that resolves to a list of user IDs

src/index.js

@@ -1 +1,7 @@
-export {getRelaySockets, joinRoom, selfId} from './nostr.js'
+export {
+  getRelaySockets,
+  joinRoom,
+  selfId,
+  pauseRelayReconnection,
+  resumeRelayReconnection
+} from './nostr.js'

src/nostr.d.ts

@@ -3,10 +3,13 @@ declare module 'trystero/nostr' {
 
   export function joinRoom(
     config: BaseRoomConfig & RelayConfig,
-    roomId: string
+    roomId: string,
+    manualRelayReconnection?: boolean
   ): Room
 
   export function getRelaySockets(): Record<string, WebSocket>
+  export function pauseRelayReconnection(): void
+  export function resumeRelayReconnection(): void
 
   export * from 'trystero'
 }

src/nostr.js

@@ -129,7 +129,11 @@ export const joinRoom = strategy({
 
 export const getRelaySockets = socketGetter(clients)
 
-export {selfId} from './utils.js'
+export {
+  selfId,
+  pauseRelayReconnection,
+  resumeRelayReconnection
+} from './utils.js'
 
 export const defaultRelayUrls = [
   'black.nostrcity.club',

src/strategy.js

@@ -10,7 +10,8 @@ import {
   noOp,
   selfId,
   toJson,
-  topicPath
+  topicPath,
+  watchOnline
 } from './utils.js'
 
 const poolSize = 20
@@ -24,6 +25,7 @@ export default ({init, subscribe, announce}) => {
   let initPromises
   let offerPool
   let offerCleanupTimer
+  let cleanupWatchOnline
 
   return (config, roomId, onJoinError) => {
     const {appId} = config
@@ -237,6 +239,7 @@ export default ({init, subscribe, announce}) => {
           })),
         offerTtl * 1.03
       )
+      cleanupWatchOnline = config.manualRelayReconnection ? noOp : watchOnline()
     }
 
     const announceIntervals = initPromises.map(() => announceIntervalMs)
@@ -284,6 +287,8 @@ export default ({init, subscribe, announce}) => {
         announceTimeouts.forEach(clearTimeout)
         unsubFns.forEach(async f => (await f)())
         clearInterval(offerCleanupTimer)
+        cleanupWatchOnline()
+        didInit = false
       }
     ))
   }

src/torrent.d.ts

@@ -3,10 +3,13 @@ declare module 'trystero/torrent' {
 
   export function joinRoom(
     config: BaseRoomConfig & RelayConfig,
-    roomId: string
+    roomId: string,
+    manualRelayReconnection?: boolean
   ): Room
 
   export function getRelaySockets(): Record<string, WebSocket>
+  export function pauseRelayReconnection(): void
+  export function resumeRelayReconnection(): void
 
   export * from 'trystero'
 }

src/torrent.js

@@ -174,7 +174,11 @@ export const joinRoom = strategy({
 
 export const getRelaySockets = socketGetter(clients)
 
-export {selfId} from './utils.js'
+export {
+  selfId,
+  pauseRelayReconnection,
+  resumeRelayReconnection
+} from './utils.js'
 
 export const defaultRelayUrls = [
   'tracker.webtorrent.dev',

src/utils.js

@@ -73,13 +73,47 @@ export const strToNum = (str, limit = Number.MAX_SAFE_INTEGER) =>
 const defaultRetryMs = 3333
 const socketRetryPeriods = {}
 
+// Prevents reconnection to the socket until the promise resolves
+let reconnectionLockingPromise = null
+// Resolver for the promise that pauses reconnection
+let resolver = null
+
+/**
+ * Pauses reconnection attempts until resumed.
+ * If already paused, no new promise is created.
+ */
+export const pauseRelayReconnection = () => {
+  if (!reconnectionLockingPromise) {
+    reconnectionLockingPromise = new Promise(resolve => {
+      resolver = resolve
+    }).finally(() => {
+      resolver = null
+      reconnectionLockingPromise = null
+    })
+  }
+}
+
+/**
+ * Resumes reconnection attempts if they are currently paused.
+ * If not paused, this function has no effect.
+ */
+export const resumeRelayReconnection = () =>
+  // resolver will be set to null after resolving.
+  // Do not change here to avoid multiple calls to _resolver and creating new locker-promise
+  // If not paused, do nothing
+  resolver?.()
+
 export const makeSocket = (url, onMessage) => {
   const client = {}
 
   const init = () => {
     const socket = new WebSocket(url)
-
     socket.onclose = () => {
+      if (reconnectionLockingPromise) {
+        // If reconnect is paused, wait for the promise to resolve
+        reconnectionLockingPromise.then(init)
+        return
+      }
       socketRetryPeriods[url] ??= defaultRetryMs
       setTimeout(init, socketRetryPeriods[url])
       socketRetryPeriods[url] *= 2
@@ -109,3 +143,20 @@ export const makeSocket = (url, onMessage) => {
 
 export const socketGetter = clientMap => () =>
   fromEntries(entries(clientMap).map(([url, client]) => [url, client.socket]))
+
+export const watchOnline = () => {
+  if (isBrowser) {
+    const controller = new AbortController()
+
+    addEventListener('online', resumeRelayReconnection, {
+      signal: controller.signal
+    })
+    addEventListener('offline', pauseRelayReconnection, {
+      signal: controller.signal
+    })
+
+    return () => controller.abort()
+  }
+
+  return noOp
+}