proto: answer CORE's freeze-blockers before 1.0.0 lands
Three corrections into 1.0.0, all of which would be major bumps once the contract has landed. It has not: main still carries 1.0.0-draft, so these are corrections to an unpublished version rather than changes to a released one. ADR 0010 records that and the reasoning behind each. B1 — TaskError.code was a bare integer, and the integer space in the contract is JSON-RPC's, which is a different thing; TaskError's own description said so while typing its code as one. Freeze TaskErrorCode: a string enum mirroring vdm::Error by name and in order, all 27 failure values, verified against core/include/vdm/util/error.hpp mechanically. ErrorCode says why a call failed; TaskErrorCode says why a download failed, and a download fails while every RPC succeeds. Adds TaskError.cause so max_retries_exhausted names what kept failing. B2 — TaskSummary.segments is now explicitly the effective count in use right now, after the per-host cap and the non-resumable demotion to 1. DownloadSpec.segments and download.update's patch say they are the requested value. B3 — Segment.endByte's "minimum: 0" contradicted the description's own empty-range encoding of startByte - 1, which is -1 for the first segment of every download. Empty ranges are no longer representable and are not needed. The range stays CLOSED and INCLUSIVE, matching the HTTP Range header the two fields are copied into verbatim, and that is now stated in the schema, the README, an ADR, a fixture assertion and a conformance check. CORE asked for half-open and gets a written notice rather than a silent schema edit. Segment state spells 'downloading' as CORE asked, not 'receiving'. check_contract.py now enforces segment contiguity, coverage of exactly [0, sizeBytes-1], downloadedBytes within the range size, and the entry count matching TaskSummary.segments. The download.get fixture claimed 8 segments while carrying 2; it now carries 8 contiguous ones covering the whole file. contracts/proto-answers-m1.md answers every item in core/docs/proto-requests-m1.md, including the ones not being landed now: B2a and F2 accepted as follow-ups, F1 answered with the notify path for M1, F3 already frozen as a Checksum object rather than a string, and D1 left for DAEMON to draft as the three-way ADR it is. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_012fgjnqFCS5h5L7gZTZo3rV
This commit is contained in:
Claude Opus 5
+139
-19
@@ -486,8 +486,10 @@
|
||||
"null"
|
||||
],
|
||||
"minimum": 1,
|
||||
"maximum": 32
|
||||
}
|
||||
"maximum": 32,
|
||||
"description": "The REQUESTED connection count. An upper bound, not a promise: the daemon lowers it to the per-host cap, and to 1 when the source turns out not to be resumable. What is actually in use comes back as TaskSummary.segments. null means use connection.maxSegmentsPerDownload."
|
||||
},
|
||||
"description": "The REQUESTED connection count. An upper bound, not a promise: the daemon lowers it to the per-host cap, and to 1 when the source turns out not to be resumable. What is actually in use comes back as TaskSummary.segments. null means use connection.maxSegmentsPerDownload."
|
||||
},
|
||||
{
|
||||
"name": "bufferBytes",
|
||||
@@ -1357,7 +1359,7 @@
|
||||
],
|
||||
"minimum": 1,
|
||||
"maximum": 32,
|
||||
"description": "Takes effect on the next start; a running task is not re-segmented underneath the user."
|
||||
"description": "The REQUESTED connection count, subject to the same per-host cap and non-resumable demotion as DownloadSpec.segments. Takes effect on the next start; a running task is not re-segmented underneath the user."
|
||||
},
|
||||
"bufferBytes": {
|
||||
"type": [
|
||||
@@ -3128,7 +3130,8 @@
|
||||
"null"
|
||||
],
|
||||
"minimum": 1,
|
||||
"maximum": 32
|
||||
"maximum": 32,
|
||||
"description": "The REQUESTED connection count. An upper bound, not a promise: the daemon lowers it to the per-host cap, and to 1 when the source turns out not to be resumable. What is actually in use comes back as TaskSummary.segments. null means use connection.maxSegmentsPerDownload."
|
||||
},
|
||||
"bufferBytes": {
|
||||
"type": [
|
||||
@@ -3672,7 +3675,7 @@
|
||||
"title": "Schedule"
|
||||
},
|
||||
"Segment": {
|
||||
"description": "One byte range being fetched by one connection. This is the deepest the contract ever exposes the engine: the GUI draws a bar per segment and never learns what a segment steal is.",
|
||||
"description": "One byte range being fetched by one connection. This is the deepest the contract ever exposes the engine: the GUI draws a bar per segment and is never told what a segment steal is.\n\nRANGE CONVENTION \u2014 READ THIS BEFORE IMPLEMENTING. The range is CLOSED and INCLUSIVE on both ends: [startByte, endByte]. The segment covers endByte - startByte + 1 bytes, and endByte is the index of the LAST byte in the range, not one past it. This deliberately matches the HTTP Range header the engine actually sends ('Range: bytes=<startByte>-<endByte>' is a byte-for-byte copy of these two fields, and RFC 9110 ranges are inclusive), so no arithmetic happens between the wire and the socket and there is nowhere for an off-by-one to hide. CORE asked for half-open [start, end); PROTO chose inclusive for that reason and this note exists so nobody discovers the difference at integration. A segment always covers at least one byte: endByte >= startByte always holds. An empty range is not representable and is not needed \u2014 a zero-length download carries an empty segmentDetail array, and a segment that has donated its remainder to a steal keeps the bytes it already wrote.",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
@@ -3686,20 +3689,23 @@
|
||||
"index": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 31
|
||||
"maximum": 31,
|
||||
"description": "Position in TaskDetail.segmentDetail. Spelled 'index' here and in event.task.progress; there is no 'i' spelling anywhere in the contract."
|
||||
},
|
||||
"startByte": {
|
||||
"type": "integer",
|
||||
"minimum": 0
|
||||
"minimum": 0,
|
||||
"description": "Absolute offset of the first byte of the range. Inclusive."
|
||||
},
|
||||
"endByte": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"description": "Inclusive. Equal to startByte - 1 for an empty segment."
|
||||
"description": "Absolute offset of the LAST byte of the range. Inclusive \u2014 this is not one-past-the-end. Always >= startByte."
|
||||
},
|
||||
"downloadedBytes": {
|
||||
"type": "integer",
|
||||
"minimum": 0
|
||||
"minimum": 0,
|
||||
"description": "Bytes written for this range so far, out of endByte - startByte + 1."
|
||||
},
|
||||
"speedBps": {
|
||||
"type": "integer",
|
||||
@@ -3710,17 +3716,21 @@
|
||||
"enum": [
|
||||
"pending",
|
||||
"connecting",
|
||||
"receiving",
|
||||
"downloading",
|
||||
"stalled",
|
||||
"complete",
|
||||
"failed"
|
||||
]
|
||||
],
|
||||
"description": "'downloading' is spelled as in TaskState, not 'receiving'. 'pending' is a range that has been planned but not yet dialled."
|
||||
},
|
||||
"httpStatus": {
|
||||
"type": [
|
||||
"integer",
|
||||
"null"
|
||||
]
|
||||
],
|
||||
"minimum": 100,
|
||||
"maximum": 599,
|
||||
"description": "The status this segment's request got. 206 on a healthy ranged fetch."
|
||||
}
|
||||
},
|
||||
"title": "Segment"
|
||||
@@ -3994,7 +4004,8 @@
|
||||
"maxItems": 32,
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/Segment"
|
||||
}
|
||||
},
|
||||
"description": "Exactly TaskSummary.segments entries, in index order, covering [0, sizeBytes) with no gaps and no overlaps. Empty for a zero-length download, and empty before the task has been segmented."
|
||||
},
|
||||
"headers": {
|
||||
"oneOf": [
|
||||
@@ -4071,7 +4082,7 @@
|
||||
"title": "TaskDetail"
|
||||
},
|
||||
"TaskError": {
|
||||
"description": "Why a task is in the failed or retry_wait state. Distinct from the JSON-RPC Error, which describes a failed call rather than a failed download.",
|
||||
"description": "Why a task is in the failed or retry_wait state. Distinct from the JSON-RPC Error, which describes a failed call rather than a failed download \u2014 the two live in different code spaces on purpose, and `code` here is a TaskErrorCode string, never a JSON-RPC integer.",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
@@ -4081,19 +4092,35 @@
|
||||
],
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "integer"
|
||||
"$ref": "#/components/schemas/TaskErrorCode"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"description": "Human-readable, safe to show a user. Never carries a credential, a token or a full local path outside the download roots."
|
||||
},
|
||||
"httpStatus": {
|
||||
"type": [
|
||||
"integer",
|
||||
"null"
|
||||
]
|
||||
],
|
||||
"minimum": 100,
|
||||
"maximum": 599,
|
||||
"description": "Set for the codes listed in TaskErrorCode's x-carriesHttpStatus, and null otherwise."
|
||||
},
|
||||
"retryable": {
|
||||
"type": "boolean"
|
||||
"type": "boolean",
|
||||
"description": "Whether the scheduler will pick this task up again on its own. Carried per-occurrence rather than derived from the code, because 'probe_failed' is retryable or not depending on what the probe hit."
|
||||
},
|
||||
"cause": {
|
||||
"oneOf": [
|
||||
{
|
||||
"$ref": "#/components/schemas/TaskErrorCode"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"description": "The underlying failure, for codes that wrap one. max_retries_exhausted sets it to whatever the last attempt actually failed with, so a user learns the reason rather than just that Velox gave up."
|
||||
},
|
||||
"attempt": {
|
||||
"type": [
|
||||
@@ -4113,6 +4140,99 @@
|
||||
},
|
||||
"title": "TaskError"
|
||||
},
|
||||
"TaskErrorCode": {
|
||||
"description": "Why a download failed. This is the WIRE failure taxonomy and it is deliberately NOT the JSON-RPC ErrorCode space: ErrorCode says why a *call* failed, TaskErrorCode says why a *download* failed. A task can fail while every RPC involved succeeded. The values mirror vdm::Error in core/include/vdm/util/error.hpp one-for-one, by name, so DAEMON's projection from the engine taxonomy onto the wire is lossless and the GUI can tell 'the file on the server changed' from 'the checksum did not match'. CORE's 'ok' has no wire spelling: a TaskError only exists when there is a failure. Adding a value here is a minor bump; renaming or removing one is major, and would desynchronise the engine.",
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"canceled",
|
||||
"resolve_failed",
|
||||
"connect_failed",
|
||||
"tls_failed",
|
||||
"connection_reset",
|
||||
"timeout",
|
||||
"too_many_redirects",
|
||||
"http_client_error",
|
||||
"http_server_error",
|
||||
"auth_required",
|
||||
"forbidden",
|
||||
"not_found",
|
||||
"range_not_satisfiable",
|
||||
"gone",
|
||||
"server_file_changed",
|
||||
"content_length_mismatch",
|
||||
"checksum_mismatch",
|
||||
"disk_full",
|
||||
"io_error",
|
||||
"path_rejected",
|
||||
"permission_denied",
|
||||
"meta_corrupt",
|
||||
"meta_version_unsupported",
|
||||
"probe_failed",
|
||||
"unsupported_url_scheme",
|
||||
"max_retries_exhausted",
|
||||
"internal"
|
||||
],
|
||||
"x-groups": {
|
||||
"cancellation": [
|
||||
"canceled"
|
||||
],
|
||||
"network": [
|
||||
"resolve_failed",
|
||||
"connect_failed",
|
||||
"tls_failed",
|
||||
"connection_reset",
|
||||
"timeout",
|
||||
"too_many_redirects"
|
||||
],
|
||||
"http": [
|
||||
"http_client_error",
|
||||
"http_server_error",
|
||||
"auth_required",
|
||||
"forbidden",
|
||||
"not_found",
|
||||
"range_not_satisfiable",
|
||||
"gone"
|
||||
],
|
||||
"content": [
|
||||
"server_file_changed",
|
||||
"content_length_mismatch",
|
||||
"checksum_mismatch"
|
||||
],
|
||||
"localIo": [
|
||||
"disk_full",
|
||||
"io_error",
|
||||
"path_rejected",
|
||||
"permission_denied"
|
||||
],
|
||||
"resumeMetadata": [
|
||||
"meta_corrupt",
|
||||
"meta_version_unsupported"
|
||||
],
|
||||
"probe": [
|
||||
"probe_failed",
|
||||
"unsupported_url_scheme"
|
||||
],
|
||||
"retry": [
|
||||
"max_retries_exhausted"
|
||||
],
|
||||
"internal": [
|
||||
"internal"
|
||||
]
|
||||
},
|
||||
"x-carriesHttpStatus": [
|
||||
"http_client_error",
|
||||
"http_server_error",
|
||||
"auth_required",
|
||||
"forbidden",
|
||||
"not_found",
|
||||
"range_not_satisfiable",
|
||||
"gone",
|
||||
"server_file_changed",
|
||||
"probe_failed",
|
||||
"max_retries_exhausted"
|
||||
],
|
||||
"title": "TaskErrorCode"
|
||||
},
|
||||
"TaskFilter": {
|
||||
"description": "Which rows download.list returns. This is the category tree and the All/Unfinished/Finished nodes, expressed on the wire. Absent clauses are not constraints.",
|
||||
"type": "object",
|
||||
@@ -4292,7 +4412,7 @@
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 32,
|
||||
"description": "Connection count. Per-segment detail lives in TaskDetail."
|
||||
"description": "The EFFECTIVE connection count in use right now \u2014 not the number that was requested. It is what remains after the per-host connection cap has been applied and after the demotion to 1 for a non-resumable source, so a task the user asked for 16 connections on legitimately reports 4, or 1. The GUI displays this value and must not assume it equals what download.add asked for. The requested value lives in DownloadSpec.segments and is not echoed back on this type. TaskDetail.segmentDetail always has exactly this many entries."
|
||||
},
|
||||
"categoryId": {
|
||||
"type": [
|
||||
|
||||
Reference in New Issue
Block a user