@decentnetwork/peer 0.1.111 → 0.1.112

package/dist/index.d.ts

@@ -10,4 +10,4 @@ export { LegacyProtocolNotImplementedError } from "./runtime/errors.js";
 export type { CarrierPacket, FriendMessagePacket, FriendRequestPacket, InviteReqPacket, InviteRspPacket } from "./compat/packet.js";
 export type { ToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 export type { CarrierAddressParts } from "./compat/address.js";
-export type { CompatibilityMode, CustomPacketEvent, FriendConnectionEvent, FriendConnectionStatus, FriendInfoEvent, FriendRequest, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";
+export type { CompatibilityMode, CustomPacketEvent, FriendConnectionEvent, FriendConnectionStatus, FriendInfoEvent, FriendRequest, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, SendTextUntilAckOptions, TextMessage } from "./types/peer.js";

package/dist/peer.d.ts

@@ -1,6 +1,6 @@
 import { type BootstrapResult } from "./compat/bootstrap.js";
 import type { FriendRecord } from "./store/friends.js";
-import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";
+import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, SendTextUntilAckOptions, TextMessage } from "./types/peer.js";
 export declare class Peer {
     #private;
     private constructor();
@@ -84,9 +84,21 @@ export declare class Peer {
      */
     removeFriend(pubkey: string): boolean;
     sendText(pubkey: string, text: string): Promise<void>;
+    /**
+     * Send text and keep retransmitting until the peer explicitly ACKs it.
+     *
+     * The receiving peer sends that ACK only after every onText handler returns
+     * successfully. If a handler persists to an inbox, return its write Promise
+     * from the handler; then this method resolves only after that durable write
+     * completed on the far side. Pass a stable deliveryId when retrying an item
+     * from an application outbox across process restarts.
+     */
+    sendTextUntilAck(pubkey: string, text: string, opts?: SendTextUntilAckOptions): Promise<{
+        deliveryId: string;
+    }>;
     waitForFriendConnected(pubkey: string, timeoutMs?: number): Promise<boolean>;
     onFriendRequest(cb: (req: FriendRequest) => void): void;
-    onText(cb: (msg: TextMessage) => void): void;
+    onText(cb: (msg: TextMessage) => unknown | Promise<unknown>): void;
     /** Files received inline over (bulk)messages — the iOS/C Carrier apps'
      *  native way of sending images/audio online (FileModel JSON envelope). */
     onInlineFile(cb: (evt: InlineFileEvent) => void): void;

package/dist/peer.js

@@ -168,15 +168,18 @@ const PEER_NICKNAME = process.env.DECENT_PEER_NAME ?? "@decentnetwork/peer";
 const PEER_STATUS_MESSAGE = process.env.DECENT_PEER_STATUS_MESSAGE ?? "decent peer";
 const GREETING_TEXT = process.env.DECENT_GREETING_TEXT ?? "";
 // AgentNet wire-protocol version advertised in the userinfo profile (field 7).
-// Bump when the wire capabilities change so peers can negotiate. v1 marks a peer
-// that carries this field AND supports the toxcore file-transfer channel
-// (PACKET_ID_FILE 80-82) for large files — a sender can prefer that over inline
-// bulkmsg (capped at CARRIER_MAX_APP_BULKMSG_LEN) when the peer's protoVersion>=1.
-const AGENTNET_PROTO_VERSION = 1;
+// v1 marks a peer that supports the toxcore file-transfer channel. v2 adds
+// application-level text delivery ACKs: senders keep outbox entries until the
+// receiver's onText handler has returned successfully.
+const AGENTNET_PROTO_VERSION = 2;
 // Peer package version, advertised as the default appVersion when the embedder
 // doesn't override it. Read lazily so a bundler that inlines this file doesn't
 // need the package.json at runtime.
-const PEER_PKG_VERSION = "0.1.91";
+const PEER_PKG_VERSION = "0.1.112";
+const TEXT_ACK_PREFIX = "\x1eDNPACK1:";
+const TEXT_ACK_TIMEOUT_MS = readEnvInt("DECENT_TEXT_ACK_TIMEOUT_MS", 300_000);
+const TEXT_ACK_RETRY_MS = readEnvInt("DECENT_TEXT_ACK_RETRY_MS", 5_000);
+const TEXT_AUTO_ACK_TIMEOUT_MS = readEnvInt("DECENT_TEXT_AUTO_ACK_TIMEOUT_MS", 15_000);
 // Toxcore Messenger.h packet IDs (live inside encrypted 0x1b crypto data plain payload)
 const PACKET_ID_PADDING = 0;
 const PACKET_ID_REQUEST = 1; // request retransmission of unreceived packets
@@ -273,6 +276,10 @@ export class Peer {
     #nodeBlacklist = new Map();
     #pendingFriendRequests = new Map();
     #friends = new Map();
+    #textHandlers = new Set();
+    #pendingTextAcks = new Map();
+    #deliveredTextIds = new Set();
+    #deliveredTextOrder = [];
     #friendStoreFile;
     #persistSeq = 0; // makes atomic friend-store temp filenames unique per write
     #cookieSymmetricKey;
@@ -1059,6 +1066,16 @@ export class Peer {
         }
     }
     async sendText(pubkey, text) {
+        if (text.length > 0 && !text.startsWith(TEXT_ACK_PREFIX) && this.#shouldRequireTextAck(pubkey)) {
+            await this.sendTextUntilAck(pubkey, text, {
+                timeoutMs: TEXT_AUTO_ACK_TIMEOUT_MS,
+                retryIntervalMs: Math.min(TEXT_ACK_RETRY_MS, TEXT_AUTO_ACK_TIMEOUT_MS)
+            });
+            return;
+        }
+        await this.#sendTextPlain(pubkey, text);
+    }
+    async #sendTextPlain(pubkey, text) {
         const friend = this.#friends.get(pubkey);
         if (!friend) {
             throw new Error(`Not a friend: ${pubkey}`);
@@ -1175,6 +1192,75 @@ export class Peer {
         }
         throw new Error("friend is offline and no express node is configured");
     }
+    #shouldRequireTextAck(pubkey) {
+        const friend = this.#friends.get(pubkey);
+        if ((friend?.protoVersion ?? 0) >= 2)
+            return true;
+        // decentlan data-plane peers run with expressControlPlaneOnly so an
+        // accepted local send must not be treated as final delivery. A short ACK
+        // timeout makes the caller keep its outbox item and retry on reconnect.
+        return this.#opts.expressControlPlaneOnly === true;
+    }
+    /**
+     * Send text and keep retransmitting until the peer explicitly ACKs it.
+     *
+     * The receiving peer sends that ACK only after every onText handler returns
+     * successfully. If a handler persists to an inbox, return its write Promise
+     * from the handler; then this method resolves only after that durable write
+     * completed on the far side. Pass a stable deliveryId when retrying an item
+     * from an application outbox across process restarts.
+     */
+    async sendTextUntilAck(pubkey, text, opts = {}) {
+        const deliveryId = opts.deliveryId ?? createTextDeliveryId();
+        const retryIntervalMs = Math.max(250, opts.retryIntervalMs ?? TEXT_ACK_RETRY_MS);
+        const timeoutMs = Math.max(retryIntervalMs, opts.timeoutMs ?? TEXT_ACK_TIMEOUT_MS);
+        const envelope = encodeTextAckEnvelope({ t: "msg", id: deliveryId, text });
+        const started = Date.now();
+        let lastError;
+        while (Date.now() - started < timeoutMs) {
+            const remaining = Math.max(1, timeoutMs - (Date.now() - started));
+            const waitMs = Math.min(retryIntervalMs, remaining);
+            const ackPromise = this.#waitForTextAck(deliveryId, waitMs);
+            try {
+                await this.#sendTextPlain(pubkey, envelope);
+            }
+            catch (error) {
+                this.#cancelTextAckWait(deliveryId);
+                lastError = error;
+                await sleep(waitMs);
+                continue;
+            }
+            if (await ackPromise) {
+                return { deliveryId };
+            }
+        }
+        this.#cancelTextAckWait(deliveryId);
+        throw lastError ?? new Error(`text delivery ACK timed out for ${pubkey}`);
+    }
+    #waitForTextAck(deliveryId, timeoutMs) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.#pendingTextAcks.delete(deliveryId);
+                resolve(false);
+            }, timeoutMs);
+            timer.unref?.();
+            this.#pendingTextAcks.set(deliveryId, {
+                resolve: () => {
+                    clearTimeout(timer);
+                    this.#pendingTextAcks.delete(deliveryId);
+                    resolve(true);
+                },
+                reject: () => {
+                    clearTimeout(timer);
+                    this.#pendingTextAcks.delete(deliveryId);
+                    resolve(false);
+                }
+            });
+        });
+    }
+    #cancelTextAckWait(deliveryId) {
+        this.#pendingTextAcks.get(deliveryId)?.reject(new Error("text delivery ACK wait cancelled"));
+    }
     waitForFriendConnected(pubkey, timeoutMs = 30000) {
         return this.#waitForFriendConnected(pubkey, timeoutMs);
     }
