Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 — 索引层

Expand Down
2 changes: 1 addition & 1 deletion mcpp.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
152 changes: 152 additions & 0 deletions src/xpkg-loader.cppm
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,157 @@ std::vector<std::string> 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<unsigned>(c));
else out += static_cast<char>(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<std::size_t>(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<std::string>& 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<std::size_t>(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<lua::Integer>(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<std::string> 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<std::string>& warnings) {
lua::getfield(L, idx, "extensions");
std::string out;
const int type = lua::type(L, -1);
if (type == lua::TTABLE) {
std::vector<std::string> 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;
Expand Down Expand Up @@ -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;
Expand Down
9 changes: 9 additions & 0 deletions src/xpkg.cppm
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,15 @@ struct Package {
std::vector<std::string> 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<std::string> warnings;
~Package();
};

Expand Down
79 changes: 79 additions & 0 deletions tests/test_loader.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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());
}
Loading