Enum Error 

#[non_exhaustive]
pub enum Error {
    BadMagic {
        got: [u8; 8],
    },
    UnsupportedVersion {
        found_major: u16,
        found_minor: u16,
        supported_major: u16,
    },
    Truncated {
        context: &'static str,
        need: usize,
        got: usize,
    },
    MalformedHeader {
        reason: &'static str,
    },
    NoMatchingSlot,
    HeaderMacMismatch,
    ChunkAuthFailed {
        index: u64,
    },
    UnknownCriticalTlv {
        tlv_type: u16,
    },
    MissingTlv {
        tlv_type: u16,
    },
    MalformedTlv {
        tlv_type: u16,
        reason: &'static str,
    },
    ChunkOutOfRange {
        index: u64,
        total: u64,
    },
    TooManySlots {
        got: usize,
        max: usize,
    },
    InvalidChunkSize {
        got: u32,
        min: u32,
        max: u32,
    },
    ShardCrcMismatch {
        index: u32,
        expected: u32,
        computed: u32,
    },
    MissingShards {
        missing: Vec<u32>,
        total: u32,
    },
    ShardUuidMismatch {
        index: u32,
    },
    ContentHashMismatch,
    Compression {
        reason: String,
    },
    KeyDerivation {
        reason: &'static str,
    },
    Io(Error),
}

omy 核心库的错误类型。

每个变体都携带定位问题所需的结构化字段，供上层渲染本地化消息。

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

BadMagic

文件头 magic 不匹配，不是 omy 文件。

Fields

got: [u8; 8]

实际读到的前 8 字节。

UnsupportedVersion

主版本号高于本实现支持的上限，必须拒绝打开（规范 §9 步骤 2）。

Fields

found_major: u16

文件声明的主版本。

found_minor: u16

文件声明的次版本。

supported_major: u16

本实现支持的最高主版本。

Truncated

输入数据长度不足，无法解析出完整结构。

Fields

context: &'static str

正在解析的结构名，便于定位。

need: usize

需要的字节数。

got: usize

实际可用的字节数。

MalformedHeader

头部字段取值非法或自相矛盾。

Fields

reason: &'static str

具体原因。

NoMatchingSlot

没有任何候选密钥能解开任何一个 key slot。

注意：这不代表文件损坏，也可能只是该文件不属于当前解锁的密码。 面向用户的文案必须同时表达这两种可能。

HeaderMacMismatch

头部 HMAC 校验失败：文件被篡改，或 FEK 不正确。

规范 §7 要求此时必须终止，不得继续读取载荷。

ChunkAuthFailed

载荷块的 AEAD 认证失败。

Fields

index: u64

出错的块序号。

UnknownCriticalTlv

遇到未知且标记为 CRITICAL 的 TLV，按规范必须拒绝打开（§4.2）。

Fields

tlv_type: u16

未知的 TLV 类型号。

MissingTlv

必需的 TLV 缺失。

Fields

tlv_type: u16

缺失的 TLV 类型号。

MalformedTlv

TLV 内容解析失败。

Fields

tlv_type: u16

出错的 TLV 类型号。

reason: &'static str

具体原因。

ChunkOutOfRange

请求的块序号超出文件实际块数。

Fields

index: u64

请求的块序号。

total: u64

实际总块数。

TooManySlots

key slot 数量超过格式上限。

Fields

got: usize

请求的数量。

max: usize

格式允许的上限。

InvalidChunkSize

分块大小超出允许范围。

Fields

got: u32

请求的分块大小。

min: u32

下限。

max: u32

上限。

ShardCrcMismatch

分片的 CRC-32 校验失败。

Fields

index: u32

分片序号。

expected: u32

头部记录的 CRC。

computed: u32

实际算出的 CRC。

MissingShards

分片集合中缺少某些序号。

Fields

missing: Vec<u32>

缺失的分片序号列表。

total: u32

应有的总片数。

ShardUuidMismatch

分片的 file_uuid 与其它片不一致，属于不同文件。

Fields

index: u32

不一致的分片序号。

ContentHashMismatch

解密后内容哈希与 TLV_CONTENT_HASH 记录不符。

Compression

压缩或解压失败。

Fields

reason: String

具体原因。

KeyDerivation

密钥派生失败。

Fields

reason: &'static str

具体原因。

Io(Error)

底层 IO 错误。

Implementations

impl Error

pub const fn exit_code(&self) -> ExitCode

映射到 CLI 退出码。

见 docs/research/09-cli-design.md §3.1。

pub const fn code(&self) -> &'static str

稳定的机器可读错误码，供 --json 输出与前端 i18n 查表使用。

这些字符串是接口契约，脚本会匹配它们，因此不得随意更名。

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.