From 29e64132852746d34a43ffdffc2c385a6b20f5fe Mon Sep 17 00:00:00 2001 From: guolin Date: Wed, 30 Sep 2026 09:33:09 +0800 Subject: [PATCH] docs(skill): ban dispatch-level wl_resource type checks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. libwayland validates object arguments before a request handler runs: non-nullable args are never NULL, unknown ids, type mismatches and destroyed resources fail dispatch with a protocol error, and only allow-null args can arrive as NULL. 2. Condense the Request Handler Argument Validation section in treeland-private-wayland-protocol SKILL accordingly: handlers need no validation that a passed object matches its protocol-declared type or is still alive; the semantic-layer checks stay (cross-client ownership, inert resources, missing wrappers, value validity, allow-null args). 3. Add the matching Output Requirements checklist item. Log: codify the WM-558 lesson that libwayland already validates wl_resource arguments, so handlers need no dispatch-level type checks Influence: 1. Docs-only change, no build or runtime impact. 2. Request-handler code written per the skill should omit dispatch-level type checks. 3. Reviewers can apply the new checklist item when auditing protocol handler patches. docs(skill): 禁止请求处理函数内分发级 wl_resource 类型检查 1. libwayland 分发层在调用请求处理函数前已完成对象参数校验：非空参数不会 为 NULL，未知 id、类型不符或已销毁对象在进入处理函数前即报协议错误， 仅 allow-null 参数可为 NULL。 2. treeland-private-wayland-protocol SKILL 的 Request Handler Argument Validation 一节据此收为两段：处理函数无需再校验传入对象是否符合协议 声明类型或仍然存活，保留语义层检查（跨 client 归属、inert resource、 缺失包装对象、数值/枚举合法性、allow-null 参数判 NULL）。 3. Output Requirements 审查清单补充对应条目。 Log: 将 WM-558 经验（libwayland 已校验 wl_resource，处理函数无需重复类型检查）落实进协议 SKILL Influence: 1. 仅文档变更，不影响编译与运行。 2. 后续按该 skill 生成的协议处理代码应省略分发级类型检查。 3. 走查协议处理补丁时可使用新增审查条目。 Multica Issue: WM-561 --- .agents/skills/treeland-private-wayland-protocol/SKILL.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.agents/skills/treeland-private-wayland-protocol/SKILL.md b/.agents/skills/treeland-private-wayland-protocol/SKILL.md index 671077883..8b6327e26 100644 --- a/.agents/skills/treeland-private-wayland-protocol/SKILL.md +++ b/.agents/skills/treeland-private-wayland-protocol/SKILL.md @@ -131,6 +131,11 @@ Use this rule: Do not create a public header for every protocol child object just because the protocol contains one. Promote it to a public wrapper only when business code actually needs to know about it. +## Request Handler Argument Validation +libwayland validates every object argument before a request handler runs: non-nullable args are never NULL, unknown ids and type mismatches fail dispatch with a protocol error, destroyed resources no longer resolve, and only `allow-null="true"` args can arrive as NULL. Request handlers therefore need no validation that a passed object matches its protocol-declared type or is still alive — such checks are unreachable dead code. + +What the dispatch layer cannot know, the handler must still check: cross-client ownership (`wl_resource_get_client`), inert resources (`wlr_*_from_resource` returning NULL), missing wrappers (`WSurface::fromHandle` / `WOutput::fromHandle` returning nullptr), protocol value rules (positive sizes, enum ranges), and NULL when the xml marks the arg `allow-null="true"`. + ## Manager Interface Wiring The public class usually implements: @@ -366,3 +371,4 @@ When using this skill for a real task, make these explicit first: 2. how manager `create/destroy/global/interfaceName` should be implemented 3. how `destroy(...)` and `destroy_resource(...)` split responsibilities 4. where the protocol enters the startup path from `Helper::init` +5. that request handlers add no object validation already done by the dispatch layer (see Request Handler Argument Validation)