Skip to content

Latest commit

 

History

History
182 lines (136 loc) · 17.6 KB

ERROR_HANDLING.md

File metadata and controls

182 lines (136 loc) · 17.6 KB

错误语义与 expected 试点改造评估

状态:首批 Format 错误分类、信息读取接口和 CLI info 已实现;2026-10-13 用户确认提交 2b2999a 的 MSVC/Linux 远端验证全部通过。

本文规定程序错误的含义及传递边界,并评估将 expected 接入 CLI info 的范围。 它不修改 v1 文件格式、协议边界或认证与输出事务规则。 实现进度与验证依据见 TODO。

1. 改造背景与当前实现

改造前 include/filecrypt/error.hpp 提供 ErrorCode 和 Error,分类为 invalid_argument、length、logic、runtime,反映标准异常的继承关系。 当时 Format 的 Header、Metadata 和 AAD try_* 接口调用原异常接口,再捕获标准异常并转换错误值。 生产流程尚未消费结果接口;tests/format/expected_test.cpp 仅覆盖 Header 成功、错误 Magic 和短 Header 的 AAD 拒绝。

本轮已在失败点标识语义,Format 的 try_* 仅转换已分类异常,并通过 try_inspect_file 接入 CLI info。错误类别与具体诊断均使用中文展示, 底层继续复用异常实现;不以消除异常开销或全模块迁移为目标。

2. 错误类型与语义

以下八类语义均已加入 ErrorCode;首批实际接入参数、格式不支持、结构异常和 IO 错误, 其余类别保留供后续流程评估,尚未统一接入对应失败路径。 名称表示程序错误类别,不是文件协议编号,也不规定 CLI 退出码。

类型 语义 典型触发 处理原则
invalid_argument 调用者提供的选项或 API 参数不合法 缺少选项值、非法数值、冲突选项、不合法的调用参数 指出需要修正的参数;不据此判断输入文件损坏
unsupported_format 输入记录的格式能力当前不受支持 未支持的文件版本、Algorithm/KDF/Compression 编号、未分配且按规范应报告不支持的 File Type 明确当前程序无法解释该内容;不猜测、不降级
invalid_format 输入字节不符合已知格式的结构或字段约束 错误 Magic、容器截断、Metadata 长度不符、非零 Padding、非法参数编码、无效目录树或数据范围 报告结构异常并保留具体诊断;不声称已认证或已确认篡改
resource_limit 操作超过当前允许执行的资源上限 合法 KDF 参数超出本机策略、解压窗口或累计输出超过配置上限 说明超出哪项限制;与协议字段合法性分开判断
authentication_failed 完整 AEAD 消息未通过认证 错误密码、错误 Tag、AAD 或密文被改变 保持“密码错误或文件已被篡改”的统一提示,不细分密码与篡改原因
output_conflict 输出名称已被占用或提交时发生冲突 已有目标、无覆盖提交遇到竞争目标、目标文件系统名称别名冲突 拒绝覆盖;保留已有目标
io_error 文件或平台 IO 操作失败 打开、定位、读取、写入、刷新失败,权限或磁盘错误 保留操作诊断;有可靠系统错误码时保留该码,不推断未确认的原因
internal_error 程序状态或内部调用契约被违反 已关闭的密码上下文再次使用、已提交事务继续写入、Reader 返回超出缓冲区的长度 保留诊断;不提示用户通过修改密码、文件或资源上限解决

