diff --git a/docs/architecture.md b/docs/architecture.md index 417bbd6..6860cd0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -78,6 +78,7 @@ graph TD - 平台继承:平台段的 `inherits = "<平台>"` 与 V1 写法 `{ ref = "<平台>" }` 都表示继承。加载时沿继承链补齐:本平台缺少的版本取自被继承的平台,`deps`、`exports`、`source` 在本平台未声明时同样继承;遇到环或不存在的平台即停止。平台级的 `ref` 不再生成名为 `ref` 的版本(0.0.64) - 版本条目的 `min_client`:能使用该版本的最旧客户端版本,解析为 `PlatformResource::min_client`。未指定版本时,客户端据此跳过自己不能使用的版本(0.0.64) - 版本条目的 `floor`:该版本仍可用的最旧打包修订号(`0 ≤ floor ≤ revision`,缺省 0),解析为 `PlatformResource::floor`,`resolve_resource` 随 `ref` 报告解析到的条目的值;高于 `revision` 时按 `revision` 读。客户端保留记录修订号不低于它的已装载荷,替换低于它的(0.0.65) +- 包级的 `extensions`:按命名空间区分的扩展数据(`extensions = { luban = { ... } }`),第一层键是读它的程序。加载为 `Package::extensions`:对象的 JSON 文本(键排序;键恰为 1..n 的表与空表是数组),原样交给调用方,libxpkg 不解释。JSON 表达不了的值(函数、userdata、非有限数、数组之外的非字符串键)、嵌套超过 16 层的表丢弃,序列化后超过 4 KiB 时整个丢弃(不截断);每次丢弃在 `Package::warnings` 里记一行。只改 `extensions` 不改变安装的内容,不 bump `revision`;旧加载器按名字取已知字段,读到它时忽略(0.0.66) ### mcpplibs.xpkg.index — 索引层 diff --git a/mcpp.toml b/mcpp.toml index b750984..7de739c 100644 --- a/mcpp.toml +++ b/mcpp.toml @@ -1,7 +1,7 @@ [package] namespace = "mcpplibs" name = "xpkg" -version = "0.0.65" +version = "0.0.66" description = "C++23 reference implementation of the xpkg V2 spec (multi-arch)" license = "Apache-2.0" repo = "https://github.com/openxlings/libxpkg" diff --git a/src/xpkg-loader.cppm b/src/xpkg-loader.cppm index 245d1a6..5c2aa5e 100644 --- a/src/xpkg-loader.cppm +++ b/src/xpkg-loader.cppm @@ -223,6 +223,157 @@ std::vector get_str_array(lua::State* L, int idx, const char* key) return result; } +// ---- extensions: namespaced data the loader keeps as JSON text ---- +// +// `extensions = { luban = { tier = 2, title = { en = "labwc" } } }` is read by +// the program each first-level key names; libxpkg and xlings keep it and hand +// it on unchanged (xpkg V2 spec, "extensions"). The loader turns the Lua table +// into canonical JSON text: object keys sorted, a table whose keys are exactly +// 1..n an array, an empty table an array. A value JSON cannot carry (a +// function, userdata, a non-finite number, a non-string key outside an array) +// is dropped with a warning; a table nested deeper than kExtensionsMaxDepth is +// dropped the same way (a table that holds itself ends there). The whole +// `extensions` is dropped, with a warning, when its text is over +// kExtensionsMaxBytes -- never cut, so half of it is never read as all of it. +inline constexpr std::size_t kExtensionsMaxBytes = 4096; +inline constexpr int kExtensionsMaxDepth = 16; + +void json_quote(std::string& out, std::string_view s) { + out += '"'; + for (unsigned char c : s) { + switch (c) { + case '"': out += "\\\""; break; + case '\\': out += "\\\\"; break; + case '\n': out += "\\n"; break; + case '\r': out += "\\r"; break; + case '\t': out += "\\t"; break; + case '\b': out += "\\b"; break; + case '\f': out += "\\f"; break; + default: + if (c < 0x20) out += std::format("\\u{:04x}", static_cast(c)); + else out += static_cast(c); + } + } + out += '"'; +} + +std::string lua_string_at(lua::State* L, int idx) { + unsigned long long len = 0; + const char* p = lua::tolstring(L, idx, &len); + return p ? std::string(p, static_cast(len)) : std::string{}; +} + +// Appends the value at `idx` as JSON; false (and a warning) when it is dropped. +bool lua_to_json(lua::State* L, int idx, std::string& out, const std::string& where, + std::vector& warnings, int depth) { + idx = lua::absindex(L, idx); + switch (lua::type(L, idx)) { + case lua::TSTRING: + json_quote(out, lua_string_at(L, idx)); + return true; + case lua::TBOOLEAN: + out += lua::toboolean(L, idx) ? "true" : "false"; + return true; + case lua::TNUMBER: { + if (lua::isinteger(L, idx)) { + out += std::to_string(lua::tointeger(L, idx)); + return true; + } + const double v = lua::tonumber(L, idx); + if (!std::isfinite(v)) { + warnings.push_back(where + ": a number that is not finite, dropped"); + return false; + } + out += std::format("{}", v); + return true; + } + case lua::TTABLE: break; + default: + warnings.push_back(where + ": a value of a type JSON cannot carry, dropped"); + return false; + } + if (depth >= kExtensionsMaxDepth) { + warnings.push_back(where + ": nested deeper than " + std::to_string(kExtensionsMaxDepth) + ", dropped"); + return false; + } + // Count the keys; the table is an array when they are exactly 1..n. + std::size_t keys = 0; + bool allStrings = true; + lua::pushnil(L); + while (lua::next(L, idx)) { + ++keys; + if (lua::type(L, -2) != lua::TSTRING) allStrings = false; + lua::pop(L, 1); + } + const auto n = static_cast(lua::rawlen(L, idx)); + if (keys == 0 || (n == keys && !allStrings)) { + out += '['; + bool first = true; + for (std::size_t i = 1; i <= n; ++i) { + lua::rawgeti(L, idx, static_cast(i)); + std::string item; + if (lua_to_json(L, -1, item, where + "[" + std::to_string(i) + "]", warnings, depth + 1)) { + if (!first) out += ','; + out += item; + first = false; + } + lua::pop(L, 1); + } + out += ']'; + return true; + } + std::vector names; + lua::pushnil(L); + while (lua::next(L, idx)) { + if (lua::type(L, -2) == lua::TSTRING) names.push_back(lua_string_at(L, -2)); + else warnings.push_back(where + ": a key that is not a string, dropped"); + lua::pop(L, 1); + } + std::ranges::sort(names); + out += '{'; + bool first = true; + for (const auto& name : names) { + lua::pushstring(L, name.c_str()); + lua::rawget(L, idx); + std::string item; + if (lua_to_json(L, -1, item, where + "." + name, warnings, depth + 1)) { + if (!first) out += ','; + json_quote(out, name); + out += ':'; + out += item; + first = false; + } + lua::pop(L, 1); + } + out += '}'; + return true; +} + +// The package's `extensions` as JSON text of an object, or "" when it has none. +std::string get_extensions(lua::State* L, int idx, std::vector& warnings) { + lua::getfield(L, idx, "extensions"); + std::string out; + const int type = lua::type(L, -1); + if (type == lua::TTABLE) { + std::vector notes; + std::string text; + lua_to_json(L, -1, text, "extensions", notes, 0); + if (text.size() > kExtensionsMaxBytes) { + warnings.push_back(std::format("extensions: {} bytes, over the {} limit, dropped", + text.size(), kExtensionsMaxBytes)); + } else if (text.starts_with('[') && text != "[]") { + warnings.push_back("extensions: a list, not a table of namespaces, dropped"); + } else { + for (auto& note : notes) warnings.push_back(std::move(note)); + out = text == "[]" ? std::string{} : std::move(text); + } + } else if (type != lua::TNIL) { + warnings.push_back("extensions: not a table, dropped"); + } + lua::pop(L, 1); + return out; +} + PackageType parse_type(const std::string& s) { if (s == "script") return PackageType::Script; if (s == "template") return PackageType::Template; @@ -845,6 +996,7 @@ load_package(const fs::path& pkg_path, const LoaderContext& context) { p.archs = loader_detail::get_str_array(L, pkg_idx, "archs"); p.programs = loader_detail::get_str_array(L, pkg_idx, "programs"); p.xpm = loader_detail::parse_xpm(L, pkg_idx); + p.extensions = loader_detail::get_extensions(L, pkg_idx, p.warnings); lua::close(L); return p; diff --git a/src/xpkg.cppm b/src/xpkg.cppm index 7cadeb6..67365b4 100644 --- a/src/xpkg.cppm +++ b/src/xpkg.cppm @@ -145,6 +145,15 @@ struct Package { std::vector categories, keywords, programs, archs; bool xvm_enable = false; PlatformMatrix xpm; + // Namespaced data for other programs (`extensions = { luban = {...} }`): + // each first-level key names the program that reads it. libxpkg and xlings + // keep it and hand it on unchanged, never interpreting it; it does not + // change what is installed (xpkg V2 spec, "extensions"). JSON text of an + // object with sorted keys; empty when the recipe states none. + std::string extensions; + // What the loader dropped while reading the recipe, one line each (an + // `extensions` value JSON cannot carry, an `extensions` over the limit). + std::vector warnings; ~Package(); }; diff --git a/tests/test_loader.cpp b/tests/test_loader.cpp index 7433ade..40fe578 100644 --- a/tests/test_loader.cpp +++ b/tests/test_loader.cpp @@ -812,3 +812,82 @@ TEST(LoaderTest, AVersionNamesTheOldestClientThatCanUseIt) { EXPECT_EQ(result->xpm.entries.at("macosx").at("1.1.0").min_client, "2026.10.16.2"); EXPECT_TRUE(result->xpm.entries.at("linux").at("1.0.0").min_client.empty()); } + +// ---- extensions (xpkg V2, libxpkg 0.0.66) ---- + +static fs::path write_recipe(std::string_view test_name, std::string_view extensions) { + auto dir = fs::temp_directory_path() / ("libxpkg-ext-" + std::string(test_name)); + fs::remove_all(dir); + fs::create_directories(dir); + auto file = dir / "pkg.lua"; + std::ofstream out(file); + out << "package = {\n spec = \"1\", name = \"ext\", description = \"d\",\n" + << extensions + << "\n xpm = { linux = { [\"1.0.0\"] = { url = \"https://example.com/a.tar.gz\", sha256 = \"00\" } } },\n}\n"; + return file; +} + +TEST(LoaderTest, Extensions_KeptAsCanonicalJson) { + auto file = write_recipe("canonical", + " extensions = { luban = { tier = 2, gpu = \"better\", size = 1.5, preview = false,\n" + " title = { zh = \"标题\", en = \"Title \\\"q\\\"\" }, highlights = { \"cmake\", \"yazi\" }, empty = {} } },"); + auto p = load_package(file); + ASSERT_TRUE(p.has_value()) << p.error(); + EXPECT_EQ(p->extensions, + R"({"luban":{"empty":[],"gpu":"better","highlights":["cmake","yazi"],"preview":false,"size":1.5,"tier":2,"title":{"en":"Title \"q\"","zh":"标题"}}})"); + EXPECT_TRUE(p->warnings.empty()); +} + +TEST(LoaderTest, Extensions_AbsentIsEmpty) { + auto p = load_package(write_recipe("absent", "")); + ASSERT_TRUE(p.has_value()) << p.error(); + EXPECT_TRUE(p->extensions.empty()); + EXPECT_TRUE(p->warnings.empty()); +} + +TEST(LoaderTest, Extensions_DropsWhatJsonCannotCarry) { + auto p = load_package(write_recipe("types", + " extensions = { luban = { tier = 1, hook = function() end, [3] = \"x\", inf = math.huge } },")); + ASSERT_TRUE(p.has_value()) << p.error(); + EXPECT_EQ(p->extensions, R"({"luban":{"tier":1}})"); + EXPECT_EQ(p->warnings.size(), 3u); +} + +TEST(LoaderTest, Extensions_SelfReferenceEndsAtTheDepthLimit) { + auto p = load_package(write_recipe("cycle", + " extensions = (function() local t = { luban = {} }; t.luban.self = t.luban; return t end)(),")); + ASSERT_TRUE(p.has_value()) << p.error(); + EXPECT_TRUE(p->extensions.starts_with(R"({"luban":{"self":{"self":)")); + EXPECT_FALSE(p->warnings.empty()); +} + +TEST(LoaderTest, Extensions_OverTheLimitIsDroppedWhole) { + auto p = load_package(write_recipe("size", + " extensions = { luban = { summary = string.rep(\"x\", 5000), tier = 1 } },")); + ASSERT_TRUE(p.has_value()) << p.error(); + EXPECT_TRUE(p->extensions.empty()); + ASSERT_EQ(p->warnings.size(), 1u); + EXPECT_NE(p->warnings[0].find("over the 4096 limit"), std::string::npos); +} + +TEST(LoaderTest, Extensions_NotATableIsDropped) { + auto p = load_package(write_recipe("scalar", " extensions = \"luban\",")); + ASSERT_TRUE(p.has_value()) << p.error(); + EXPECT_TRUE(p->extensions.empty()); + EXPECT_EQ(p->warnings.size(), 1u); + auto list = load_package(write_recipe("list", " extensions = { \"a\", \"b\" },")); + ASSERT_TRUE(list.has_value()) << list.error(); + EXPECT_TRUE(list->extensions.empty()); + EXPECT_EQ(list->warnings.size(), 1u); +} + +// A loader that predates `extensions` reads known fields by name and has no +// check for unknown keys: a recipe with `extensions` loads, the rest unchanged. +TEST(LoaderTest, Extensions_DoNotChangeTheOtherFields) { + auto with = load_package(write_recipe("with", " extensions = { luban = { tier = 3 } },")); + auto without = load_package(write_recipe("without", "")); + ASSERT_TRUE(with.has_value() && without.has_value()); + EXPECT_EQ(with->name, without->name); + EXPECT_EQ(with->description, without->description); + EXPECT_EQ(with->xpm.entries.size(), without->xpm.entries.size()); +}