Enum Payload

#[non_exhaustive]
pub enum Payload<'a> {
    Version {
        num: u16,
        encoding: Encoding,
        range: Range<usize>,
    },
    TypeSection(TypeSectionReader<'a>),
    ImportSection(ImportSectionReader<'a>),
    FunctionSection(FunctionSectionReader<'a>),
    TableSection(TableSectionReader<'a>),
    MemorySection(MemorySectionReader<'a>),
    TagSection(TagSectionReader<'a>),
    GlobalSection(GlobalSectionReader<'a>),
    ExportSection(ExportSectionReader<'a>),
    StartSection {
        func: u32,
        range: Range<usize>,
    },
    ElementSection(ElementSectionReader<'a>),
    DataCountSection {
        count: u32,
        range: Range<usize>,
    },
    DataSection(DataSectionReader<'a>),
    CodeSectionStart {
        count: u32,
        range: Range<usize>,
        size: u32,
    },
    CodeSectionEntry(FunctionBody<'a>),
    ModuleSection {
        parser: Parser,
        unchecked_range: Range<usize>,
    },
    InstanceSection(InstanceSectionReader<'a>),
    CoreTypeSection(CoreTypeSectionReader<'a>),
    ComponentSection {
        parser: Parser,
        unchecked_range: Range<usize>,
    },
    ComponentInstanceSection(ComponentInstanceSectionReader<'a>),
    ComponentAliasSection(SectionLimited<'a, ComponentAlias<'a>>),
    ComponentTypeSection(ComponentTypeSectionReader<'a>),
    ComponentCanonicalSection(ComponentCanonicalSectionReader<'a>),
    ComponentStartSection {
        start: ComponentStartFunction,
        range: Range<usize>,
    },
    ComponentImportSection(ComponentImportSectionReader<'a>),
    ComponentExportSection(ComponentExportSectionReader<'a>),
    CustomSection(CustomSectionReader<'a>),
    UnknownSection {
        id: u8,
        contents: &'a [u8],
        range: Range<usize>,
    },
    End(usize),
}

Values that can be parsed from a WebAssembly module or component.

This enumeration is all possible chunks of pieces that can be parsed by a Parser from a binary WebAssembly module or component. Note that for many sections the entire section is parsed all at once, whereas other functions, like the code section, are parsed incrementally. This is a distinction where some sections, like the type section, are required to be fully resident in memory (fully downloaded) before proceeding. Other sections, like the code section, can be processed in a streaming fashion where each function is extracted individually so it can possibly be shipped to another thread while you wait for more functions to get downloaded.

Note that payloads, when returned, do not indicate that the module or component is valid. For example when you receive a Payload::TypeSection the type section itself has not yet actually been parsed. The reader returned will be able to parse it, but you’ll have to actually iterate the reader to do the full parse. Each payload returned is intended to be a window into the original data passed to Parser::parse which can be further processed if necessary.

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.

Version

Indicates the header of a WebAssembly module or component.

Fields

num: u16

The version number found in the header.

encoding: Encoding

The encoding format being parsed.

range: Range<usize>

The range of bytes that were parsed to consume the header of the module or component. Note that this range is relative to the start of the byte stream.

TypeSection(TypeSectionReader<'a>)

A module type section was received and the provided reader can be used to parse the contents of the type section.

ImportSection(ImportSectionReader<'a>)

A module import section was received and the provided reader can be used to parse the contents of the import section.

FunctionSection(FunctionSectionReader<'a>)

A module function section was received and the provided reader can be used to parse the contents of the function section.

TableSection(TableSectionReader<'a>)

A module table section was received and the provided reader can be used to parse the contents of the table section.

MemorySection(MemorySectionReader<'a>)

A module memory section was received and the provided reader can be used to parse the contents of the memory section.

TagSection(TagSectionReader<'a>)

A module tag section was received, and the provided reader can be used to parse the contents of the tag section.

GlobalSection(GlobalSectionReader<'a>)

A module global section was received and the provided reader can be used to parse the contents of the global section.

ExportSection(ExportSectionReader<'a>)

A module export section was received, and the provided reader can be used to parse the contents of the export section.

StartSection

A module start section was received.

Fields

func: u32

The start function index

range: Range<usize>

The range of bytes that specify the func field, specified in offsets relative to the start of the byte stream.

ElementSection(ElementSectionReader<'a>)

A module element section was received and the provided reader can be used to parse the contents of the element section.

DataCountSection

A module data count section was received.

Fields

count: u32

The number of data segments.

range: Range<usize>

The range of bytes that specify the count field, specified in offsets relative to the start of the byte stream.

DataSection(DataSectionReader<'a>)

A module data section was received and the provided reader can be used to parse the contents of the data section.

CodeSectionStart

Indicator of the start of the code section of a WebAssembly module.

This entry is returned whenever the code section starts. The count field indicates how many entries are in this code section. After receiving this start marker you’re guaranteed that the next count items will be either CodeSectionEntry or an error will be returned.

This, unlike other sections, is intended to be used for streaming the contents of the code section. The code section is not required to be fully resident in memory when we parse it. Instead a Parser is capable of parsing piece-by-piece of a code section.

Fields

count: u32

The number of functions in this section.

range: Range<usize>

The range of bytes that represent this section, specified in offsets relative to the start of the byte stream.

size: u32

The size, in bytes, of the remaining contents of this section.

This can be used in combination with Parser::skip_section where the caller will know how many bytes to skip before feeding bytes into Parser again.

CodeSectionEntry(FunctionBody<'a>)

An entry of the code section, a function, was parsed from a WebAssembly module.

This entry indicates that a function was successfully received from the code section, and the payload here is the window into the original input where the function resides. Note that the function itself has not been parsed, it’s only been outlined. You’ll need to process the FunctionBody provided to test whether it parses and/or is valid.

ModuleSection

Available on crate feature component-model only.

A core module section was received and the provided parser can be used to parse the nested module.

This variant is special in that it returns a sub-Parser. Upon receiving a ModuleSection it is expected that the returned Parser will be used instead of the parent Parser until the parse has finished. You’ll need to feed data into the Parser returned until it returns Payload::End. After that you’ll switch back to the parent parser to resume parsing the rest of the current component.

Note that binaries will not be parsed correctly if you feed the data for a nested module into the parent Parser.

Fields

parser: Parser

The parser for the nested module.

unchecked_range: Range<usize>

The range of bytes that represent the nested module in the original byte stream.

Note that, to better support streaming parsing and validation, the validator does not check that this range is in bounds.

InstanceSection(InstanceSectionReader<'a>)

Available on crate feature component-model only.

A core instance section was received and the provided parser can be used to parse the contents of the core instance section.

Currently this section is only parsed in a component.

CoreTypeSection(CoreTypeSectionReader<'a>)

Available on crate feature component-model only.

A core type section was received and the provided parser can be used to parse the contents of the core type section.

Currently this section is only parsed in a component.

ComponentSection

Available on crate feature component-model only.

A component section from a WebAssembly component was received and the provided parser can be used to parse the nested component.

This variant is special in that it returns a sub-Parser. Upon receiving a ComponentSection it is expected that the returned Parser will be used instead of the parent Parser until the parse has finished. You’ll need to feed data into the Parser returned until it returns Payload::End. After that you’ll switch back to the parent parser to resume parsing the rest of the current component.

Note that binaries will not be parsed correctly if you feed the data for a nested component into the parent Parser.

Fields

parser: Parser

The parser for the nested component.

unchecked_range: Range<usize>

The range of bytes that represent the nested component in the original byte stream.

Note that, to better support streaming parsing and validation, the validator does not check that this range is in bounds.

ComponentInstanceSection(ComponentInstanceSectionReader<'a>)

Available on crate feature component-model only.

A component instance section was received and the provided reader can be used to parse the contents of the component instance section.

ComponentAliasSection(SectionLimited<'a, ComponentAlias<'a>>)

Available on crate feature component-model only.

A component alias section was received and the provided reader can be used to parse the contents of the component alias section.

ComponentTypeSection(ComponentTypeSectionReader<'a>)

Available on crate feature component-model only.

A component type section was received and the provided reader can be used to parse the contents of the component type section.

ComponentCanonicalSection(ComponentCanonicalSectionReader<'a>)

Available on crate feature component-model only.

A component canonical section was received and the provided reader can be used to parse the contents of the component canonical section.

ComponentStartSection

Available on crate feature component-model only.

A component start section was received.

Fields

start: ComponentStartFunction

The start function description.

range: Range<usize>

The range of bytes that specify the start field.

ComponentImportSection(ComponentImportSectionReader<'a>)

Available on crate feature component-model only.

A component import section was received and the provided reader can be used to parse the contents of the component import section.

ComponentExportSection(ComponentExportSectionReader<'a>)

Available on crate feature component-model only.

A component export section was received, and the provided reader can be used to parse the contents of the component export section.

CustomSection(CustomSectionReader<'a>)

A module or component custom section was received.

UnknownSection

An unknown section was found.

This variant is returned for all unknown sections encountered. This likely wants to be interpreted as an error by consumers of the parser, but this can also be used to parse sections currently unsupported by the parser.

Fields

id: u8

The 8-bit identifier for this section.

contents: &'a [u8]

The contents of this section.

range: Range<usize>

The range of bytes, relative to the start of the original data stream, that the contents of this section reside in.

End(usize)

The end of the WebAssembly module or component was reached.

The value is the offset in the input byte stream where the end was reached.

Implementations

impl Payload<'_>

pub fn as_section(&self) -> Option<(u8, Range<usize>)>

If this Payload represents a section in the original wasm module then the section’s id and range within the original wasm binary are returned.

Not all payloads refer to entire sections, such as the Version and CodeSectionEntry variants. These variants will return None from this function.

Otherwise this function will return Some where the first element is the byte identifier for the section and the second element is the range of the contents of the section within the original wasm binary.

The purpose of this method is to enable tools to easily iterate over entire sections if necessary and handle sections uniformly, for example dropping custom sections while preserving all other sections.

Trait Implementations

impl Debug for Payload<'_>

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

Formats the value using the given formatter.