@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/zalo/listener/friend-events.js

@@ -0,0 +1,113 @@
+/**
+ * Friend controls (cmd 601/603 `controls[]` with `content.act_type === "fr"`) -> the `friend_event` object.
+ *
+ * `{type, data, threadId, isSelf}` with `type` a number. The numbers are the ones the engine has always read
+ * (`listen` labels 0-7), so they stay as they are in 3.0.0.
+ *
+ * Pure functions. Ids are compared as strings, so an id the parser left as a number still matches.
+ */
+
+/** The `type` numbers. */
+export const FRIEND_EVENT_TYPE = Object.freeze({
+    ADD: 0,
+    REMOVE: 1,
+    REQUEST: 2,
+    UNDO_REQUEST: 3,
+    REJECT_REQUEST: 4,
+    SEEN_FRIEND_REQUEST: 5,
+    BLOCK: 6,
+    UNBLOCK: 7,
+    BLOCK_CALL: 8,
+    UNBLOCK_CALL: 9,
+    PIN_UNPIN: 10,
+    PIN_CREATE: 11,
+    UNKNOWN: 12,
+});
+
+const T = FRIEND_EVENT_TYPE;
+
+/** Server act -> type. */
+const BY_ACT = new Map([
+    ["add", T.ADD],
+    ["remove", T.REMOVE],
+    ["block", T.BLOCK],
+    ["unblock", T.UNBLOCK],
+    ["block_call", T.BLOCK_CALL],
+    ["unblock_call", T.UNBLOCK_CALL],
+    ["req_v2", T.REQUEST],
+    ["reject", T.REJECT_REQUEST],
+    ["undo_req", T.UNDO_REQUEST],
+    ["seen_fr_req", T.SEEN_FRIEND_REQUEST],
+    ["pin_unpin", T.PIN_UNPIN],
+    ["pin_create", T.PIN_CREATE],
+]);
+
+/**
+ * Acts the listener drops. A friend request arrives twice, as `req` and as `req_v2`
+ * (agent/docs/zca-replace/spec-listener.md 2.5, the `fr` row); only `req_v2` becomes an event, so one request is
+ * announced once.
+ */
+export const SKIPPED_FRIEND_ACTS = Object.freeze(["req"]);
+
+/** Types whose `data` is the other account's uid itself. */
+const UID_DATA = new Set([T.ADD, T.REMOVE, T.BLOCK, T.UNBLOCK, T.BLOCK_CALL, T.UNBLOCK_CALL]);
+/** Types whose `data` is a request `{fromUid, toUid, ...}`. */
+const REQUEST_DATA = new Set([T.REQUEST, T.UNDO_REQUEST, T.REJECT_REQUEST]);
+/** Types whose `data` is a pinned topic change `{actorId, conversationId, topic, ...}`. */
+const PIN_DATA = new Set([T.PIN_UNPIN, T.PIN_CREATE]);
+
+const sameId = (v, uid) => v !== null && v !== undefined && String(v) === String(uid);
+
+/**
+ * The `type` number of a friend act.
+ *
+ * @param {string} act
+ * @returns {number} a {@link FRIEND_EVENT_TYPE} value; UNKNOWN (12) for an act not listed
+ */
+export function friendEventType(act) {
+    return BY_ACT.get(act) ?? T.UNKNOWN;
+}
+
+/**
+ * Build the `friend_event` object for one act.
+ *
+ * @param {string} uid - the own uid
+ * @param {string} act - `content.act`
+ * @param {any} data - `content.data`, already parsed (a uid for add/remove/block/unblock and their call forms)
+ * @returns {{type: number, data: any, threadId: any, isSelf: boolean}} for an unknown act, `data` is the JSON text
+ *   of what came, `threadId` is "" and `isSelf` false
+ */
+export function toFriendEvent(uid, act, data) {
+    const type = friendEventType(act);
+    if (UID_DATA.has(type)) {
+        // The server sends add and remove about the other account; the others are this account's own doing.
+        return { type, data, threadId: data, isSelf: type !== T.ADD && type !== T.REMOVE };
+    }
+    if (REQUEST_DATA.has(type)) return { type, data, threadId: data.toUid, isSelf: sameId(data.fromUid, uid) };
+    if (type === T.SEEN_FRIEND_REQUEST) return { type, data, threadId: uid, isSelf: true };
+    if (PIN_DATA.has(type)) return { type, data, threadId: data.conversationId, isSelf: sameId(data.actorId, uid) };
+    return { type: T.UNKNOWN, data: JSON.stringify(data), threadId: "", isSelf: false };
+}
+
+/**
+ * Turn one friend control's `content` into its `friend_event`, or null for a skipped act.
+ *
+ * A string `data` is JSON and is parsed, except that a string holding a bare number (a uid) is kept as the string,
+ * so a uid past 2^53 keeps its digits. A `topic.params` held as a JSON string (pin events) is parsed too.
+ *
+ * @param {string} uid - the own uid
+ * @param {{act: string, data: any}} content - the control's `content` (`act_type` "fr")
+ * @returns {{type: number, data: any, threadId: any, isSelf: boolean}|null}
+ * @throws {SyntaxError} when a string `data` or `topic.params` is not JSON
+ */
+export function friendControlEvent(uid, content) {
+    if (SKIPPED_FRIEND_ACTS.includes(content.act)) return null;
+    let data = content.data;
+    if (typeof data === "string") {
+        const parsed = JSON.parse(data);
+        if (typeof parsed !== "number") data = parsed;
+    }
+    const topic = data && typeof data === "object" ? data.topic : undefined;
+    if (topic && typeof topic === "object" && typeof topic.params === "string") topic.params = JSON.parse(topic.params);
+    return toFriendEvent(uid, content.act, data);
+}

