sami/vdm
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
sami
2026-09-09 23:20:58 +04:00
co-authored by Claude Sonnet 5
parent a5ac817f01
commit 60363a7142
22 changed files with 408 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files
core/generated/velox_proto.cpp
+49 -9
View File
@@ -3,7 +3,7 @@
//
// Source: contracts/schema/**
// Generator: contracts/codegen/gen_cpp.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_cpp.py
@@ -401,6 +401,8 @@ std::string_view to_string(SettingKey v) noexcept {
case SettingKey::ConnectionPreset: return "connection.preset";
case SettingKey::ConnectionMaxSegmentsPerDownload: return "connection.maxSegmentsPerDownload";
case SettingKey::ConnectionBufferBytes: return "connection.bufferBytes";
case SettingKey::ConnectionMaxTotalBufferBytes: return "connection.maxTotalBufferBytes";
case SettingKey::ConnectionMaxActiveSegments: return "connection.maxActiveSegments";
case SettingKey::ConnectionMaxConcurrentDownloads: return "connection.maxConcurrentDownloads";
case SettingKey::ConnectionTimeoutSec: return "connection.timeoutSec";
case SettingKey::ConnectionMaxRetries: return "connection.maxRetries";
@@ -447,6 +449,8 @@ Result<SettingKey> parse_SettingKey(std::string_view s) {
if (s == "connection.preset") return SettingKey::ConnectionPreset;
if (s == "connection.maxSegmentsPerDownload") return SettingKey::ConnectionMaxSegmentsPerDownload;
if (s == "connection.bufferBytes") return SettingKey::ConnectionBufferBytes;
if (s == "connection.maxTotalBufferBytes") return SettingKey::ConnectionMaxTotalBufferBytes;
if (s == "connection.maxActiveSegments") return SettingKey::ConnectionMaxActiveSegments;
if (s == "connection.maxConcurrentDownloads") return SettingKey::ConnectionMaxConcurrentDownloads;
if (s == "connection.timeoutSec") return SettingKey::ConnectionTimeoutSec;
if (s == "connection.maxRetries") return SettingKey::ConnectionMaxRetries;
@@ -1601,8 +1605,8 @@ template <> Result<DownloadSpec> parse<DownloadSpec>(const nlohmann::json& j, st
if (it != j.end() && !it->is_null()) {
if (!(*it).is_number_integer()) return std::unexpected(ParseError{std::string(fp), "expected an integer"});
auto val = (*it).get<std::int64_t>();
if (val < 4096) return std::unexpected(ParseError{std::string(fp), "value is below the minimum of 4096"});
if (val > 8388608) return std::unexpected(ParseError{std::string(fp), "value is above the maximum of 8388608"});
if (val < 65536) return std::unexpected(ParseError{std::string(fp), "value is below the minimum of 65536"});
if (val > 16777216) return std::unexpected(ParseError{std::string(fp), "value is above the maximum of 16777216"});
out.bufferBytes = std::move(val);
}
}
@@ -2428,6 +2432,8 @@ void to_json(nlohmann::json& j, const Settings& v) {
if (v.sounds_onComplete.has_value()) j["sounds.onComplete"] = *v.sounds_onComplete;
if (v.sounds_onQueueComplete.has_value()) j["sounds.onQueueComplete"] = *v.sounds_onQueueComplete;
if (v.sounds_onError.has_value()) j["sounds.onError"] = *v.sounds_onError;
if (v.connection_maxTotalBufferBytes.has_value()) j["connection.maxTotalBufferBytes"] = *v.connection_maxTotalBufferBytes;
if (v.connection_maxActiveSegments.has_value()) j["connection.maxActiveSegments"] = *v.connection_maxActiveSegments;
}
template <> Result<Settings> parse<Settings>(const nlohmann::json& j, std::string_view path) {
@@ -2660,8 +2666,8 @@ template <> Result<Settings> parse<Settings>(const nlohmann::json& j, std::strin
if (it != j.end() && !it->is_null()) {
if (!(*it).is_number_integer()) return std::unexpected(ParseError{std::string(fp), "expected an integer"});
auto val = (*it).get<std::int64_t>();
if (val < 4096) return std::unexpected(ParseError{std::string(fp), "value is below the minimum of 4096"});
if (val > 8388608) return std::unexpected(ParseError{std::string(fp), "value is above the maximum of 8388608"});
if (val < 65536) return std::unexpected(ParseError{std::string(fp), "value is below the minimum of 65536"});
if (val > 16777216) return std::unexpected(ParseError{std::string(fp), "value is above the maximum of 16777216"});
out.connection_bufferBytes = std::move(val);
}
}
@@ -2865,6 +2871,28 @@ template <> Result<Settings> parse<Settings>(const nlohmann::json& j, std::strin
out.sounds_onError = std::move(val);
}
}
{
const std::string fp = join(path, "connection.maxTotalBufferBytes");
const auto it = j.find("connection.maxTotalBufferBytes");
if (it != j.end() && !it->is_null()) {
if (!(*it).is_number_integer()) return std::unexpected(ParseError{std::string(fp), "expected an integer"});
auto val = (*it).get<std::int64_t>();
if (val < 16777216) return std::unexpected(ParseError{std::string(fp), "value is below the minimum of 16777216"});
if (val > 2147483648) return std::unexpected(ParseError{std::string(fp), "value is above the maximum of 2147483648"});
out.connection_maxTotalBufferBytes = std::move(val);
}
}
{
const std::string fp = join(path, "connection.maxActiveSegments");
const auto it = j.find("connection.maxActiveSegments");
if (it != j.end() && !it->is_null()) {
if (!(*it).is_number_integer()) return std::unexpected(ParseError{std::string(fp), "expected an integer"});
auto val = (*it).get<std::int64_t>();
if (val < 1) return std::unexpected(ParseError{std::string(fp), "value is below the minimum of 1"});
if (val > 256) return std::unexpected(ParseError{std::string(fp), "value is above the maximum of 256"});
out.connection_maxActiveSegments = std::move(val);
}
}
return out;
}
@@ -3183,6 +3211,7 @@ void to_json(nlohmann::json& j, const TaskDetail& v) {
if (v.userAgent.has_value()) j["userAgent"] = *v.userAgent;
if (v.mime.has_value()) j["mime"] = *v.mime;
if (v.bufferBytes.has_value()) j["bufferBytes"] = *v.bufferBytes;
if (v.effectiveBufferBytes.has_value()) j["effectiveBufferBytes"] = *v.effectiveBufferBytes;
if (v.partPath.has_value()) j["partPath"] = *v.partPath;
if (v.checksum.has_value()) j["checksum"] = *v.checksum;
if (v.checksumVerified.has_value()) j["checksumVerified"] = *v.checksumVerified;
@@ -3264,11 +3293,22 @@ template <> Result<TaskDetail> parse<TaskDetail>(const nlohmann::json& j, std::s
if (it != j.end() && !it->is_null()) {
if (!(*it).is_number_integer()) return std::unexpected(ParseError{std::string(fp), "expected an integer"});
auto val = (*it).get<std::int64_t>();
if (val < 4096) return std::unexpected(ParseError{std::string(fp), "value is below the minimum of 4096"});
if (val > 8388608) return std::unexpected(ParseError{std::string(fp), "value is above the maximum of 8388608"});
if (val < 65536) return std::unexpected(ParseError{std::string(fp), "value is below the minimum of 65536"});
if (val > 16777216) return std::unexpected(ParseError{std::string(fp), "value is above the maximum of 16777216"});
out.bufferBytes = std::move(val);
}
}
{
const std::string fp = join(path, "effectiveBufferBytes");
const auto it = j.find("effectiveBufferBytes");
if (it != j.end() && !it->is_null()) {
if (!(*it).is_number_integer()) return std::unexpected(ParseError{std::string(fp), "expected an integer"});
auto val = (*it).get<std::int64_t>();
if (val < 65536) return std::unexpected(ParseError{std::string(fp), "value is below the minimum of 65536"});
if (val > 16777216) return std::unexpected(ParseError{std::string(fp), "value is above the maximum of 16777216"});
out.effectiveBufferBytes = std::move(val);
}
}
{
const std::string fp = join(path, "partPath");
const auto it = j.find("partPath");
@@ -4711,8 +4751,8 @@ template <> Result<DownloadUpdateParamsPatch> parse<DownloadUpdateParamsPatch>(c
if (it != j.end() && !it->is_null()) {
if (!(*it).is_number_integer()) return std::unexpected(ParseError{std::string(fp), "expected an integer"});
auto val = (*it).get<std::int64_t>();
if (val < 4096) return std::unexpected(ParseError{std::string(fp), "value is below the minimum of 4096"});
if (val > 8388608) return std::unexpected(ParseError{std::string(fp), "value is above the maximum of 8388608"});
if (val < 65536) return std::unexpected(ParseError{std::string(fp), "value is below the minimum of 65536"});
if (val > 16777216) return std::unexpected(ParseError{std::string(fp), "value is above the maximum of 16777216"});
out.bufferBytes = std::move(val);
}
}