Errors

file format 6
Rust SDK 1.0 preview

Every failure is an Error with a kind, a message and JSON details. The kind is the contract: one of 22 fixed strings, the same in every implementation.

On this page, Result<T> is std::result::Result<T, plxi_sdk::Error>.

Every public struct and enum with a public field or variant is marked #[non_exhaustive]: code outside the crate builds one through its constructors and matches an enum with a _ arm.

The 22 kinds

Each kind's meaning, the step that reports it, and its test cases are listed on plxi.org. Error kinds

Reserved shard_unsupported_spec and shard_quality_below_threshold are reserved; the SDK never returns them.

Nineteen kinds are named by the full specification. io, unsupported and internal come from implementations: a file that cannot be read, a feature this SDK does not have, and a defect in the SDK itself.

Structs

struct

Error

Spec §9

#[non_exhaustive]
#[derive(Debug, Clone, PartialEq)]
pub struct Error { /* private fields */ }

impl Display for Error
impl Error for Error

Summary: An SDK error: a kind, a message for people, and JSON details.
Example: Example 8: Files, limits, errors
Spec: Spec §9

method

Error::kind

Spec §9

pub fn kind(&self) -> ErrorKind

Summary: The kind: the stable conformance key.
Parameters: None.
Returns: ErrorKind
Example: Example 8: Files, limits, errors
Spec: Spec §9

method

Error::message

Spec §9

pub fn message(&self) -> &str

Summary: A plain-language description for a person. Not part of the contract.
Parameters: None.
Returns: &str
Example: Example 8: Files, limits, errors
Spec: Spec §9

method

Error::details

Spec §9

pub fn details(&self) -> &Value

Summary: Kind-specific details, always a JSON object.
Parameters: None.
Returns: &Value
Example: Example 8: Files, limits, errors
Spec: Spec §9

method

Error::to_json

Spec §9

pub fn to_json(&self) -> String

Summary: {"kind": ..., "message": ..., "details": {...}} as one JSON text.
Parameters: None.
Returns: String
Example: Example 8: Files, limits, errors
Spec: Spec §9

Enums

enum

ErrorKind

Spec §9

#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum ErrorKind {
    Io,
    InvalidHeader,
    UnsupportedVersion,
    InvalidFooter,
    ChecksumMismatch,
    HeaderFooterMismatch,
    RecordCountMismatch,
    InvalidUtf8,
    InvalidRecord,
    Json,
    AppendixInvalid,
    AppendixCrcMismatch,
    AppendixAlignment,
    AppendixLegacyVersion,
    SectionTypeMismatch,
    DanglingEmbref,
    MergeConflict,
    ShardUnsupportedSpec,
    ShardQualityBelowThreshold,
    LimitExceeded,
    Unsupported,
    Internal,
}

impl Display for ErrorKind

Summary: The fixed, language-neutral name of a failure. A later release may add a kind; code matches with a _ arm.
Variants: Io ioThe operating system refused a read or write.
InvalidHeader invalid_headerToo short to be a PLXI file, or the header line breaks the grammar.
UnsupportedVersion unsupported_versionThe header or footer names a format version other than 6.
InvalidFooter invalid_footerThe footer is malformed or does not describe the file's layout.
ChecksumMismatch checksum_mismatchThe SHA-256 digest does not match the footer.
HeaderFooterMismatch header_footer_mismatchA final header disagrees with the footer, or is neither final nor placeholder.
RecordCountMismatch record_count_mismatchThe record lines do not match the footer's record_count.
InvalidUtf8 invalid_utf8The body is not valid UTF-8.
InvalidRecord invalid_recordA line is not a JSON object, has no string k, or the appendix marker is misplaced or missing.
Json jsonA line is not valid JSON, or a typed record fails its schema.
AppendixInvalid appendix_invalidThe embedded CSDT container fails a structural check.
AppendixCrcMismatch appendix_crc_mismatchA CRC32C inside or about the appendix fails.
AppendixAlignment appendix_alignmentAn appendix offset or alignment exponent is out of bounds.
AppendixLegacyVersion appendix_legacy_versionMerge was given a version-3 or version-4 appendix.
SectionTypeMismatch section_type_mismatchA bound embedding target is not a Compact section.
DanglingEmbref dangling_embrefA bound embedding target does not resolve.
MergeConflict merge_conflictMerge cannot combine the inputs.
ShardUnsupportedSpec shard_unsupported_specThe shard spec cannot be served by this pack.
ShardQualityBelowThreshold shard_quality_below_thresholdThe shard's quality score is below the caller's minimum.
LimitExceeded limit_exceededA caller cap or the platform's address width cannot hold a value.
Unsupported unsupportedA well-formed feature this implementation does not have.
Internal internalA defect in the SDK itself (a caught panic, an unmapped error).
Example: Example 8: Files, limits, errors
Spec: Spec §9

const

ErrorKind::ALL

Spec §9

pub const ALL: [ErrorKind; 22]

Summary: Every kind, in the order of the error-kind list on plxi.org.
Example: Example 8: Files, limits, errors
Spec: Spec §9

method

ErrorKind::as_str

Spec §9

pub fn as_str(&self) -> &'static str

Summary: The kind's fixed string, as used by the conformance cases.
Parameters: None.
Returns: &'static str
Example: Example 8: Files, limits, errors
Spec: Spec §9

method

ErrorKind::from_key

Spec §9

pub fn from_key(key: &str) -> Option<ErrorKind>

Summary: The kind whose conformance key is key.
Parameters: key: &str
Returns: Option<ErrorKind>
Example: Example 8: Files, limits, errors
Spec: Spec §9

Type aliases

type

Result

Spec §9

pub type Result<T> = std::result::Result<T, Error>;

Summary: Result with the SDK Error.
Example: Example 8: Files, limits, errors
Spec: Spec §9

Anyone may implement this format. Copying or republishing the text of this specification requires permission from Cintile Inc.