package/src/zalo/listener/group-events.js

@@ -0,0 +1,117 @@
+/**
+ * Group controls (cmd 601/603 `controls[]` with `content.act_type === "group"`) -> the `group_event` object.
+ *
+ * `{type, act, data, threadId, isSelf}`: `act` is the server's name for the change, `type` the name the engine
+ * prints and gates on (`group_${type}` in `listen`). For 3.0.0 `type` keeps the 22-name vocabulary the engine has
+ * always seen, which equals `act` for every name in it, and is "unknown" for any other act (Zalo also sends
+ * `join_accept`, `group_type`, `new_group_invitation`, `update_group_invitation`, `remove_group_invitation`,
+ * `update_status`); `act` always carries the real name.
+ *
+ * Pure functions. Ids are compared as strings, so an id the parser left as a number still matches.
+ */
+
+/**
+ * The `type` names, in the order agent/docs/zca-replace/spec-listener.md 2.6 lists them (the vocabulary the engine
+ * has always read; `listen` prints `group_${type}` and gates on these names).
+ */
+export const GROUP_EVENT_TYPES = Object.freeze([
+    "join_request",
+    "join",
+    "leave",
+    "remove_member",
+    "block_member",
+    "update_setting",
+    "update_avatar",
+    "update",
+    "new_link",
+    "add_admin",
+    "remove_admin",
+    "new_pin_topic",
+    "update_pin_topic",
+    "update_topic",
+    "update_board",
+    "remove_board",
+    "reorder_pin_topic",
+    "unpin_topic",
+    "remove_topic",
+    "accept_remind",
+    "reject_remind",
+    "remind_topic",
+]);
+
+/** The `type` of an act outside {@link GROUP_EVENT_TYPES}. */
+export const GROUP_EVENT_UNKNOWN = "unknown";
+
+/**
+ * Acts the listener drops. When an admin approves a join request the server sends `join_reject` beside
+ * `join_accept`; Zalo treats the two as one "approval update"
+ * and never announces a rejection from it (agent/docs/zca-replace/spec-listener.md 2.5 and 3, "Group acts"), so
+ * emitting it would report a rejection that did not happen.
+ */
+export const SKIPPED_GROUP_ACTS = Object.freeze(["join_reject"]);
+
+const KNOWN = new Set(GROUP_EVENT_TYPES);
+const PIN_ACTS = new Set(["new_pin_topic", "unpin_topic", "update_pin_topic", "reorder_pin_topic"]);
+const BOARD_ACTS = new Set(["update_board", "remove_board"]);
+const REMIND_ANSWER_ACTS = new Set(["accept_remind", "reject_remind"]);
+
+const sameId = (v, uid) => v !== null && v !== undefined && String(v) === String(uid);
+
+/**
+ * The `type` of a group act.
+ *
+ * @param {string} act
+ * @returns {string} the act itself when it is one of {@link GROUP_EVENT_TYPES}, else "unknown"
+ */
+export function groupEventType(act) {
+    return KNOWN.has(act) ? act : GROUP_EVENT_UNKNOWN;
+}
+
+/**
+ * Whether the own account caused or is the subject of the change, by the field each kind of act names it in.
+ *
+ * @param {string} type - from {@link groupEventType}
+ * @param {object} data
+ * @param {string} uid - the own uid
+ * @returns {boolean}
+ */
+function isSelfIn(type, data, uid) {
+    if (type === "join_request") return false;
+    if (PIN_ACTS.has(type)) return sameId(data.actorId, uid);
+    if (BOARD_ACTS.has(type)) return sameId(data.sourceId, uid);
+    if (REMIND_ANSWER_ACTS.has(type)) {
+        return Array.isArray(data.updateMembers) && data.updateMembers.some((id) => sameId(id, uid));
+    }
+    if (type === "remind_topic") return sameId(data.creatorId, uid);
+    const members = Array.isArray(data.updateMembers) ? data.updateMembers : [];
+    return members.some((m) => sameId(m?.id, uid)) || sameId(data.sourceId, uid);
+}
+
+/**
+ * Build the `group_event` object for one act.
+ *
+ * @param {string} uid - the own uid
+ * @param {string} act - `content.act`
+ * @param {object} data - `content.data`, already parsed
+ * @returns {{type: string, act: string, data: object, threadId: string, isSelf: boolean}}
+ */
+export function toGroupEvent(uid, act, data) {
+    const type = groupEventType(act);
+    const threadId = data.group_id ?? data.groupId;
+    return { type, act, data, threadId, isSelf: isSelfIn(type, data, uid) };
+}
+
+/**
+ * Turn one group control's `content` into its `group_event`, or null for a skipped act.
+ *
+ * @param {string} uid - the own uid
+ * @param {{act: string, data: object|string}} content - the control's `content` (`act_type` "group"); a string
+ *   `data` is JSON and is parsed
+ * @returns {{type: string, act: string, data: object, threadId: string, isSelf: boolean}|null}
+ * @throws {SyntaxError} when a string `data` is not JSON
+ */
+export function groupControlEvent(uid, content) {
+    if (SKIPPED_GROUP_ACTS.includes(content.act)) return null;
+    const data = typeof content.data === "string" ? JSON.parse(content.data) : content.data;
+    return toGroupEvent(uid, content.act, data);
+}

