Plugin SDK Reference

Complete type reference for the aeordb-plugin-sdk crate. This covers every public struct, enum, trait, and method available to plugin authors.

Macros

aeordb_parser!(fn_name)

Generates WASM exports for a parser plugin. Your function must have the signature:

#![allow(unused)]
fn main() {
fn fn_name(input: ParserInput) -> Result<serde_json::Value, String>
}

Generated exports:

• handle(ptr: i32, len: i32) -> i64 – deserializes the parser envelope, calls your function, returns packed pointer+length to the serialized response

aeordb_query_plugin!(fn_name)

Generates WASM exports for a query plugin. Your function must have the signature:

#![allow(unused)]
fn main() {
fn fn_name(ctx: PluginContext, request: PluginRequest) -> Result<PluginResponse, PluginError>
}

Generated exports:

• alloc(size: i32) -> i32 – allocates guest memory for the host to write request data
• handle(ptr: i32, len: i32) -> i64 – deserializes the request, creates a PluginContext, calls your function, returns packed pointer+length to the serialized response

Prelude

Import everything you need with:

#![allow(unused)]
fn main() {
use aeordb_plugin_sdk::prelude::*;
}

This re-exports: PluginError, PluginRequest, PluginResponse, json, ParserInput, FileMeta, PluginContext, FileData, DirEntry, FileMetadata, ExtractRequest, ExtractedText, QueryResult, AggregateResult, SortDirection.

PluginRequest

Request passed to a query plugin when it is invoked.

Common metadata keys:

PluginResponse

Response returned by a plugin after handling a request.

Builder Methods

PluginResponse::json(status_code: u16, body: &T) -> Result<Self, serde_json::Error>

Serializes body (any Serialize type) to JSON. Sets content_type to "application/json".

#![allow(unused)]
fn main() {
PluginResponse::json(200, &serde_json::json!({"ok": true}))
}

PluginResponse::text(status_code: u16, body: impl Into<String>) -> Self

Creates a plain text response. Sets content_type to "text/plain".

#![allow(unused)]
fn main() {
PluginResponse::text(200, "Hello, world!")
}

PluginResponse::error(status_code: u16, message: impl Into<String>) -> Self

Creates a JSON error response: {"error": "<message>"}. Sets content_type to "application/json".

#![allow(unused)]
fn main() {
PluginResponse::error(404, "not found")
}

PluginError

Error enum for the plugin system.

All variants carry a String message. PluginError implements Display, Debug, and Error.

json

The SDK re-exports serde_json directly and also provides aeordb_plugin_sdk::json helpers for common plugin request parsing, serialization, and recursive value merging.

Types and macros re-exported from serde_json:

Helper functions:

Merge semantics are recursive for object/object branches. Arrays, scalars, and null replace the existing value. This is not JSON Merge Patch; null is preserved as a value and does not delete a key.

#![allow(unused)]
fn main() {
use aeordb_plugin_sdk::prelude::*;
use serde::Deserialize;

#[derive(Deserialize)]
struct Args {
    file: String,
    options: json::Value,
}

let args: Args = json::parse_request(&request)?;
let options = json::merged(
    json::json!({"max_bytes": 65536, "format": {"pretty": false}}),
    args.options,
);
}

PluginContext

Guest-side handle for calling AeorDB host functions from WASM. Created automatically by aeordb_query_plugin! and passed to the handler.

On non-WASM targets (native compilation), all methods return PluginError::ExecutionFailed – this allows IDE support and unit testing of plugin logic without a WASM runtime.

File Operations

read_file(&self, path: &str) -> Result<FileData, PluginError>

Read a file at the given path. Returns the decoded file bytes, content type, and size.

extract_file(&self, path: &str, request: ExtractRequest) -> Result<ExtractedText, PluginError>

Extract a UTF-8 text slice without buffering the full file through the plugin boundary.

Supported modes:

Line extraction treats \r\n as one line break while preserving the original line ending in the returned text. Lone \n and lone \r also count as line breaks.

#![allow(unused)]
fn main() {
let lines = ctx.extract_file("/docs/readme.md", ExtractRequest::lines(10, 20))?;
let chars = ctx.extract_file("/docs/readme.md", ExtractRequest::chars(0, 500))?;
}

ExtractRequest.max_bytes can cap the returned text size. The host enforces an absolute upper bound and sets ExtractedText.truncated when output is cut at the cap.

write_file(&self, path: &str, data: &[u8], content_type: &str) -> Result<(), PluginError>

Write (create or overwrite) a file. Data is base64-encoded on the wire automatically.

delete_file(&self, path: &str) -> Result<(), PluginError>

Delete a file at the given path.

file_metadata(&self, path: &str) -> Result<FileMetadata, PluginError>

Retrieve metadata for a file without reading its contents.

list_directory(&self, path: &str) -> Result<Vec<DirEntry>, PluginError>

List directory entries at the given path.

Query and Aggregation

query(&self, path: &str) -> QueryBuilder

Start building a query against files at the given path. See QueryBuilder.

aggregate(&self, path: &str) -> AggregateBuilder

Start building an aggregation against files at the given path. See AggregateBuilder.

FileData

Raw file data returned by read_file.

DirEntry

A single directory entry returned by list_directory.

FileMetadata

Metadata about a stored file.

ParserInput

Input to a parser function.

FileMeta

Metadata about the file being parsed (available inside parser plugins).

QueryBuilder

Fluent builder for constructing AeorDB queries. Obtained via PluginContext::query(path) or QueryBuilder::new(path).

Field Conditions

Start with .field("name") to get a FieldQueryBuilder, then chain one operator:

Equality

Greater Than

Less Than

Range

Set Membership

Text Search

Boolean Combinators

Sorting and Pagination

Execution

QueryResult

A single query result returned by the host.

SortDirection

Sort direction for query results.

AggregateBuilder

Fluent builder for constructing AeorDB aggregation queries. Obtained via PluginContext::aggregate(path) or AggregateBuilder::new(path).

Aggregation Operations

Grouping and Filtering

Execution

AggregateResult

Aggregation result returned by the host.

See Also

• Parser Plugins – how to write and deploy parser plugins
• Query Plugins – how to write and deploy query plugins