分类边界

  • 同样是 std::invalid_argument,CLI 选项错误、未知文件版本和非零 Padding 分别属于三种不同语义。必须在知道失败原因的位置确定分类,不能匹配 what() 文本,也不能单凭标准异常类型判断。
  • 选项里未知的算法名称属于 invalid_argument;文件中未知的算法编号属于 unsupported_format。已知编号下违反冻结参数布局的值属于 invalid_format。
  • 保留 Flags 位被置位、Reserved 字节非零、File Type 0xFFFF 属于 invalid_format。未分配 File Type 按 Registry 的严格读取规则属于 unsupported_format。合法 Unknown 值 0xFFFE 不产生错误。
  • KDF 参数违反协议的最小成本、版本或保留字段规则属于 invalid_format;参数合法但超过调用者资源策略属于 resource_limit。调用者传入不合法运行配置属于 invalid_argument。
  • 超出算法单消息长度上限与超出可调整资源策略是不同原因,诊断不得混写。该路径不在首批改造中,后续接入时单独确定映射,不暗示提高本机上限能突破算法边界。
  • IO 层不理解 .fcry。它报告意外结束或读取失败;应用层在读取识别前缀、Header 或 Metadata 时,将意外结束解释为 invalid_format。
  • 只有操作系统或文件系统确认名称冲突时才报告 output_conflict;不能把全部创建或提交失败都归为冲突。权限不足等仍属于 io_error。
  • 符号链接拒绝、源对象变化、目标平台名称限制等路径不在首批范围内。后续迁移前需按具体操作确定语义,不能笼统归为格式损坏或程序错误。
  • 文件同时包含多个问题时,按现有校验顺序返回首先遇到的错误;不为分类重排验证或绕过结构检查。

3. 错误对象与传递方式

首批错误值继续使用两个字段:

struct Error {
    ErrorCode code;
    std::string message;
};

code 用于稳定的程序分支;message 说明失败原因,保留原有可定位诊断。 错误对象不保存密码、派生密钥或明文。普通路径等上下文仅在有助于定位操作时添加。

系统错误码可在后续需要时增加为可选的 std::error_code;首批不强制引入。 仅在失败接口提供可靠错误码时记录,不从流状态或残留的 errno 猜测“文件不存在”“权限不足”等原因。 暂不添加统一路径、阶段、字段偏移、建议动作等必填字段。

错误语义独立于异常或 expected。首批允许底层继续抛异常,应用边界将已识别的失败转换为错误值, CLI 消费 expected。返回类型体现的是已分类失败,不承诺任何异常均被转换。

  • 已迁移的失败通过 FormatError : std::invalid_argument 和 OperationError : std::runtime_error 携带类别,转换时直接保留类别与诊断。
  • 保留 Header、Metadata、AAD 和 inspect_file 原异常 API 的签名、成功行为及既有异常基类约定;不让旧调用方依赖新的 ErrorCode 才能运行。
  • 原 invalid_argument、length、logic、runtime 枚举及数值 0..3 保留;error_from_exception 对普通标准异常仍采用旧映射。已迁移的 try_* 只捕获已分类异常,因此格式失败现在返回具体语义类别,旧调用方若检查结果码需相应调整。
  • std::bad_alloc 等分配失败继续传播,不作为普通格式或 IO 错误吞掉。构造错误字符串也可能分配,try_* 和新增接口不声明 noexcept。
  • 未迁移或未识别的异常继续交给原外层处理,不统一伪装为 io_error 或 internal_error。遇到这类路径时记录后续分类需求。
  • Crypto、Compression、IO、Platform 的构造、回调和异常清理流程暂不改成 expected。析构清理诊断继续独立报告,不能覆盖原操作错误,也不能在析构中抛出新异常。

4. 首个实际调用:CLI info

已增加应用接口:

[[nodiscard]] std::expected<FileInfo, Error> try_inspect_file(
    const std::filesystem::path& path);

调用流程:CLI info → try_inspect_file → 现有版本分发及 v1 信息读取。 原 inspect_file 异常接口继续保留,共享同一信息读取实现;不复制一套协议解析逻辑。 应用边界只转换 FormatError 和 OperationError,内部继续使用原异常接口。 空路径返回 invalid_argument,同时保留旧接口的 std::runtime_error 捕获约定。

当前版本识别与支持判断分开:format::detect_version 对正确 Magic 的完整前缀返回版本值, 未知版本由 Application 的 operations_for_version 返回 unsupported_format; inspect_file / try_inspect_file 的未知版本类别与异常基类保持不变。 encrypt 和 sample 也使用同一选择入口,未知目标版本在任何输入路径检查或输出创建前失败, 统一抛出带 unsupported_format 的 FormatError,仍可由 std::invalid_argument 捕获。

IO 的 UnexpectedEndOfInput 表示字段未读满,应用层将其映射为 invalid_format。 read_exact 和非消耗前瞻 has_data 优先检查 badbit,避免将读取故障误报为 EOF。 读取期间临时启用 badbit 异常以传播流缓冲区的分配失败,结束时恢复调用者的异常掩码。

