@peers-app/peers-sdk 0.25.8 → 0.25.10

package/dist/data/local-folders.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localFolderBlocksMetaData = exports.localFolderFilesMetaData = exports.localFolderGrantsMetaData = exports.localFolderBlockRowSchema = exports.localFolderFileSchema = exports.localFolderGrantSchema = exports.localFolderGrantModeSchema = exports.localFolderBlockSchema = void 0;
+exports.LocalFolderGrants = LocalFolderGrants;
+exports.LocalFolderFiles = LocalFolderFiles;
+exports.LocalFolderBlocks = LocalFolderBlocks;
+const zod_1 = require("zod");
+const user_context_singleton_1 = require("../context/user-context-singleton");
+const zod_types_1 = require("../types/zod-types");
+const table_definitions_system_1 = require("./orm/table-definitions.system");
+const types_1 = require("./orm/types");
+/** Content-defined block descriptor stored on an indexed file. */
+exports.localFolderBlockSchema = zod_1.z.object({
+    hash: zod_1.z.string().describe("SHA-256 hex digest of the block bytes."),
+    size: zod_1.z.number().describe("Block length in bytes."),
+});
+/** Access mode recorded on a folder grant. */
+exports.localFolderGrantModeSchema = zod_1.z.enum(["read", "readwrite"]);
+/**
+ * Operator grant of one absolute folder to an optional package.
+ * Stored only on this device, in the personal database.
+ */
+exports.localFolderGrantSchema = zod_1.z.object({
+    grantId: zod_types_1.zodPeerId.describe("Grant id."),
+    packageId: zod_types_1.zodPeerId
+        .optional()
+        .describe("Isolated package allowed to use this grant. Absent for operator-owned grants."),
+    groupId: zod_types_1.zodPeerId.describe("Group the folder is associated with."),
+    absolutePath: zod_1.z.string().describe("Absolute filesystem path of the granted root."),
+    mode: exports.localFolderGrantModeSchema.describe("Whether the grant allows writes."),
+    createdAt: zod_1.z.number().describe("Unix epoch milliseconds when the grant was created."),
+    revokedAt: zod_1.z
+        .number()
+        .optional()
+        .describe("Unix epoch milliseconds when the grant was revoked. Absent while active."),
+});
+/** Indexed file under a grant. One row per `(grantId, relPath)`. */
+exports.localFolderFileSchema = zod_1.z.object({
+    fileIndexId: zod_types_1.zodPeerId.describe("Index row id."),
+    grantId: zod_types_1.zodPeerId.describe("Grant this file belongs to."),
+    relPath: zod_1.z.string().describe("Path relative to the grant root, `/`-separated, NFC."),
+    size: zod_1.z.number().describe("File size in bytes at index time."),
+    mtimeMs: zod_1.z.number().describe("File mtime in milliseconds at index time."),
+    inode: zod_1.z.string().describe("File identity string (`stat.ino`) at index time."),
+    blocks: zod_1.z.array(exports.localFolderBlockSchema).describe("Ordered content-defined blocks."),
+});
+/**
+ * One servable block location. The same hash may appear in several files;
+ * `blockHash` is indexed, not unique.
+ */
+exports.localFolderBlockRowSchema = zod_1.z.object({
+    blockRowId: zod_types_1.zodPeerId.describe("Block-location row id."),
+    blockHash: zod_1.z.string().describe("SHA-256 hex digest of the block bytes."),
+    grantId: zod_types_1.zodPeerId.describe("Grant whose file contains the block."),
+    relPath: zod_1.z.string().describe("File path relative to the grant root."),
+    offset: zod_1.z.number().describe("Byte offset of the block within the file."),
+    length: zod_1.z.number().describe("Block length in bytes."),
+    mtimeMs: zod_1.z.number().describe("File mtime in milliseconds when the block was indexed."),
+});
+const grantMetaData = {
+    name: "LocalFolderGrants",
+    description: "Device-local scoped folder grants for System Local Folders.",
+    primaryKeyName: "grantId",
+    fields: (0, types_1.schemaToFields)(exports.localFolderGrantSchema),
+    localOnly: true,
+    indexes: [{ fields: ["packageId"] }, { fields: ["groupId"] }],
+};
+const fileMetaData = {
+    name: "LocalFolderFiles",
+    description: "Device-local file index for System Local Folders.",
+    primaryKeyName: "fileIndexId",
+    fields: (0, types_1.schemaToFields)(exports.localFolderFileSchema),
+    localOnly: true,
+    indexes: [{ fields: ["grantId", "relPath"], unique: true }, { fields: ["grantId"] }],
+};
+const blockMetaData = {
+    name: "LocalFolderBlocks",
+    description: "Device-local block locations for System Local Folders.",
+    primaryKeyName: "blockRowId",
+    fields: (0, types_1.schemaToFields)(exports.localFolderBlockRowSchema),
+    localOnly: true,
+    indexes: [{ fields: ["blockHash"] }, { fields: ["grantId", "relPath"] }],
+};
+(0, table_definitions_system_1.registerSystemTableDefinition)(grantMetaData, exports.localFolderGrantSchema);
+(0, table_definitions_system_1.registerSystemTableDefinition)(fileMetaData, exports.localFolderFileSchema);
+(0, table_definitions_system_1.registerSystemTableDefinition)(blockMetaData, exports.localFolderBlockRowSchema);
+/** Table metadata for {@link LocalFolderGrants}. */
+exports.localFolderGrantsMetaData = grantMetaData;
+/** Table metadata for {@link LocalFolderFiles}. */
+exports.localFolderFilesMetaData = fileMetaData;
+/** Table metadata for {@link LocalFolderBlocks}. */
+exports.localFolderBlocksMetaData = blockMetaData;
+/**
+ * Device-local folder grants. Pass the personal data context; these rows do not sync.
+ *
+ * @param dataContext Context whose database holds the grants. Defaults to the current context.
+ */
+function LocalFolderGrants(dataContext) {
+    return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(grantMetaData, exports.localFolderGrantSchema);
+}
+/**
+ * Device-local indexed files. Pass the personal data context; these rows do not sync.
+ *
+ * @param dataContext Context whose database holds the index. Defaults to the current context.
+ */
+function LocalFolderFiles(dataContext) {
+    return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(fileMetaData, exports.localFolderFileSchema);
+}
+/**
+ * Device-local block locations. Pass the personal data context; these rows do not sync.
+ *
+ * @param dataContext Context whose database holds the index. Defaults to the current context.
+ */
+function LocalFolderBlocks(dataContext) {
+    return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(blockMetaData, exports.localFolderBlockRowSchema);
+}

