kicksdk-js 0.1.1 → 0.2.0

package/index.js

@@ -6,7 +6,7 @@
 // cannot be fetched beside this file, pass its bytes: `init(bytes)`).
 //
 // Where it works: Kick's realtime server only takes a socket whose Origin is
-// https://kick.com. Node sets that header itself (see `createSocket` below); a
+// https://kick.com. Node sets that header itself (see `socketFactory` below); a
 // browser cannot, so in a browser connectChat only works on kick.com - a page
 // there, or an extension's content script. Elsewhere, relay through a server.
 
@@ -19,7 +19,8 @@ import initWasm, {
   connectionRequest,
   parseConnection,
   tokenRequest,
-  parseToken
+  parseToken,
+  retryAfterMs
 } from './pkg/kicksdk.js';
 
 export * from './pkg/kicksdk.js';
@@ -28,14 +29,34 @@ export const REQUIRED_ORIGIN = 'https://kick.com';
 
 let ready = null;
 
-/** Loads the WebAssembly. Safe to call more than once. */
+/**
+ * Loads the WebAssembly. Safe to call more than once; if loading fails, the
+ * next call tries again.
+ */
 export function init(input) {
   if (!ready) {
-    if (input instanceof Uint8Array || input instanceof ArrayBuffer) {
-      initSync({ module: input });
+    const bytes =
+      input instanceof Uint8Array ||
+      input instanceof ArrayBuffer ||
+      (typeof WebAssembly !== 'undefined' && input instanceof WebAssembly.Module);
+    if (bytes) {
+      try {
+        initSync({ module: input });
+      } catch (e) {
+        return Promise.reject(e);
+      }
       ready = Promise.resolve();
     } else {
-      ready = initWasm(input === undefined ? undefined : { module_or_path: input });
+      // A failed load (a fetch that did not get through) is not kept: a
+      // later init() starts over instead of returning the same rejection.
+      const loading = initWasm(input === undefined ? undefined : { module_or_path: input }).then(
+        () => undefined,
+        (e) => {
+          if (ready === loading) ready = null;
+          throw e;
+        }
+      );
+      ready = loading;
     }
   }
   return ready;
@@ -43,100 +64,267 @@ export function init(input) {
 
 const isNode = typeof process !== 'undefined' && !!(process.versions && process.versions.node);
 
-function defaultSocket(url) {
-  // Node's WebSocket (undici) takes headers; a browser's ignores the argument
-  // and sends its own page's origin.
-  return isNode ? new WebSocket(url, { headers: { Origin: REQUIRED_ORIGIN } }) : new WebSocket(url);
+/** How long one step of connecting (a fetch, the WebSocket handshake) may take. */
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** The longest wait setTimeout holds; a longer one fires at once. */
+const MAX_TIMEOUT_MS = 2 ** 31 - 1;
+
+const NO_WEBSOCKET =
+  'no WebSocket in this runtime (Node 22 and later have one): pass connectChat a `WebSocket` ' +
+  "constructor (the `ws` package's will do) or `createSocket`";
+
+const noop = () => {};
+
+const message = (e) => String((e && e.message) || e);
+
+/** A clock that only goes forward, so a wall-clock jump cannot fake silence. */
+function monotonicClock() {
+  const p = globalThis.performance;
+  return p && typeof p.now === 'function' ? () => p.now() : () => Date.now();
+}
+
+/**
+ * The session's clock, whole ms: the caller's `now`, or performance.now().
+ * A reading of the caller's that is not a number from 0 to
+ * Number.MAX_SAFE_INTEGER (or a `now` that throws) is reported once, and the
+ * clock goes on with performance.now() from the last good reading: the
+ * session could do nothing with it, and every attempt would fail the same way.
+ */
+function sessionClock(given, report) {
+  const mono = monotonicClock();
+  if (!given) return () => Math.floor(mono());
+  let last = 0;
+  let fallback = null;
+  return () => {
+    if (!fallback) {
+      let bad;
+      try {
+        const t = given();
+        if (typeof t === 'number' && t >= 0 && t <= Number.MAX_SAFE_INTEGER) return (last = Math.floor(t));
+        bad = new RangeError(`connectChat: now() returned ${String(t)}, not milliseconds; using performance.now()`);
+      } catch (e) {
+        bad = e;
+      }
+      report(bad);
+      const base = last;
+      const start = mono();
+      fallback = () => base + Math.floor(mono() - start);
+    }
+    return fallback();
+  };
+}
+
+/** A guest client id, a v4 UUID. Not a secret: it names the connection. */
+function guestId() {
+  const c = globalThis.crypto;
+  // randomUUID is missing outside secure contexts, and Node 18 has no
+  // global crypto at all.
+  if (c && typeof c.randomUUID === 'function') return c.randomUUID();
+  const b = new Uint8Array(16);
+  if (c && typeof c.getRandomValues === 'function') c.getRandomValues(b);
+  else for (let i = 0; i < b.length; i++) b[i] = Math.floor(Math.random() * 256);
+  b[6] = (b[6] & 0x0f) | 0x40;
+  b[8] = (b[8] & 0x3f) | 0x80;
+  const h = Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
 }
 
-async function send(fetchImpl, req) {
-  // A browser drops the headers it forbids (origin, referer) and sends its own.
-  const res = await fetchImpl(req.url, {
-    method: req.method,
-    headers: Object.fromEntries(req.headers),
-    body: req.body ?? undefined,
-    credentials: 'omit'
-  });
-  return { status: res.status, body: await res.text() };
+function socketFactory(o) {
+  if (o.createSocket) return (url) => o.createSocket(url);
+  const WS = o.WebSocket || globalThis.WebSocket;
+  if (typeof WS !== 'function') return null;
+  // Node's WebSocket (undici) and the `ws` package take headers; a browser's
+  // would read the object as a subprotocol, and sends its page's origin
+  // whatever it is given.
+  return isNode ? (url) => new WS(url, { headers: { Origin: REQUIRED_ORIGIN } }) : (url) => new WS(url);
 }
 
 /**
  * Connects to one channel's chat and keeps the connection up until close().
+ * Whatever ends a connection, connectChat waits and connects again; after one
+ * of Kick's terminal closes (a refused token, a ban, a connection limit) the
+ * wait is long - 5, 10, 20, then 30 minutes in a row, see KICK.md §6.1 - and
+ * each new connection is a new guest client.
+ *
+ * Callbacks are isolated: one that throws is reported to `onError` (or
+ * console.error) and the connection carries on. None is called after
+ * close(), which may be called from inside one.
  *
- * @param {object} o
- * @param {number} o.chatroomId          the chatroom (website API `chatroom.id`)
- * @param {number} [o.channelId]         the channel; also locates the chat's region
- * @param {string[]} [o.channels]        feeds to subscribe to; chatChannels() by default
- * @param {(e: {channel, name, data, event}) => void} o.onEvent
- * @param {(s: {connected: boolean, subscribed: string[]}) => void} [o.onState]
- * @param {(reason: string) => void} [o.onDrop]   a connection ended (a new one follows)
- * @param {typeof fetch} [o.fetch]
- * @param {(url: string) => WebSocket} [o.createSocket]
- * @param {object} [o.endpoints]         overrides of Kick's URLs
- * @param {() => number} [o.now]
+ * @param {object} o  ChatOptions, in index.d.ts
  * @returns {{ close(): void }}
  */
 export function connectChat(o) {
-  const fetchImpl = o.fetch || ((...a) => fetch(...a));
-  const createSocket = o.createSocket || defaultSocket;
-  const now = o.now || (() => Date.now());
-  const channels = o.channels || chatChannels(o.chatroomId, o.channelId);
-  const backoff = new Backoff();
-  let closed = false;
+  if (!o || typeof o.onEvent !== 'function') throw new TypeError('connectChat: onEvent is required');
+  for (const name of ['onState', 'onDrop', 'onError', 'fetch', 'createSocket', 'WebSocket', 'now']) {
+    if (o[name] != null && typeof o[name] !== 'function') {
+      throw new TypeError(`connectChat: ${name} must be a function`);
+    }
+  }
+  const timeoutMs = o.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  // setTimeout fires a longer wait (Infinity among them) at once: every
+  // request would time out before it began, and nothing would connect.
+  if (typeof timeoutMs !== 'number' || !(timeoutMs > 0 && timeoutMs <= MAX_TIMEOUT_MS)) {
+    throw new RangeError(`connectChat: timeoutMs must be a number of ms above 0, at most ${MAX_TIMEOUT_MS}`);
+  }
+  // Ids and endpoints are checked here, where a mistake throws, rather than
+  // failing every reconnect.
+  // A feed listed twice is subscribed once, and reported once.
+  const channels = [...new Set(o.channels ?? chatChannels(o.chatroomId, o.channelId))];
+  const hasChannel = o.channelId !== undefined && o.channelId !== null;
+  if (hasChannel) chatConnectionRequest(o.channelId, 'x', o.endpoints);
+  else connectionRequest('x', o.endpoints);
+
+  const fetchImpl = o.fetch || ((...a) => globalThis.fetch(...a));
+  const createSocket = socketFactory(o);
+  // It would fail the same way on every attempt.
+  if (!createSocket) throw new TypeError(`connectChat: ${NO_WEBSOCKET}`);
+  const now = sessionClock(o.now, (e) => report(e));
+
+  let session = new Session(channels);
+  let backoff = new Backoff();
+  let closed = false; // close() was called
   let ws = null;
-  let session = null;
-  let timer = null;
-  let retry = null;
+  let attempt = null; // aborts the current connection's fetches
   let clientId = null;
+  let timer = null; // session.deadline()
+  let handshake = null;
+  let retry = null;
 
-  const state = () => {
-    if (o.onState && session) {
-      o.onState({ connected: session.isConnected(), subscribed: channels.filter((c) => session.isSubscribed(c)) });
+  function report(error) {
+    if (o.onError) {
+      try {
+        o.onError(error);
+        return;
+      } catch (e) {
+        error = e;
+      }
     }
-  };
+    console.error('kicksdk connectChat:', error);
+  }
+
+  /** A user callback, by name: never after close(), and never fatal. */
+  function callback(name, ...args) {
+    const fn = o[name];
+    if (closed || typeof fn !== 'function') return;
+    try {
+      fn.apply(o, args);
+    } catch (e) {
+      report(e);
+    }
+  }
+
+  /** An entry point (a socket event, a timer): a failure ends the connection, not the driver. */
+  function guard(fn) {
+    return (...args) => {
+      try {
+        return fn(...args);
+      } catch (e) {
+        report(e);
+        if (!closed) end(`kicksdk: ${message(e)}`, 0, 0, false);
+      }
+    };
+  }
+
+  /** A fetch that gives up after timeoutMs, or when `signal` aborts. */
+  function request(req, what, signal) {
+    return new Promise((resolve, reject) => {
+      const ctrl = new AbortController();
+      const cleanup = () => {
+        clearTimeout(timeout);
+        signal.removeEventListener('abort', onAbort);
+      };
+      const fail = (e) => {
+        cleanup();
+        ctrl.abort(e);
+        reject(e);
+      };
+      const onAbort = () => fail(new Error(`${what}: cancelled`));
+      const timeout = setTimeout(() => fail(new Error(`${what}: no answer in ${timeoutMs} ms`)), timeoutMs);
+      if (signal.aborted) return onAbort();
+      signal.addEventListener('abort', onAbort);
+      (async () => {
+        // A browser drops the headers it forbids (origin, referer) and sends its own.
+        const res = await fetchImpl(req.url, {
+          method: req.method,
+          headers: Object.fromEntries(req.headers),
+          body: req.body ?? undefined,
+          credentials: 'omit',
+          signal: ctrl.signal
+        });
+        return { status: res.status, body: await res.text() };
+      })().then(
+        (r) => {
+          cleanup();
+          resolve(r);
+        },
+        (e) => {
+          cleanup();
+          reject(e);
+        }
+      );
+    });
+  }
+
+  function state() {
+    if (closed) return;
+    callback('onState', {
+      connected: session.isConnected(),
+      subscribed: channels.filter((c) => session.isSubscribed(c))
+    });
+  }
 
   function arm() {
     clearTimeout(timer);
-    const at = session && session.deadline();
-    if (at !== undefined && at !== null) timer = setTimeout(() => apply(session.tick(now())), Math.max(0, at - now()));
+    timer = null;
+    if (closed) return;
+    const at = session.deadline();
+    if (at === undefined || at === null) return;
+    timer = setTimeout(
+      guard(() => {
+        timer = null;
+        if (!closed) apply(session.tick(now()));
+      }),
+      // A clock that jumped could ask for more than setTimeout holds; a tick
+      // before the deadline does nothing, and arms the rest.
+      Math.min(MAX_TIMEOUT_MS, Math.max(0, at - now()))
+    );
   }
 
   function apply(actions) {
-    // Anything still in flight once close() has run - a timer, a token
-    // arriving - finds nothing left to act on.
-    if (closed || !session) return;
     let changed = false;
     for (const a of actions) {
+      // A callback may have called close().
+      if (closed) return;
       switch (a.action) {
         case 'send':
           if (ws && ws.readyState === 1) ws.send(a.text);
           break;
         case 'close':
-          if (o.onDrop) o.onDrop(a.reason);
-          if (ws) ws.close();
-          break;
+          // Kick said goodbye, or went quiet. The socket is finished now: a
+          // dead connection may not deliver its close event for minutes.
+          end(a.reason, a.code, a.retry_after_ms, a.terminal);
+          return;
         case 'refresh_token':
-          send(fetchImpl, tokenRequest(clientId, o.endpoints))
-            .then((r) => parseToken(r.status, r.body))
-            .then((token) => {
-              if (!closed && session) apply(session.refresh(token, now()));
-            })
-            .catch(() => {
-              // Kick ends the connection when the old token runs out; the
-              // reconnect fetches a new one.
-            });
+          refresh();
           break;
         case 'subscribed':
+          // The chat feed (the first listed) is up: back to short waits, and
+          // a terminal streak is over.
           if (a.channel === channels[0]) backoff.reset();
           changed = true;
           break;
         case 'connected':
+          // With no feed to subscribe to, the connection is all there is.
+          if (channels.length === 0) backoff.reset();
+          changed = true;
+          break;
         case 'unsubscribed':
         case 'subscribe_failed':
           changed = true;
           break;
         case 'event':
-          o.onEvent({ channel: a.channel, name: a.name, data: a.data, event: a.event });
+          callback('onEvent', { channel: a.channel, name: a.name, data: a.data, event: a.event });
           break;
       }
     }
@@ -144,77 +332,168 @@ export function connectChat(o) {
     arm();
   }
 
-  function again() {
+  function refresh() {
+    const ctrl = attempt;
+    if (!ctrl) return;
+    request(tokenRequest(clientId, o.endpoints), 'token refresh', ctrl.signal)
+      .then((r) => parseToken(r.status, r.body))
+      .then(
+        guard((token) => {
+          if (!closed && attempt === ctrl) apply(session.refresh(token, now()));
+        }),
+        // Kick ends the connection when the old token runs out; the
+        // reconnect fetches a new one.
+        noop
+      );
+  }
+
+  /** Lets go of the socket, without waiting for it, and of what hangs on it. */
+  function detach() {
+    clearTimeout(timer);
+    clearTimeout(handshake);
+    timer = handshake = null;
+    if (attempt) {
+      attempt.abort();
+      attempt = null;
+    }
+    const s = ws;
+    ws = null;
+    if (s) {
+      s.onopen = s.onmessage = s.onclose = null;
+      // The `ws` package emits an error on closing a socket still
+      // connecting, and throws one that nobody listens to.
+      s.onerror = noop;
+      try {
+        s.close();
+      } catch {
+        // Closed already.
+      }
+    }
+  }
+
+  function release() {
+    if (session) session.free();
+    if (backoff) backoff.free();
+    session = backoff = null;
+  }
+
+  /**
+   * A connection, or an attempt at one, ended: wait, then connect again.
+   * `retryAfterMs` is the least wait the end asked for (0: the ordinary
+   * backoff); `terminal`, that Kick will not take this client back.
+   */
+  function drop(reason, code, retryAfterMs, terminal) {
+    if (closed) return;
+    const waitMs = Math.min(backoff.nextDelayFor(retryAfterMs, Math.random()), MAX_TIMEOUT_MS);
+    callback('onDrop', reason, { code, terminal, waitMs });
     if (closed) return;
     clearTimeout(retry);
-    retry = setTimeout(connect, backoff.nextDelay());
+    // connect() makes a new client id (so a new guest token) every time,
+    // which a terminal close needs; after any other end it does no harm.
+    retry = setTimeout(start, waitMs);
+  }
+
+  /** The socket is finished, however it ended. */
+  function end(reason, code, retryAfterMs, terminal) {
+    detach();
+    if (closed) return;
+    session.closed();
+    state();
+    drop(reason, code, retryAfterMs, terminal);
+  }
+
+  function start() {
+    retry = null;
+    connect().catch((e) => {
+      report(e);
+      if (!closed) end(`kicksdk: ${message(e)}`, 0, 0, false);
+    });
   }
 
   async function connect() {
     if (closed) return;
-    // A guest identity: the token is issued to this id, and so is every
-    // refreshed one for this connection.
-    clientId = crypto.randomUUID();
+    const ctrl = new AbortController();
+    attempt = ctrl;
+    const mine = () => !closed && attempt === ctrl;
     let url;
     let token;
     try {
-      const where = o.channelId
+      // A guest identity: the token is issued to this id, and so is every
+      // refreshed one for this connection.
+      clientId = guestId();
+      const where = hasChannel
         ? chatConnectionRequest(o.channelId, clientId, o.endpoints)
         : connectionRequest(clientId, o.endpoints);
-      const c = await send(fetchImpl, where);
+      const c = await request(where, 'connection', ctrl.signal);
+      if (!mine()) return;
       const found = parseConnection(c.status, c.body).find((x) => x.provider === 'centrifugo');
       if (!found) throw new Error('Kick offered no Centrifugo server');
       url = found.url;
-      const t = await send(fetchImpl, tokenRequest(clientId, o.endpoints));
+      const t = await request(tokenRequest(clientId, o.endpoints), 'token', ctrl.signal);
+      if (!mine()) return;
       token = parseToken(t.status, t.body);
     } catch (e) {
-      if (o.onDrop) o.onDrop(String((e && e.message) || e));
-      again();
+      // Closed meanwhile: nobody is left to tell.
+      if (!mine()) return;
+      attempt = null;
+      drop(message(e), 0, 0, false);
       return;
     }
-    if (closed) return;
 
-    if (!session) session = new Session(channels);
     let socket;
     try {
       socket = createSocket(url);
     } catch (e) {
-      again();
+      attempt = null;
+      drop(`could not open a WebSocket: ${message(e)}`, 0, 0, false);
       return;
     }
     ws = socket;
-    socket.onopen = () => apply(session.open(token, now()));
-    socket.onmessage = (e) => {
+    handshake = setTimeout(
+      guard(() => {
+        handshake = null;
+        if (ws === socket) end(`WebSocket handshake: no answer in ${timeoutMs} ms`, 0, 0, false);
+      }),
+      timeoutMs
+    );
+    socket.onopen = guard(() => {
+      if (ws !== socket) return;
+      clearTimeout(handshake);
+      handshake = null;
+      apply(session.open(token, now()));
+    });
+    socket.onmessage = guard((e) => {
       if (ws === socket) apply(session.receive(String(e.data), now()));
-    };
-    socket.onclose = () => {
+    });
+    socket.onclose = guard((e) => {
       if (ws !== socket) return;
-      ws = null;
-      clearTimeout(timer);
-      apply(session.closed());
-      state();
-      again();
-    };
-    socket.onerror = () => {};
+      // A refused handshake ends here too, with no open before it. A close
+      // without a code a peer can send (1000-4999) is 1006, abnormal
+      // closure: Node 22's WebSocket reports a refused handshake as 0.
+      const code = e && Number.isInteger(e.code) && e.code >= 1000 && e.code <= 4999 ? e.code : 1006;
+      const why = e && e.reason ? `: ${e.reason}` : '';
+      // 3500-3999 and 4500-4999 are terminal: a long wait, then a new client.
+      const after = retryAfterMs(code);
+      end(`WebSocket closed (${code})${why}`, code, after, after > 0);
+    });
+    // After the handshake a close event follows an error. A refused
+    // handshake may end with the error alone (Node 22's WebSocket fires no
+    // close then), so an error before the open ends the socket here, as a
+    // close would have, rather than at the handshake timeout.
+    socket.onerror = guard(() => {
+      if (ws === socket && handshake !== null) end('WebSocket handshake failed (1006)', 1006, 0, false);
+    });
   }
 
-  connect();
+  retry = setTimeout(start, 0);
   return {
     close() {
+      if (closed) return;
       closed = true;
-      clearTimeout(timer);
       clearTimeout(retry);
-      if (ws) {
-        const s = ws;
-        ws = null;
-        s.onclose = null;
-        s.close();
-      }
-      if (session) {
-        session.free();
-        session = null;
-      }
-      backoff.free();
+      retry = null;
+      detach();
+      release();
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kicksdk-js",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Kick (kick.com) without the I/O: requests, parsers, the realtime chat protocol and webhook verification, from one Rust core",
   "license": "MIT OR Apache-2.0",
   "repository": { "type": "git", "url": "git+https://github.com/AnisAbdellatif/kicksdk.git", "directory": "bindings/js" },
@@ -12,11 +12,14 @@
     ".": { "types": "./index.d.ts", "default": "./index.js" },
     "./kicksdk_bg.wasm": "./pkg/kicksdk_bg.wasm"
   },
-  "files": ["index.js", "index.d.ts", "pkg/", "README.md"],
+  "files": ["index.js", "index.d.ts", "pkg/", "README.md", "LICENSE-MIT", "LICENSE-APACHE"],
   "engines": { "node": ">=22" },
   "sideEffects": false,
   "scripts": {
     "build": "../../scripts/build-js.sh",
-    "test": "node --test test/*.test.js"
+    "prepack": "node -e \"for (const f of ['LICENSE-MIT', 'LICENSE-APACHE']) require('fs').copyFileSync('../../' + f, f)\"",
+    "postpack": "node -e \"for (const f of ['LICENSE-MIT', 'LICENSE-APACHE']) require('fs').rmSync(f, { force: true })\"",
+    "test": "node --test test/*.test.js",
+    "typecheck": "tsc -p test/types/tsconfig.json"
   }
 }