@peers-app/peers-sdk 0.30.2 → 0.30.4

package/dist/contracts/system/mesh-metrics-types.d.ts

@@ -0,0 +1,169 @@
+/** Trigger for an overlapping, at most five-minute connectivity measurement. */
+export type MeshEpisodeReason = "startup" | "resume" | "network-change" | "connection-loss";
+/** Provenance of a dial; explicit requests and group joins are also distinguished. */
+export type MeshDialReason = "own-device" | "group-network-info" | "broadcast-answer" | "configured-server" | "lan-scan" | "websocket-upgrade" | "incoming" | "direct-request" | "group-join";
+/** Bounded path categories used for lifetime counters; attempts also retain the address. */
+export type MeshPath = "websocket" | "webrtc" | "cloud" | "discovery";
+/** Failure categories, independent of free-form transport error messages. */
+export type MeshFailureReason = "ttl0" | "no-route" | "signaling-timeout" | "socket-error" | "socket-timeout" | "handshake" | "rejected" | "closed" | "superseded" | "unsupported" | "sender-not-known" | "trust-refused" | "identity-mismatch" | "cancelled" | "capacity";
+/** Observed stage; timestamps are offsets in milliseconds from the attempt's queued time. */
+export type MeshStage = "queued" | "started" | "authenticated" | "admitted" | "ready" | "firstSync";
+/** Local dial metadata and cancellation; never serialized into device messages. */
+export interface IMeshDial {
+    /** Cancels pending transport work; an admitted winner is retained. */
+    signal?: AbortSignal;
+    /** Scheduler priority: bootstrap, coverage, repair, then redundancy. */
+    priority?: 1 | 2 | 3 | 4;
+    attemptId?: string;
+    reason?: MeshDialReason;
+    targetDeviceId?: string;
+    /** One-based retry number; absent for the initial dial. */
+    retry?: number;
+}
+/** One dial or inbound connection. Missing stages have not been observed. */
+export interface IMeshAttempt {
+    attemptId: string;
+    targetDeviceId?: string;
+    reason: MeshDialReason;
+    /** One-based retry number; absent for initial and incoming attempts. */
+    retry?: number;
+    /** Scheduler priority when this was planned locally. */
+    priority?: 1 | 2 | 3 | 4;
+    direction: "outgoing" | "incoming";
+    path: MeshPath;
+    address?: string;
+    queuedAt: number;
+    stages: Partial<Record<MeshStage, number>>;
+    answeredDeviceId?: string;
+    expectedIdentity?: boolean;
+    answered: boolean;
+    lastSignalFailure?: {
+        reason: "ttl0" | "no-route";
+        detail?: string;
+    };
+    ready: Record<string, number>;
+    firstSync: Record<string, number>;
+    outcome: "pending" | "admitted" | "failed" | "cancelled" | "unfinished";
+    endReason?: "buffer-evicted" | "disposed";
+    endedAt?: number;
+    durationMs?: number;
+    failure?: {
+        stage: MeshStage;
+        reason: MeshFailureReason;
+        detail?: string;
+    };
+    doubleDial: boolean;
+    offline: boolean;
+    outOfOrder: boolean;
+}
+/** Millisecond durations derived from one episode; absent means not observed. */
+export interface IMeshDurations {
+    T_first?: number;
+    T_own?: number;
+    T_cover?: number;
+    T_resume?: number;
+    repairStart?: number;
+}
+/** Coverage at the latest observation (at completion for a finished episode). */
+export interface IMeshContextCoverage {
+    dataContextId: string;
+    possibleSourceDeviceIds: string[];
+    usableDeviceIds: string[];
+    excluded: boolean;
+    /** True when an unmet context cannot currently fit at the connection cap. */
+    limitedByCapacity?: boolean;
+    /** Planner target; zero means no possible source. */
+    target?: number;
+}
+/** One connectivity episode, independent of any other episode in flight. */
+export interface IMeshEpisode {
+    episodeId: string;
+    reason: MeshEpisodeReason;
+    trigger?: string;
+    startedAt: number;
+    endedAt?: number;
+    durationMs?: number;
+    outcome: "active" | "covered" | "unfinished" | "not-measured";
+    endReason?: "covered" | "deadline" | "buffer-evicted" | "disposed" | "page-hidden" | "still-covered";
+    metrics: IMeshDurations;
+    contexts: IMeshContextCoverage[];
+}
+/** Nearest-rank percentiles of observed values only; count exposes the denominator. */
+export interface IMeshPercentiles {
+    count: number;
+    p50?: number;
+    p90?: number;
+    p95?: number;
+    p99?: number;
+}
+/** Lifetime dial totals. Incoming connections are separate from the outgoing-dial ratio. */
+export interface IMeshPathCounters {
+    dials: number;
+    connections: number;
+    incomingConnections: number;
+    dialsPerConnection: number | null;
+    failures: Partial<Record<MeshFailureReason, number>>;
+}
+/** Shared relay totals and current gauges, also exposed on non-Services hosts. */
+export interface IMeshServicesCounters {
+    directRelays: number;
+    floodsForwarded: number;
+    floodsPruned: number;
+    pendingEmits: number;
+    concurrentConnections: number;
+    connects: number;
+    disconnects: number;
+}
+/** In-memory diagnostics snapshot. No history survives a runtime restart. */
+export interface IMeshStats {
+    startedAt: number;
+    sampledAt: number;
+    uptimeMs: number;
+    readyToDialMs?: number;
+    limits: {
+        episodes: number;
+        attempts: number;
+        episodeMs: number;
+    };
+    currentEpisodes: IMeshEpisode[];
+    recentEpisodes: IMeshEpisode[];
+    percentiles: Record<keyof IMeshDurations, IMeshPercentiles>;
+    counters: {
+        paths: Record<MeshPath, IMeshPathCounters>;
+        lanScan: {
+            scans: number;
+            probes: number;
+            connected: number;
+        };
+        /** Lifetime episodes excluded from latency percentiles, by reason. */
+        unmeasuredEpisodes?: {
+            pageHidden: number;
+            stillCovered: number;
+        };
+        unfinishedAttempts: number;
+        doubleDials: number;
+        offlineDials: number;
+        offlineDialsPerHour: number;
+        broadcasts: {
+            sent: number;
+            answered: number;
+            ttl0: number;
+            failed: number;
+            pending: number;
+            perHour: number;
+        };
+        services: IMeshServicesCounters;
+    };
+    recentAttempts: IMeshAttempt[];
+    recentBroadcasts: IMeshBroadcast[];
+    /** Latest planner coverage, including zero targets and capacity limitations. */
+    coverage?: IMeshContextCoverage[];
+}
+/** A discovery broadcast and its observed reply, bounded with the attempt history. */
+export interface IMeshBroadcast {
+    broadcastId: string;
+    dataContextId?: string;
+    sentAt: number;
+    durationMs?: number;
+    outcome: "pending" | "answered" | "ttl0" | "failed";
+}

