@peers-app/peers-sdk 0.31.5 → 0.31.7

package/dist/device/device-election.d.ts

@@ -1,18 +1,32 @@
 import type { IDeviceConnection, INetworkInfo } from "../types/peer-device";
+/** Local connections and remote topology snapshots used to choose a group's sync edges. */
 export interface IElectionData {
     deviceId: string;
     myConnections: IDeviceConnection[];
     allNetworkInfo: INetworkInfo[];
 }
+/**
+ * Choose the devices this one syncs with in a group: its preferred devices, plus the devices
+ * that prefer it.
+ *
+ * Once preferences are established, ongoing changes move along these edges in either direction:
+ * a write notifies the writer's preferred and preferred-by devices, and periodic resync pulls
+ * only from preferred devices. The edges must therefore join every device in the group.
+ *
+ * @param data - This device, its direct connections, and each connected device's network info.
+ * @returns The devices to prefer, and the devices whose network info says they prefer this one.
+ */
 export declare function electDevices({ deviceId, myConnections, allNetworkInfo }: IElectionData): {
     preferredDeviceIds: string[];
     preferredByDeviceIds: string[];
 };
+/** A remote topology snapshot annotated with its local link and incoming preferences. */
 export interface ISortableConnection extends INetworkInfo {
     connectedDeviceIds: string[];
     preferredByDeviceIds: string[];
     myConnection: IDeviceConnection | undefined;
 }
+/** Candidate connections and the devices not yet covered by the greedy election pass. */
 export interface ISortConnectionsArgs {
     myDeviceId: string;
     unconnectedDeviceIds: Set<string>;

package/dist/device/device-election.js

@@ -3,6 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.electDevices = electDevices;
 exports.getLeastPreferredConnection = getLeastPreferredConnection;
 const lodash_1 = require("lodash");
+/**
+ * Choose the devices this one syncs with in a group: its preferred devices, plus the devices
+ * that prefer it.
+ *
+ * Once preferences are established, ongoing changes move along these edges in either direction:
+ * a write notifies the writer's preferred and preferred-by devices, and periodic resync pulls
+ * only from preferred devices. The edges must therefore join every device in the group.
+ *
+ * @param data - This device, its direct connections, and each connected device's network info.
+ * @returns The devices to prefer, and the devices whose network info says they prefer this one.
+ */
 function electDevices({ deviceId, myConnections, allNetworkInfo }) {
     const allDeviceIdsSet = new Set();
     const _preferredByDeviceIdsSet = new Set();
@@ -47,11 +58,55 @@ function electDevices({ deviceId, myConnections, allNetworkInfo }) {
             break;
         }
     }
+    const preferredDeviceIds = preferredConnections.map((c) => c.deviceId);
+    preferredDeviceIds.push(...connectCompleteViews({
+        deviceId,
+        myConnections,
+        preferredDeviceIds,
+        connections: allConnectionInfos,
+    }));
     return {
-        preferredDeviceIds: preferredConnections.map((c) => c.deviceId),
+        preferredDeviceIds,
         preferredByDeviceIds: Array.from(_preferredByDeviceIdsSet),
     };
 }
+/**
+ * Add stable sync edges when this device has network info for every known device directly.
+ *
+ * The greedy pass counts a device as covered once a preferred device is connected to it, but
+ * ongoing changes move along preference edges. In a full mesh the greedy pass prefers one other,
+ * and two devices that pick each other form an island: their writes never reach the rest, and
+ * the rest's never reach them.
+ *
+ * Devices connected to everyone form an id-ordered chain: each prefers its predecessor. The
+ * first also prefers every device without a complete view, since those cannot build the chain
+ * themselves. In a full mesh this adds at most one preference per device and at most two incident
+ * edges per device, rather than concentrating the extra sync traffic on one hub.
+ *
+ * These edges depend only on topology, never on cached preferences. Bridging only the components
+ * in a snapshot is insufficient: concurrent elections can each rely on edges the others remove,
+ * repeatedly splitting a full mesh even when just one device adds bridges. Once topology and
+ * network-info availability settle, every complete view builds the same chain regardless of
+ * election order or stale preferences. Partial views still use only the greedy pass.
+ */
+function connectCompleteViews({ deviceId, myConnections, preferredDeviceIds, connections, }) {
+    const direct = connections.filter((c) => c.myConnection);
+    const visibleIds = new Set(direct.map((c) => c.deviceId));
+    const knownIds = new Set([
+        deviceId,
+        ...myConnections.map((c) => c.deviceId),
+        ...connections.flatMap((c) => c.connectedDeviceIds),
+    ]);
+    if ([...knownIds].some((id) => id !== deviceId && !visibleIds.has(id)))
+        return [];
+    const seesEveryone = (c) => [...knownIds].every((id) => c.connectedDeviceIds.includes(id));
+    const completeIds = [deviceId, ...direct.filter(seesEveryone).map((c) => c.deviceId)].sort();
+    const index = completeIds.indexOf(deviceId);
+    const backbone = index > 0
+        ? [completeIds[index - 1]]
+        : direct.filter((c) => !seesEveryone(c)).map((c) => c.deviceId);
+    return backbone.filter((id) => !preferredDeviceIds.includes(id));
+}
 /**
  * Sort connections from most preferred to least preferred
  *   The most preferred connections are ones that link us to the most new devices
@@ -66,12 +121,9 @@ function sortConnections({ myDeviceId, connections, unconnectedDeviceIds }) {
         const bLatency = (b.myConnection?.latencyMs || 1) * (b.myConnection?.errorRate || 0.00001);
         return aLatency - bLatency;
     });
-    // sort by preferred by other devices count (higher is better)
-    connections.sort((a, b) => {
-        const aPreferredCount = a.preferredDeviceIds.length;
-        const bPreferredCount = b.preferredDeviceIds.length;
-        return bPreferredCount - aPreferredCount;
-    });
+    // sort by how many other devices prefer it (higher is better), so devices gather on one
+    // another's choices instead of pairing off
+    connections.sort((a, b) => b.preferredByDeviceIds.length - a.preferredByDeviceIds.length);
     // sort by links to new devices - in general, this is most important except for the later edge-cases
     connections.sort((a, b) => {
         const linksToDeviceA = a.connectedDeviceIds.filter((id) => unconnectedDeviceIds.has(id)).length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.31.5",
+  "version": "0.31.7",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"