amule-ec-client 0.7.0 → 0.7.1

package/dist/UpdateState-LhdtiATk.js

@@ -0,0 +1,443 @@
+import { f as findNumericTag, p as findTag } from "./Tag-D_Ybe5RQ.js";
+import { n as PARTSIZE, t as ChunkStatus } from "./download-details-OM0FJUhZ.js";
+import { a as toOptionalNumber, i as toOptionalIp, n as tagOwnNumericValue, r as toOptionalBool } from "./utils-CNoUroOI.js";
+import { r as parseKnownFileFields, t as SharedFilesResponseParser } from "./SharedFilesResponse-CFl0NuO-.js";
+import { t as ClientQueueResponseParser } from "./ClientQueueResponse-RfXh2JGa.js";
+import { t as ServerListResponseParser } from "./ServerListResponse-M3C2OcfZ.js";
+//#region src/response/DownloadDetailsResponse.ts
+/**
+* Decode an aMule EC RLE-compressed buffer.
+* Format: [value, value, count] repeats value count times; other bytes pass through.
+*/
+function rleDecode(buf) {
+	let size = 0;
+	let index = 0;
+	while (index < buf.length) if (index < buf.length - 2 && buf[index + 1] === buf[index]) {
+		size += buf[index + 2];
+		index += 3;
+	} else {
+		size += 1;
+		index += 1;
+	}
+	const output = Buffer.alloc(size);
+	let outIndex = 0;
+	index = 0;
+	while (index < buf.length) if (index < buf.length - 2 && buf[index + 1] === buf[index]) {
+		const count = buf[index + 2];
+		output.fill(buf[index], outIndex, outIndex + count);
+		outIndex += count;
+		index += 3;
+	} else {
+		output[outIndex++] = buf[index];
+		index += 1;
+	}
+	return output;
+}
+/**
+* Reconstruct the current state from the previous state and an RLE-decoded XOR diff,
+* mirroring aMule's RLE_Data: resize previous buffer to the diff size (zero-extend on
+* grow, truncate on shrink), then XOR byte-wise.
+*/
+function xorReconstruct(previous, decodedDiff) {
+	const result = Buffer.alloc(decodedDiff.length, 0);
+	previous.copy(result, 0, 0, Math.min(previous.length, decodedDiff.length));
+	for (let i = 0; i < decodedDiff.length; i++) result[i] ^= decodedDiff[i];
+	return result;
+}
+/**
+* Decode an RLE-decoded buffer of byte-interleaved (column-major) little-endian uint64 values.
+*/
+function decodeInterleavedUint64(decoded) {
+	if (decoded.length === 0 || decoded.length % 8 !== 0) return [];
+	const valueCount = decoded.length / 8;
+	const values = new Array(valueCount);
+	for (let i = 0; i < valueCount; i++) {
+		let value = 0;
+		for (let byte = 7; byte >= 0; byte--) value = value * 256 + decoded[i + byte * valueCount];
+		values[i] = value;
+	}
+	return values;
+}
+function stringValue(tag) {
+	if (!tag) return "";
+	const value = tag.getValue();
+	return typeof value === "string" ? value : "";
+}
+function bufferValue(tag) {
+	if (!tag) return;
+	const value = tag.getValue();
+	return Buffer.isBuffer(value) ? value : void 0;
+}
+function nestedTag(parent, tagName) {
+	return parent.nestedTags ? findTag(parent.nestedTags, tagName) : void 0;
+}
+function nestedNumeric(parent, tagName) {
+	if (!parent.nestedTags) return 0;
+	const numeric = findNumericTag(parent.nestedTags, tagName);
+	if (numeric) return Number(numeric.getValue());
+	return tagOwnNumericValue(findTag(parent.nestedTags, tagName)) ?? 0;
+}
+/**
+* Extract the raw (RLE-encoded) part/gap/req status buffers of a partfile tag.
+*/
+function extractPartFileStatusBuffers(fileTag) {
+	return {
+		partStatus: bufferValue(nestedTag(fileTag, 786)),
+		gapStatus: bufferValue(nestedTag(fileTag, 787)),
+		reqStatus: bufferValue(nestedTag(fileTag, 788))
+	};
+}
+/**
+* Compute per-chunk status from RLE-decoded part/gap/req status buffers.
+*/
+function computeChunkInfo(sizeFull, buffers) {
+	const partCount = sizeFull > 0 ? Math.ceil(sizeFull / PARTSIZE) : 0;
+	const availability = new Array(partCount).fill(0);
+	if (buffers.partStatus && buffers.partStatus.length > 0) for (let i = 0; i < Math.min(buffers.partStatus.length, partCount); i++) availability[i] = buffers.partStatus[i];
+	const chunks = new Array(partCount).fill(ChunkStatus.COMPLETE);
+	if (partCount > 0 && buffers.gapStatus && buffers.gapStatus.length > 0) {
+		const gapValues = decodeInterleavedUint64(buffers.gapStatus);
+		for (let i = 0; i + 1 < gapValues.length; i += 2) {
+			const gapStart = gapValues[i];
+			const gapEnd = gapValues[i + 1];
+			if (gapStart > sizeFull || gapEnd > sizeFull || gapStart >= gapEnd) continue;
+			const startPart = Math.floor(gapStart / PARTSIZE);
+			const endPart = Math.min(Math.floor(gapEnd / PARTSIZE) + 1, partCount);
+			for (let part = startPart; part < endPart; part++) {
+				const chunkStart = part * PARTSIZE;
+				if (gapStart < Math.min((part + 1) * 9728e3, sizeFull) && gapEnd > chunkStart) chunks[part] = availability[part] > 0 ? ChunkStatus.AVAILABLE : ChunkStatus.UNAVAILABLE;
+			}
+		}
+	}
+	if (partCount > 0 && buffers.reqStatus && buffers.reqStatus.length > 0) {
+		const reqValues = decodeInterleavedUint64(buffers.reqStatus);
+		for (let i = 0; i + 1 < reqValues.length; i += 2) {
+			const reqStart = reqValues[i];
+			const reqEnd = reqValues[i + 1];
+			if (reqStart > sizeFull || reqEnd > sizeFull || reqStart >= reqEnd) continue;
+			const startPart = Math.floor(reqStart / PARTSIZE);
+			const endPart = Math.min(Math.floor(reqEnd / PARTSIZE) + 1, partCount);
+			for (let part = startPart; part < endPart; part++) {
+				if (chunks[part] === ChunkStatus.COMPLETE) continue;
+				const chunkStart = part * PARTSIZE;
+				if (reqStart < Math.min((part + 1) * 9728e3, sizeFull) && reqEnd > chunkStart) chunks[part] = ChunkStatus.DOWNLOADING;
+			}
+		}
+	}
+	return {
+		chunks,
+		availability,
+		partCount,
+		sizeFull
+	};
+}
+/**
+* Decode the status buffers of a file tag encoded after a daemon-side encoder reset,
+* i.e. a full snapshot: EC_OP_GET_DLOAD_QUEUE / EC_OP_GET_SHARED_FILES responses at any
+* detail level other than EC_DETAIL_UPDATE (see Get_EC_Response_GetDownloadQueue in
+* aMule's ExternalConn.cpp). After the reset, a present buffer holds the complete
+* current state and an absent one means the state is empty (the daemon skips the tag
+* when there is nothing to encode), so every key is always defined.
+*/
+function decodeFullPartFileStatusBuffers(fileTag) {
+	const raw = extractPartFileStatusBuffers(fileTag);
+	return {
+		partStatus: raw.partStatus ? rleDecode(raw.partStatus) : Buffer.alloc(0),
+		gapStatus: raw.gapStatus ? rleDecode(raw.gapStatus) : Buffer.alloc(0),
+		reqStatus: raw.reqStatus ? rleDecode(raw.reqStatus) : Buffer.alloc(0)
+	};
+}
+/**
+* Raw diff entries of the source-names map of a partfile tag, or undefined when the
+* packet carries no source-names changes for this file.
+*
+* The daemon sends source names (the filenames under which the sources share the file)
+* as a per-connection incremental map (see CPartFile_Encoder::Encode in aMule's
+* ExternalConn.cpp): an EC_TAG_PARTFILE_SOURCE_NAMES container whose children are
+* integer-valued EC_TAG_PARTFILE_SOURCE_NAMES tags (the map key), each carrying a
+* nested count (0 removes the entry) and, only when the entry is new, a nested name
+* string. The map is never reset while the connection lives, not even for
+* EC_DETAIL_FULL requests.
+*/
+function sourceNameEntriesFromFileTag(fileTag) {
+	const container = nestedTag(fileTag, 789);
+	if (!container) return;
+	const entries = [];
+	for (const child of container.nestedTags || []) {
+		if (child.name !== 789) continue;
+		const id = tagOwnNumericValue(child);
+		if (id === void 0) continue;
+		const name = stringValue(nestedTag(child, 789)) || void 0;
+		const count = nestedNumeric(child, 796);
+		entries.push({
+			id,
+			name,
+			count
+		});
+	}
+	return entries;
+}
+//#endregion
+//#region src/response/DownloadQueueResponse.ts
+var DownloadQueueResponseParser = class {
+	static fromPacket(packet) {
+		const files = [];
+		const partfileTags = packet.tags.filter((tag) => tag.name === 768);
+		for (const fileTag of partfileTags) {
+			const tags = fileTag.nestedTags || [];
+			let a4afSources = void 0;
+			const a4afSourcesTag = findTag(tags, 802);
+			if (a4afSourcesTag) {
+				a4afSources = [];
+				a4afSourcesTag.nestedTags = a4afSourcesTag.nestedTags || [];
+				for (const sourceTag of a4afSourcesTag.nestedTags) if (sourceTag.name === 15) a4afSources.push(sourceTag.getValue());
+			}
+			const file = {
+				...parseKnownFileFields(fileTag),
+				partMetID: findNumericTag(tags, 770)?.getShort(),
+				sizeXfer: toOptionalNumber(findNumericTag(tags, 772)?.getLong()),
+				sizeDone: toOptionalNumber(findNumericTag(tags, 774)?.getLong()),
+				fileStatus: findNumericTag(tags, 776)?.getInt(),
+				stopped: toOptionalBool(findNumericTag(tags, 791)?.getInt()),
+				sourceCount: findNumericTag(tags, 778)?.getShort(),
+				sourceNotCurrCount: findNumericTag(tags, 780)?.getShort(),
+				sourceXferCount: findNumericTag(tags, 781)?.getShort(),
+				sourceCountA4AF: findNumericTag(tags, 779)?.getShort(),
+				speed: toOptionalNumber(findNumericTag(tags, 775)?.getLong()),
+				downPrio: findNumericTag(tags, 777)?.getInt(),
+				fileCat: toOptionalNumber(findNumericTag(tags, 783)?.getLong()),
+				lastSeenComplete: toOptionalNumber(findNumericTag(tags, 785)?.getLong()),
+				lastDateChanged: toOptionalNumber(findNumericTag(tags, 784)?.getLong()),
+				downloadActiveTime: findNumericTag(tags, 792)?.getInt(),
+				availablePartCount: findNumericTag(tags, 797)?.getShort(),
+				a4AFAuto: toOptionalBool(findNumericTag(tags, 801)?.getInt()),
+				hashedPartCount: findNumericTag(tags, 800)?.getInt(),
+				getLostDueToCorruption: toOptionalNumber(findNumericTag(tags, 793)?.getLong()),
+				getGainDueToCompression: toOptionalNumber(findNumericTag(tags, 794)?.getLong()),
+				totalPacketsSavedDueToICH: findNumericTag(tags, 795)?.getInt(),
+				a4afSources
+			};
+			files.push(file);
+		}
+		return { files };
+	}
+};
+//#endregion
+//#region src/response/UpdateResponse.ts
+var UpdateResponseParser = class {
+	static fromPacket(packet) {
+		const sharedFiles = SharedFilesResponseParser.fromPacket(packet).files;
+		const downloadQueue = DownloadQueueResponseParser.fromPacket(packet).files;
+		const clientContainer = findTag(packet.tags, 1536);
+		const clients = clientContainer && clientContainer.nestedTags ? ClientQueueResponseParser.fromTags(clientContainer.nestedTags).clients : [];
+		const serverContainer = findTag(packet.tags, 1280);
+		const servers = serverContainer && serverContainer.nestedTags ? ServerListResponseParser.fromTags(serverContainer.nestedTags).servers : [];
+		const friendContainer = findTag(packet.tags, 2048);
+		return {
+			sharedFiles,
+			downloadQueue,
+			clients,
+			servers,
+			friends: friendContainer && friendContainer.nestedTags ? this.parseFriends(friendContainer.nestedTags) : []
+		};
+	}
+	static parseFriends(tags) {
+		const friends = [];
+		const friendTags = tags.filter((t) => t.name === 2048);
+		for (const friendTag of friendTags) {
+			const nested = friendTag.nestedTags || [];
+			friends.push({
+				name: findTag(nested, 2049)?.getValue(),
+				userHashHexString: findTag(nested, 2050)?.getValue()?.toString("hex"),
+				ip: toOptionalIp(findNumericTag(nested, 2051)?.getInt()),
+				port: findNumericTag(nested, 2052)?.getInt(),
+				friendSlot: toOptionalBool(findNumericTag(nested, 2056)?.getInt()),
+				shared: toOptionalBool(findNumericTag(nested, 2057)?.getInt()),
+				client: ClientQueueResponseParser.fromTags(nested).clients[0]
+			});
+		}
+		return friends;
+	}
+};
+//#endregion
+//#region src/client/UpdateState.ts
+const STATUS_BUFFER_KEYS = [
+	"partStatus",
+	"gapStatus",
+	"reqStatus"
+];
+/**
+* Merge update fields into the existing object. Fields absent from an incremental
+* response are undefined after parsing and must not clobber previously known values.
+*/
+function mergeDefined(existing, updates) {
+	const result = { ...existing };
+	for (const [key, value] of Object.entries(updates)) if (value !== void 0) result[key] = value;
+	return result;
+}
+var UpdateState = class {
+	sessionGeneration;
+	downloads = /* @__PURE__ */ new Map();
+	sharedFiles = /* @__PURE__ */ new Map();
+	clients = /* @__PURE__ */ new Map();
+	statusBuffers = /* @__PURE__ */ new Map();
+	sourceNames = /* @__PURE__ */ new Map();
+	/**
+	* @param sessionGeneration Connection generation this state belongs to (see
+	* AmuleConnection.getSessionGeneration). The state is only valid while the
+	* connection that produced it is alive, since the daemon diffs per connection.
+	*/
+	constructor(sessionGeneration) {
+		this.sessionGeneration = sessionGeneration;
+	}
+	/**
+	* Apply an incremental EC_OP_GET_UPDATE response.
+	*/
+	apply(packet) {
+		const parsed = UpdateResponseParser.fromPacket(packet);
+		const downloadQueue = this.mergeCollection(this.downloads, parsed.downloadQueue);
+		const sharedFiles = this.mergeCollection(this.sharedFiles, parsed.sharedFiles);
+		const clients = this.mergeCollection(this.clients, parsed.clients);
+		for (const ecid of [...this.statusBuffers.keys()]) if (!this.downloads.has(ecid)) this.statusBuffers.delete(ecid);
+		for (const ecid of [...this.sourceNames.keys()]) if (!this.downloads.has(ecid)) this.sourceNames.delete(ecid);
+		this.reconstructFileDetails(packet);
+		this.attachSources();
+		return {
+			downloadQueue,
+			sharedFiles,
+			clients,
+			servers: parsed.servers,
+			friends: parsed.friends
+		};
+	}
+	/**
+	* Apply a full (non-EC_DETAIL_UPDATE) EC_OP_GET_DLOAD_QUEUE response.
+	*
+	* The daemon resets each file's diff encoder before encoding it, so the buffers
+	* are complete snapshots that become the connection's new diff baseline; they are
+	* stored here as-is (replace, not XOR) to keep later incremental updates decodable.
+	* Source-name diffs are applied to the shared per-connection map.
+	*/
+	applyDownloadQueue(packet) {
+		const parsed = DownloadQueueResponseParser.fromPacket(packet);
+		const partfileTags = packet.tags.filter((tag) => tag.name === 768);
+		const seen = /* @__PURE__ */ new Set();
+		for (const fileTag of partfileTags) {
+			const ecid = tagOwnNumericValue(fileTag);
+			if (ecid === void 0) continue;
+			seen.add(ecid);
+			this.statusBuffers.set(ecid, decodeFullPartFileStatusBuffers(fileTag));
+			this.applySourceNameEntries(ecid, sourceNameEntriesFromFileTag(fileTag));
+		}
+		for (const ecid of [...this.statusBuffers.keys()]) if (!seen.has(ecid)) this.statusBuffers.delete(ecid);
+		for (const ecid of [...this.sourceNames.keys()]) if (!seen.has(ecid)) this.sourceNames.delete(ecid);
+		for (const file of parsed.files) {
+			if (file.ecid === void 0) continue;
+			const buffers = this.statusBuffers.get(file.ecid);
+			if (buffers && file.sizeFull && file.sizeFull > 0) file.chunkInfo = computeChunkInfo(file.sizeFull, buffers);
+			const nameMap = this.sourceNames.get(file.ecid);
+			if (nameMap) file.sourceNames = [...nameMap.values()];
+		}
+		return parsed.files;
+	}
+	/**
+	* Track the encoder side effects of a full (non-EC_DETAIL_UPDATE)
+	* EC_OP_GET_SHARED_FILES response.
+	*
+	* Shared partfiles use the same per-connection encoder as the download paths: the
+	* daemon resets it and re-encodes part/gap/req status (and consumes source-name
+	* diffs) into each EC_TAG_KNOWNFILE tag, so the new baselines must be recorded here
+	* or the next incremental update decodes into garbage.
+	*/
+	applySharedFiles(packet) {
+		const knownfileTags = packet.tags.filter((tag) => tag.name === 1024);
+		for (const fileTag of knownfileTags) {
+			const ecid = tagOwnNumericValue(fileTag);
+			if (ecid === void 0) continue;
+			this.statusBuffers.set(ecid, decodeFullPartFileStatusBuffers(fileTag));
+			this.applySourceNameEntries(ecid, sourceNameEntriesFromFileTag(fileTag));
+		}
+	}
+	mergeCollection(state, items) {
+		const seen = /* @__PURE__ */ new Set();
+		const result = [];
+		for (const item of items) {
+			if (item.ecid === void 0) {
+				result.push(item);
+				continue;
+			}
+			seen.add(item.ecid);
+			const existing = state.get(item.ecid);
+			const merged = existing ? mergeDefined(existing, item) : item;
+			state.set(item.ecid, merged);
+			result.push(merged);
+		}
+		for (const ecid of [...state.keys()]) if (!seen.has(ecid)) state.delete(ecid);
+		return result;
+	}
+	/**
+	* Reconstruct the incremental per-file details of each partfile in the packet:
+	* RLE-decode and XOR-reconstruct the status buffers (recomputing chunk info from the
+	* accumulated state), and apply the source-names map diffs.
+	*/
+	reconstructFileDetails(packet) {
+		const partfileTags = packet.tags.filter((tag) => tag.name === 768);
+		for (const fileTag of partfileTags) {
+			const ecid = tagOwnNumericValue(fileTag);
+			if (ecid === void 0) continue;
+			const file = this.downloads.get(ecid);
+			if (!file) continue;
+			const raw = extractPartFileStatusBuffers(fileTag);
+			const state = this.statusBuffers.get(ecid) || {};
+			for (const key of STATUS_BUFFER_KEYS) {
+				const rawBuffer = raw[key];
+				if (!rawBuffer) continue;
+				const decoded = rleDecode(rawBuffer);
+				const previous = state[key];
+				state[key] = previous ? xorReconstruct(previous, decoded) : decoded;
+			}
+			this.statusBuffers.set(ecid, state);
+			if (file.sizeFull && file.sizeFull > 0) file.chunkInfo = computeChunkInfo(file.sizeFull, state);
+			this.applySourceNameEntries(ecid, sourceNameEntriesFromFileTag(fileTag));
+			const nameMap = this.sourceNames.get(ecid);
+			if (nameMap) file.sourceNames = [...nameMap.values()];
+		}
+	}
+	/**
+	* Apply source-names map diffs: new entry (carries the name), count change
+	* (no name resent) or removal (count 0).
+	*/
+	applySourceNameEntries(ecid, entries) {
+		if (!entries) return;
+		const nameMap = this.sourceNames.get(ecid) || /* @__PURE__ */ new Map();
+		for (const entry of entries) {
+			if (entry.count === 0) {
+				nameMap.delete(entry.id);
+				continue;
+			}
+			const existing = nameMap.get(entry.id);
+			if (existing) {
+				existing.count = entry.count;
+				if (entry.name !== void 0) existing.name = entry.name;
+			} else if (entry.name !== void 0) nameMap.set(entry.id, {
+				name: entry.name,
+				count: entry.count
+			});
+		}
+		this.sourceNames.set(ecid, nameMap);
+	}
+	/**
+	* Group clients by the download they are requesting (client.requestFileId -> file.ecid).
+	*/
+	attachSources() {
+		for (const file of this.downloads.values()) file.sources = [];
+		for (const client of this.clients.values()) {
+			const requestFileId = toOptionalNumber(client.requestFileId);
+			if (requestFileId === void 0) continue;
+			const file = this.downloads.get(requestFileId);
+			if (file) file.sources.push(client);
+		}
+	}
+};
+//#endregion
+export { UpdateState };