package/dist/data/orm/sql-db.d.ts

@@ -5,7 +5,9 @@ export interface ISqlDb {
         changes: number;
     }>;
     close: () => Promise<void>;
-    execSync?: (sql: string, params?: any) => void;
+    execSync?: (sql: string, params?: any) => {
+        changes: number;
+    };
     getSync?: (sql: string, params?: any) => any;
     allSync?: (sql: string, params?: any) => any[];
     /**

package/dist/data/orm/table.d.ts

@@ -4,6 +4,13 @@ import { type DataFilter, type ICursorIterable, type IDataQueryParams, type IDat
 import { type IDataChangedEvent } from "./subscribable.data-source";
 import type { ITableDependencies } from "./table-dependencies";
 import { type ITableMetaData } from "./types";
+/**
+ * ORM table over a data source, including change notifications and validation.
+ *
+ * Subclasses override {@link Table.resolveUniqueConflict} when a unique index can be
+ * settled from the two competing records alone. The base implementation declines so
+ * sync leaves the conflict queued instead of deleting either row.
+ */
 export declare class Table<T extends {
     [key: string]: any;
 }> implements IDataSource<T> {
@@ -37,7 +44,19 @@ export declare class Table<T extends {
     update(record: T): Promise<T>;
     delete(idOrRecord: string | T): Promise<void>;
     initRecord(data?: Partial<T>): T;
+    /**
+     * Choose which record should own a contested unique key.
+     *
+     * Return undefined to leave the conflict queued for an operator. Overrides must be a
+     * pure function of the two records so every device computes the same winner.
+     * `loserId` is the primary key of the record that should be tombstoned.
+     */
+    resolveUniqueConflict(_incoming: T, _existing: T): {
+        winner: T;
+        loserId: string;
+    } | undefined;
     initDoc(record: T): import("./doc").IDoc<T>;
     getDoc(id: string): import("./doc").IDoc<T>;
 }
+/** Bootstrap icon class for a table, falling back to a question mark. */
 export declare function getIconClassName(table: Table<any>): string;

package/dist/data/orm/table.js

@@ -13,6 +13,13 @@ const doc_1 = require("./doc");
 const sql_data_source_1 = require("./sql.data-source");
 const subscribable_data_source_1 = require("./subscribable.data-source");
 const types_1 = require("./types");
+/**
+ * ORM table over a data source, including change notifications and validation.
+ *
+ * Subclasses override {@link Table.resolveUniqueConflict} when a unique index can be
+ * settled from the two competing records alone. The base implementation declines so
+ * sync leaves the conflict queued instead of deleting either row.
+ */
 class Table {
     tableName;
     primaryKeyName;
@@ -241,6 +248,16 @@ class Table {
         }
         return { ...defaults, ...data };
     }
+    /**
+     * Choose which record should own a contested unique key.
+     *
+     * Return undefined to leave the conflict queued for an operator. Overrides must be a
+     * pure function of the two records so every device computes the same winner.
+     * `loserId` is the primary key of the record that should be tombstoned.
+     */
+    resolveUniqueConflict(_incoming, _existing) {
+        return undefined;
+    }
     initDoc(record) {
         return (0, doc_1.initDoc)(record, this);
     }
@@ -252,6 +269,7 @@ class Table {
     }
 }
 exports.Table = Table;
