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.

§Quick Start

Add this to your plugin’s Cargo.toml:

[dependencies]
rustledger-plugin-types = "0.10"
rmp-serde = "1"

Then in your plugin:

use rustledger_plugin_types::*;

#[no_mangle]
pub extern "C" fn process(input_ptr: u32, input_len: u32) -> u64 {
    let input_bytes = unsafe {
        std::slice::from_raw_parts(input_ptr as *const u8, input_len as usize)
    };

    let input: PluginInput = rmp_serde::from_slice(input_bytes).unwrap();

    // Process directives...
    let output = PluginOutput {
        directives: input.directives,
        errors: vec![],
    };

    let output_bytes = rmp_serde::to_vec(&output).unwrap();
    let output_ptr = alloc(output_bytes.len() as u32);
    unsafe {
        std::ptr::copy_nonoverlapping(
            output_bytes.as_ptr(),
            output_ptr,
            output_bytes.len(),
        );
    }
    ((output_ptr as u64) << 32) | (output_bytes.len() as u64)
}

#[no_mangle]
pub extern "C" fn alloc(size: u32) -> *mut u8 {
    let layout = std::alloc::Layout::from_size_align(size as usize, 1).unwrap();
    unsafe { std::alloc::alloc(layout) }
}

§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.10.x for rustledger 0.10.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

Structs§

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.
EventData: Event data.
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.
TransactionData: Transaction data for serialization.

Enums§

DirectiveData: Directive-specific data.
MetaValueData: Metadata value for serialization.
PluginErrorSeverity: Severity of a plugin error.

Functions§

sort_directives: Sort directives using beancount’s standard ordering.