@@ -1202,7 +1288,65 @@ export class Peer {
         this.#events.on("friendRequest", cb);
     }
     onText(cb) {
-        this.#events.on("text", cb);
+        this.#textHandlers.add(cb);
+    }
+    async #dispatchTextMessage(msg) {
+        const envelope = decodeTextAckEnvelope(msg.text);
+        if (envelope?.t === "ack") {
+            this.#pendingTextAcks.get(envelope.id)?.resolve();
+            return;
+        }
+        let deliveryId;
+        let text = msg.text;
+        if (envelope?.t === "msg") {
+            deliveryId = envelope.id;
+            text = envelope.text;
+            if (this.#deliveredTextIds.has(deliveryId)) {
+                await this.#sendTextAck(msg.pubkey, deliveryId);
+                return;
+            }
+        }
+        if (this.#textHandlers.size === 0) {
+            if (deliveryId)
+                this.#debugLog(`text delivery ${deliveryId} from ${msg.pubkey} has no onText handlers; not ACKing`);
+            return;
+        }
+        const ack = deliveryId
+            ? async () => { await this.#sendTextAck(msg.pubkey, deliveryId); }
+            : undefined;
+        const delivered = { ...msg, text, deliveryId, ack };
+        try {
+            for (const handler of this.#textHandlers) {
+                await handler(delivered);
+            }
+        }
+        catch (error) {
+            this.#debugLog(`text handler failed for ${msg.pubkey}: ${error.message}`);
+            return;
+        }
+        if (deliveryId) {
+            this.#rememberDeliveredTextId(deliveryId);
+            await ack?.();
+        }
+    }
+    async #sendTextAck(pubkey, deliveryId) {
+        try {
+            await this.sendText(pubkey, encodeTextAckEnvelope({ t: "ack", id: deliveryId }));
+        }
+        catch (error) {
+            this.#debugLog(`text ACK send failed for ${pubkey}: ${error.message}`);
+        }
+    }
+    #rememberDeliveredTextId(deliveryId) {
+        if (this.#deliveredTextIds.has(deliveryId))
+            return;
+        this.#deliveredTextIds.add(deliveryId);
+        this.#deliveredTextOrder.push(deliveryId);
+        while (this.#deliveredTextOrder.length > 4096) {
+            const old = this.#deliveredTextOrder.shift();
+            if (old)
+                this.#deliveredTextIds.delete(old);
+        }
     }
     /** Files received inline over (bulk)messages — the iOS/C Carrier apps'
      *  native way of sending images/audio online (FileModel JSON envelope). */