package/src/zalo/listener/keepalive.js

@@ -0,0 +1,191 @@
+/**
+ * WebSocket heartbeat for the long idle windows in the socket stages.
+ *
+ * WHY THIS EXISTS, and why it is not `api.keepAlive()`
+ * ---------------------------------------------------
+ * The session exposes `api.keepAlive()`, which looks like the obvious instrument and
+ * is the wrong one: it is an HTTP GET to `<chat host>/keepalive`
+ * (src/zalo/api/session.js). It touches the session, never the socket, so it cannot
+ * keep a WebSocket flow warm.
+ *
+ * What actually keeps this socket warm is Zalo's own application-level ping --
+ * `cmd 2 / subCmd 1` carrying `{eventId}`, which the server echoes back
+ * verbatim. The listener already sends it, on an interval the server hands out at
+ * login (`settings.features.socket.ping_interval`, measured at **180000 ms**
+ * for this account).
+ *
+ * So the socket is not unpinged. It is pinged every three minutes, which leaves
+ * two problems this module fixes:
+ *
+ *   1. **Three minutes is the whole idle window.** A restore waiting on the
+ *      phone sends nothing and receives nothing for up to the full wait budget,
+ *      so the flow can sit silent right up to the server's own liveness bound
+ *      with no margin. One late ping means six minutes of silence.
+ *   2. **The interval is armed once, on the cipher-key frame, and never
+ *      re-phased.** `setInterval` also queues catch-up work when the event loop
+ *      blocks -- and the decode/store phase does block it.
+ *
+ * This sends the same frame, on a shorter interval, using a
+ * self-rescheduling timer (no catch-up burst after a blocked loop), and counts
+ * the echoes so a caller can say how long the socket had been silent before it
+ * dropped. It never closes the socket on its own: a missed echo is evidence,
+ * not a verdict.
+ */
+
+/** Zalo's heartbeat frame: `cmd 2 / subCmd 1`, body `{eventId}`. */
+export const PING_CMD = 2;
+export const PING_SUBCMD = 1;
+
+/** What the server advises, and what the listener uses. */
+export const SERVER_PING_INTERVAL_MS = 180000;
+
+/**
+ * The interval used when the caller names none: the one the server advises (Y11).
+ *
+ * This used to be a third of it (60 s), on the argument that one late ping meant six silent minutes. A live
+ * `listen` on the test account then held its socket for 274 s on the server's own interval alone, so the extra
+ * frames bought no safety and only made this client's traffic unusual.
+ * The echo count stays, so a caller can still say how long the socket had been silent when it dropped.
+ */
+export const DEFAULT_KEEPALIVE_MS = SERVER_PING_INTERVAL_MS;
+
+/** Never ping faster than this, whatever a caller asks for. */
+export const MIN_KEEPALIVE_MS = 15000;
+
+/**
+ * Clamp a requested heartbeat interval into a sane range.
+ *
+ * @param {number|undefined} ms - requested interval
+ * @param {number} [advisedMs] - the interval the server advised for this session (`ping_interval`); the default
+ *   when `ms` is not usable, and the most it may be
+ * @returns {number} a finite interval between MIN_KEEPALIVE_MS and the server's own
+ */
+export function resolveKeepAliveInterval(ms, advisedMs) {
+    const advised = Number.isFinite(advisedMs) && advisedMs >= MIN_KEEPALIVE_MS ? advisedMs : SERVER_PING_INTERVAL_MS;
+    if (!Number.isFinite(ms) || ms <= 0) return advised;
+    return Math.min(advised, Math.max(MIN_KEEPALIVE_MS, ms));
+}
+
+/**
+ * The ping payload, in the shape `Listener.sendWs` expects.
+ *
+ * @param {number} [now=Date.now()] - the eventId the server echoes back
+ * @returns {{version: number, cmd: number, subCmd: number, data: {eventId: number}}}
+ */
+export function pingPayload(now = Date.now()) {
+    return { version: 1, cmd: PING_CMD, subCmd: PING_SUBCMD, data: { eventId: now } };
+}
+
+/**
+ * True for a raw frame that is a `cmd 2 / subCmd 1` heartbeat echo.
+ *
+ * @param {Buffer} buf - a raw socket frame
+ * @returns {boolean}
+ */
+export function isPingEcho(buf) {
+    return Buffer.isBuffer(buf) && buf.length >= 4 && buf.readUInt16LE(1) === PING_CMD && buf[3] === PING_SUBCMD;
+}
+
+/**
+ * Start pinging a listener's socket until the returned stop function is called.
+ *
+ * The timer is unref'd, so it can never hold the process open, and it stops
+ * rescheduling once the socket is gone -- `sendWs` is a silent no-op on a null
+ * socket, so a running timer on a dead wire would just spin.
+ *
+ * @param {object} listener - a listener (needs `sendWs` and `ws`)
+ * @param {object} [opts]
+ * @param {number} [opts.intervalMs] - heartbeat interval; clamped
+ * @param {number} [opts.advisedMs] - the server's advised interval, the default and the ceiling
+ * @param {(info: {sent: number, echoed: number}) => void} [opts.onPing] - called after each ping
+ * @param {() => number} [opts.now=Date.now] - injectable clock
+ * @param {{setTimeout: Function, clearTimeout: Function}} [opts.timers] - injectable scheduler
+ * @returns {{stop: () => void, stats: () => {sent: number, echoed: number, intervalMs: number, silentMs: number}}}
+ */
+export function startKeepAlive(listener, opts = {}) {
+    const intervalMs = resolveKeepAliveInterval(opts.intervalMs, opts.advisedMs);
+    const now = typeof opts.now === "function" ? opts.now : Date.now;
+    const timers = opts.timers || { setTimeout, clearTimeout };
+    const onPing = typeof opts.onPing === "function" ? opts.onPing : () => {};
+
+    let sent = 0;
+    let echoed = 0;
+    let lastEchoAt = now();
+    let handle = null;
+    let stopped = false;
+
+    // The echo tap goes on the RAW socket, and a reconnect replaces that object
+    // -- so the tap follows the socket rather than being pinned to the one that
+    // was there at startup. Without this a keepalive held across a reconnect
+    // would keep pinging (sendWs reads `listener.ws` fresh) while silently
+    // counting no echoes at all, which is exactly the signal it exists to give.
+    const onFrame = (buf) => {
+        if (!isPingEcho(buf)) return;
+        echoed++;
+        lastEchoAt = now();
+    };
+    let tapped = null;
+    const retap = () => {
+        const ws = listener?.ws;
+        if (ws === tapped) return;
+        try {
+            tapped?.off?.("message", onFrame);
+        } catch {
+            /* the old socket is gone; nothing to detach */
+        }
+        tapped = ws || null;
+        try {
+            tapped?.on?.("message", onFrame);
+        } catch {
+            /* a socket shape without events still gets pinged, just uncounted */
+        }
+    };
+    retap();
+
+    const tick = () => {
+        if (stopped) return;
+        // A closed socket cannot be kept alive, and the listener nulls `ws` on close,
+        // so an absent socket is just as dead as a CLOSING/CLOSED one.
+        if (!listener?.ws || listener.ws.readyState > 1) return;
+        retap();
+        // The listener pings on the server's interval from the hello on. A second timer at the same cadence only doubled
+        // every ping (two 2/1 frames in one millisecond; one is expected), so on the default cadence this one just
+        // keeps counting echoes. A caller that asks for its own interval still gets its own pings.
+        const listenerPings = !opts.intervalMs && Boolean(listener.pingInterval);
+        try {
+            if (!listenerPings) {
+                listener.sendWs(pingPayload(now()));
+                sent++;
+                onPing({ sent, echoed });
+            }
+        } catch {
+            /* a send on a dying socket is not worth failing the run over */
+        }
+        schedule();
+    };
+
+    // setTimeout chaining, not setInterval: a blocked event loop must not queue
+    // a burst of catch-up pings the moment it frees up.
+    const schedule = () => {
+        handle = timers.setTimeout(tick, intervalMs);
+        if (typeof handle?.unref === "function") handle.unref();
+    };
+    schedule();
+
+    return {
+        stop() {
+            stopped = true;
+            if (handle) timers.clearTimeout(handle);
+            handle = null;
+            try {
+                tapped?.off?.("message", onFrame);
+            } catch {
+                /* already torn down */
+            }
+            tapped = null;
+        },
+        stats() {
+            return { sent, echoed, intervalMs, silentMs: now() - lastEchoAt };
+        },
+    };
+}