package/dist/contracts/system/mesh-metrics-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/system/network-contracts.d.ts

@@ -4,12 +4,15 @@ import type { Observable } from "../../observable";
 import type { INetworkInfo } from "../../types/peer-device";
 import type { IContractConsumerBase } from "../contract-proxy";
 import type { IContractDefinition } from "../types";
+import type { IMeshStats } from "./mesh-metrics-types";
+export type * from "./mesh-metrics-types";
 /** Version of the built-in System Network Diagnostics contract. */
 export declare const NETWORK_DIAGNOSTICS_CONTRACT_VERSION = 1;
 /** Version of the built-in System Network Control contract. */
 export declare const NETWORK_CONTROL_CONTRACT_VERSION = 1;
 /** Stable IDs for tools in System Network Diagnostics v1. */
 export declare const networkDiagnosticsToolIds: {
+    readonly getMeshStats: string;
     readonly getOverview: "00ms1yb50ym353ads0gel5jpv";
     readonly getConnections: "00ms1yb50ykny9kdgiclpa1t4";
     readonly getGroupSyncStatus: "00ms1yb50yp2q7jr0jglzsztq";
@@ -241,6 +244,11 @@ export interface INetworkDiagnosticsConsumer extends IContractConsumerBase {
         getOverview(): Promise<{
             overview: INetworkOverview;
         }>;
+        getMeshStats(input?: {
+            limit?: number;
+        }): Promise<{
+            stats: IMeshStats;
+        }>;
         getConnections(): Promise<{
             connections: INetworkConnectionInfo[];
         }>;

package/dist/contracts/system/network-contracts.js

@@ -6,12 +6,18 @@ exports.getNetworkControlContractDefinition = getNetworkControlContractDefinitio
 const system_ids_1 = require("../../system-ids");
 const field_type_1 = require("../../types/field-type");
 const system_contracts_1 = require("../system-contracts");
+const tool_catalog_identity_1 = require("../tool-catalog-identity");
 /** Version of the built-in System Network Diagnostics contract. */
 exports.NETWORK_DIAGNOSTICS_CONTRACT_VERSION = 1;
 /** Version of the built-in System Network Control contract. */
 exports.NETWORK_CONTROL_CONTRACT_VERSION = 1;
 /** Stable IDs for tools in System Network Diagnostics v1. */
 exports.networkDiagnosticsToolIds = {
+    getMeshStats: (0, tool_catalog_identity_1.deriveToolCatalogId)({
+        contractId: system_ids_1.networkDiagnosticsContractId,
+        version: exports.NETWORK_DIAGNOSTICS_CONTRACT_VERSION,
+        toolName: "getMeshStats",
+    }),
     getOverview: "00ms1yb50ym353ads0gel5jpv",
     getConnections: "00ms1yb50ykny9kdgiclpa1t4",
     getGroupSyncStatus: "00ms1yb50yp2q7jr0jglzsztq",
@@ -46,6 +52,16 @@ function getNetworkDiagnosticsContractDefinition() {
         description: "Portable local network, connection, and synchronization diagnostics.",
         tables: [],
         tools: [
+            {
+                name: "getMeshStats",
+                usageDescription: "Read bounded in-memory connectivity episodes, attempts, percentiles and relay counters.",
+                inputFields: [
+                    field("limit", field_type_1.FieldType.number, "Maximum recent attempts and broadcasts (default 50, range 0–500). Episodes and counters are always complete.", { optional: true }),
+                ],
+                outputFields: [
+                    field("stats", field_type_1.FieldType.object, "Connectivity measurements since runtime startup."),
+                ],
+            },
             {
                 name: "getOverview",
                 usageDescription: "Return aggregate network and group information.",

package/dist/data/files/files.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FilesTable = void 0;
 exports.Files = Files;
 const user_context_singleton_1 = require("../../context/user-context-singleton");
-const rpc_types_1 = require("../../rpc-types");
 const orm_1 = require("../orm");
 const table_definitions_system_1 = require("../orm/table-definitions.system");
 const chunk_store_1 = require("./chunk-store");
@@ -166,18 +165,3 @@ exports.FilesTable = FilesTable;
 function Files(dataContext) {
     return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(file_types_1.filesMetaData, file_types_1.fileSchema);
 }
-// Deprecated RPCs, kept only for Family Hub 0.3.x until its port is Home's version. New code
-// uses System Files, which is bound to the caller's own data context.
-rpc_types_1.rpcServerCalls.getFileContentsBase64 = async (fileId) => {
-    const data = await Files().getFileContents(fileId);
-    if (data === null) {
-        throw new Error(`File not found: ${fileId}`);
-    }
-    return Buffer.from(data).toString("base64");
-};
-rpc_types_1.rpcServerCalls.saveFile = async (input) => {
-    const encoding = input.encoding || "utf8";
-    const dataBuffer = encoding === "base64" ? Buffer.from(input.data, "base64") : Buffer.from(input.data, "utf8");
-    // Kept: Family Hub 0.3.x doesn't declare its file fields, so nothing would reference these.
-    return await Files().saveFile({ name: input.name, mimeType: input.mimeType, keep: true }, new Uint8Array(dataBuffer));
-};

package/dist/device/connection.d.ts

@@ -21,6 +21,9 @@ export declare class Connection {
     private _remoteDeviceInfo;
     /** Trust assigned to the remote identity once the handshake completes. */
     trustLevel: TrustLevel;
+    /** Synchronous diagnostics only; observer errors cannot affect handshake results. */
+    onHandshakeObserved?: (stage: "authenticated" | "failed", error?: unknown) => void;
+    private observeHandshake;
     /** Server-side hook fired shortly after the successful handshake reply has been sent. */
     onHandshakeComplete: ((deviceInfo: IDeviceInfo) => void) | undefined;
     /** RPC timeout for {@link Connection.emit}. */
@@ -39,6 +42,8 @@ export declare class Connection {
     private pendingSendArm;
     /** Bumped by every {@link Connection.reset}, so a handshake can tell it was cut short. */
     private handshakeGeneration;
+    /** Local close intent, retained through reset so retry owners do not penalize orderly shedding. */
+    closeIntent?: "remote" | "policy";
     constructor(socket: ISocket, localDevice: Device, localDeviceServerAddresses?: string[] | undefined, getTrustLevel?: GetTrustLevel);
     /** True once the remote identity has been authenticated by the handshake. */
     get verified(): boolean;
@@ -148,5 +153,8 @@ export declare class Connection {
      */
     close(): Promise<void>;
 }
-/** Normalizes a peer address for transport and security comparisons. */
+/** Lowercases a peer address and removes a trailing slash; preserves its scheme. */
 export declare function normalizeAddress(address: string): string;
+/** Local handshake refusal. Its existing Error text remains compatible with older peers. */
+export declare class ConnectionTrustError extends Error {
+}

package/dist/device/connection.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Connection = void 0;
+exports.ConnectionTrustError = exports.Connection = void 0;
 exports.normalizeAddress = normalizeAddress;
 const user_context_singleton_1 = require("../context/user-context-singleton");
 const data_1 = require("../data");
@@ -32,6 +32,16 @@ class Connection {
     };
     /** Trust assigned to the remote identity once the handshake completes. */
     trustLevel = socket_type_1.TrustLevel.Unknown;
+    /** Synchronous diagnostics only; observer errors cannot affect handshake results. */
+    onHandshakeObserved;
+    observeHandshake(stage, error) {
+        try {
+            this.onHandshakeObserved?.(stage, error);
+        }
+        catch {
+            /* diagnostics never affect the handshake */
+        }
+    }
     /** Server-side hook fired shortly after the successful handshake reply has been sent. */
     onHandshakeComplete;
     /** RPC timeout for {@link Connection.emit}. */
@@ -52,6 +62,8 @@ class Connection {
     pendingSendArm;
     /** Bumped by every {@link Connection.reset}, so a handshake can tell it was cut short. */
     handshakeGeneration = 0;
+    /** Local close intent, retained through reset so retry owners do not penalize orderly shedding. */
+    closeIntent;
     constructor(socket, localDevice, localDeviceServerAddresses, getTrustLevel = () => Promise.resolve(socket_type_1.TrustLevel.Unknown)) {
         this.localDevice = localDevice;
         this.localDeviceServerAddresses = localDeviceServerAddresses;
@@ -66,6 +78,7 @@ class Connection {
         socket.setPlaintextStreamsAllowed?.(false);
         // Only the server side of a connection should expose these methods
         this.exposeRPC("close", () => {
+            this.closeIntent ??= "remote";
             (0, utils_1.sleep)(100).then(() => {
                 this.closeLocal();
             });
@@ -133,6 +146,7 @@ class Connection {
             }
         }
         catch (e) {
+            this.observeHandshake("failed", e);
             console.error("Error handling completeHandshake", e);
             callback({ error: e?.message ?? String(e), errorType: "RPC_ERROR" });
         }
@@ -393,7 +407,7 @@ class Connection {
         this.assertHandshakeCurrent(generation);
         if (trustLevel < socket_type_1.TrustLevel.Unknown) {
             this.resetRemote();
-            throw new Error("Untrusted connection");
+            throw new ConnectionTrustError("Untrusted connection");
         }
         // The client seals everything after it reads our response, so receive
         // can arm now; send arms after the response frame goes out.
@@ -412,6 +426,7 @@ class Connection {
         };
         this.trustLevel = trustLevel;
         this._verified = true;
+        this.observeHandshake("authenticated");
         return handshakeResponse;
     }
     /**
@@ -454,11 +469,12 @@ class Connection {
             this.trustLevel = trustLevel;
             if (this.trustLevel < socket_type_1.TrustLevel.Unknown) {
                 this.resetRemote();
-                throw new Error("Untrusted connection");
+                throw new ConnectionTrustError("Untrusted connection");
             }
             return handshakeResponse;
         }
         catch (e) {
+            this.observeHandshake("failed", e);
             // A failed or timed-out attempt must neither retain its ephemeral secret nor let a
             // late reply authenticate it. Do not clear state belonging to a newer handshake.
             if (generation === this.handshakeGeneration)
@@ -522,6 +538,7 @@ class Connection {
                 : remoteDeviceInfo.deviceName,
         };
         this._verified = true;
+        this.observeHandshake("authenticated");
         this._connectionAddress = remoteAddress;
         return handshakeResponse;
     }
@@ -599,7 +616,11 @@ async function noteHandshakeContest(contest) {
         console.warn("Could not apply a key contest from the handshake", err);
     }
 }
-/** Normalizes a peer address for transport and security comparisons. */
+/** Lowercases a peer address and removes a trailing slash; preserves its scheme. */
 function normalizeAddress(address) {
     return address.toLowerCase().replace(/\/$/, "");
 }
+/** Local handshake refusal. Its existing Error text remains compatible with older peers. */
+class ConnectionTrustError extends Error {
+}
+exports.ConnectionTrustError = ConnectionTrustError;

package/dist/device/socket-io-binary-peer.d.ts

@@ -14,6 +14,7 @@ import type { IBinaryPeer } from "./binary-peer-connection-v2";
 interface ISocketIO {
     id?: string;
     on(event: string, handler: (...args: any[]) => void): void;
+    off(event: string, handler: (...args: any[]) => void): void;
     emit(event: string, ...args: any[]): void;
     removeAllListeners(event?: string): void;
     disconnect(): void;

package/dist/device/socket-io-binary-peer.js

@@ -22,8 +22,11 @@ function wrapSocketIOAsBinaryPeer(socket) {
     const closeHandlers = [];
     const drainHandlers = [];
     let pendingBytes = 0;
+    let closed = false;
     // Listen for binary data
-    socket.on(BINARY_EVENT, (data) => {
+    const onData = (data) => {
+        if (closed)
+            return;
         // Ensure we have a proper Uint8Array
         const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
         dataHandlers.forEach((handler) => {
@@ -34,9 +37,16 @@ function wrapSocketIOAsBinaryPeer(socket) {
                 console.error("[socket-io-binary] Error in data handler:", err);
             }
         });
-    });
+    };
     // Listen for disconnect
-    socket.on("disconnect", () => {
+    const onDisconnect = () => {
+        if (closed)
+            return;
+        closed = true;
+        // This adapter belongs to one connection incarnation. A delayed close from it
+        // must never disconnect a reconnected Socket.IO socket or remove its listeners.
+        socket.off(BINARY_EVENT, onData);
+        socket.off("disconnect", onDisconnect);
         closeHandlers.forEach((handler) => {
             try {
                 handler();
@@ -45,7 +55,9 @@ function wrapSocketIOAsBinaryPeer(socket) {
                 console.error("[socket-io-binary] Error in close handler:", err);
             }
         });
-    });
+    };
+    socket.on(BINARY_EVENT, onData);
+    socket.on("disconnect", onDisconnect);
     return {
         on(event, handler) {
             if (event === "data") {
@@ -59,6 +71,8 @@ function wrapSocketIOAsBinaryPeer(socket) {
             }
         },
         send(data) {
+            if (closed)
+                return;
             const bytes = typeof data === "string"
                 ? Buffer.from(data)
                 : data instanceof Uint8Array
@@ -79,7 +93,9 @@ function wrapSocketIOAsBinaryPeer(socket) {
             });
         },
         destroy() {
-            socket.removeAllListeners(BINARY_EVENT);
+            if (closed)
+                return;
+            onDisconnect();
             socket.disconnect();
         },
         getBufferedAmount() {

package/dist/rpc-types.d.ts

@@ -29,28 +29,6 @@ export interface IRemoteLogsQueryInput {
 export declare const rpcServerCalls: {
     encryptData: (value: string, groupId?: string) => Promise<string>;
     tableMethodCall: (dataContextId: string, tableName: string, methodName: string, ...args: any[]) => Promise<any>;
-    /**
-     * @deprecated Use System Files (`SystemFiles`, `readWholeFile`). Kept only for Family Hub
-     * 0.3.x; deleted once its port is Home's version.
-     */
-    getFileContentsBase64: (fileId: string) => Promise<string>;
-    /**
-     * @deprecated Use System Files (`SystemFiles`). Kept only for Family Hub 0.3.x; deleted once
-     * its port is Home's version.
-     */
-    saveFile: (input: {
-        name: string;
-        mimeType?: string;
-        data: string;
-        encoding?: "utf8" | "base64";
-        fileId?: string;
-    }) => Promise<{
-        fileId: string;
-        name: string;
-        fileSize: number;
-        fileHash: string;
-        mimeType?: string;
-    }>;
     deleteLocalDatabase: () => Promise<void>;
     /** Returns info about the pre-migration data directory, or `null` if already cleaned up. */
     getOldDataDirInfo: () => Promise<{

package/dist/rpc-types.js

@@ -14,16 +14,6 @@ function rpcStub(rpcName) {
 exports.rpcServerCalls = {
     encryptData: rpcStub("encryptData"),
     tableMethodCall: rpcStub("tableMethodCall"),
-    /**
-     * @deprecated Use System Files (`SystemFiles`, `readWholeFile`). Kept only for Family Hub
-     * 0.3.x; deleted once its port is Home's version.
-     */
-    getFileContentsBase64: rpcStub("getFileContentsBase64"),
-    /**
-     * @deprecated Use System Files (`SystemFiles`). Kept only for Family Hub 0.3.x; deleted once
-     * its port is Home's version.
-     */
-    saveFile: rpcStub("saveFile"),
     deleteLocalDatabase: rpcStub("deleteLocalDatabase"),
     /** Returns info about the pre-migration data directory, or `null` if already cleaned up. */
     getOldDataDirInfo: rpcStub("getOldDataDirInfo"),

package/dist/types/peer-device.d.ts

@@ -26,7 +26,11 @@ export interface IDeviceMessage<T = any> {
     deviceMessageId: string;
     /** Device that originated the message. */
     fromDeviceId: string;
-    /** Signed source identity used to bootstrap fresh same-user devices. */
+    /**
+     * Signed source identity. Lets a receiver accept a device it hasn't met yet when the device
+     * belongs to the receiver's own user (personal context) or to a counted member of the
+     * message's group.
+     */
     fromDeviceInfo?: ISignedObject<IDeviceInfo>;
     /** Intended destination device. */
     toDeviceId: string;

package/package.json

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