@@ -2620,7 +2764,7 @@ export class Peer {
             // (iOS posts the whole thing as one express MESSAGE packet).
             if (this.#tryEmitInlineFile(fromUserId, text, "offline"))
                 return;
-            this.#events.emit("text", { pubkey: fromUserId, text, via: "offline" });
+            void this.#dispatchTextMessage({ pubkey: fromUserId, text, via: "offline" });
         }
         catch {
             // Ignore invalid offline payloads.
@@ -3607,7 +3751,7 @@ export class Peer {
             // as files, not as a wall of base64 text.
             if (this.#tryEmitInlineFile(friendId, text, "online"))
                 return;
-            this.#events.emit("text", {
+            void this.#dispatchTextMessage({
                 pubkey: friendId,
                 text,
                 via: "online"
@@ -6057,6 +6201,33 @@ function decodeUtf8Best(payload) {
         return "";
     }
 }
+function encodeTextAckEnvelope(envelope) {
+    return TEXT_ACK_PREFIX + Buffer.from(JSON.stringify(envelope), "utf8").toString("base64url");
+}
+function decodeTextAckEnvelope(text) {
+    if (!text.startsWith(TEXT_ACK_PREFIX))
+        return undefined;
+    try {
+        const raw = Buffer.from(text.slice(TEXT_ACK_PREFIX.length), "base64url").toString("utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed.t === "ack" && typeof parsed.id === "string" && parsed.id.length > 0) {
+            return { t: "ack", id: parsed.id };
+        }
+        if (parsed.t === "msg" &&
+            typeof parsed.id === "string" &&
+            parsed.id.length > 0 &&
+            typeof parsed.text === "string") {
+            return { t: "msg", id: parsed.id, text: parsed.text };
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function createTextDeliveryId() {
+    return `${Date.now().toString(36)}-${Buffer.from(randomBytes(12)).toString("base64url")}`;
+}
 function tryDecodeCarrierMessagePacket(payload) {
     try {
         const decoded = decodeCarrierPacket(payload);

package/dist/types/peer.d.ts

@@ -122,11 +122,26 @@ export type FriendInfoEvent = {
 export type TextMessage = {
     pubkey: string;
     text: string;
+    /** Stable id for SDK-level acknowledged delivery. Present only for messages
+     *  sent with sendTextUntilAck(). Receivers can persist this id for dedupe. */
+    deliveryId?: string;
+    /** Send the delivery ACK. The SDK calls this automatically after all onText
+     *  handlers return successfully; handlers that need durable inbox semantics
+     *  should return a Promise that resolves only after the inbox write is done. */
+    ack?: () => Promise<void>;
     /** Delivery path: "online" = live net_crypto session (direct/relay), "offline"
      *  = express store-and-forward. Lets the UI color the two differently so a user
      *  can see when online delivery is failing and only offline messages land. */
     via?: "online" | "offline";
 };
+export type SendTextUntilAckOptions = {
+    /** Stable id for retries across a caller-managed outbox. Defaults to a random id. */
+    deliveryId?: string;
+    /** How long to keep retrying before rejecting. Defaults to 5 minutes. */
+    timeoutMs?: number;
+    /** Delay between retransmit attempts while no ACK has arrived. Defaults to 5s. */
+    retryIntervalMs?: number;
+};
 /**
  * An application-defined custom packet received from a friend, over the
  * toxcore custom packet ranges: lossless `160–191` (reliable, ordered) or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.111",
+  "version": "0.1.112",
   "description": "Pure TypeScript port of Elastos Carrier (toxcore-derived) P2P messaging. DHT, onion routing, TCP relay, FlatBuffers app payloads, Express offline relay. Wire-compatible with iOS Beagle and the Carrier C SDK.",
   "type": "module",
   "main": "./dist/index.js",