proto: land B4 and B2a — buffer bounds, budget knobs, effective readback (1.1.0)

Minor bump on 1.0.0, per core/docs/buffer-sizing.md. B4 — bufferBytes bounds corrected in all four locations (DownloadSpec, TaskDetail, download.update's patch, Settings.connection.bufferBytes): was 4 KiB-8 MiB with no stated default, now 64 KiB-16 MiB with a 1 MiB default. 64 KiB because 4 KiB is smaller than one libcurl HTTP/2 write-callback delivery; 16 MiB because throughput from write size is flat past ~1-4 MiB and past 16 MiB there is stall-cover left to buy but no memory left to spend it on; 1 MiB default because it is the only candidate for which docs/04's 60 MB RSS target actually holds once buffers are counted per segment, not per download. Two new settings keys: connection.maxTotalBufferBytes (128 MiB default) and connection.maxActiveSegments (32 default). Without them CORE's clamp — reduce every live segment's buffer to fit the global cap — has no wire configuration surface, and "20 active downloads" has no meaning distinct from 160 live TLS connections. B2a — TaskDetail.effectiveBufferBytes: what a segment is actually using right now, after the clamp. Placed on TaskDetail next to bufferBytes, following the requested/effective pattern ADR 0010 already established for segments. The download.get fixture now demonstrates a real clamp (16 MiB requested, 4 MiB effective) rather than a case where the cap happens not to bind. docs/04-engine-design.md §4 and §8 updated in the same change per CORE's request and CLAUDE.md rule 5: the RSS target is now stated as conditional on maxActiveSegments = 32, and the old 4 MiB/64 MiB/256 MiB numbers are corrected to match the schema. ADR 0012 records the reasoning and explicitly keeps the 60 MB target over CORE's offered 120 MB alternative, with the arithmetic that makes 60 MB achievable with margin. Numbered 0012 rather than 0011: DAEMON is independently drafting ADR 0011 (admission control / segment budget split) in a peer session at time of writing, so 0011 was reserved to avoid a collision. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_012fgjnqFCS5h5L7gZTZo3rV
2026-09-09 23:20:58 +04:00
parent a5ac817f01
commit 60363a7142
22 changed files with 408 additions and 80 deletions
@@ -3,7 +3,7 @@
 //
 // Source:    contracts/schema/**
 // Generator: contracts/codegen/gen_ts.py
-// Contract:  v1.0.0
+// Contract:  v1.1.0
 //
 // Hand-editing this file is a merge blocker. Fix the schema and regenerate:
 //     python3 contracts/codegen/gen_ts.py
@@ -3,7 +3,7 @@
 //
 // Source:    contracts/schema/**
 // Generator: contracts/codegen/gen_ts.py
-// Contract:  v1.0.0
+// Contract:  v1.1.0
 //
 // Hand-editing this file is a merge blocker. Fix the schema and regenerate:
 //     python3 contracts/codegen/gen_ts.py
@@ -3,7 +3,7 @@
 //
 // Source:    contracts/schema/**
 // Generator: contracts/codegen/gen_ts.py
-// Contract:  v1.0.0
+// Contract:  v1.1.0
 //
 // Hand-editing this file is a merge blocker. Fix the schema and regenerate:
 //     python3 contracts/codegen/gen_ts.py
@@ -3,7 +3,7 @@
 //
 // Source:    contracts/schema/**
 // Generator: contracts/codegen/gen_ts.py
-// Contract:  v1.0.0
+// Contract:  v1.1.0
 //
 // Hand-editing this file is a merge blocker. Fix the schema and regenerate:
 //     python3 contracts/codegen/gen_ts.py
@@ -11,7 +11,7 @@
 // ---------------------------------------------------------------------------


-export const PROTOCOL_VERSION = "1.0.0";
+export const PROTOCOL_VERSION = "1.1.0";

 /**
 * Every error code the daemon may return. Adding one is a minor bump; changing the meaning
@@ -214,6 +214,12 @@ export interface DownloadSpec {
   * connection.maxSegmentsPerDownload.
   */
  segments?: number | null;
+  /**
+   * Requested write buffer per segment, in bytes. null means use connection.bufferBytes.
+   * Default 1 MiB; range 64 KiB - 16 MiB. Silently reduced to fit
+   * connection.maxTotalBufferBytes across all live segments; the effective value is reported
+   * back as TaskDetail.effectiveBufferBytes.
+   */
  bufferBytes?: number | null;
  startMode?: StartMode;
  description?: string | null;
@@ -440,7 +446,7 @@ export interface Segment {
 * must not invent a key that is not here. Kept in lockstep with Settings.schema.json by a
 * conformance check.
 */
-export type SettingKey = "general.launchOnLogin" | "general.minimizeToTray" | "general.showDropTarget" | "general.confirmOnExit" | "general.language" | "general.checkForUpdates" | "capture.enabled" | "capture.monitoredExtensions" | "capture.monitoredMimeTypes" | "capture.minSizeBytes" | "capture.excludedHosts" | "capture.bypassModifier" | "capture.autoStartTypes" | "saveTo.defaultDir" | "saveTo.tempDir" | "saveTo.allowedRoots" | "saveTo.fileExistsPolicy" | "saveTo.createSubfolderPerSite" | "connection.preset" | "connection.maxSegmentsPerDownload" | "connection.bufferBytes" | "connection.maxConcurrentDownloads" | "connection.timeoutSec" | "connection.maxRetries" | "connection.retryBackoffSec" | "downloads.speedLimitBps" | "downloads.speedLimitEnabled" | "downloads.virusScanCommand" | "downloads.postDownloadCommand" | "downloads.duplicatePolicy" | "downloads.verifyChecksums" | "proxy.mode" | "proxy.host" | "proxy.port" | "proxy.username" | "proxy.bypassHosts" | "proxy.pacUrl" | "sounds.enabled" | "sounds.onComplete" | "sounds.onQueueComplete" | "sounds.onError";
+export type SettingKey = "general.launchOnLogin" | "general.minimizeToTray" | "general.showDropTarget" | "general.confirmOnExit" | "general.language" | "general.checkForUpdates" | "capture.enabled" | "capture.monitoredExtensions" | "capture.monitoredMimeTypes" | "capture.minSizeBytes" | "capture.excludedHosts" | "capture.bypassModifier" | "capture.autoStartTypes" | "saveTo.defaultDir" | "saveTo.tempDir" | "saveTo.allowedRoots" | "saveTo.fileExistsPolicy" | "saveTo.createSubfolderPerSite" | "connection.preset" | "connection.maxSegmentsPerDownload" | "connection.bufferBytes" | "connection.maxTotalBufferBytes" | "connection.maxActiveSegments" | "connection.maxConcurrentDownloads" | "connection.timeoutSec" | "connection.maxRetries" | "connection.retryBackoffSec" | "downloads.speedLimitBps" | "downloads.speedLimitEnabled" | "downloads.virusScanCommand" | "downloads.postDownloadCommand" | "downloads.duplicatePolicy" | "downloads.verifyChecksums" | "proxy.mode" | "proxy.host" | "proxy.port" | "proxy.username" | "proxy.bypassHosts" | "proxy.pacUrl" | "sounds.enabled" | "sounds.onComplete" | "sounds.onQueueComplete" | "sounds.onError";
 export const SETTING_KEY_VALUES = [
  "general.launchOnLogin",
  "general.minimizeToTray",
@@ -463,6 +469,8 @@ export const SETTING_KEY_VALUES = [
  "connection.preset",
  "connection.maxSegmentsPerDownload",
  "connection.bufferBytes",
+  "connection.maxTotalBufferBytes",
+  "connection.maxActiveSegments",
  "connection.maxConcurrentDownloads",
  "connection.timeoutSec",
  "connection.maxRetries",
@@ -553,6 +561,11 @@ export interface Settings {
  "saveTo.createSubfolderPerSite"?: boolean;
  "connection.preset"?: SettingsConnectionPreset;
  "connection.maxSegmentsPerDownload"?: number;
+  /**
+   * Default per-segment write buffer, in bytes, when a task does not request its own.
+   * Default 1 MiB (1048576); range 64 KiB - 16 MiB. This is the single biggest throughput
+   * knob and is exposed in Options -> Downloads -> 'Write buffer per connection'.
+   */
  "connection.bufferBytes"?: number;
  "connection.maxConcurrentDownloads"?: number;
  "connection.timeoutSec"?: number;
@@ -574,6 +587,21 @@ export interface Settings {
  "sounds.onComplete"?: string;
  "sounds.onQueueComplete"?: string;
  "sounds.onError"?: string;
+  /**
+   * Global cap on write-buffer memory across every live segment, in bytes. Default 128 MiB
+   * (134217728). Every live segment's buffer is reduced to fit maxTotalBufferBytes / (live
+   * segment count, capped at maxActiveSegments); the reduced value is reported per task as
+   * TaskDetail.effectiveBufferBytes. Exists so a burst of large downloads with a large
+   * per-segment buffer cannot exhaust memory.
+   */
+  "connection.maxTotalBufferBytes"?: number;
+  /**
+   * Global ceiling on segments actually transferring at once, across every task. Default 32.
+   * This is the real bound behind '20 active downloads': the rest of each download's
+   * segments queue rather than all dialling out simultaneously. DAEMON's scheduler needs
+   * this value to decide what to admit; CORE enforces it.
+   */
+  "connection.maxActiveSegments"?: number;
 }

 /**
@@ -708,7 +736,19 @@ export interface TaskDetail {
  referrer?: string | null;
  userAgent?: string | null;
  mime?: string | null;
+  /**
+   * The REQUESTED write buffer per segment. See effectiveBufferBytes for what is actually in
+   * use.
+   */
  bufferBytes?: number | null;
+  /**
+   * The write buffer actually in use per live segment, right now. May be well below
+   * bufferBytes: the daemon reduces every live segment's buffer to fit
+   * connection.maxTotalBufferBytes across connection.maxActiveSegments
+   * concurrently-transferring segments, and reports the reduced value here so the GUI can
+   * show '16 MiB (using 4 MiB)'. null before the task has started its first segment.
+   */
+  effectiveBufferBytes?: number | null;
  /** Absolute path of the .veloxpart file while the task is unfinished. */
  partPath?: string | null;
  checksum?: Checksum | null;
@@ -995,6 +1035,11 @@ export interface DownloadUpdateParamsPatch {
   * re-segmented underneath the user.
   */
  segments?: number | null;
+  /**
+   * The REQUESTED write buffer per segment. Subject to the same maxTotalBufferBytes
+   * reduction as DownloadSpec.bufferBytes; the effective value comes back on the next
+   * download.get.
+   */
  bufferBytes?: number | null;
  checksum?: Checksum | null;
 }
@@ -3,7 +3,7 @@
 //
 // Source:    contracts/schema/**
 // Generator: contracts/codegen/gen_ts.py
-// Contract:  v1.0.0
+// Contract:  v1.1.0
 //
 // Hand-editing this file is a merge blocker. Fix the schema and regenerate:
 //     python3 contracts/codegen/gen_ts.py
@@ -490,7 +490,7 @@ export function validateDownloadSpec(v: unknown, path = ''): Validated<DownloadS
  if (!r.ok) return r;
  r = opt(v, "segments", path, vLimited(vInteger, { minimum: 1, maximum: 32 }), out);
  if (!r.ok) return r;
-  r = opt(v, "bufferBytes", path, vLimited(vInteger, { minimum: 4096, maximum: 8388608 }), out);
+  r = opt(v, "bufferBytes", path, vLimited(vInteger, { minimum: 65536, maximum: 16777216 }), out);
  if (!r.ok) return r;
  r = opt(v, "startMode", path, validateStartMode, out);
  if (!r.ok) return r;
@@ -754,7 +754,7 @@ export function validateSettings(v: unknown, path = ''): Validated<Settings> {
  if (!r.ok) return r;
  r = opt(v, "connection.maxSegmentsPerDownload", path, vLimited(vInteger, { minimum: 1, maximum: 32 }), out);
  if (!r.ok) return r;
-  r = opt(v, "connection.bufferBytes", path, vLimited(vInteger, { minimum: 4096, maximum: 8388608 }), out);
+  r = opt(v, "connection.bufferBytes", path, vLimited(vInteger, { minimum: 65536, maximum: 16777216 }), out);
  if (!r.ok) return r;
  r = opt(v, "connection.maxConcurrentDownloads", path, vLimited(vInteger, { minimum: 1, maximum: 64 }), out);
  if (!r.ok) return r;
@@ -796,6 +796,10 @@ export function validateSettings(v: unknown, path = ''): Validated<Settings> {
  if (!r.ok) return r;
  r = opt(v, "sounds.onError", path, vString, out);
  if (!r.ok) return r;
+  r = opt(v, "connection.maxTotalBufferBytes", path, vLimited(vInteger, { minimum: 16777216, maximum: 2147483648 }), out);
+  if (!r.ok) return r;
+  r = opt(v, "connection.maxActiveSegments", path, vLimited(vInteger, { minimum: 1, maximum: 256 }), out);
+  if (!r.ok) return r;
  return { ok: true, value: out as unknown as Settings };
 }

@@ -824,7 +828,9 @@ export function validateTaskDetail(v: unknown, path = ''): Validated<TaskDetail>
  if (!r.ok) return r;
  r = opt(v, "mime", path, vString, out);
  if (!r.ok) return r;
-  r = opt(v, "bufferBytes", path, vLimited(vInteger, { minimum: 4096, maximum: 8388608 }), out);
+  r = opt(v, "bufferBytes", path, vLimited(vInteger, { minimum: 65536, maximum: 16777216 }), out);
+  if (!r.ok) return r;
+  r = opt(v, "effectiveBufferBytes", path, vLimited(vInteger, { minimum: 65536, maximum: 16777216 }), out);
  if (!r.ok) return r;
  r = opt(v, "partPath", path, vString, out);
  if (!r.ok) return r;
@@ -1336,7 +1342,7 @@ export function validateDownloadUpdateParamsPatch(v: unknown, path = ''): Valida
  if (!r.ok) return r;
  r = opt(v, "segments", path, vLimited(vInteger, { minimum: 1, maximum: 32 }), out);
  if (!r.ok) return r;
-  r = opt(v, "bufferBytes", path, vLimited(vInteger, { minimum: 4096, maximum: 8388608 }), out);
+  r = opt(v, "bufferBytes", path, vLimited(vInteger, { minimum: 65536, maximum: 16777216 }), out);
  if (!r.ok) return r;
  r = opt(v, "checksum", path, validateChecksum, out);
  if (!r.ok) return r;