Skip to main content

Rust SDK

The Rust guest SDK exposes traits for approved host operations and a bounded HTTP stream helper. Generated wit-bindgen imports implement the actual host calls. You compile a cdylib to a WebAssembly component using wasm32-wasip2.

Create, test and build

glxdev new --kind reference --reference workflow-text-stats --language rust --package-id org.example.text-stats --name "Text statistics" --publisher org.example --output ./text-stats-rust
cd text-stats-rust
glxdev doctor
glxdev check
rustup toolchain install 1.96.0
rustup target add wasm32-wasip2 --toolchain 1.96.0
cargo +1.96.0 install wasm-tools --version 1.239.0 --locked
cargo +1.96.0 test --locked
cargo +1.96.0 build --locked --release --target wasm32-wasip2 --target-dir target
node scripts/copy-artifact.mjs target/wasm32-wasip2/release/glixo_contribution_guest.wasm dist/glixo-extension.component.wasm
wasm-tools component wit dist/glixo-extension.component.wasm

The recipe pins Rust/Cargo 1.96.0, wit-bindgen 0.62.0 and wasm-tools 1.239.0. Install those versions before doctor; keep the generated Cargo.lock. Text Stats names its library glixo_contribution_guest, which determines the artifact path above. For a different template, use its recipe's artifact name. Inspect the Cargo project and matrix.

Use the source crate

There is no published Cargo SDK package yet. Templates that use SDK helpers include vendor/glixo-extension-sdk. In a project with that folder, add a path dependency when you need the library:

[dependencies]
glixo-extension-sdk = { path = "vendor/glixo-extension-sdk" }

Keep the dependency settings already in your scaffold, including serde_json and wit-bindgen. Text Stats implements its pure handler directly and does not need an SDK helper for counting. The SDK source download also contains the crate; extract it, set the path to its directory, and update Cargo.lock intentionally. Read Cargo.toml and crate exports.

Modules and contracts

Module Public API
guest GuestEnvelope<T>, GuestContext, Endpoint, GuestReply<T>; camelCase envelope serialization
state ScopedState: get, set, list, delete, each returning a Result
workspace Workspace: search and read, returning JSON/text strings
logging Logger::log(&mut self,level,message) -> Result<(),String>
http Header, Request, Broker, NdjsonStream<B>, read/line size constants
llm ContentPart, ToolCallDetails, Usage, FinishReason, ProviderEvent, TypedError
crate root JsonValue alias for serde_json::Value

See envelope, state, workspace, HTTP and LLM. A missing state key is Ok(None); denied access is Err. These traits describe operations, so supply adapters calling generated imports rather than assuming the crate contains a live state store.

Generate bindings and export a guest

Text Stats generates bindings and exports its implementation in src/lib.rs:

wit_bindgen::generate!({ path: "wit", world: "contribution", generate_all });

struct GuestImpl;
impl exports::glixo::contribution::guest::Guest for GuestImpl {
    fn invoke(request_json: String) -> Result<String, String> {
        handle(&request_json)
    }
}

export!(GuestImpl);

This entry-point excerpt calls the project's handle function. Read its complete source for imports and validation. Return Err for expected input or host failures. An unexpected panic can trap the component. Use bounded, public error codes; avoid unwrapping guest input or imported results.

Parse request JSON into a validated struct or JsonValue. Check kind, contributionId, required properties and limits. GuestEnvelope<T> types configuration, while input remains JSON. The invocation guide explains which fields Glixo supplies and what JSON to return.

HTTP ownership and tests

NdjsonStream::open(broker,request,max_line_bytes) takes ownership of a Broker. It returns Result<Self,String>. The broker trait uses start, status, response_headers, read, cancel and drop_response; an HTTP read's None is EOF. next_line() returns Result<Option<Vec<u8>>,String>.

The reader's Drop implementation releases the response even on early return. Call cancel() to stop upstream work, or close() after completion; release is idempotent. Unlike Go, a zero line limit is clamped to one byte. Use DEFAULT_MAX_LINE_BYTES for the 1 MiB default and DEFAULT_READ_BYTES for 16 KiB reads. See HTTP behavior.

Run native cargo test --locked tests for handlers and injected adapters. Then build and inspect the component's imports/exports with wasm-tools component wit. Finish with the package and installed-app checks; native tests cannot establish the installed account's permissions.