CLI 直接检查结果并按类别显示错误,再保留具体诊断。 首批处理 invalid_argument、unsupported_format、invalid_format、io_error; 其余类别记录为后续加解密流程的目标,不能声称本轮已覆盖。

info 结果 展示与行为
成功 保持现有公开信息和“未验证”状态;不执行 KDF 或 AEAD 认证
invalid_argument 说明信息读取请求的参数不合法
unsupported_format 说明当前程序不支持该格式内容,并保留版本或编号诊断
invalid_format 说明文件结构不合法,并保留截断、字段或 Padding 诊断
io_error 说明读取操作失败,并保留打开、定位或读取诊断

成功退出码继续为 0,失败继续为 1。分类展示仅接入 info;共享 Format 和 IO 诊断改为中文后,调用这些失败路径的其他命令也会显示对应中文诊断。 info 结构校验成功仍不能证明文件真实;载荷为空也不能仅因此判定无效,格式样本仍可查看。

5. 改造前评估与实施复评

改造前评估认为首批范围可控,适合独立实现和验证;主要成本是明确失败原因与保持旧接口兼容, 不是增加几个 expected 返回类型。

范围 改造前差距 实施范围与成本评估
include/filecrypt/error.hpp 按异常继承关系分类,泛化捕获所有标准异常 定义目标语义及已分类异常的转换边界;明确旧枚举兼容和分配失败传播,成本中等
src/format/detect.cpp、src/format/v1/header.cpp 未知版本、短前缀和错误 Magic 主要使用同一标准异常基类 在原失败点标识不支持与结构异常;Header 编解码仍保持原有语义校验边界,成本较低
src/format/v1/registry.cpp、metadata.cpp、aad.cpp Registry 不支持与字段非法难以程序区分;try_* 统一转换标准异常 按原因分类并透传错误;布局辅助函数同样纳入,避免信息读取在进入 Metadata 解析前丢失分类,成本中等
src/io/file.cpp read_exact 将截断与读取失败合并 区分意外 EOF 与真正 IO 失败;向应用提供版本无关的短读信号,IO 不依赖 Format,成本中等
src/app/operations.cpp、src/app/v1/operations.cpp 与应用头文件 生产信息读取只提供异常接口,部分布局检查直接抛普通异常 复用读取实现,增加应用边界结果接口,补齐打开、定位、前缀短读与布局检查分类,成本中等
src/cli/main.cpp info 走通用异常打印 消费结果并统一显示类别与诊断,保持输出成功路径和退出码,成本较低
Format、应用信息读取及 CLI 测试 expected 覆盖不完整,缺少应用返回错误的验证 补充语义与兼容性回归;共享读取改动影响加解密,需要执行完整现有测试,验证成本中等

实施顺序(首批代码、测试与远端验证已完成):

  1. 完成 ErrorCode 兼容策略及携带语义的失败通道;审查 error_from_exception,分类不得依赖异常文本。
  2. 完善 Format 失败点和已有 try_* 接口,补齐 Header、Metadata、两种 AAD 入口的成功与失败测试。
  3. 区分短读与 IO 错误,增加并验证 try_inspect_file;核对布局检查、版本分发和文件打开路径都保留正确类别。
  4. 接入 CLI info,验证分类展示、具体诊断、Unicode 和退出码兼容,再完成本地与远端验证。
  5. 对最终调用代码复评:若仅增加包装与重复分支,诊断和调用并未改善,则停止扩大 expected;错误语义本身仍可用于异常接口。

首批不扩大到目录恢复、密码学认证、压缩回调或输出事务;不改变协议、不改变输出提交时机, 也不新增按类别区分的 CLI 退出码。

实施后,CLI 已能稳定区分“不支持的格式”“文件结构不合法”和“读取操作失败”, 无需检查异常文本;信息读取成功结果与旧接口共用实现。实际收益来自可供调用者分支处理的语义, expected 使这一分支在调用处显式可见,但仍保留异常构造和边界转换成本。 当前值得保留此试点;后续按具体调用需求评估下一处应用边界。

6. 验证与扩大条件