+/** Bootstrap icon class for a table, falling back to a question mark. */
 function getIconClassName(table) {
     return table.metaData.iconClassName ?? "bi bi-question";
 }

package/dist/data/persistent-vars.conflict.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/data/persistent-vars.conflict.test.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const originalClientFlag = process.env.PEERS_IS_CLIENT;
+function createEventRegistry() {
+    return {
+        getEmitter: jest.fn().mockReturnValue({
+            event: { subscribe: jest.fn() },
+            emit: jest.fn(),
+        }),
+    };
+}
+function pvar(overrides) {
+    return {
+        name: "shared-name",
+        scope: "user",
+        value: { value: overrides.persistentVarId },
+        ...overrides,
+    };
+}
+afterEach(() => {
+    if (originalClientFlag === undefined) {
+        delete process.env.PEERS_IS_CLIENT;
+    }
+    else {
+        process.env.PEERS_IS_CLIENT = originalClientFlag;
+    }
+    jest.resetModules();
+});
+describe("PersistentVars unique-name conflict", () => {
+    async function table() {
+        delete process.env.PEERS_IS_CLIENT;
+        jest.resetModules();
+        let loaded;
+        await jest.isolateModulesAsync(async () => {
+            jest.doMock("../context/user-context-singleton", () => ({
+                getTableContainer: jest.fn(),
+                getUserContext: jest.fn(),
+            }));
+            const { PersistentVarsTable, persistentVarsMetaData } = await Promise.resolve().then(() => require("./persistent-vars"));
+            const { deterministicPvarId } = await Promise.resolve().then(() => require("../utils"));
+            loaded = {
+                deterministicPvarId,
+                vars: new PersistentVarsTable(persistentVarsMetaData, {
+                    dataSource: {},
+                    eventRegistry: createEventRegistry(),
+                }),
+            };
+        });
+        if (!loaded) {
+            throw new Error("PersistentVarsTable failed to load");
+        }
+        return loaded;
+    }
+    it("keeps the deterministic id and the newer value regardless of argument order", async () => {
+        const { deterministicPvarId, vars } = await table();
+        const legacy = pvar({
+            persistentVarId: "00mriijkhq94msfe9m2j6quwp",
+            value: { value: "from-legacy" },
+            modifiedAt: 20,
+            scope: "groupUser",
+            isSecret: true,
+        });
+        const deterministic = pvar({
+            persistentVarId: deterministicPvarId(legacy.name),
+            value: { value: "from-deterministic" },
+            modifiedAt: 10,
+        });
+        const forward = vars.resolveUniqueConflict(legacy, deterministic);
+        const reverse = vars.resolveUniqueConflict(deterministic, legacy);
+        expect(forward).toEqual(reverse);
+        expect(forward).toEqual({
+            loserId: legacy.persistentVarId,
+            winner: expect.objectContaining({
+                persistentVarId: deterministic.persistentVarId,
+                name: legacy.name,
+                scope: "groupUser",
+                isSecret: true,
+                value: { value: "from-legacy" },
+                modifiedAt: 20,
+            }),
+        });
+    });
+    it("keeps the identity winner's value when modifiedAt ties", async () => {
+        const { deterministicPvarId, vars } = await table();
+        const legacy = pvar({
+            persistentVarId: "00mriijkhq94msfe9m2j6quwp",
+            value: { value: "legacy-value" },
+            modifiedAt: 5,
+        });
+        const deterministic = pvar({
+            persistentVarId: deterministicPvarId(legacy.name),
+            value: { value: "deterministic-value" },
+            modifiedAt: 5,
+        });
+        expect(vars.resolveUniqueConflict(legacy, deterministic)?.winner.value).toEqual({
+            value: "deterministic-value",
+        });
+    });
+    it("uses the smaller id when neither record is deterministic", async () => {
+        const { vars } = await table();
+        const larger = pvar({
+            persistentVarId: "00mriijkhq94msfe9m2j6quwz",
+            value: { value: "larger-newer" },
+            modifiedAt: 9,
+        });
+        const smaller = pvar({
+            persistentVarId: "00mriijkhq94msfe9m2j6quwa",
+            value: { value: "smaller-older" },
+            modifiedAt: 1,
+        });
+        expect(vars.resolveUniqueConflict(larger, smaller)).toEqual({
+            loserId: larger.persistentVarId,
+            winner: expect.objectContaining({
+                persistentVarId: smaller.persistentVarId,
+                value: { value: "larger-newer" },
+                modifiedAt: 9,
+            }),
+        });
+    });
+    it("declines when the records are not two ids for one name", async () => {
+        const { vars } = await table();
+        const row = pvar({ persistentVarId: "00mriijkhq94msfe9m2j6quwp" });
+        expect(vars.resolveUniqueConflict(row, row)).toBeUndefined();
+        expect(vars.resolveUniqueConflict(row, pvar({ persistentVarId: "00mriijkhq94msfe9m2j6quwq", name: "other" }))).toBeUndefined();
+    });
+});