package/dist/index.d.ts

@@ -125,7 +125,9 @@ interface AmuleUpDownClient {
   serverIP?: string;
   serverPort?: number;
   serverName?: string;
+  /** Upload speed towards this client, in bytes/s */
   upSpeed?: number;
+  /** Download speed from this client, in bytes/s (the daemon sends kB/s; normalized on parse) */
   downSpeed?: number;
   uploadSession?: number;
   transferredDown?: number;
@@ -824,11 +826,18 @@ declare class StringTag extends Tag<string> {
   parseValue(value: Buffer): void;
   encodeValue(): Buffer;
 }
-declare class DoubleTag extends Tag<number> {
+/**
+ * EC_TAGTYPE_DOUBLE tags are transmitted as a null-terminated ASCII decimal string,
+ * not as a binary double (see CECTag(ec_tagname_t, double) in aMule's ECTag.cpp).
+ */
+declare class DoubleTag extends Tag<number> implements NumericTag {
   constructor(name: ECTagName, value?: number, subtags?: Tag<any>[], nameValue?: number);
   static withValue(name: ECTagName, value: number, subtags?: Tag<any>[]): DoubleTag;
   parseValue(value: Buffer): void;
   encodeValue(): Buffer;
+  getShort(): number;
+  getInt(): number;
+  getLong(): bigint;
 }
 interface Ipv4Value {
   address: string;
@@ -957,6 +966,14 @@ declare class AmuleClient {
    * Get server statistics
    */
   getStats(): Promise<StatsResponse>;
+  /**
+   * Per-connection file-detail state (diff baselines, source names, merged snapshots).
+   * The daemon diffs per connection and shares the diff state between the update,
+   * download-queue and shared-files requests, so this state must be fed by all of
+   * them (see UpdateState). Call only after sendRequest: connecting may have started
+   * a new session, which invalidates the previous state.
+   */
+  private getFileState;
   /**
    * Get updates for files, clients, servers, and friends.
    *
@@ -1005,7 +1022,12 @@ declare class AmuleClient {
    */
   downloadEd2kLink(link: string): Promise<void>;
   /**
-   * Get download queue
+   * Get download queue (EC_OP_GET_DLOAD_QUEUE, full detail).
+   *
+   * The response rebases the per-connection diff state the daemon shares with
+   * getUpdate()/getDownloadQueueWithSources(), so it is fed into the same
+   * client-side state: both methods stay consistent however they are interleaved,
+   * and chunkInfo/sourceNames are correct across repeated calls.
    */
   getDownloadQueue(): Promise<AmuleTransferringFile[]>;
   /**