@torrent-tv/proxy 2.101.9 → 2.101.11

package/package.json

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

package/server.js

@@ -1068,6 +1068,7 @@ export async function startProxyServer({
     // seconds into bytes, what to ask the swarm for, what to keep in memory —
     // is its own business.
     setDownloadRate: (bytesPerSecond, because) => torrentPool.setDownloadRate?.(bytesPerSecond, because),
+    setSpeculativeHold: (held, because) => torrentPool.setSpeculativeHold?.(held, because),
     setPriorityMap: async ({ sourceKey, fileIndex, durationSeconds, zones }) => {
       void sourcePreparation?.refresh();
       const record = sourceRegistry.get(sourceKey);

package/services/encode/EncodeOrchestrator.js

@@ -152,6 +152,23 @@ export class EncodeOrchestrator {
    */
   #pauseRule = new PauseRule();
 
+  /**
+   * Whether the run a viewer needs first is short of the processor, from the
+   * last time who has the processor was decided (`processorShortfall`).
+   *
+   * @type {{ address: string, speed: { middle: number, scatter: number }, need: number, seconds: number,
+   *   waitedFor?: number } | null}
+   */
+  #shortfall = null;
+
+  /**
+   * The piece each waiting viewer's start is held by the production of, as
+   * the start forecast last said it (`noteViewerWaiting`), by viewer.
+   *
+   * @type {Map<string, { address: string, index: number }>}
+   */
+  #viewersWaiting = new Map();
+
   /**
    * What starting and stopping an encoder was measured to cost on this host,
    * before any viewer existed. Told once; real runs replace it as they end.
@@ -238,6 +255,8 @@ export class EncodeOrchestrator {
    * @param {{ freeCores: () => number | null, otherCores: () => number | null } | null} [params.processor] -
    *   The processor left free and the processor other work takes, in cores
    *   (`ProcessorBudget`); absent, both are unknown.
+   * @param {() => void} [params.shortfallNoted] - Told each time who has the
+   *   processor was decided, so the download can read `processorShortfall`.
    */
   constructor({
     maxRunsFor,
@@ -253,6 +272,7 @@ export class EncodeOrchestrator {
     describeWaits = null,
     admission = null,
     processor = null,
+    shortfallNoted = null,
     logger,
     now
   }) {
@@ -262,6 +282,7 @@ export class EncodeOrchestrator {
     // is about one output, and then only the per-output limit binds.
     this.admission = admission && typeof admission.placesFor === "function" ? admission : null;
     this.processor = processor && typeof processor.freeCores === "function" ? processor : null;
+    this.shortfallNoted = typeof shortfallNoted === "function" ? shortfallNoted : () => undefined;
     this.#describeWaits = typeof describeWaits === "function" ? describeWaits : () => "";
     // Only the segment facts and operations this planner needs cross the
     // storage boundary; the concrete storage remains in the server assembly.
@@ -443,6 +464,7 @@ export class EncodeOrchestrator {
     this.#lastError.delete(address);
     this.#lastProgress.delete(address);
     this.#failedStarts.delete(address);
+    this.#forgetWaitsOn(address);
   }
 
   /** @param {string} address @returns {{ at: number, count: number, blocked: boolean, limit: number }} */
@@ -598,6 +620,37 @@ export class EncodeOrchestrator {
     // right whatever the last one met.
     if (!Array.isArray(zones) || zones.length === 0) {
       this.#forgetInputState(address);
+      this.#forgetWaitsOn(address);
+    }
+  }
+
+  /**
+   * What a viewer's start waits for, as the start forecast says each time it
+   * is asked: the production of piece `index` of `address`, or nothing an
+   * encoder makes (null). The map's deadlines can be met while the forecast
+   * still holds the viewer for the stock it wants after the piece they stand
+   * in: on Home Assistant (r87, torrent-tv/meta#180) the download was let go
+   * 5.3 s before a seek's viewer started, while the forecast held them for
+   * the production of the next piece. Who has the processor is decided again
+   * when it changes.
+   *
+   * @param {string} viewer
+   * @param {{ address: string, index: number } | null} wait
+   */
+  noteViewerWaiting(viewer, wait) {
+    const said = this.#viewersWaiting.get(viewer) ?? null;
+    const next = typeof wait?.address === "string" && Number.isInteger(wait.index)
+      ? { address: wait.address, index: wait.index } : null;
+    if (said?.address === next?.address && said?.index === next?.index) return;
+    if (next) this.#viewersWaiting.set(viewer, next);
+    else this.#viewersWaiting.delete(viewer);
+    this.shareTheMachine();
+  }
+
+  /** @param {string} address */
+  #forgetWaitsOn(address) {
+    for (const [viewer, wait] of this.#viewersWaiting) {
+      if (wait.address === address) this.#viewersWaiting.delete(viewer);
     }
   }
 
@@ -720,12 +773,21 @@ export class EncodeOrchestrator {
     const leading = this.#leadingBand();
     this.#leading = leading;
     if (!leading) {
+      this.#noteShortfall(null);
       this.#placeHeldBack(null);
       return;
     }
     const now = this.now();
     const running = this.#runningNow();
     const need = this.#needOf(leading);
+    // Only a run in a band a viewer is in can be short for a viewer, and a run
+    // making a piece the start forecast holds a viewer for needs all it can
+    // make, whatever the map's deadlines say.
+    const waited = this.#runAViewerWaitsFor();
+    const judged = waited ?? (leading.urgent === true ? leading : null);
+    const short = judged
+      ? this.#pauseRule.shortfall({ leader: judged.run, need: waited ? Number.POSITIVE_INFINITY : need }) : null;
+    this.#noteShortfall(short ? { address: judged.address, ...short, ...(waited ? { waitedFor: waited.index } : {}) } : null);
     const free = this.#processorReading("freeCores");
     const others = this.#processorReading("otherCores");
     for (const [address, runs] of this.#runs) {
@@ -752,6 +814,46 @@ export class EncodeOrchestrator {
     this.#placeHeldBack(leading);
   }
 
+  /**
+   * The live run making a piece the start forecast holds a viewer for, the
+   * most urgent if there are several; null where none is.
+   *
+   * @returns {{ address: string, index: number, run: object, band: { urgent: boolean, priority: number } } | null}
+   */
+  #runAViewerWaitsFor() {
+    let found = null;
+    for (const { address, index } of this.#viewersWaiting.values()) {
+      for (const run of this.#runs.get(address) ?? []) {
+        if (!run.isAlive || run.isStopping || run.isSuspended === true || index < run.head || index > run.to) continue;
+        const band = this.#bandAt(address, run.head);
+        if (!found || compareUrgency(band, found.band) < 0) found = { address, index, run, band };
+      }
+    }
+    return found;
+  }
+
+  /**
+   * Whether the run a viewer needs first is short of the processor, and by
+   * what: its output, the speed it made over its seconds kept (median and
+   * scatter) and the speed its deadlines need, infinite where a viewer waits
+   * for it (`PauseRule.shortfall`, torrent-tv/meta#180). The run the start
+   * forecast holds a viewer for is judged before the map's leader, and names
+   * the piece it is waited for by (`waitedFor`). Null where it is not short,
+   * or nothing measured it.
+   *
+   * @returns {{ address: string, speed: { middle: number, scatter: number }, need: number, seconds: number,
+   *   waitedFor?: number } | null}
+   */
+  processorShortfall() {
+    return this.#shortfall;
+  }
+
+  /** @param {{ address: string, speed: { middle: number, scatter: number }, need: number, seconds: number, waitedFor?: number } | null} short */
+  #noteShortfall(short) {
+    this.#shortfall = short;
+    this.shortfallNoted();
+  }
+
   /**
    * One second of each encoder's processor and speed, by process
    * (`storage/processor-report.js`): what `PauseRule` judges from. Who has the

package/services/encode/PauseRule.js

@@ -198,6 +198,29 @@ export class PauseRule {
     return { runs: true, because: measured };
   }
 
+  /**
+   * Whether the leader is short of the processor: its last second made film
+   * without waiting for its input, and over the seconds kept it made less than
+   * its need — anything at all where a viewer waits for it. Null where it is
+   * not short, waits for its input, or has fewer seconds than a median is
+   * taken from (torrent-tv/meta#180, phase 5: what the download's speculative
+   * levels give way to).
+   *
+   * @param {object} params
+   * @param {object} params.leader
+   * @param {number} params.need - `s*`, as for `judge`.
+   * @returns {{ speed: { middle: number, scatter: number }, need: number, seconds: number } | null}
+   */
+  shortfall({ leader, need }) {
+    const kept = this.#seconds.get(leader) ?? [];
+    if (!(need > 0) || kept.length === 0 || kept.at(-1).waiting) return null;
+    const lead = kept.filter((second) => !second.waiting && second.speed !== null);
+    if (lead.length < LEAST_SECONDS) return null;
+    const speed = middleAndScatter(lead.map((second) => second.speed));
+    if (Number.isFinite(need) && speed.middle >= need) return null;
+    return { speed, need, seconds: lead.length };
+  }
+
   /**
    * Whether a run not started yet, on `address` and less urgent than
    * `leader`, would be let go at once: a start the rule would pause is not

package/services/encode/quality/HostLoad.js

@@ -123,6 +123,15 @@ export class HostLoad {
   /** @type {number[]} Recent readings behind that median. */
   #torrentCostReadings = [];
 
+  /**
+   * What every torrent carried per interval, in bytes per second: in all, and
+   * over the time our selection held no connection back (`SelectionLimit`).
+   * Kept as readings for `swarmRate`.
+   *
+   * @type {{ carried: number[], unheld: number[] }}
+   */
+  #swarmReadings = { carried: [], unheld: [] };
+
   /**
    * The share of the machine this process draws with nothing encoding and the
    * torrents moving nothing — the spending that would have happened anyway.
@@ -264,6 +273,7 @@ export class HostLoad {
     // worker starts its clock again: such an interval says nothing.
     if (!(elapsedSec > 0) || megabytes < 0 || now.threadCpuSeconds < previous.threadCpuSeconds) return;
     const cpuSeconds = (now.threadCpuSeconds - previous.threadCpuSeconds) / Math.max(1, os.cpus().length);
+    this.#noteSwarm(now, previous, megabytes * 1e6 / elapsedSec);
     const limit = this.downloadLimit;
     // What else the thread moved over the same interval, across every torrent:
     // sent back to the swarm, and handed to readers (encoder inputs, container
@@ -311,6 +321,39 @@ export class HostLoad {
     );
   }
 
+  /**
+   * What the swarm can give every torrent, in bytes per second: the median of
+   * what it carried while our selection held no connection back, but never
+   * less than the median of what it carried in all — the same choice the
+   * start forecast makes for one source (`ViewerRequests` `sourceService`).
+   * Time our selection held a connection back measures our asking, not the
+   * swarm, so holding the speculative levels back does not lower it
+   * (torrent-tv/meta#180). Null before any interval was read.
+   *
+   * @returns {number | null}
+   */
+  swarmRate() {
+    const carried = medianOf(this.#swarmReadings.carried);
+    const unheld = medianOf(this.#swarmReadings.unheld);
+    if (carried === null && unheld === null) return null;
+    return Math.max(carried ?? 0, unheld ?? 0);
+  }
+
+  /**
+   * @param {{ selection: { freeBytes?: number, freeMs?: number } | null }} now
+   * @param {{ selection: { freeBytes?: number, freeMs?: number } | null }} previous
+   * @param {number} carried - Bytes per second over the interval, every torrent.
+   */
+  #noteSwarm(now, previous, carried) {
+    this.#swarmReadings.carried = [...this.#swarmReadings.carried, carried].slice(-READINGS_KEPT);
+    const freeMs = (now.selection?.freeMs ?? 0) - (previous.selection?.freeMs ?? 0);
+    const freeBytes = (now.selection?.freeBytes ?? 0) - (previous.selection?.freeBytes ?? 0);
+    // Totals that went back belong to a torrent that left: nothing to read.
+    if (freeMs > 0 && freeBytes >= 0) {
+      this.#swarmReadings.unheld = [...this.#swarmReadings.unheld, freeBytes * 1000 / freeMs].slice(-READINGS_KEPT);
+    }
+  }
+
   /**
    * What the torrent thread draws in an interval that downloaded nothing.
    *

package/services/server/ViewerRequests.js

@@ -790,6 +790,11 @@ export class ViewerRequests {
       })}`);
     }
     this.#sayHolding(session, consumerId, measurement, forecast, input, now);
+    // The encoder this viewer waits for, told to whoever shares the processor
+    // (torrent-tv/meta#180): the forecast knows it before the map's deadlines do.
+    const holding = forecast.holdingBy;
+    this.#host.noteViewerWaiting?.(consumerId || session.id,
+      holding?.kind === "production" ? { address: holding.track, index: holding.segment } : null);
     return forecast;
   }
 

package/services/server/wire-outputs.js

@@ -205,6 +205,7 @@ export function wireOutputs({
     getSourceStats = null,
     setPriorityMap = null,
     setDownloadRate = null,
+    setSpeculativeHold = null,
     // What a second job costs on this host, measured at startup. Null when it
     // could not be measured, and then nothing is corrected — the alternative
     // is inventing a penalty, which is the same fault as inventing a fill rate.
@@ -630,6 +631,7 @@ export function wireOutputs({
     disposeSession: (...args) => parts.lifecycle.disposeSession(...args),
     planEncodersSoon: (...args) => parts.encodeRuns.planEncodersSoon(...args),
     waitUntilReady: (...args) => parts.serving.waitUntilReady(...args),
+    noteViewerWaiting: (viewer, wait) => parts.encodeOrchestrator?.noteViewerWaiting(viewer, wait),
     get encodeRuns() { return parts.encodeRuns; },
     // When this viewer's playback can start and run to the end: the viewer
     // component's forecast, which models the viewer's browser.
@@ -753,6 +755,49 @@ export function wireOutputs({
     void Promise.resolve(parts.setDownloadRate(share.bytesPerSecond, `film speed ${share.filmSpeed.toFixed(2)}x ` +
       `over ${watched.length} file(s), ${Math.round(share.capacity * 100)}% of the machine for the proxy`)).catch(() => {});
   };
+  parts.setSpeculativeHold = typeof setSpeculativeHold === "function" ? setSpeculativeHold : null;
+  // THE DOWNLOAD GIVES WAY TO THE ENCODER A VIEWER NEEDS FIRST
+  // (torrent-tv/meta#180, phase 5). While that encoder makes film on the
+  // processor and less than its deadlines need, what nobody needs yet — the
+  // film's tail, the gap behind a seek — is not downloaded, so the torrent
+  // thread's processor goes to it. Only where the swarm gives more than the
+  // film needs at the speed asked of it (its need, or with a viewer waiting
+  // what it makes up to its scatter): then every byte an encoder will reach
+  // still comes first and in time, and nothing is lost by not fetching ahead.
+  // Where the swarm is slower than that, the bytes fetched ahead are what the
+  // film will play from, and they are fetched. Decided each time who has the
+  // processor is decided and each time the machine is read.
+  parts.speculativeHeld = false;
+  parts.applySpeculativeHold = () => {
+    if (!parts.setSpeculativeHold || !parts.hostLoad || !parts.encodeOrchestrator) return;
+    const short = parts.encodeOrchestrator.processorShortfall();
+    let held = false;
+    let because = "the encoder a viewer needs first is not short of the processor";
+    if (short) {
+      const output = parts.outputs.outputsOn(short.address)[0] ?? null;
+      const length = Number(output?.file?.lengthBytes ?? parts.hostLoad.fileLengthByKey.get(output?.file?.key));
+      const bytesPerFilmSecond = length / Number(output?.file?.durationSeconds);
+      const asked = Number.isFinite(short.need) ? short.need : short.speed.middle + short.speed.scatter;
+      const needs = bytesPerFilmSecond * asked;
+      const swarm = parts.hostLoad.swarmRate();
+      const made = `the encoder a viewer needs first made ${short.speed.middle.toFixed(2)}x ` +
+        `(scatter ${short.speed.scatter.toFixed(2)}) over ${short.seconds}s` +
+        (Number.isFinite(short.need) ? `, needing ${short.need.toFixed(2)}x` : " with a viewer waiting") +
+        (Number.isInteger(short.waitedFor) ? ` for its #${short.waitedFor} by the start forecast` : "");
+      if (!Number.isFinite(needs) || needs <= 0) {
+        because = `${made}; its film's bytes per second are unknown`;
+      } else if (swarm === null) {
+        because = `${made}; the swarm's rate is not measured yet`;
+      } else {
+        held = swarm > needs;
+        because = `${made}; the swarm gives ${(swarm / 1e6).toFixed(2)} MB/s, ` +
+          `${held ? "more than" : "not more than"} the ${(needs / 1e6).toFixed(2)} MB/s its film needs at ${asked.toFixed(2)}x`;
+      }
+    }
+    if (held === parts.speculativeHeld) return;
+    parts.speculativeHeld = held;
+    void Promise.resolve(parts.setSpeculativeHold(held, because)).catch(() => {});
+  };
   // The one owner of what the processor gives the encoders: the share of the
   // machine other work leaves and the measured contention penalties, read by
   // every place that decides on the processor (torrent-tv/meta#180).
@@ -1090,6 +1135,7 @@ export function wireOutputs({
     // The processor left free and what other work takes, for the pause rule
     // (torrent-tv/meta#180, phase 4).
     processor: parts.processor,
+    shortfallNoted: () => parts.applySpeculativeHold?.(),
     startingSpeedFor: (address) => parts.encodeCost.speedForOutput(address),
     segmentCoverage,
     // HOW IT ASKS TO DECIDE AGAIN. A plan that refuses to place anything
@@ -1257,7 +1303,11 @@ export function wireOutputs({
     liveConsumers: (...args) => parts.renditions.liveConsumers(...args),
     liveRunsOf: (...args) => parts.encodeRuns.liveRunsOf(...args),
     producedNumbers: (...args) => parts.serving.producedNumbers(...args),
-    reportHostLoad: async (...args) => { await parts.hostLoad.reportHostLoad(...args); parts.applyDownloadShare?.(); },
+    reportHostLoad: async (...args) => {
+      await parts.hostLoad.reportHostLoad(...args);
+      parts.applyDownloadShare?.();
+      parts.applySpeculativeHold?.();
+    },
     runStateOf: (...args) => parts.encodeRuns.runStateOf(...args),
     sampleDownloadRates: (...args) => parts.hostLoad.sampleDownloadRates(...args),
     get encodeCost() { return parts.encodeCost; },

package/services/torrent/download/registry.js

@@ -30,6 +30,12 @@ let futurePending = null;
 let publishingSelections = false;
 /** What the last reconciliation told the swarm to fetch first, for the pool to say. */
 let firstClassStated = "none";
+/**
+ * Whether the speculative levels are held back for the processor: the encoder
+ * a viewer needs first is short of it, and the swarm gives more than its film
+ * needs (`holdSpeculative`, torrent-tv/meta#180).
+ */
+let speculativeHeld = false;
 
 /**
  * The last forecast that finished on the maps it was begun on: its result, the
@@ -222,6 +228,26 @@ export function firstClassStatement() {
   return firstClassStated;
 }
 
+/**
+ * Hold the speculative levels back, or let them go again, on every torrent.
+ *
+ * Downloading what nobody needs yet takes the torrent thread's processor
+ * (Home Assistant r84: 9-19 % of the machine while it downloaded 7-14 MB/s
+ * and handed readers about 0.5 MB/s in most intervals, with 0-6 % of the
+ * machine free). The side that measures the encoders decides when that processor is
+ * worth more to them (torrent-tv/meta#180, phase 5); the urgent levels are
+ * never held, so every byte an encoder will reach is still asked for first.
+ *
+ * @param {boolean} held
+ * @returns {boolean} Whether this changed anything.
+ */
+export function holdSpeculative(held) {
+  const next = held === true;
+  if (next === speculativeHeld) return false;
+  speculativeHeld = next;
+  return true;
+}
+
 /**
  * Bring every torrent's download set into line with what is stated.
  *
@@ -235,7 +261,7 @@ export function firstClassStatement() {
 export function reconcileAll() {
   if (publishingSelections) return { torrents: live.size, speculativeAllowed: false, stated: 0, withdrawn: 0 };
   const entries = [...live];
-  const speculativeAllowed = !entries.some((entry) => entry.selection.hasUrgentMissing());
+  const speculativeAllowed = !speculativeHeld && !entries.some((entry) => entry.selection.hasUrgentMissing());
   // The first class across every torrent: the most urgent missing level and
   // its highest priority. Lower classes stay out of every torrent's selection.
   const bands = entries.map(entry => entry.selection.missingBand()).filter(Boolean);

package/services/torrent/torrent-pool.js

@@ -18,7 +18,7 @@ import { logger } from "../../utils/logger.js";
 import { pieceStoreOf } from "./piece-store-of.js";
 import { demandProgress } from "./demand-progress.js";
 import { Urgency, urgencyName } from "./demand/index.js";
-import { demandFor, firstClassStatement, forgetTorrent, reconcileAll, hasUnmetDemand, selectionLimitOf } from "./download/registry.js";
+import { demandFor, firstClassStatement, forgetTorrent, holdSpeculative, reconcileAll, hasUnmetDemand, selectionLimitOf } from "./download/registry.js";
 import { applyDownloadRate } from "./download/throttle.js";
 import { withdrawClaim } from "./download/withdraw-claim.js";
 import { deadlineOfMapZone, levelOfMapZone, priorityOfMapZone } from "./map-zones.js";
@@ -1309,6 +1309,20 @@ export class TorrentPool {
   /** The power of two the last limit said was nearest, null for none. */
   #downloadLimitScale = null;
 
+  /**
+   * Hold back, or let go, what every torrent downloads speculatively: the
+   * film's tail and the gap behind a seek (`download/registry.js`
+   * `holdSpeculative`, torrent-tv/meta#180). Said when it changes.
+   *
+   * @param {boolean} held
+   * @param {string} [because]
+   */
+  setSpeculativeHold(held, because = "") {
+    if (!holdSpeculative(held)) return;
+    logger.info(`torrent-pool: speculative download ${held === true ? "held" : "let go"}${because ? ` (${because})` : ""}`);
+    reconcileAll();
+  }
+
   applyPriorityMap(torrent, fileIndex, zones, durationSeconds) {
     // A MAP WITH NOTHING IN IT IS A STATEMENT, and it is answered before
     // anything else is looked at. It says nobody wants any of this file, and

package/services/torrent/worker/client.js

@@ -511,6 +511,17 @@ export class TorrentWorkerClient {
     return this.#caller.call(Command.DOWNLOAD_RATE, { bytesPerSecond: Number.isFinite(bytesPerSecond) ? bytesPerSecond : null, because });
   }
 
+  /**
+   * Whether the speculative levels are held back (`Command.SPECULATIVE_HOLD`).
+   *
+   * @param {boolean} held
+   * @param {string} [because]
+   * @returns {Promise<void>}
+   */
+  async setSpeculativeHold(held, because = "") {
+    return this.#caller.call(Command.SPECULATIVE_HOLD, { held: held === true, because });
+  }
+
   async setPriorityMap({ sourceKey, fileIndex, zones, durationSeconds, postedAt }) {
     return this.#caller.call(Command.PRIORITY_MAP, {
       sourceKey,

package/services/torrent/worker/pool-adapter.js

@@ -179,6 +179,17 @@ export class WorkerTorrentPool {
     return this.#client.setDownloadRate(bytesPerSecond, because);
   }
 
+  /**
+   * Whether the speculative levels are held back for the encoders.
+   *
+   * @param {boolean} held
+   * @param {string} [because]
+   * @returns {Promise<void>}
+   */
+  async setSpeculativeHold(held, because = "") {
+    return this.#client.setSpeculativeHold(held, because);
+  }
+
   async setPriorityMap({ sourceKey, fileIndex, durationSeconds, zones, postedAt }) {
     if (!sourceKey) {
       return;

package/services/torrent/worker/protocol.js

@@ -72,6 +72,12 @@ export const Command = {
    * (`storage/processor-share.js`, torrent-tv/meta#178).
    */
   DOWNLOAD_RATE: "download-rate",
+  /**
+   * Whether the speculative levels are held back for the processor the
+   * encoders need (`download/registry.js` `holdSpeculative`,
+   * torrent-tv/meta#180).
+   */
+  SPECULATIVE_HOLD: "speculative-hold",
   /** Read a byte range; the body arrives as CHUNK messages. */
   READ_RANGE: "read-range",
   /** Abandon an in-flight READ_RANGE (viewer gone, seek superseded). */

package/services/torrent/worker/worker.js

@@ -525,6 +525,11 @@ async function runCommand(command, params, id) {
       return true;
     }
 
+    case Command.SPECULATIVE_HOLD: {
+      pool.setSpeculativeHold(params.held === true, params.because);
+      return true;
+    }
+
     case Command.READ_RANGE: {
       // Streams its own reply; the caller's promise resolves once the body has
       // been fully sent, which is what lets the client await completion.