package/dist/data/persistent-vars.d.ts

@@ -70,6 +70,19 @@ export declare class PersistentVarsTable extends Table<IPersistentVar> {
      * deterministic record already exists, it wins and the duplicate legacy row is removed.
      */
     migrateLegacyId(persistentVar: IPersistentVar): Promise<IPersistentVar>;
+    /**
+     * Settle two rows that share a `name`.
+     *
+     * The deterministic id owns the name when either row has one; otherwise the
+     * lexicographically smaller id does. The value, scope, and secret flag come from
+     * the row with the greater `modifiedAt` (missing counts as 0). A tie keeps the
+     * identity winner's value. Both devices see the same two change records, so they
+     * pick the same winner and the loser can be tombstoned.
+     */
+    resolveUniqueConflict(incoming: IPersistentVar, existing: IPersistentVar): {
+        winner: IPersistentVar;
+        loserId: string;
+    } | undefined;
     /** Return a stored variable's raw value by name. */
     getPersistentVarValue<T>(name: string): Promise<T | undefined>;
 }

package/dist/data/persistent-vars.js

@@ -91,6 +91,20 @@ exports.persistentVarsMetaData = {
     iconClassName: "bi bi-braces",
     indexes: [{ fields: ["name"], unique: true }],
 };
+/**
+ * Pick the record id that should own a duplicated persistent-variable name.
+ *
+ * A deterministic id beats a legacy random id. When neither (or both) is
+ * deterministic, the lexicographically smaller id wins.
+ */
+function persistentVarIdentityWinner(left, right) {
+    const leftDeterministic = (0, utils_1.isDeterministicPvarId)(left.persistentVarId);
+    const rightDeterministic = (0, utils_1.isDeterministicPvarId)(right.persistentVarId);
+    if (leftDeterministic !== rightDeterministic) {
+        return leftDeterministic ? left : right;
+    }
+    return left.persistentVarId < right.persistentVarId ? left : right;
+}
 /** Persistent-variable table with deterministic IDs and secret-value handling. */
 let PersistentVarsTable = (() => {
     let _classSuper = table_1.Table;
@@ -156,6 +170,45 @@ let PersistentVarsTable = (() => {
                 throw error;
             }
         }
+        /**
+         * Settle two rows that share a `name`.
+         *
+         * The deterministic id owns the name when either row has one; otherwise the
+         * lexicographically smaller id does. The value, scope, and secret flag come from
+         * the row with the greater `modifiedAt` (missing counts as 0). A tie keeps the
+         * identity winner's value. Both devices see the same two change records, so they
+         * pick the same winner and the loser can be tombstoned.
+         */
+        resolveUniqueConflict(incoming, existing) {
+            if (incoming.name !== existing.name) {
+                return undefined;
+            }
+            if (incoming.persistentVarId === existing.persistentVarId) {
+                return undefined;
+            }
+            const identity = persistentVarIdentityWinner(incoming, existing);
+            const other = identity === incoming ? existing : incoming;
+            const identityModified = identity.modifiedAt ?? 0;
+            const otherModified = other.modifiedAt ?? 0;
+            const valueSource = otherModified > identityModified ? other : identity;
+            const winner = {
+                persistentVarId: identity.persistentVarId,
+                name: identity.name,
+                scope: valueSource.scope,
+                value: valueSource.value,
+                modifiedAt: Math.max(identityModified, otherModified) || undefined,
+            };
+            if (valueSource.description !== undefined) {
+                winner.description = valueSource.description;
+            }
+            if (valueSource.userCreated !== undefined) {
+                winner.userCreated = valueSource.userCreated;
+            }
+            if (valueSource.isSecret !== undefined) {
+                winner.isSecret = valueSource.isSecret;
+            }
+            return { winner, loserId: other.persistentVarId };
+        }
         /** Return a stored variable's raw value by name. */
         async getPersistentVarValue(name) {
             const pVars = await this.list({ name });

package/dist/data/sync-recovery-queue.d.ts

@@ -5,6 +5,14 @@
  */
 import { z } from "zod";
 import { type ISqlDb, type ITableMetaData, SQLDataSource } from "./orm";
+/** How many attempts mark a still-retrying entry as stuck. */
+export declare const SYNC_RECOVERY_STUCK_ATTEMPTS = 5;
+/** How long a still-retrying entry must have been failing before it is stuck. */
+export declare const SYNC_RECOVERY_STUCK_AGE_MS: number;
+/** Why automatic recovery stopped asking peers for an entry. */
+export declare const syncRecoveryParkedReasons: readonly ["schema", "unique-conflict", "unresolvable"];
+/** Why automatic recovery stopped asking peers for an entry. */
+export type SyncRecoveryParkedReason = (typeof syncRecoveryParkedReasons)[number];
 /** One recorded materialization failure for a synchronized record. */
 export declare const syncRecoveryFailureSchema: z.ZodObject<{
     error: z.ZodString;
@@ -40,6 +48,16 @@ export declare const syncRecoveryEntrySchema: z.ZodObject<{
         erroredAt: number;
         sourceDeviceId?: string | undefined;
     }>, "many">;
+    /** Set when peer retry has stopped. Absent while the entry is still retrying. */
+    parkedAt: z.ZodOptional<z.ZodNumber>;
+    parkedReason: z.ZodOptional<z.ZodEnum<["schema", "unique-conflict", "unresolvable"]>>;
+    /** Earliest time a retrying entry should ask peers again. */
+    nextAttemptAt: z.ZodOptional<z.ZodNumber>;
+    /**
+     * How many due peer sweeps have failed to clear this entry.
+     * Local only. Backoff uses this instead of the materialization attempt count.
+     */
+    sweepCount: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     tableName: string;
     recordId: string;
@@ -52,6 +70,10 @@ export declare const syncRecoveryEntrySchema: z.ZodObject<{
         erroredAt: number;
         sourceDeviceId?: string | undefined;
     }[];
+    parkedAt?: number | undefined;
+    parkedReason?: "schema" | "unique-conflict" | "unresolvable" | undefined;
+    nextAttemptAt?: number | undefined;
+    sweepCount?: number | undefined;
 }, {
     tableName: string;
     recordId: string;
@@ -64,11 +86,29 @@ export declare const syncRecoveryEntrySchema: z.ZodObject<{
         erroredAt: number;
         sourceDeviceId?: string | undefined;
     }[];
+    parkedAt?: number | undefined;
+    parkedReason?: "schema" | "unique-conflict" | "unresolvable" | undefined;
+    nextAttemptAt?: number | undefined;
+    sweepCount?: number | undefined;
 }>;
 /** One recorded materialization failure for a synchronized record. */
 export type ISyncRecoveryFailure = z.infer<typeof syncRecoveryFailureSchema>;
 /** Durable local recovery state for one synchronized record. */
 export type ISyncRecoveryEntry = z.infer<typeof syncRecoveryEntrySchema>;
+/**
+ * True when an operator should look at this entry.
+ *
+ * Parked entries are stuck immediately. Retrying entries are stuck after
+ * {@link SYNC_RECOVERY_STUCK_ATTEMPTS} attempts spanning {@link SYNC_RECOVERY_STUCK_AGE_MS}.
+ */
+export declare function isStuckSyncRecoveryEntry(entry: Pick<ISyncRecoveryEntry, "parkedAt" | "attemptCount" | "firstFailedAt">, now?: number): boolean;
+/**
+ * When the earliest not-yet-stuck entry will cross the stuck age, if any will.
+ *
+ * Parked entries are already stuck. Entries below {@link SYNC_RECOVERY_STUCK_ATTEMPTS}
+ * do not become stuck by time alone.
+ */
+export declare function nextStuckSyncRecoveryAt(entries: Array<Pick<ISyncRecoveryEntry, "parkedAt" | "attemptCount" | "firstFailedAt">>, now?: number): number | undefined;
 /** Input used to append a materialization failure to the recovery queue. */
 export interface IRecordSyncFailure {
     tableName: string;
@@ -106,7 +146,44 @@ export declare class SyncRecoveryQueueTable extends SQLDataSource<ISyncRecoveryE
      * The queue table must be initialized before this method is called.
      */
     clearRecordSync(tableName: string, recordId: string): void;
+    /**
+     * Delete one queue row only when its attempt count still matches.
+     *
+     * A failure recorded after the caller chose this generation changes
+     * `attemptCount`, so the delete matches nothing and throws. Call this inside
+     * the same transaction as the table write so that throw rolls the write back.
+     */
+    clearGenerationSync(syncRecoveryId: string, attemptCount: number): void;
     private mergeFailure;
+    /**
+     * Stop peer retry for an entry without removing it.
+     *
+     * Writes only the park columns. A failure recorded in the same window keeps
+     * its attempt count and history. Parking the same reason again keeps the
+     * original `parkedAt`.
+     */
+    park(tableName: string, recordId: string, reason: SyncRecoveryParkedReason): Promise<void>;
+    /**
+     * Return an entry to peer retry.
+     *
+     * Clears only the park marker and any scheduled next attempt.
+     */
+    unpark(tableName: string, recordId: string): Promise<void>;
+    /**
+     * Schedule the next peer retry for an entry that is still queued.
+     *
+     * Writes only `nextAttemptAt`.
+     */
+    setNextAttempt(tableName: string, recordId: string, nextAttemptAt: number): Promise<void>;
+    /**
+     * Count one due peer sweep that did not clear the entry.
+     *
+     * Writes only `sweepCount` and returns the new value. Returns undefined when
+     * the row was removed before the update.
+     */
+    noteUnresolvedSweep(tableName: string, recordId: string): Promise<number | undefined>;
+    /** Apply a column-level update without rewriting the rest of the queue row. */
+    private patchEntry;
 }
 /** Return the single SyncRecoveryQueue table associated with a database instance. */
 export declare function syncRecoveryQueueTable(db: ISqlDb): SyncRecoveryQueueTable;