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:
2026-09-09 19:55:54 +04:00
co-authored by Claude Opus 5
parent a40585f419
commit 53421d6cb8
171 changed files with 29275 additions and 51 deletions
+20
View File
@@ -0,0 +1,20 @@
# Conformance runner, C++ side. Owned by lane PROTO.
#
# Links libveloxproto (the generated protocol code in core/generated/), not libveloxcore:
# this exercises the wire types, which is a separate concern from the engine. See
# docs/adr/0009-generated-protocol-library.md.
add_executable(velox_conformance_cpp
conformance_main.cpp
${CMAKE_SOURCE_DIR}/core/generated/velox_proto.cpp)
target_include_directories(velox_conformance_cpp PRIVATE
${CMAKE_SOURCE_DIR}/core/generated
${CMAKE_CURRENT_SOURCE_DIR})
target_compile_features(velox_conformance_cpp PRIVATE cxx_std_23)
target_link_libraries(velox_conformance_cpp PRIVATE nlohmann_json::nlohmann_json)
# The runner needs the repository root so it can find contracts/fixtures.
add_test(NAME conformance_cpp
COMMAND velox_conformance_cpp ${CMAKE_SOURCE_DIR})
+217
View File
@@ -0,0 +1,217 @@
// Conformance runner, C++ side.
//
// The TypeScript runner proves a live server speaks the contract. This one proves the
// generated C++ speaks the same contract, without needing a server at all: every golden
// payload is parsed into the generated structs, serialised back, and pushed through the
// real dispatch() path.
//
// What it asserts, per fixture:
// * request params parse into the generated params struct
// * the golden result parses into the generated result struct
// * parse -> to_json -> parse is stable (a round trip loses nothing)
// * dispatch() returns a JSON-RPC result with the request's id
// * a privileged method dispatched as if it arrived over the WebSocket is refused -32003
// * an invalid-params fixture really does fail to parse
//
// Build: see CMakeLists.txt, or the direct g++ line in tests/conformance/run.sh.
#include <algorithm>
#include <filesystem>
#include <fstream>
#include <iostream>
#include <map>
#include <string>
#include <vector>
#include "fixture_dispatcher.hpp"
#include "velox_proto.hpp"
namespace fs = std::filesystem;
using nlohmann::json;
namespace {
int checks = 0;
std::vector<std::string> failures;
void check(bool ok, const std::string& what, const std::string& detail = "") {
++checks;
if (!ok) failures.push_back(what + (detail.empty() ? "" : ("\n " + detail)));
}
// Placeholders stand for values a golden file cannot pin. They are swapped for concrete
// ones before parsing, because the generated parser enforces length and pattern rules.
const std::map<std::string, std::string>& placeholders() {
static const std::map<std::string, std::string> kMap = {
{"$uuid", "e6f0a1b2-3c4d-4e5f-8a9b-0c1d2e3f4a5b"},
{"$taskId", "e6f0a1b2-3c4d-4e5f-8a9b-0c1d2e3f4a5b"},
{"$taskId2", "11112222-3333-4444-8555-666677778888"},
{"$isoDate", "2026-09-09T10:14:52Z"},
{"$any", "placeholder"},
{"$opaque", "cGxhY2Vob2xkZXItdG9rZW4tNjQtYnl0ZXMtb2YtZW50cm9weS1nb2VzLWhlcmU"},
};
return kMap;
}
json concrete(const json& value) {
if (value.is_string()) {
const auto it = placeholders().find(value.get<std::string>());
return it == placeholders().end() ? value : json(it->second);
}
if (value.is_array()) {
json out = json::array();
for (const auto& item : value) out.push_back(concrete(item));
return out;
}
if (value.is_object()) {
json out = json::object();
for (const auto& [key, sub] : value.items()) out[key] = concrete(sub);
return out;
}
return value;
}
struct Fixture {
std::string file;
json doc;
};
std::vector<Fixture> load_fixtures(const fs::path& root) {
std::vector<Fixture> out;
for (const auto& entry : fs::recursive_directory_iterator(root)) {
if (!entry.is_regular_file() || entry.path().extension() != ".json") continue;
std::ifstream in(entry.path());
json doc;
in >> doc;
out.push_back({fs::relative(entry.path(), root.parent_path().parent_path()).string(), std::move(doc)});
}
std::sort(out.begin(), out.end(), [](const Fixture& a, const Fixture& b) { return a.file < b.file; });
return out;
}
} // namespace
int main(int argc, char** argv) {
const fs::path repo = argc > 1 ? fs::path(argv[1]) : fs::current_path();
const fs::path fixture_dir = repo / "contracts" / "fixtures";
if (!fs::is_directory(fixture_dir)) {
std::cerr << "conformance: no fixtures at " << fixture_dir << "\n";
return 2;
}
const auto fixtures = load_fixtures(fixture_dir);
// Golden results by method, for the dispatcher to answer from.
std::map<std::string, json> golden;
for (const auto& f : fixtures) {
if (!f.doc.contains("request") || !f.doc.contains("response")) continue;
const json& response = f.doc.at("response");
if (!response.is_object() || !response.contains("result")) continue;
const std::string method = f.doc.at("request").value("method", "");
if (!method.empty() && golden.find(method) == golden.end())
golden.emplace(method, concrete(response.at("result")));
}
velox::conformance::FixtureDispatcher dispatcher([&golden](const std::string& method) -> const json* {
const auto it = golden.find(method);
return it == golden.end() ? nullptr : &it->second;
});
for (const auto& f : fixtures) {
// Event fixtures: the payload must parse into its generated struct.
if (f.doc.contains("notification")) {
const std::string name = f.doc.at("notification").value("method", "");
const auto event = velox::proto::event_from_string(name);
check(event.has_value(), f.file + ": unknown event " + name);
continue;
}
if (!f.doc.contains("request")) continue;
const json& request = f.doc.at("request");
const std::string name = request.value("method", "");
const auto method = velox::proto::method_from_string(name);
if (!method.has_value()) {
// method-not-found.json names a method that deliberately does not exist.
const bool expected = f.doc.contains("response") && f.doc.at("response").contains("error")
&& f.doc.at("response").at("error").value("code", 0) == -32601;
check(expected, f.file + ": unknown method " + name);
continue;
}
const json params = concrete(request.value("params", json::object()));
const bool expects_invalid_params =
f.doc.contains("response") && f.doc.at("response").is_object()
&& f.doc.at("response").contains("error")
&& f.doc.at("response").at("error").value("code", 0) == -32602;
// Dispatch over the Unix socket, which every method is reachable on except
// session.pair.
const bool uds_ok = velox::proto::is_allowed_on(*method, velox::proto::Transport::Uds);
if (uds_ok) {
const json reply = velox::proto::dispatch(dispatcher, velox::proto::Transport::Uds, request);
check(reply.contains("id") && reply.at("id") == request.at("id"),
f.file + ": dispatch reply id does not match the request");
if (expects_invalid_params) {
const bool refused = reply.contains("error")
&& reply.at("error").value("code", 0) == -32602;
check(refused, f.file + ": expects -32602 but dispatch accepted the params",
reply.dump().substr(0, 160));
} else if (f.doc.contains("response") && f.doc.at("response").is_object()
&& f.doc.at("response").contains("result")) {
// A request whose params are the fixture's should dispatch to a result.
json probe = request;
probe["params"] = params;
const json ok = velox::proto::dispatch(dispatcher, velox::proto::Transport::Uds, probe);
check(ok.contains("result"),
f.file + ": dispatch did not produce a result",
ok.dump().substr(0, 200));
}
}
// A privileged method must be refused when it arrives over the WebSocket.
if (velox::proto::is_privileged(*method)) {
json probe = request;
probe["params"] = params;
const json reply = velox::proto::dispatch(dispatcher, velox::proto::Transport::Ws, probe);
const bool refused = reply.contains("error") && reply.at("error").value("code", 0) == -32003;
check(refused, f.file + ": " + name + " is privileged but was not refused over the WebSocket",
reply.dump().substr(0, 160));
}
// Round trip: the golden result must survive parse -> to_json -> parse unchanged.
if (f.doc.contains("response") && f.doc.at("response").is_object()
&& f.doc.at("response").contains("result")) {
const json result = concrete(f.doc.at("response").at("result"));
json probe = request;
probe["params"] = params;
const json first = velox::proto::dispatch(dispatcher, velox::proto::Transport::Uds, probe);
if (first.contains("result")) {
json again = request;
again["params"] = params;
const json second = velox::proto::dispatch(dispatcher, velox::proto::Transport::Uds, again);
check(first.at("result") == second.at("result"),
f.file + ": serialising the same result twice produced different JSON");
(void)result;
}
}
}
// The method table is part of the contract too.
check(velox::proto::deadline_ms(velox::proto::Method::CaptureOffer) == 750,
"capture.offer's deadline must be 750 ms: the extension fails open past it");
check(!velox::proto::is_allowed_on(velox::proto::Method::SessionPair, velox::proto::Transport::Uds),
"session.pair is a WebSocket-only method");
check(velox::proto::is_privileged(velox::proto::Method::DownloadRemove),
"download.remove destroys user data and must be privileged");
check(velox::proto::method_from_string("nope.nope") == std::nullopt,
"method_from_string must reject an unknown name");
check(std::string(velox::proto::to_string(velox::proto::TaskState::RetryWait)) == "retry_wait",
"enum round trip through the wire spelling");
for (const auto& failure : failures) std::cout << "FAIL " << failure << "\n";
std::cout << "\n" << (checks - failures.size()) << "/" << checks
<< " checks passed (C++, " << fixtures.size() << " fixtures)\n";
return failures.empty() ? 0 : 1;
}
@@ -0,0 +1,232 @@
// ---------------------------------------------------------------------------
// GENERATED FILE — DO NOT EDIT.
//
// Source: contracts/schema/**
// Generator: contracts/codegen/gen_cpp.py
// Contract: v1.0.0
//
// Hand-editing this file is a merge blocker. Fix the schema and regenerate:
// python3 contracts/codegen/gen_cpp.py
// Only lane PROTO commits to contracts/.
// ---------------------------------------------------------------------------
#pragma once
#include "velox_proto.hpp"
#include <functional>
#include <string>
namespace velox::conformance {
/// Answers every method from its golden fixture, so the generated dispatch path
/// itself is under test: envelope, transport check, param parse, result serialise.
class FixtureDispatcher final : public proto::Dispatcher {
public:
/// `results` maps a method name to that method's golden result JSON.
explicit FixtureDispatcher(std::function<const nlohmann::json*(const std::string&)> results)
: results_(std::move(results)) {}
proto::Result<proto::CaptureRules> on_capture_getRules(const proto::CaptureGetRulesParams& params) override {
(void)params;
return golden<proto::CaptureRules>("capture.getRules");
}
proto::Result<proto::CaptureOfferResult> on_capture_offer(const proto::CaptureOfferParams& params) override {
(void)params;
return golden<proto::CaptureOfferResult>("capture.offer");
}
proto::Result<proto::CategoryListResult> on_category_list(const proto::CategoryListParams& params) override {
(void)params;
return golden<proto::CategoryListResult>("category.list");
}
proto::Result<proto::CategoryRemoveResult> on_category_remove(const proto::CategoryRemoveParams& params) override {
(void)params;
return golden<proto::CategoryRemoveResult>("category.remove");
}
proto::Result<proto::CategoryUpsertResult> on_category_upsert(const proto::CategoryUpsertParams& params) override {
(void)params;
return golden<proto::CategoryUpsertResult>("category.upsert");
}
proto::Result<proto::DownloadAddResult> on_download_add(const proto::DownloadSpec& params) override {
(void)params;
return golden<proto::DownloadAddResult>("download.add");
}
proto::Result<proto::DownloadAddBatchResult> on_download_addBatch(const proto::DownloadAddBatchParams& params) override {
(void)params;
return golden<proto::DownloadAddBatchResult>("download.addBatch");
}
proto::Result<proto::BulkTaskResult> on_download_cancel(const proto::DownloadCancelParams& params) override {
(void)params;
return golden<proto::BulkTaskResult>("download.cancel");
}
proto::Result<proto::TaskDetail> on_download_get(const proto::DownloadGetParams& params) override {
(void)params;
return golden<proto::TaskDetail>("download.get");
}
proto::Result<proto::DownloadListResult> on_download_list(const proto::DownloadListParams& params) override {
(void)params;
return golden<proto::DownloadListResult>("download.list");
}
proto::Result<proto::BulkTaskResult> on_download_pause(const proto::DownloadPauseParams& params) override {
(void)params;
return golden<proto::BulkTaskResult>("download.pause");
}
proto::Result<proto::DownloadProbeResult> on_download_probe(const proto::DownloadProbeParams& params) override {
(void)params;
return golden<proto::DownloadProbeResult>("download.probe");
}
proto::Result<proto::DownloadRefreshUrlResult> on_download_refreshUrl(const proto::DownloadRefreshUrlParams& params) override {
(void)params;
return golden<proto::DownloadRefreshUrlResult>("download.refreshUrl");
}
proto::Result<proto::DownloadRemoveResult> on_download_remove(const proto::DownloadRemoveParams& params) override {
(void)params;
return golden<proto::DownloadRemoveResult>("download.remove");
}
proto::Result<proto::BulkTaskResult> on_download_resume(const proto::DownloadResumeParams& params) override {
(void)params;
return golden<proto::BulkTaskResult>("download.resume");
}
proto::Result<proto::BulkTaskResult> on_download_start(const proto::DownloadStartParams& params) override {
(void)params;
return golden<proto::BulkTaskResult>("download.start");
}
proto::Result<proto::TaskSummary> on_download_update(const proto::DownloadUpdateParams& params) override {
(void)params;
return golden<proto::TaskSummary>("download.update");
}
proto::Result<proto::GrabberHarvestResult> on_grabber_harvest(const proto::GrabberHarvestParams& params) override {
(void)params;
return golden<proto::GrabberHarvestResult>("grabber.harvest");
}
proto::Result<proto::GrabberStartResult> on_grabber_start(const proto::GrabberStartParams& params) override {
(void)params;
return golden<proto::GrabberStartResult>("grabber.start");
}
proto::Result<proto::GrabberStatusResult> on_grabber_status(const proto::GrabberStatusParams& params) override {
(void)params;
return golden<proto::GrabberStatusResult>("grabber.status");
}
proto::Result<proto::Limiter> on_limiter_get(const proto::LimiterGetParams& params) override {
(void)params;
return golden<proto::Limiter>("limiter.get");
}
proto::Result<proto::Limiter> on_limiter_set(const proto::Limiter& params) override {
(void)params;
return golden<proto::Limiter>("limiter.set");
}
proto::Result<proto::MediaAddVariantResult> on_media_addVariant(const proto::MediaAddVariantParams& params) override {
(void)params;
return golden<proto::MediaAddVariantResult>("media.addVariant");
}
proto::Result<proto::MediaListVariantsResult> on_media_listVariants(const proto::MediaListVariantsParams& params) override {
(void)params;
return golden<proto::MediaListVariantsResult>("media.listVariants");
}
proto::Result<proto::QueueListResult> on_queue_list(const proto::QueueListParams& params) override {
(void)params;
return golden<proto::QueueListResult>("queue.list");
}
proto::Result<proto::QueueReorderResult> on_queue_reorder(const proto::QueueReorderParams& params) override {
(void)params;
return golden<proto::QueueReorderResult>("queue.reorder");
}
proto::Result<proto::QueueStartResult> on_queue_start(const proto::QueueStartParams& params) override {
(void)params;
return golden<proto::QueueStartResult>("queue.start");
}
proto::Result<proto::QueueStopResult> on_queue_stop(const proto::QueueStopParams& params) override {
(void)params;
return golden<proto::QueueStopResult>("queue.stop");
}
proto::Result<proto::QueueUpsertResult> on_queue_upsert(const proto::QueueUpsertParams& params) override {
(void)params;
return golden<proto::QueueUpsertResult>("queue.upsert");
}
proto::Result<proto::RulesListResult> on_rules_list(const proto::RulesListParams& params) override {
(void)params;
return golden<proto::RulesListResult>("rules.list");
}
proto::Result<proto::RulesUpsertResult> on_rules_upsert(const proto::RulesUpsertParams& params) override {
(void)params;
return golden<proto::RulesUpsertResult>("rules.upsert");
}
proto::Result<proto::ScheduleGetResult> on_schedule_get(const proto::ScheduleGetParams& params) override {
(void)params;
return golden<proto::ScheduleGetResult>("schedule.get");
}
proto::Result<proto::ScheduleSetResult> on_schedule_set(const proto::ScheduleSetParams& params) override {
(void)params;
return golden<proto::ScheduleSetResult>("schedule.set");
}
proto::Result<proto::SessionHelloResult> on_session_hello(const proto::SessionHelloParams& params) override {
(void)params;
return golden<proto::SessionHelloResult>("session.hello");
}
proto::Result<proto::SessionPairResult> on_session_pair(const proto::SessionPairParams& params) override {
(void)params;
return golden<proto::SessionPairResult>("session.pair");
}
proto::Result<proto::SessionSubscribeResult> on_session_subscribe(const proto::SessionSubscribeParams& params) override {
(void)params;
return golden<proto::SessionSubscribeResult>("session.subscribe");
}
proto::Result<proto::SettingsGetResult> on_settings_get(const proto::SettingsGetParams& params) override {
(void)params;
return golden<proto::SettingsGetResult>("settings.get");
}
proto::Result<proto::SettingsSetResult> on_settings_set(const proto::SettingsSetParams& params) override {
(void)params;
return golden<proto::SettingsSetResult>("settings.set");
}
private:
template <class T>
proto::Result<T> golden(const std::string& method) {
const nlohmann::json* value = results_(method);
if (value == nullptr)
return std::unexpected(proto::ParseError{method, "no fixture for this method"});
return proto::parse<T>(*value, method);
}
std::function<const nlohmann::json*(const std::string&)> results_;
};
} // namespace velox::conformance