@koolbase/core 12.12.0 → 12.13.0

package/dist/cjs/collection-controller.d.ts

@@ -11,8 +11,9 @@ export interface CollectionQuery {
     /**
      * Re-read page one, silently, when Koolbase realtime reports a record
      * created, updated or deleted in this collection (debounced: a burst is one
-     * read). Realtime needs a signed-in user; until there is one, the list
-     * behaves as a normal list and goes live once the session exists.
+     * read). Signed out, only a collection anyone can read (read rule
+     * "public") is live; any other behaves as a normal list until a user signs
+     * in, and goes live then.
      */
     live?: boolean;
 }

package/dist/cjs/realtime.d.ts

@@ -9,6 +9,9 @@ export declare class KoolbaseRealtime {
     private reconnectAttempts;
     private reconnectTimer;
     private connecting;
+    private anonymous;
+    private connectedAs;
+    private generation;
     private idleTimer;
     /** How long an unused connection stays open, in ms: a screen that comes
      *  straight back (navigating back, React's development double start)
@@ -30,6 +33,9 @@ export declare class KoolbaseRealtime {
     private connect;
     private sendSubscribe;
     private sendUnsubscribe;
+    /** A signed-out visitor's message leaves project_id out: it has none to
+     *  give, and the server uses the public key's project. */
+    private send;
     /**
      * Reconnects with backoff, rather than every three seconds forever.
      *
@@ -51,6 +57,16 @@ export declare class KoolbaseRealtime {
      * it: reconnecting needs a subscriber.
      */
     private scheduleIdleClose;
+    /**
+     * The signed-in user changed: signed in, signed out, or another user. The
+     * open connection was made for the previous session -- signed out it sees
+     * only public collections, signed in it carries that user's access -- so it
+     * is replaced by one for the new session, resubscribing every collection.
+     * The same user again (a token refresh) changes nothing, and with nothing
+     * open there is nothing to do: the next subscribe connects as whoever is
+     * signed in then.
+     */
+    sessionChanged(): void;
     disconnect(): void;
 }
 export {};

package/dist/cjs/realtime.js

