Crate rustledger_plugin_types

Expand description

WASM Plugin Interface Types for rustledger

This crate provides the type definitions for rustledger’s WASM plugin interface. Use it as a dependency in your plugin crate to ensure type compatibility with the rustledger host.

§Two subsystems

Rustledger has two distinct WASM plugin subsystems, and this crate hosts the shared types for both:

Directive plugins transform the directive stream after parsing (tagging, dedup, categorization). Required export: process. Host loader: rustledger-plugin. The Quick Start below covers this case.
WASM importers turn bank-statement files into directives. Required exports: metadata, identify, extract, extract_enriched. Host loader: rustledger-importer::WasmImporter. Use the wasm_importer_main! macro (behind the guest feature) to generate the boilerplate. See the guest module for details.

§Directive-Plugin Quick Start

Use the wasm_plugin_main! macro (behind the guest feature) to generate the required alloc + process exports from a single user fn. Add this to your plugin’s Cargo.toml:

[dependencies]
rustledger-plugin-types = { version = "0.15", features = ["guest"] }

Then in your plugin:

use rustledger_plugin_types::{
    PluginInput, PluginOutput, wasm_plugin_main,
};

fn process(input: PluginInput) -> PluginOutput {
    // Simplest case: keep every input unchanged.
    PluginOutput::passthrough(input.directives.len())
}

wasm_plugin_main! {
    process: process,
}

See the guest module for the full macro reference (including the once-per-crate constraint on the wasm32 target). If you need to write the extern "C" exports manually — for finer control or to avoid the guest feature — see the “Without the macro” section in the crate README.

§Serialization Format

Plugins communicate with the host via MessagePack serialization. The host calls process(ptr, len) with a pointer to MessagePack-encoded PluginInput. The plugin returns a packed u64 containing a pointer and length to MessagePack-encoded PluginOutput.

§Memory Management

Plugins must export an alloc(size: u32) -> *mut u8 function. The host uses this to allocate memory in the WASM linear memory for passing input data. The plugin uses it to allocate memory for output data.

Optionally, plugins can export a dealloc(ptr: *mut u8, size: u32) function to free memory. This is not required by the host but can be useful for memory management within longer-running plugin operations.

§Version Compatibility

Plugin types are versioned with rustledger. For best compatibility, use the same minor version of rustledger-plugin-types as the rustledger host you’re targeting (e.g., 0.15.x for rustledger 0.15.x).

§Building

Build your plugin for the WASM target:

rustup target add wasm32-unknown-unknown
cargo build --target wasm32-unknown-unknown --release

The output will be in target/wasm32-unknown-unknown/release/your_plugin.wasm

§WASM-Importer Quick Start

Importers read source files (CSV, OFX, …) and emit directives. The host loader lives in rustledger-importer; the wire format and a boilerplate-eliminating macro live here.

Enable the guest feature, then use wasm_importer_main!:

[dependencies]
rustledger-plugin-types = { version = "0.15", features = ["guest"] }

use rustledger_plugin_types::{
    DirectiveData, DirectiveWrapper, ImporterInput, ImporterOutput,
    OpenData, wasm_importer_main,
};

fn identify(path: &str) -> bool {
    path.ends_with(".mybank")
}

fn extract(input: ImporterInput) -> ImporterOutput {
    // Parse input.content; emit DirectiveWrapper values.
    ImporterOutput::new(vec![/* … */])
}

wasm_importer_main! {
    name: "my-bank",
    description: "MyBank CSV statements",
    identify: identify,
    extract: extract,
    // `extract_enriched` is auto-generated as a Default-categorization
    // passthrough. Add `extract_enriched: my_fn` to override.
}

Importer ABI types defined in this crate: ImporterInput, IdentifyInput, IdentifyOutput, ImporterOutput, EnrichedImporterOutput, MetadataOutput, EnrichmentWrapper, AlternativeWrapper.

Wire-format method strings for EnrichmentWrapper::method: "rule", "merchant-dict" (hyphen, not underscore), "ml", "llm", "manual", "default". Unknown values trigger a host warning and fall back to Default.

Structs§

AlternativeWrapper: Wire-format counterpart to rustledger_ops::enrichment::Alternative.
AmountData: Amount data for serialization.
BalanceData: Balance assertion data.
CloseData: Close account data.
CommodityData: Commodity declaration data.
CostData: Cost data for serialization.
CustomData: Custom directive data.
DirectiveWrapper: A wrapper around directives for serialization.
DocumentData: Document data.
EnrichedImporterOutput: Wire-format output returned from a WASM importer’s extract_enriched. Each directive is paired with per-directive categorization metadata.
EnrichmentWrapper: Wire-format counterpart to rustledger_ops::enrichment::Enrichment.
EventData: Event data.
IdentifyInput: Wire-format input to a WASM importer’s identify entry point.
IdentifyOutput: Wire-format output from a WASM importer’s identify.
ImporterInput: Wire-format input passed from the host to a WASM importer’s extract / extract_enriched entry point.
ImporterOutput: Wire-format output returned from a WASM importer’s extract.
MetadataOutput: Wire-format output from a WASM importer’s metadata entry point. Returned once at load time and cached by the host registry — used for Importer::name() and Importer::description() on the wrapper.
NoteData: Note data.
OpenData: Open account data.
PadData: Pad directive data.
PluginError: Error generated by a plugin.
PluginInput: Input passed to a plugin.
PluginOptions: Ledger options passed to plugins.
PluginOutput: Output returned from a plugin.
PostingData: Posting data for serialization.
PriceAnnotationData: Price annotation data.
PriceData: Price directive data.
QueryData: Query directive data.
SourceSpan: Source-location metadata for a posting that the host parsed from a beancount file.
TransactionData: Transaction data for serialization.

Enums§

CostNumberData: The numeric component of a CostData.
DirectiveData: Directive-specific data.
MetaValueData: Metadata value for serialization.
PluginErrorSeverity: Severity of a plugin error.
PluginOp: One operation in a PluginOutput’s ordered op list.
PriceAnnotationView: Typed view of a PriceAnnotationData.

Constants§

ABI_VERSION: Version of the host/guest WASM ABI defined by this crate.
ABI_VERSION_EXPORT: The WASM export symbol a guest uses to advertise ABI_VERSION. The wasm_*_main! macros emit it; the host looks it up by this name. Kept here as the single source of truth shared by both sides.

Functions§

sort_directives: Sort directives using beancount’s standard ordering.
validate_op_coverage: Validate that ops form a complete, non-overlapping cover of the input.