@mega-yfue/eufy-sdk 0.5.0-beta.93 → 0.5.0-beta.94

package/dist/transport/p2p/codec.d.ts

@@ -8,7 +8,12 @@ export declare const MAGIC_WORD = "XZYH";
 export declare const RequestMessageType: {
     readonly LOCAL_LOOKUP: Buffer<ArrayBuffer>;
     readonly LOOKUP_WITH_KEY: Buffer<ArrayBuffer>;
+    /** `ListReq_DSK`: the same body as a variant-2 lookup, answered with {@link ResponseMessageType.LIST_REQ_ACK}. */
     readonly LOOKUP_WITH_KEY2: Buffer<ArrayBuffer>;
+    readonly RLY_HELLO: Buffer<ArrayBuffer>;
+    readonly RLY_PORT: Buffer<ArrayBuffer>;
+    readonly RLY_REQ: Buffer<ArrayBuffer>;
+    readonly RLY_PKT: Buffer<ArrayBuffer>;
     readonly CHECK_CAM: Buffer<ArrayBuffer>;
     readonly CHECK_CAM2: Buffer<ArrayBuffer>;
     readonly PING: Buffer<ArrayBuffer>;
@@ -20,14 +25,24 @@ export declare const RequestMessageType: {
 export declare const ResponseMessageType: {
     readonly LOCAL_LOOKUP_RESP: Buffer<ArrayBuffer>;
     readonly LOOKUP_ADDR: Buffer<ArrayBuffer>;
-    readonly LOOKUP_ADDR2: Buffer<ArrayBuffer>;
+    /** The relay servers a cloud lookup server names: `[count:1][pad:3]` then `count` address records. */
+    readonly LIST_REQ_ACK: Buffer<ArrayBuffer>;
+    readonly RLY_HELLO_ACK: Buffer<ArrayBuffer>;
+    /** A relay's answer to RLY_PORT: `[mark:4 BE][port:2 BE][pad:2]`, the port being the one it relays on. */
+    readonly RLY_PORT_ACK: Buffer<ArrayBuffer>;
+    readonly RLY_REQ_ACK: Buffer<ArrayBuffer>;
+    /** A relay endpoint to register with: one address record, then `[handle:4 BE]`. */
+    readonly RLY_TO: Buffer<ArrayBuffer>;
     readonly CAM_ID: Buffer<ArrayBuffer>;
+    /** A lookup server's answer to a P2P request: `[result:1]` first, 0 when the request is accepted. */
+    readonly P2P_REQ_ACK: Buffer<ArrayBuffer>;
     /**
      * The device's own address record, sent in answer to CHECK_CAM ahead of CAM_ID: its 20-byte device id, one
-     * record in `encodeSelfAddress`'s shape naming the address it answers from, then 8 zero bytes (44-byte payload).
+     * record in `encodeAddress`'s shape naming the address it answers from, then 8 zero bytes (44-byte payload).
      */
     readonly CAM_ADDR: Buffer<ArrayBuffer>;
-    readonly TURN_SERVER_CAM_ID: Buffer<ArrayBuffer>;
+    /** A relay reporting the path to the device ready: the device's 20-byte id, sent from the relay endpoint. */
+    readonly RLY_RDY: Buffer<ArrayBuffer>;
     readonly PING: Buffer<ArrayBuffer>;
     readonly PONG: Buffer<ArrayBuffer>;
     readonly DATA: Buffer<ArrayBuffer>;
@@ -160,6 +175,10 @@ export declare function buildLookupWithKeyPayload2(p2pDid: string, dskKey: strin
  * its exact semantics (and whether it's validated) are unconfirmed.
  */
 export declare function buildLookupWithKeyPayload(p2pDid: string, selfHost: string, selfPort: number, dskKey: string): Buffer;
+/** RLY_REQ payload: `[p2pDid:20][relay address record:16][mark:4 BE]`, naming the relay port and mark a RLY_PORT_ACK gave. */
+export declare function buildRelayRequestPayload(p2pDid: string, relay: Address, mark: number): Buffer;
+/** RLY_PKT payload: `[handle:4 BE][p2pDid:20][role:1][pad:3]`; a connecting client's role byte is 0. */
+export declare function buildRelayPacketPayload(handle: number, p2pDid: string): Buffer;
 /** CHECK_CAM hole-punch payload: `[p2pDid:20][0x000000]`. */
 export declare function buildCheckCamPayload(p2pDid: string): Buffer;
 /** 10-byte command header: `[dataTypeHeader:2][seq:2 BE]["XZYH"][cmd:2 LE]`. */
@@ -205,7 +224,19 @@ export declare function buildRawCommandPayload(data: Buffer, channel?: number, s
 export declare function buildAckPayload(dataTypeHeader: Buffer, seqNo: number): Buffer;
 /** Parse the 16-byte data-frame header that follows the "XZYH" magic. */
 export declare function parseDataFrameHeader(frame: Buffer): P2PDataFrameHeader;
-/** Parse a LOOKUP_ADDR / LOOKUP_ADDR2 response into a device address. */
+/** Parse a LOOKUP_ADDR or RLY_TO message's leading address record. */
 export declare function parseLookupAddr(msg: Buffer): Address;
+/** The relay servers a LIST_REQ_ACK names, in the order listed, without the unspecified address; records past the message's end are dropped. */
+export declare function parseRelayList(msg: Buffer): Address[];
+/** A RLY_PORT_ACK's mark and relay port, or `undefined` for a message too short to carry them. */
+export declare function parseRelayPortAck(msg: Buffer): {
+    mark: number;
+    port: number;
+} | undefined;
+/** A RLY_TO's relay endpoint and handle, or `undefined` for a message too short to carry them. */
+export declare function parseRelayTo(msg: Buffer): {
+    address: Address;
+    handle: number;
+} | undefined;
 /** Read a NUL-terminated UTF-8 string (CMD_NOTIFY_PAYLOAD carries JSON this way). */
 export declare function readNullTerminatedString(data: Buffer, encoding?: BufferEncoding): string;

package/dist/transport/p2p/command-router.d.ts

@@ -22,7 +22,7 @@ import { FragmentRecording } from "./fragment-recording.js";
  * negotiation is re-prompted once.
  */
 export declare const P2P_STATION_WAITS: {
-    readonly connect: 15000;
+    readonly connect: 45000;
     readonly level2Grace: 25000;
     readonly level2Settle: 8000;
 };
@@ -218,6 +218,15 @@ export declare class P2PCommandRouter {
      * carry the start is not a connected session, so this refuses rather than returning one.
      */
     private openMediaSession;
+    /**
+     * Wait for `session` to connect, for up to the session's own connect deadline, and throw
+     * {@link StationUnreachableError} when it does not.
+     *
+     * `connect()` resolves once the lookups are under way, not once a path answers, so a session handed back by
+     * {@link openSession} may still be connecting: a relay connect lands about 25 s in. A level-2 grace counted
+     * before this would be spent on the connect rather than on the key.
+     */
+    private awaitConnected;
     /** Open (or reuse) the session filed under `key`, dialling `parentSn`'s endpoint. */
     private openSession;
     /**

package/dist/transport/p2p/p2p-session.d.ts

@@ -23,8 +23,13 @@ import { type Logger } from "../../core/logger.js";
  * a connection that reaches this closes itself, so nothing addressed to that station can succeed afterwards.
  * Published because it bounds every wait on a session connecting — a second number for the same deadline
  * elsewhere would outlive the connection it waits on and charge the difference to every failure.
+ *
+ * The relay handshake starts once the lookup server has acknowledged the P2P request for 24 lookup rounds, so
+ * about 25 s in. The vendor app's own remote connect has a 30 s budget, which leaves the handshake 3–6 s.
+ * Forty-five seconds keeps the vendor's threshold and gives the handshake about 20 s to complete. A station that
+ * never acknowledges the request, as an offline one does, takes this long to fail.
  */
-export declare const CONNECT_TIMEOUT_MS = 15000;
+export declare const CONNECT_TIMEOUT_MS = 45000;
 /**
  * The channel a command addresses the station itself on, rather than one of its cameras, and the value a
  * session's channel-taking methods resolve an omitted channel to.
@@ -140,6 +145,17 @@ export declare class P2PSession extends EventEmitter {
     private probeSockets;
     /** Cloud lookup inputs resolved once for a connection. */
     private cloudLookup?;
+    /**
+     * Lookup rounds since the lookup server acknowledged this connect's P2P request, or `undefined` while it
+     * has not; see {@link RELAY_AFTER_ACKED_ROUNDS}.
+     */
+    private ackedRounds?;
+    /**
+     * The relay handshake of a connect that has fallen back to one, by the step it waits on: the relay list
+     * (`list`, answering ListReq_DSK), a relay's hello acknowledgement (`hello`), that relay's port (`port`),
+     * then the relay-ready the device's registration produces (`request`, re-sending RLY_REQ meanwhile).
+     */
+    private relay?;
     /** Local outbound IPv4 reported inside LOOKUP_WITH_KEY requests. */
     private selfHost?;
     /**
@@ -341,21 +357,42 @@ export declare class P2PSession extends EventEmitter {
      */
     private static detectLocalIp;
     private sendLookups;
+    /** Step {@link ackedRounds} for one lookup round, and start the relay handshake once it passes its threshold. */
+    private countAckedRound;
+    /**
+     * How far this connect got towards a relay: the handshake step it was waiting on (`list` meaning no lookup
+     * server named a relay), `not started` where it had not fallen back yet, or `no cloud lookup` where it could
+     * not.
+     */
+    private relayProgress;
+    /**
+     * Send the relay handshake's message for the step it waits on, from the session's own socket.
+     *
+     * The order is the vendor client's: ListReq_DSK to the cloud lookup servers, RLY_HELLO to every relay they
+     * list, RLY_PORT to the first of those relays that acknowledges, then RLY_REQ to the lookup servers naming
+     * that relay's port and mark. The lookup server has the device register with the relay, and the relay
+     * answers RLY_RDY.
+     */
+    private sendRelay;
+    /** Advance the relay handshake on one of its answers, arriving on the session's own socket. */
+    private onRelayMessage;
     /** Register a bound socket's own port with each configured cloud lookup address. */
     private sendCloudLookup;
     /**
      * Route one inbound UDP datagram by its message type, tracing every non-DATA one and any type this session
      * does not model.
      *
-     * An unmodelled type is not by itself evidence about a session that is failing. `0xf169` — a relay-pool
-     * listing answering a cloud lookup, which a connected session has no use for — reaches the UNHANDLED branch
-     * on the sessions of cameras that stream and cameras that do not alike. `0xf121` has been observed
-     * straddling a level-2 wait on a camera whose failure to deliver video had a separate cause, and did not
-     * recur across later probes of it. Correlate an unmodelled type against a WORKING session before reading it
-     * as a cause.
+     * An unmodelled type is not by itself evidence about a session that is failing. Correlate one against a
+     * WORKING session before reading it as a cause.
+     *
+     * P2P_REQ_ACK is the lookup server acknowledging this connect's P2P request; the first one carrying result 0
+     * starts the round count {@link RELAY_AFTER_ACKED_ROUNDS} measures.
      *
      * CAM_ADDR is recognised and dropped: it names the address the device is already answering from, and the
-     * CAM_ID that follows it is what completes the connect.
+     * CAM_ID that follows it is what completes the connect. RLY_TO is a relay endpoint, never the device: it is
+     * answered with {@link RELAY_PACKET_COPIES} RLY_PKTs carrying its handle, and the RLY_RDY naming this
+     * session's device completes the connect with the relay as the peer. The other relay answers advance the
+     * handshake {@link sendRelay} drives, and are dropped outside it.
      */
     private onMessage;
     private beginCheckCam;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mega-yfue/eufy-sdk",
-  "version": "0.5.0-beta.93",
+  "version": "0.5.0-beta.94",
   "description": "One typed TypeScript client for the Anker eufy v6 cloud — capability-driven devices, realtime events over P2P/MQTT/push, and live media",
   "license": "Apache-2.0",
   "author": "mega-yfue",