@torrent-tv/proxy 2.95.8 → 2.95.10

package/bin/cli.js

@@ -24,7 +24,7 @@ import { createTunnelClient } from "../services/transport/tunnel-client.js";
 import { createWebRtcManager } from "../services/transport/webrtc-manager.js";
 import { createDataChannelHandler } from "../services/transport/data-channel-handler.js";
 import { dumpsToRemove, pruneCoreDumps } from "../services/storage/core-dumps.js";
-import { availableMemoryBytes } from "../services/storage/machine-memory.js";
+import { availableMemory } from "../services/storage/machine-memory.js";
 import { Diagnostics } from "../services/storage/Diagnostics.js";
 import { adoptOrphanRingFiles, createPacketWitness, pruneWitnessCaptures } from "../services/transport/packet-witness.js";
 import { createUsrsctpStateReader } from "../services/transport/usrsctp-state.js";
@@ -586,7 +586,7 @@ try {
       const encode = started?.outputParts?.admission?.headroom?.() ?? null;
       return {
         metrics: {
-          ...collectHealthMetrics({ availableMemoryBytes }),
+          ...collectHealthMetrics({ availableMemory }),
           ...(encode ? { encodeSpeedX: encode.encodeSpeedX, encodeOccupiedCostSec: encode.occupiedCostSec } : {})
         },
         holds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.95.8",
+  "version": "2.95.10",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "repository": {

package/server.js

@@ -494,7 +494,7 @@ export async function startProxyServer({
   });
   const indexMemory = new IndexMemory({
     reviseBudget: () => { void outputParts.machineBudget.revise().catch(error => logger.warn(`packet index budget: ${error.message}`)); },
-    changed: () => { mediaReads.memoryChanged(); probeReads.memoryChanged(); }
+    changed: () => { mediaReads.memoryChanged(); probeReads.memoryChanged(); outputParts.encodeInputs?.memoryChanged(); }
   });
   const containerOver = async ({ sourceKey, fileIndex, requestId, packetInterval, demand }) => {
     const record = sourceRegistry.get(sourceKey);
@@ -531,6 +531,10 @@ export async function startProxyServer({
       onReadResult: async (statement, result, revision) => {
         if (revision.demand !== downloadMaps.epoch(sourceKey, fileIndex)) return;
         if (demand && !downloadMaps.wantsInterval(sourceKey, fileIndex, demand)) return;
+        if (statement === "keyframes" && result.kind === "result") {
+          keyframeTables.learn(params, { times: result.value?.times ?? null, tolerance: result.value?.tolerance ?? 0,
+            format: containerOrchestrator.known(sourceKey, fileIndex)?.formatName ?? "unrecognised" });
+        }
         const finished = mediaReads.record(params, statement, result, revision.storage, revision.memory);
         await downloadMaps.metadata({ sourceKey, fileIndex, statement: requestId ? `${statement}:${requestId}` : statement, result,
           ...(demand ? { priority: demand.priority, urgent: demand.urgent, deadlineAt: demand.deadlineAt, interval: demand, leadSeconds: demand.leadSeconds ?? 0 } : {}) });

package/services/encode/EncodeInputs.js

@@ -5,6 +5,7 @@ import { admitOriginalInput } from "./OriginalInput.js";
 export class EncodeInputs {
   #requests = new Map();
   #revision = 0;
+  #memoryRevision = 0;
   #held = 0;
   #allowed = 0;
   #wanted = new Map();
@@ -43,7 +44,13 @@ export class EncodeInputs {
   allow(bytes) {
     const changed = this.#allowed !== Math.max(0, bytes);
     this.#allowed = Math.max(0, bytes);
-    if (changed) this.#retryMemory();
+    if (changed) this.memoryChanged();
+  }
+
+  /** Metadata admission and input admission can change independently. */
+  memoryChanged() {
+    this.#memoryRevision++;
+    this.#retryMemory();
   }
 
   #retryMemory() {
@@ -112,6 +119,7 @@ export class EncodeInputs {
   #prepare(request) {
     request.pending = true;
     request.revision = this.#revision;
+    request.memoryRevision = this.#memoryRevision;
     request.promise = (async () => {
       const resolved = await this.#resolve(request.output, request.from, request.to);
       if (this.#requests.get(request.key) !== request) return;
@@ -133,7 +141,7 @@ export class EncodeInputs {
           return () => {
             if (!released) {
               released = true; this.#held -= bytes;
-              queueMicrotask(() => this.#retryMemory());
+              queueMicrotask(() => this.memoryChanged());
             }
           };
         }
@@ -149,7 +157,9 @@ export class EncodeInputs {
     }).finally(() => {
       request.pending = false;
       if (request.result?.kind !== "needs-memory") this.#wanted.delete(request.key);
-      if (this.#requests.get(request.key) === request && request.revision !== this.#revision &&
+      const changed = request.result?.kind === "needs-memory"
+        ? request.memoryRevision !== this.#memoryRevision : request.revision !== this.#revision;
+      if (this.#requests.get(request.key) === request && changed &&
         request.result?.kind !== "result" && request.result?.kind !== "terminal") this.#prepare(request);
     });
   }

package/services/media/KeyframeTables.js

@@ -2,6 +2,7 @@
 
 import { KeyframeTable } from "./container/KeyframeTable.js";
 import { isUnavailable } from "./container/unavailable.js";
+import { IndexMemoryUnavailable } from "./container/memory-unavailable.js";
 import { logger as defaultLogger } from "../../utils/logger.js";
 
 export class KeyframeTables {
@@ -123,6 +124,8 @@ export class KeyframeTables {
             `keyframe index "${logName}": not downloaded yet after ${Date.now() - startedMs}ms — ` +
               "read again when pieces of the file arrive"
           );
+        } else if (error instanceof IndexMemoryUnavailable) {
+          this.#logger.info(`keyframe index "${logName}": waiting for ${error.bytes} additional allocation bytes`);
         } else {
           this.#logger.warn(
             `keyframe index "${logName}": the read failed after ${Date.now() - startedMs}ms — ` +
@@ -183,7 +186,10 @@ export class KeyframeTables {
       const table = await this.read(params);
       return { table, arrived: table.answered };
     } catch (error) {
-      if (isUnavailable(error)) return { table: this.of(params), arrived: false };
+      if (isUnavailable(error) || error instanceof IndexMemoryUnavailable) {
+        const table = this.of(params);
+        return { table, arrived: table.answered };
+      }
       throw error;
     }
   }

package/services/media/container/AviContainer.js

@@ -11,6 +11,7 @@ import { ContainerTrack } from "../tracks/ContainerTrack.js";
 import { PacketIndex } from "./PacketIndex.js";
 import { openDmlPackets } from "./avi-open-dml.js";
 import { isUnavailable } from "./unavailable.js";
+import { IndexMemoryUnavailable } from "./memory-unavailable.js";
 import { Mpeg4PictureTiming } from "./mpeg4-picture-timing.js";
 import { MpegElementaryIndex } from "./mpeg-elementary-index.js";
 import { RetainedReads } from "./RetainedReads.js";
@@ -25,6 +26,7 @@ export class AviContainer extends Container {
   #tracks = null;
   #packets = null;
   #scan = null;
+  #indexed = null;
   #declarations = null;
   #workTags = null;
 
@@ -108,7 +110,7 @@ export class AviContainer extends Container {
   }
 
 
-  packetIndexBytes() { return (this.#packets ?? this.#scan?.index)?.allocatedBytes() ?? 0; }
+  packetIndexBytes() { return (this.#packets ?? this.#scan?.index ?? this.#indexed?.index)?.allocatedBytes() ?? 0; }
 
   static detect(head) {
     return isAvi(head);
@@ -221,6 +223,7 @@ export class AviContainer extends Container {
   async readPacketIndex(interval) {
     if (this.#packets) return this.#packets;
     if (this.#scan) return this.#readUnindexed(interval);
+    if (this.#indexed) return this.#readIndexed();
     const tracks = await this.readTracks();
     const { streams } = await this.#readHeaders();
     if (streams.some(stream => stream.indexChunks.length)) {
@@ -278,20 +281,30 @@ export class AviContainer extends Container {
     }
     if ((table.end - table.start) % 16 !== 0) throw new Error("AVI packet index entry is truncated.");
     const index = new PacketIndex({ packetMemory: this.packetMemory, deferMemory: true });
-    try {
     const clocks = new Map();
     const timings = new Map();
+    if (tracks.some(track => ["video", "audio", "subtitle"].includes(track.type) && !(track.timeBase > 0))) {
+      throw new Error("AVI stream time base is invalid.");
+    }
     for (const track of tracks) {
       if (!["video", "audio", "subtitle"].includes(track.type)) continue;
-      if (!(track.timeBase > 0)) throw new Error("AVI stream time base is invalid.");
       index.declareTrack(track.trackNumber, { type: track.type, codecId: track.codecId, codecRanges: streams[track.trackNumber].codecRanges });
       clocks.set(track.trackNumber, track.startTimeSeconds);
     }
-    let offsetBase = null;
-    for (let at = table.start; at < table.end; at += 16) {
+    this.#indexed = { index, clocks, timings, tracks, movi, table, offsetBase: null, at: table.start };
+    return this.#readIndexed();
+  }
+
+  async #readIndexed() {
+    const state = this.#indexed;
+    const { index, clocks, timings, tracks, movi, table } = state;
+    try {
+    index.flushPending();
+    for (; state.at < table.end;) {
+      const at = state.at;
       const entry = await this.readRange(at, at + 15);
       const chunkId = entry.toString("ascii", 0, 4);
-      if (!/^[0-9]{2}(db|dc|wb)$/.test(chunkId)) continue;
+      if (!/^[0-9]{2}(db|dc|wb)$/.test(chunkId)) { state.at += 16; continue; }
       const id = Number(chunkId.slice(0, 2));
       const track = tracks.find(track => track.trackNumber === id);
       if (!track || !clocks.has(id)) throw new Error("AVI packet refers to an undeclared stream.");
@@ -300,18 +313,19 @@ export class AviContainer extends Container {
       const length = entry.readUInt32LE(12);
       if (length === 0) {
         if (track.type === "video") { index.extendLastPresentation(id, track.timeBase); clocks.set(id, clocks.get(id) + track.timeBase); }
+        state.at += 16;
         continue;
       }
-      if (offsetBase === null) {
+      if (state.offsetBase === null) {
         for (const base of [movi.start, 0, movi.start + 4]) {
           const address = base + offset;
           if (address < movi.start + 4 || address + 8 + length > movi.end) continue;
           const probe = await this.readRange(address, address + 7);
-          if (probe.toString("ascii", 0, 4) === chunkId && probe.readUInt32LE(4) === length) { offsetBase = base; break; }
+          if (probe.toString("ascii", 0, 4) === chunkId && probe.readUInt32LE(4) === length) { state.offsetBase = base; break; }
         }
-        if (offsetBase === null) throw new Error("AVI packet index has no valid offset base.");
+        if (state.offsetBase === null) throw new Error("AVI packet index has no valid offset base.");
       }
-      const address = offsetBase + offset;
+      const address = state.offsetBase + offset;
       if (address < movi.start + 4 || address + 8 + length > movi.end) throw new Error("AVI indexed packet exceeds its media list.");
       const probe = await this.readRange(address, address + 7);
       if (probe.toString("ascii", 0, 4) !== chunkId || probe.readUInt32LE(4) !== length) throw new Error("AVI packet index disagrees with its chunk header.");
@@ -321,15 +335,21 @@ export class AviContainer extends Container {
       await this.#appendPacket(index, timings, track, { pts, duration, keyframe: track.type !== "video" || chunkId.endsWith("db") || !!(flags & 0x10),
         ranges: [[address + 8, address + 8 + length - 1]] });
       clocks.set(id, pts + duration);
+      // The pending facts own this entry even if their allocation must wait.
+      state.at += 16;
       index.flushPending();
     }
     for (const timing of timings.values()) timing.elementary?.complete();
     index.flushPending();
     for (const id of clocks.keys()) index.complete(id);
     this.#packets = index;
+    this.#indexed = null;
     return index;
     } catch (error) {
-      index.dispose();
+      if (!isUnavailable(error) && !(error instanceof IndexMemoryUnavailable)) {
+        index.dispose();
+        this.#indexed = null;
+      }
       throw error;
     }
   }

package/services/storage/machine-memory.js

@@ -1,5 +1,5 @@
 /**
- * @file How much of the machine's memory is available, read once.
+ * @file How much memory an allocation of this process could obtain, read once.
  *
  * It was written THREE TIMES, in three layers, with the same body each time:
  * `transport/health-collector.js` for the score a proxy publishes to the registry,
@@ -22,35 +22,264 @@
  * estimate of what an allocation could actually obtain. Where there is no
  * `/proc` — not Linux, or it is unreadable — `freemem` is the best answer there
  * is, and on those systems it is not misleading.
+ *
+ * **Why a container's limit as well.** `/proc/meminfo` describes the HOST. A
+ * proxy run under Docker's `--memory` or systemd's `MemoryMax=` is killed by
+ * the kernel at its cgroup's limit whatever the host has free: on 2026-10-07 a
+ * 512 MiB container was killed while this reading said 4437 MB
+ * (torrent-tv/meta#153). So the answer is the smaller of the host's figure and
+ * the room left under every memory limit on this process's cgroup path — its
+ * own and each ancestor's, because a slice limit binds every unit inside it.
+ * The proxy runs anywhere, so nothing here knows of any particular host: the
+ * cgroup is found from `/proc/self/cgroup`, and where nothing is readable the
+ * answer is the host's alone, as it always was.
+ *
+ * **The room under a limit is NOT `limit − usage`,** for the same reason the
+ * host's figure is not `freemem`: the cgroup is charged for the file pages its
+ * processes read and write, and the kernel takes those back before it kills
+ * anything. Measured in a 512 MiB container on the Home Assistant host: after a
+ * 600 MB file was written `memory.current` stood at 531 MB of 537 — 515 MB of
+ * it file cache, 0.12 MB anonymous — and a 450 MB allocation then succeeded
+ * with no OOM kill, the cache shrinking to 50 MB. `limit − usage` said 5 MB. So
+ * the reclaimable part is added back, and it is the part the kernel's own
+ * `MemAvailable` counts: the file LRU lists and reclaimable slab
+ * (`active_file`, `inactive_file`, `slab_reclaimable` in cgroup v2's
+ * `memory.stat`; v1 states the file lists hierarchically as `total_*`). The
+ * watermark share `MemAvailable` subtracts has no counterpart under a cgroup
+ * limit, which is hard, so nothing is subtracted for it.
  */
 
 import { readFileSync } from "node:fs";
 import os from "node:os";
 
 /**
- * What the machine could give an allocation right now.
+ * Where each cgroup version keeps its memory controller, and under which names.
+ *
+ * Version 1 states the file lists of the cgroup alone as `active_file` and of
+ * it with its descendants as `total_active_file`; its usage includes the
+ * descendants, so the hierarchical figures are the ones that subtract from it.
+ */
+const HIERARCHIES = {
+  1: {
+    mount: "/sys/fs/cgroup/memory",
+    limit: "memory.limit_in_bytes",
+    usage: "memory.usage_in_bytes",
+    reclaimable: ["total_active_file", "total_inactive_file"]
+  },
+  2: {
+    mount: "/sys/fs/cgroup",
+    limit: "memory.max",
+    usage: "memory.current",
+    reclaimable: ["active_file", "inactive_file", "slab_reclaimable"]
+  }
+};
+
+/**
+ * @typedef {Object} MemoryReading
+ * @property {number} bytes - What an allocation could obtain right now.
+ * @property {"cgroup v2" | "cgroup v1" | "MemAvailable" | "freemem"} source -
+ *   Which reading decided `bytes`: a container's limit, the kernel's own
+ *   estimate for the host, or free memory where that estimate was unreadable.
+ * @property {number | null} limitBytes - The smallest memory limit in force on
+ *   this process's cgroup path, or null where there is none. Reported whether
+ *   or not it decided, so a log says that a limit exists.
+ * @property {number} totalBytes - The most this process could ever hold: the
+ *   limit where there is one, the host's memory otherwise.
+ */
+
+/**
+ * What an allocation of this process could obtain right now.
  *
- * @returns {{ bytes: number, measured: boolean }} `measured` is false where the
- *   kernel's own estimate was not available, so a caller that prints the figure
- *   can say which of the two it is holding.
+ * @param {Object} [options]
+ * @param {(path: string) => string} [options.readFile] - Reads a file as text,
+ *   throwing where it is absent or unreadable; injected by the checks.
+ * @returns {MemoryReading}
  */
-export function availableMemory() {
+export function availableMemory({ readFile = (path) => readFileSync(path, "utf8") } = {}) {
+  const hostTotal = os.totalmem();
+  const host = hostAvailable(readFile);
+  const container = containerRoom(readFile, hostTotal);
+  if (container !== null && container.roomBytes < host.bytes) {
+    return {
+      bytes: container.roomBytes,
+      source: `cgroup v${container.version}`,
+      limitBytes: container.limitBytes,
+      totalBytes: container.limitBytes
+    };
+  }
+  return {
+    bytes: host.bytes,
+    source: host.source,
+    limitBytes: container?.limitBytes ?? null,
+    totalBytes: container?.limitBytes ?? hostTotal
+  };
+}
+
+/**
+ * What an allocation of this process could obtain right now, as a plain number.
+ *
+ * @returns {number}
+ */
+export function availableMemoryBytes() {
+  return availableMemory().bytes;
+}
+
+/**
+ * The host's own estimate, or its free memory where the estimate is unreadable.
+ *
+ * @param {(path: string) => string} readFile
+ * @returns {{ bytes: number, source: "MemAvailable" | "freemem" }}
+ */
+function hostAvailable(readFile) {
   try {
-    const match = /^MemAvailable:\s+(\d+)\s+kB$/m.exec(readFileSync("/proc/meminfo", "utf8"));
+    const match = /^MemAvailable:\s+(\d+)\s+kB$/m.exec(readFile("/proc/meminfo"));
     if (match) {
-      return { bytes: Number(match[1]) * 1024, measured: true };
+      return { bytes: Number(match[1]) * 1024, source: "MemAvailable" };
     }
   } catch {
     // silent-ok: not Linux, or /proc is not readable.
   }
-  return { bytes: os.freemem(), measured: false };
+  return { bytes: os.freemem(), source: "freemem" };
+}
+
+/**
+ * The room left under every memory limit on this process's cgroup path.
+ *
+ * @param {(path: string) => string} readFile
+ * @param {number} hostTotal - The host's memory; a limit at or above it cannot
+ *   be reached by memory use, which is how cgroup v1 says "no limit".
+ * @returns {{ version: 1 | 2, roomBytes: number, limitBytes: number } | null}
+ *   Null where no limit is in force or nothing is readable.
+ */
+function containerRoom(readFile, hostTotal) {
+  let membership;
+  try {
+    membership = ownCgroup(readFile("/proc/self/cgroup"));
+  } catch {
+    return null; // silent-ok: not Linux, or /proc is not readable.
+  }
+  if (membership === null) {
+    return null;
+  }
+  const hierarchy = HIERARCHIES[membership.version];
+  let found = null;
+  for (const directory of levelsOf(hierarchy.mount, membership.path)) {
+    const level = roomAt(readFile, hierarchy, directory, hostTotal);
+    if (level === null) {
+      continue;
+    }
+    found = {
+      version: membership.version,
+      roomBytes: Math.min(found?.roomBytes ?? Infinity, level.roomBytes),
+      limitBytes: Math.min(found?.limitBytes ?? Infinity, level.limitBytes)
+    };
+  }
+  return found;
 }
 
 /**
- * What the machine could give an allocation right now, as a plain number.
+ * Which cgroup this process is in, for the memory controller.
  *
+ * A host in hybrid mode lists both versions; the memory controller is then on
+ * version 1, named in the line that lists it.
+ *
+ * @param {string} text - `/proc/self/cgroup`.
+ * @returns {{ version: 1 | 2, path: string } | null}
+ */
+function ownCgroup(text) {
+  for (const line of text.split("\n")) {
+    const match = /^\d+:([^:]*):(.*)$/.exec(line);
+    if (match && match[1].split(",").includes("memory")) {
+      return { version: 1, path: match[2] };
+    }
+  }
+  const unified = /^0::(.*)$/m.exec(text);
+  return unified ? { version: 2, path: unified[1] } : null;
+}
+
+/**
+ * The cgroup's own directory and each ancestor's, up to the mount.
+ *
+ * The own directory may be absent: Docker on cgroup v1 names the host's path
+ * while mounting the container's own directory at the root. The mount is
+ * always on the list, so in that case it is what is read. A path with `..` is
+ * a cgroup outside this namespace's root, which nothing under the mount
+ * describes, so nothing is read for it and the host's figure stands.
+ *
+ * @param {string} mount
+ * @param {string} path
+ * @returns {string[]}
+ */
+function levelsOf(mount, path) {
+  const parts = path.split("/").filter(Boolean);
+  if (parts.includes("..")) {
+    return [];
+  }
+  const levels = [];
+  for (let depth = parts.length; depth >= 0; depth -= 1) {
+    levels.push([mount, ...parts.slice(0, depth)].join("/"));
+  }
+  return levels;
+}
+
+/**
+ * The limit in one cgroup directory and the room left under it.
+ *
+ * @param {(path: string) => string} readFile
+ * @param {(typeof HIERARCHIES)[1]} hierarchy
+ * @param {string} directory
+ * @param {number} hostTotal
+ * @returns {{ roomBytes: number, limitBytes: number } | null} Null where this
+ *   level states no limit — `max`, the version 1 sentinel — or is not there.
+ */
+function roomAt(readFile, hierarchy, directory, hostTotal) {
+  let limitBytes;
+  let usageBytes;
+  try {
+    limitBytes = bytesOf(readFile(`${directory}/${hierarchy.limit}`));
+    usageBytes = bytesOf(readFile(`${directory}/${hierarchy.usage}`));
+  } catch {
+    return null; // silent-ok: no such level, or no memory controller on it.
+  }
+  if (!Number.isFinite(limitBytes) || limitBytes >= hostTotal || !Number.isFinite(usageBytes)) {
+    return null;
+  }
+  let reclaimableBytes = 0;
+  try {
+    reclaimableBytes = statSum(readFile(`${directory}/memory.stat`), hierarchy.reclaimable);
+  } catch {
+    // silent-ok: counting nothing as reclaimable understates the room, which
+    // errs away from the kill this reading exists to avoid.
+  }
+  return { limitBytes, roomBytes: Math.max(0, limitBytes - usageBytes + reclaimableBytes) };
+}
+
+/**
+ * A byte count written by the kernel, or NaN for anything else (`max`).
+ *
+ * @param {string} text
  * @returns {number}
  */
-export function availableMemoryBytes() {
-  return availableMemory().bytes;
+function bytesOf(text) {
+  const trimmed = text.trim();
+  return /^\d+$/.test(trimmed) ? Number(trimmed) : Number.NaN;
+}
+
+/**
+ * The sum of the named fields of a `memory.stat`.
+ *
+ * @param {string} text
+ * @param {string[]} names
+ * @returns {number}
+ */
+function statSum(text, names) {
+  let sum = 0;
+  for (const line of text.split("\n")) {
+    const [name, value = ""] = line.split(" ");
+    if (names.includes(name)) {
+      const bytes = bytesOf(value);
+      sum += Number.isFinite(bytes) ? bytes : 0;
+    }
+  }
+  return sum;
 }

package/services/storage/memory-report.js

@@ -168,13 +168,6 @@ export async function readMappingSummary() {
   return null;
 }
 
-/**
- * Available memory, from the one place that reads it.
- *
- * @returns {{ bytes: number, measured: boolean }}
- */
-export { availableMemory };
-
 /**
  * Anonymous memory this process holds, from the kernel's own rollup.
  *
@@ -254,8 +247,8 @@ function megabytes(bytes) {
  * @param {"process" | "thread"} [reading.scope]
  * @param {string} [reading.label] - Which thread the isolate figures are of.
  * @param {{ rss: number, heapUsed: number, heapTotal: number, external: number, arrayBuffers: number }} reading.process
- * @param {number} [reading.availableBytes]
- * @param {boolean} [reading.availableMeasured]
+ * @param {import("./machine-memory.js").MemoryReading} [reading.available] -
+ *   What an allocation could obtain, and which reading decided it.
  * @param {number | null} [reading.anonymousBytes]
  * @param {ReturnType<typeof summariseMappings> | null} [reading.mappings]
  * @param {number | null} [reading.diskFreeBytes]
@@ -272,8 +265,7 @@ export function describeMemory({
   scope = "process",
   label = "",
   process: usage,
-  availableBytes,
-  availableMeasured,
+  available,
   anonymousBytes = null,
   mappings = null,
   diskFreeBytes = null,
@@ -312,13 +304,32 @@ export function describeMemory({
     `memory: rss=${megabytes(usage.rss)} ${isolate}` +
     `${anonymousBytes === null ? "" : ` anon=${megabytes(anonymousBytes)}`}${shape}; ` +
     `${storesPart}; ` +
-    `machine has ${megabytes(availableBytes ?? 0)} available` +
-    `${availableMeasured ? "" : " (estimated — /proc/meminfo could not be read)"}` +
+    describeAvailable(available) +
     `${diskFreeBytes === null ? "" : `, ${megabytes(diskFreeBytes)} free on disk`}` +
     tail
   );
 }
 
+/**
+ * What an allocation could obtain, with the reading that decided it and the
+ * container's limit, so a log says whether a limit is in force.
+ *
+ * @param {import("./machine-memory.js").MemoryReading | undefined} available
+ * @returns {string}
+ */
+function describeAvailable(available) {
+  if (!available) {
+    return "available memory not read";
+  }
+  const decided = available.source === "freemem"
+    ? "estimated from free memory — /proc/meminfo could not be read"
+    : `${available.source} decides`;
+  const limit = available.limitBytes === null
+    ? "no container limit"
+    : `container limit ${megabytes(available.limitBytes)}`;
+  return `machine has ${megabytes(available.bytes)} available (${decided}; ${limit})`;
+}
+
 /**
  * The figures whose movement earns a line, each under its own name.
  *
@@ -540,14 +551,13 @@ export function startMemoryReport({
           // mapping and a busy process has thousands; the rollup and
           // `/proc/meminfo` are single lines but still walk page tables, and
           // the reading now happens once a second rather than once a minute.
-          const { bytes, measured } = await availableMemory();
+          const available = availableMemory();
           anonymousBytes = await readAnonymousMemory();
           log(describeMemory({
             scope,
             label,
             process: processMemory,
-            availableBytes: bytes,
-            availableMeasured: measured,
+            available,
             anonymousBytes,
             mappings: await readMappingSummary(),
             diskFreeBytes: diskPath ? await readDiskFree(diskPath) : null,

package/services/transport/health-collector.js

@@ -16,16 +16,19 @@ import os from "node:os";
  *   Suitable as input to `Math.max(0, 1 - Math.min(1, cpuLoad))` for a
  *   normalised "CPU availability" score.
  *
- * `memFree`  — fraction of total system RAM that could still be given out
- *   (0–1). The reading is the storage component's (`storage/machine-memory.js`
- *   says why that is not the same as free memory), handed in.
+ * `memFree`  — fraction of the memory this process could ever hold that could
+ *   still be given out (0–1): of a container's limit where one is in force, of
+ *   the host's RAM otherwise — divided by the host's RAM, a 512 MiB container
+ *   with half its limit free read as nearly full. The reading is the storage
+ *   component's (`storage/machine-memory.js` says why that is not the same as
+ *   free memory), handed in.
  *
  * `uptime`   — process uptime in whole seconds (useful for preferring
  *   already-warmed proxies over freshly started ones).
  *
  * @typedef {Object} HealthMetrics
  * @property {number} cpuLoad - 1-min load avg / cpu-count.  0 = idle, 1 = saturated, >1 = overloaded.
- * @property {number} memFree - Memory an allocation could obtain, as a fraction of total RAM (0–1).
+ * @property {number} memFree - Memory an allocation could obtain, as a fraction of the most this process could hold (0–1).
  * @property {number} uptime  - Process uptime in seconds.
  */
 
@@ -36,14 +39,16 @@ import os from "node:os";
  * diff noise when serialising to JSON across the tunnel.
  *
  * @param {object} params
- * @param {() => number} params.availableMemoryBytes - What the machine could
- *   give an allocation right now; the storage component's reading.
+ * @param {() => { bytes: number, totalBytes: number }} params.availableMemory -
+ *   What an allocation could obtain right now and the most this process could
+ *   ever hold; the storage component's reading.
  * @returns {HealthMetrics}
  */
-export function collectHealthMetrics({ availableMemoryBytes }) {
+export function collectHealthMetrics({ availableMemory }) {
   const cpuCount = os.cpus().length || 1;
   const cpuLoad = os.loadavg()[0] / cpuCount;
-  const memFree = availableMemoryBytes() / os.totalmem();
+  const { bytes, totalBytes } = availableMemory();
+  const memFree = bytes / totalBytes;
 
   return {
     cpuLoad: Math.round(cpuLoad * 1000) / 1000,