@@ -41,6 +41,15 @@ class KoolbaseRealtime {
         this.reconnectAttempts = 0;
         this.reconnectTimer = null;
         this.connecting = false;
+        // The open connection is a signed-out visitor's (the public key): its
+        // messages leave project_id out.
+        this.anonymous = false;
+        // Whose session the open connection was made for: the user id, or null
+        // when signed out. sessionChanged compares against it.
+        this.connectedAs = null;
+        // Bumped by sessionChanged: a connect still waiting for its token gives up
+        // rather than open a connection for the old session.
+        this.generation = 0;
         // Pending close of an unused connection (scheduleIdleClose); null while
         // anyone is subscribed.
         this.idleTimer = null;
@@ -101,28 +110,49 @@ class KoolbaseRealtime {
         // double start -- found nobody connecting and opened its own socket; only
         // the last was remembered, and the others stayed open for good.
         this.connecting = true;
+        const generation = this.generation;
         let token;
         try {
             token = await this.getToken();
         }
         catch {
-            token = null;
+            // A session that could not be refreshed is still a session: try again
+            // later, never as a signed-out visitor.
+            if (generation !== this.generation)
+                return;
+            this.connecting = false;
+            this.scheduleReconnect();
+            return;
         }
+        // The session changed while the token was on its way: sessionChanged
+        // has started the connection for the new one.
+        if (generation !== this.generation)
+            return;
         if (this.listeners.size === 0) {
             // Everyone left while the token was on its way: nothing to connect for.
             this.connecting = false;
             return;
         }
-        if (!token) {
+        const userId = this.getUserId?.() ?? null;
+        if (!token && userId) {
+            // Signed in, but no usable token right now: try again later rather
+            // than drop to public-only.
             this.connecting = false;
-            this.scheduleReconnect(); // sign-in may be in flight
+            this.scheduleReconnect();
             return;
         }
-        this.projectId = projectIdFromToken(token);
+        // Signed out: the project's public key, and only collections anyone can
+        // read. The server pins the connection to the key's project.
+        this.anonymous = !token;
+        this.connectedAs = token ? userId : null;
+        this.projectId = token ? projectIdFromToken(token) : null;
+        const credential = token
+            ? `token=${encodeURIComponent(token)}`
+            : `public_key=${encodeURIComponent(this.config.publicKey)}`;
         const wsUrl = this.config.baseUrl.replace('https://', 'wss://').replace('http://', 'ws://');
         let ws;
         try {
-            ws = new WebSocket(`${wsUrl}/v1/realtime/ws?token=${encodeURIComponent(token)}`);
+            ws = new WebSocket(`${wsUrl}/v1/realtime/ws?${credential}`);
         }
         catch {
             this.connecting = false;
@@ -186,14 +216,22 @@ class KoolbaseRealtime {
         ws.onerror = () => { };
     }
     sendSubscribe(collection) {
-        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
-            return;
-        this.ws.send(JSON.stringify({ action: 'subscribe', project_id: this.projectId, collection }));
+        this.send('subscribe', collection);
     }
     sendUnsubscribe(collection) {
-        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
+        this.send('unsubscribe', collection);
+    }
+    /** A signed-out visitor's message leaves project_id out: it has none to
+     *  give, and the server uses the public key's project. */
+    send(action, collection) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
             return;
-        this.ws.send(JSON.stringify({ action: 'unsubscribe', project_id: this.projectId, collection }));
+        if (this.anonymous) {
+            this.ws.send(JSON.stringify({ action, collection }));
+        }
+        else if (this.projectId) {
+            this.ws.send(JSON.stringify({ action, project_id: this.projectId, collection }));
+        }
     }
     /**
      * Reconnects with backoff, rather than every three seconds forever.
@@ -252,6 +290,42 @@ class KoolbaseRealtime {
         }, KoolbaseRealtime.idleGraceMs);
         this.idleTimer.unref?.();
     }
+    /**
+     * The signed-in user changed: signed in, signed out, or another user. The
+     * open connection was made for the previous session -- signed out it sees
+     * only public collections, signed in it carries that user's access -- so it
+     * is replaced by one for the new session, resubscribing every collection.
+     * The same user again (a token refresh) changes nothing, and with nothing
+     * open there is nothing to do: the next subscribe connects as whoever is
+     * signed in then.
+     */
+    sessionChanged() {
+        if (!this.ws && !this.connecting && !this.reconnectTimer)
+            return;
+        if (this.ws && !this.connecting && (this.getUserId?.() ?? null) === this.connectedAs)
+            return;
+        this.generation += 1;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        const ws = this.ws;
+        this.ws = null;
+        this.connecting = false;
+        this.anonymous = false;
+        this.projectId = null;
+        this.reconnectAttempts = 0;
+        if (ws) {
+            // Detached first: this close is ours, not a dropped connection.
+            ws.onopen = null;
+            ws.onmessage = null;
+            ws.onclose = null;
+            ws.onerror = null;
+            ws.close();
+        }
+        if (this.listeners.size > 0)
+            void this.connect();
+    }
     disconnect() {
         if (this.idleTimer) {
             clearTimeout(this.idleTimer);

package/dist/esm/collection-controller.d.ts

@@ -11,8 +11,9 @@ export interface CollectionQuery {
     /**
      * Re-read page one, silently, when Koolbase realtime reports a record
      * created, updated or deleted in this collection (debounced: a burst is one
-     * read). Realtime needs a signed-in user; until there is one, the list
-     * behaves as a normal list and goes live once the session exists.
+     * read). Signed out, only a collection anyone can read (read rule
+     * "public") is live; any other behaves as a normal list until a user signs
+     * in, and goes live then.
      */
     live?: boolean;
 }

package/dist/esm/realtime.d.ts

@@ -9,6 +9,9 @@ export declare class KoolbaseRealtime {
     private reconnectAttempts;
     private reconnectTimer;
     private connecting;
+    private anonymous;
+    private connectedAs;
+    private generation;
     private idleTimer;
     /** How long an unused connection stays open, in ms: a screen that comes
      *  straight back (navigating back, React's development double start)
@@ -30,6 +33,9 @@ export declare class KoolbaseRealtime {
     private connect;
     private sendSubscribe;
     private sendUnsubscribe;
+    /** A signed-out visitor's message leaves project_id out: it has none to
+     *  give, and the server uses the public key's project. */
+    private send;
     /**
      * Reconnects with backoff, rather than every three seconds forever.
      *
@@ -51,6 +57,16 @@ export declare class KoolbaseRealtime {
      * it: reconnecting needs a subscriber.
      */
     private scheduleIdleClose;
+    /**
+     * The signed-in user changed: signed in, signed out, or another user. The
+     * open connection was made for the previous session -- signed out it sees
+     * only public collections, signed in it carries that user's access -- so it
+     * is replaced by one for the new session, resubscribing every collection.
+     * The same user again (a token refresh) changes nothing, and with nothing
+     * open there is nothing to do: the next subscribe connects as whoever is
+     * signed in then.
+     */
+    sessionChanged(): void;
     disconnect(): void;
 }
 export {};

package/dist/esm/realtime.js

@@ -38,6 +38,15 @@ export class KoolbaseRealtime {
         this.reconnectAttempts = 0;
         this.reconnectTimer = null;
         this.connecting = false;
+        // The open connection is a signed-out visitor's (the public key): its
+        // messages leave project_id out.
+        this.anonymous = false;
+        // Whose session the open connection was made for: the user id, or null
+        // when signed out. sessionChanged compares against it.
+        this.connectedAs = null;
+        // Bumped by sessionChanged: a connect still waiting for its token gives up
+        // rather than open a connection for the old session.
+        this.generation = 0;
         // Pending close of an unused connection (scheduleIdleClose); null while
         // anyone is subscribed.
         this.idleTimer = null;
@@ -98,28 +107,49 @@ export class KoolbaseRealtime {
         // double start -- found nobody connecting and opened its own socket; only
         // the last was remembered, and the others stayed open for good.
         this.connecting = true;
+        const generation = this.generation;
         let token;
         try {
             token = await this.getToken();
         }
         catch {
-            token = null;
+            // A session that could not be refreshed is still a session: try again
+            // later, never as a signed-out visitor.
+            if (generation !== this.generation)
+                return;
+            this.connecting = false;
+            this.scheduleReconnect();
+            return;
         }
+        // The session changed while the token was on its way: sessionChanged
+        // has started the connection for the new one.
+        if (generation !== this.generation)
+            return;
         if (this.listeners.size === 0) {
             // Everyone left while the token was on its way: nothing to connect for.
             this.connecting = false;
             return;
         }
-        if (!token) {
+        const userId = this.getUserId?.() ?? null;
+        if (!token && userId) {
+            // Signed in, but no usable token right now: try again later rather
+            // than drop to public-only.
             this.connecting = false;
-            this.scheduleReconnect(); // sign-in may be in flight
+            this.scheduleReconnect();
             return;
         }
-        this.projectId = projectIdFromToken(token);
+        // Signed out: the project's public key, and only collections anyone can
+        // read. The server pins the connection to the key's project.
+        this.anonymous = !token;
+        this.connectedAs = token ? userId : null;
+        this.projectId = token ? projectIdFromToken(token) : null;
+        const credential = token
+            ? `token=${encodeURIComponent(token)}`
+            : `public_key=${encodeURIComponent(this.config.publicKey)}`;
         const wsUrl = this.config.baseUrl.replace('https://', 'wss://').replace('http://', 'ws://');
         let ws;
         try {
-            ws = new WebSocket(`${wsUrl}/v1/realtime/ws?token=${encodeURIComponent(token)}`);
+            ws = new WebSocket(`${wsUrl}/v1/realtime/ws?${credential}`);
         }
         catch {
             this.connecting = false;
@@ -183,14 +213,22 @@ export class KoolbaseRealtime {
         ws.onerror = () => { };
     }
     sendSubscribe(collection) {
-        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
-            return;
-        this.ws.send(JSON.stringify({ action: 'subscribe', project_id: this.projectId, collection }));
+        this.send('subscribe', collection);
     }
     sendUnsubscribe(collection) {
-        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
+        this.send('unsubscribe', collection);
+    }
+    /** A signed-out visitor's message leaves project_id out: it has none to
+     *  give, and the server uses the public key's project. */
+    send(action, collection) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
             return;
-        this.ws.send(JSON.stringify({ action: 'unsubscribe', project_id: this.projectId, collection }));
+        if (this.anonymous) {
+            this.ws.send(JSON.stringify({ action, collection }));
+        }
+        else if (this.projectId) {
+            this.ws.send(JSON.stringify({ action, project_id: this.projectId, collection }));
+        }
     }
     /**
      * Reconnects with backoff, rather than every three seconds forever.
@@ -249,6 +287,42 @@ export class KoolbaseRealtime {
         }, KoolbaseRealtime.idleGraceMs);
         this.idleTimer.unref?.();
     }
+    /**
+     * The signed-in user changed: signed in, signed out, or another user. The
+     * open connection was made for the previous session -- signed out it sees
+     * only public collections, signed in it carries that user's access -- so it
+     * is replaced by one for the new session, resubscribing every collection.
+     * The same user again (a token refresh) changes nothing, and with nothing
+     * open there is nothing to do: the next subscribe connects as whoever is
+     * signed in then.
+     */
+    sessionChanged() {
+        if (!this.ws && !this.connecting && !this.reconnectTimer)
+            return;
+        if (this.ws && !this.connecting && (this.getUserId?.() ?? null) === this.connectedAs)
+            return;
+        this.generation += 1;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        const ws = this.ws;
+        this.ws = null;
+        this.connecting = false;
+        this.anonymous = false;
+        this.projectId = null;
+        this.reconnectAttempts = 0;
+        if (ws) {
+            // Detached first: this close is ours, not a dropped connection.
+            ws.onopen = null;
+            ws.onmessage = null;
+            ws.onclose = null;
+            ws.onerror = null;
+            ws.close();
+        }
+        if (this.listeners.size > 0)
+            void this.connect();
+    }
     disconnect() {
         if (this.idleTimer) {
             clearTimeout(this.idleTimer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/core",
-  "version": "12.12.0",
+  "version": "12.13.0",
   "description": "Koolbase SDK core \u2014 shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",