已扩展 format_expected、app_file_crypt 和 cli_info,覆盖八组合法布局、 截断与非法字段、旧异常基类和枚举兼容、流故障与分配失败注入、中文重定向诊断及退出码。 新增应用测试源编入已有测试目标,测试注册数量仍为 Windows 15 项、Linux 14 项。 本地与远端验证状态见 TODO;以下条件用于后续扩大评估。

  • 成功结果与原 inspect_file 一致,包括格式样本、公开字段、载荷存在性和未认证状态。
  • 不支持版本或编号与结构异常分别返回正确类别;短前缀、短 Header、短 Metadata、错误 Magic、长度矛盾、非零 Padding 和已知参数编码非法均有覆盖。
  • 读至正常 EOF 但未满足完整字段长度返回格式异常;注入流读取故障返回 IO 错误,不能依赖机器权限或操作系统错误文本使测试通过。
  • 已有异常接口仍符合各自的异常基类约定;新增结果接口保留具体诊断。用类型和结果码断言分类,不解析诊断文本决定类别。
  • 补齐 Metadata 与两种 AAD try_* 的成功、失败和兼容测试;检查分配失败不会被转换为普通格式错误。
  • CLI 分类信息在 Windows/Linux 重定向时保持 UTF-8,成功输出与退出码保持兼容。
  • 本地 build_all、完整 CTest 及远端 MSVC/Linux Actions 通过;共享 read_exact 和 Format 失败通道的改动需覆盖现有加解密、认证顺序、资源限制与事务清理回归。

只有实际调用更清楚、错误分类可靠且维护成本可接受时,才讨论下一个应用边界。 加解密阶段还需验证认证失败的统一提示、系统错误与输出冲突的区分,以及所有异常或错误返回路径的清理语义。

7. verify 的应用边界

verify_file 保持操作接口的异常形式,直接复用解密的认证流程;本批不新增仅作包装的 expected 接口。格式与目录结构错误为 invalid_format,不支持的版本或算法为 unsupported_format;错误密码或标签不匹配为 authentication_failed。目录策略、KDF 或解压上限为 resource_limit;输入读取与临时文件系统操作失败为 io_error。输入路径、空密码和非法选项属于参数错误,分配失败及未知库错误继续传播。

目录解析的结构错误与策略超限在已知原因处分类,同时保留原 invalid_argument 基类。Zstandard 解码数据错误使用携带 invalid_format 的运行时异常,读取回调的 IO 错误直接传播。验证不创建最终输出,不产生输出路径冲突;尚未完成认证的压缩或目录载荷不会进入解码器。

新增回归编入现有 app_file_crypt、cli_file_crypt 和 cli_directory_crypt,测试注册数量仍为 Windows 15 项、Linux 14 项。覆盖两种算法、压缩与目录组合、空文件、篡改和截断、认证正确但载荷非法、资源限制、协议合法但平台不支持的名称,以及临时输出不可提交和清理行为。

8. rekey 的应用边界

rekey_file 保持异常操作接口,参数包括旧密码、新密码和换密选项。空密码、缺少输出、替换时指定其他输出及非法资源配置属于参数错误;CLI 在读取密码前拒绝重复、未知及不适用的选项,新密码确认不一致时不进入应用流程。

旧文件认证失败为 authentication_failed,仍统一表示“密码错误或文件已被篡改”,不区分密码与损坏原因。新密文回读认证失败为 io_error,明确提示新密文回读失败,不能归因于旧密码错误。回读认证和载荷校验失败均阻止提交;压缩或目录结构非法为 invalid_format,不支持的版本或算法为 unsupported_format,KDF、解压与目录策略超限为 resource_limit。分配失败和未知库错误继续传播。

另存输入输出相同、目标已存在或提交时被占用属于 output_conflict;读取、写入、刷新及平台替换操作失败属于 io_error,不能将所有平台失败都解释为名称冲突。--replace 只授权替换所指定的输入文件,文件身份变化时停止提交。失败时清理尚未发布的新密文,不把部分结果发布为成功;文件系统和断电持久性边界由平台事务约束,不承诺回滚其他进程的并发修改。

换密回读过程不得转换成解密载荷暂存。已完成旧认证这一内部前提只适用于同一流程生成并由同一受控句柄持有的新密文,普通外部输入继续遵守先完整认证、后解码规则。POSIX 的排他创建和受限权限不等于强制排除同用户其他进程的写入。