proto: freeze the wire contract at 1.0.0
Schemas for the whole v1 surface: 38 methods, 9 events, 25 named types and the
JSON-RPC envelope, with x-privileged / x-transports / x-deadlineMs / x-errors
annotations that both generators emit as data rather than prose.
Four generators over one IR (contracts/codegen/schema_ir.py), so the C++ structs,
the TypeScript types and the OpenRPC document cannot disagree about what the
contract says:
gen_cpp.py -> core/generated/velox_proto.{hpp,cpp}
gen_ts.py -> extension/src/shared/protocol/
gen_openrpc.py -> contracts/openrpc.json
gen_cpp_conformance.py -> tests/conformance/cpp/fixture_dispatcher.hpp
Inbound parsing never throws: parse<T>() returns std::expected<T, ParseError> and
nlohmann's throwing ADL from_json is deliberately not emitted. Schema constraints
(minimum, maxLength, pattern, ...) become real runtime checks in both languages —
the daemon does not trust the extension and the extension does not trust the
daemon.
59 golden fixtures: a success case per method, 12 error cases, 9 events. Replayed
by tests/conformance/ against both the generated C++ and a live server over both
transports. tools/mockd serves the same fixtures with unhappy-path flags so the
GUI and EXT lanes never wait for veloxd.
run.sh also proves capture.offer fails open: with a daemon answering slower than
750 ms the client gives up and lets Firefox take the download.
core/generated/ is libveloxproto, a separate target from libveloxcore, which
still never sees JSON — see docs/adr/0009.
Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_012fgjnqFCS5h5L7gZTZo3rV
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"name": "event.auth.required \u2014 a server wants Basic credentials",
|
||||
"description": "The task waits in retry_wait until the client supplies them. Credentials go to the Secret Service, never back through this event and never into a log.",
|
||||
"notification": {
|
||||
"jsonrpc": "2.0",
|
||||
"method": "event.auth.required",
|
||||
"params": {
|
||||
"taskId": "3f7a2b1c-5d6e-4f80-9a1b-2c3d4e5f6071",
|
||||
"host": "files.example.org",
|
||||
"realm": "Restricted",
|
||||
"scheme": "basic"
|
||||
}
|
||||
},
|
||||
"assertions": [
|
||||
"no credential material appears in this payload",
|
||||
"the task sits in retry_wait rather than failing outright"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"name": "event.grabber.progress \u2014 a crawl in flight",
|
||||
"description": "done true means the file list in grabber.status is final.",
|
||||
"notification": {
|
||||
"jsonrpc": "2.0",
|
||||
"method": "event.grabber.progress",
|
||||
"params": {
|
||||
"jobId": "grab-7f21",
|
||||
"found": 3,
|
||||
"crawled": 12,
|
||||
"done": false,
|
||||
"currentUrl": "https://releases.ubuntu.com/26.04/"
|
||||
}
|
||||
},
|
||||
"assertions": [
|
||||
"emitted at no more than 4 Hz",
|
||||
"the wizard shows found and crawled separately: they diverge on a deep crawl"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"name": "event.notify \u2014 a download finished",
|
||||
"description": "The client decides between a toast, a tray balloon and a sound; the daemon does not assume a GUI is running.",
|
||||
"notification": {
|
||||
"jsonrpc": "2.0",
|
||||
"method": "event.notify",
|
||||
"params": {
|
||||
"level": "success",
|
||||
"title": "Download complete",
|
||||
"body": "ubuntu-26.04-desktop-amd64.iso (5.8 GB) finished in 3 m 28 s.",
|
||||
"taskId": "3f7a2b1c-5d6e-4f80-9a1b-2c3d4e5f6071",
|
||||
"sound": "complete"
|
||||
}
|
||||
},
|
||||
"assertions": [
|
||||
"the daemon never assumes a GUI is running to see this",
|
||||
"sound names an event, not a file path \u2014 the client owns its sound set"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"name": "event.settings.changed \u2014 capture policy was edited",
|
||||
"description": "Carries only key names. The extension watches for capture.* here and re-fetches capture.getRules so its mirror never lags the daemon.",
|
||||
"notification": {
|
||||
"jsonrpc": "2.0",
|
||||
"method": "event.settings.changed",
|
||||
"params": {
|
||||
"keys": [
|
||||
"capture.monitoredExtensions",
|
||||
"capture.minSizeBytes"
|
||||
]
|
||||
}
|
||||
},
|
||||
"assertions": [
|
||||
"a client re-reads only the keys it cares about",
|
||||
"the extension treats any capture.* key as a signal to call capture.getRules"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"name": "event.speed.global \u2014 the status bar's 1 Hz tick",
|
||||
"description": "Emitted even when nothing is active, so a client can tell 'idle' from 'disconnected'.",
|
||||
"notification": {
|
||||
"jsonrpc": "2.0",
|
||||
"method": "event.speed.global",
|
||||
"params": {
|
||||
"downBps": 29796556,
|
||||
"activeCount": 1,
|
||||
"queuedCount": 2,
|
||||
"limitBps": null
|
||||
}
|
||||
},
|
||||
"assertions": [
|
||||
"emitted at 1 Hz whether or not anything is downloading",
|
||||
"limitBps null means the limiter is off"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
{
|
||||
"name": "event.task.added \u2014 a new row appears",
|
||||
"description": "summary is always present so a client can insert the row without a follow-up download.get.",
|
||||
"notification": {
|
||||
"jsonrpc": "2.0",
|
||||
"method": "event.task.added",
|
||||
"params": {
|
||||
"taskId": "3f7a2b1c-5d6e-4f80-9a1b-2c3d4e5f6071",
|
||||
"summary": {
|
||||
"taskId": "3f7a2b1c-5d6e-4f80-9a1b-2c3d4e5f6071",
|
||||
"filename": "ubuntu-26.04-desktop-amd64.iso",
|
||||
"saveDir": "/home/sami/Downloads/Programs",
|
||||
"url": "https://releases.ubuntu.com/26.04/ubuntu-26.04-desktop-amd64.iso",
|
||||
"effectiveUrl": "https://releases.ubuntu.com/26.04/ubuntu-26.04-desktop-amd64.iso",
|
||||
"sizeBytes": 6228541440,
|
||||
"downloadedBytes": 0,
|
||||
"state": "queued",
|
||||
"speedBps": 0,
|
||||
"etaSeconds": null,
|
||||
"resumable": true,
|
||||
"segments": 8,
|
||||
"categoryId": "programs",
|
||||
"queueId": null,
|
||||
"queuePosition": null,
|
||||
"description": null,
|
||||
"createdAt": "$isoDate",
|
||||
"lastTryAt": null,
|
||||
"completedAt": null,
|
||||
"error": null
|
||||
}
|
||||
}
|
||||
},
|
||||
"assertions": [
|
||||
"every subscriber sees this, including the client that made the download.add call",
|
||||
"the row can be drawn from this payload alone"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
{
|
||||
"name": "event.task.progress \u2014 one batched tick for two tasks",
|
||||
"description": "A single array at no more than 4 Hz, never one notification per task. At twenty active downloads that is four messages a second instead of eighty.",
|
||||
"notification": {
|
||||
"jsonrpc": "2.0",
|
||||
"method": "event.task.progress",
|
||||
"params": {
|
||||
"tasks": [
|
||||
{
|
||||
"taskId": "3f7a2b1c-5d6e-4f80-9a1b-2c3d4e5f6071",
|
||||
"downloadedBytes": 2941190144,
|
||||
"speedBps": 29796556,
|
||||
"etaSeconds": 110,
|
||||
"segments": [
|
||||
{
|
||||
"index": 0,
|
||||
"downloadedBytes": 402653184,
|
||||
"speedBps": 4089446
|
||||
},
|
||||
{
|
||||
"index": 1,
|
||||
"downloadedBytes": 356515840,
|
||||
"speedBps": 3565158
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"taskId": "8c1d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
|
||||
"downloadedBytes": 402653184,
|
||||
"speedBps": 0,
|
||||
"etaSeconds": null,
|
||||
"segments": []
|
||||
}
|
||||
],
|
||||
"at": "$isoDate"
|
||||
}
|
||||
},
|
||||
"assertions": [
|
||||
"emitted at no more than 4 Hz regardless of how many tasks are active",
|
||||
"clients apply a row patch; rebuilding the model on this event is a bug",
|
||||
"a task with no segment detail still reports its byte counter"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"name": "event.task.removed \u2014 a row disappears",
|
||||
"description": "There is nothing further to fetch: the client deletes the row.",
|
||||
"notification": {
|
||||
"jsonrpc": "2.0",
|
||||
"method": "event.task.removed",
|
||||
"params": {
|
||||
"taskId": "3f7a2b1c-5d6e-4f80-9a1b-2c3d4e5f6071",
|
||||
"deletedFile": true
|
||||
}
|
||||
},
|
||||
"assertions": [
|
||||
"deletedFile tells the GUI whether to offer an undo that is still meaningful"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
{
|
||||
"name": "event.task.state \u2014 a task fails on a dead link",
|
||||
"description": "Carries the summary so the row repaints in full, and the error whenever the new state is failed or retry_wait.",
|
||||
"notification": {
|
||||
"jsonrpc": "2.0",
|
||||
"method": "event.task.state",
|
||||
"params": {
|
||||
"taskId": "3f7a2b1c-5d6e-4f80-9a1b-2c3d4e5f6071",
|
||||
"state": "failed",
|
||||
"previousState": "downloading",
|
||||
"summary": {
|
||||
"taskId": "3f7a2b1c-5d6e-4f80-9a1b-2c3d4e5f6071",
|
||||
"filename": "ubuntu-26.04-desktop-amd64.iso",
|
||||
"saveDir": "/home/sami/Downloads/Programs",
|
||||
"url": "https://releases.ubuntu.com/26.04/ubuntu-26.04-desktop-amd64.iso",
|
||||
"effectiveUrl": "https://releases.ubuntu.com/26.04/ubuntu-26.04-desktop-amd64.iso",
|
||||
"sizeBytes": 6228541440,
|
||||
"downloadedBytes": 0,
|
||||
"state": "failed",
|
||||
"speedBps": 0,
|
||||
"etaSeconds": null,
|
||||
"resumable": true,
|
||||
"segments": 8,
|
||||
"categoryId": "programs",
|
||||
"queueId": null,
|
||||
"queuePosition": null,
|
||||
"description": null,
|
||||
"createdAt": "$isoDate",
|
||||
"lastTryAt": "$isoDate",
|
||||
"completedAt": null,
|
||||
"error": {
|
||||
"code": -32013,
|
||||
"message": "HTTP 404 on resume",
|
||||
"httpStatus": 404,
|
||||
"retryable": false,
|
||||
"attempt": 3,
|
||||
"nextRetryAt": null
|
||||
}
|
||||
},
|
||||
"error": {
|
||||
"code": -32013,
|
||||
"message": "HTTP 404 on resume",
|
||||
"httpStatus": 404,
|
||||
"retryable": false,
|
||||
"attempt": 3,
|
||||
"nextRetryAt": null
|
||||
}
|
||||
}
|
||||
},
|
||||
"assertions": [
|
||||
"error is present exactly when state is failed or retry_wait",
|
||||
"retryable false means the scheduler will not pick this up again on its own"
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user