Skip to main content

Crate node_app_sdk_rust

Crate node_app_sdk_rust 

Source
Expand description

§Node-App SDK for Rust

Build native Node-App plugins as shared libraries (cdylib) with a safe, ergonomic Rust API. The SDK targets the Node Host API v1 (the canonical C header is core/host-abi-v1/include/node-host-api-v1.h in the host repository).

§What this crate provides

§Stability

This crate is published as 1.0.1-experimental. The trait surface and the underlying C ABI are FROZEN for the v1 series, but breaking changes between 1.0.x-experimental releases are possible until at least two first-party packages have proven the surface in production. Pin to an exact version in Cargo.toml.

§Quick start

# Cargo.toml
[lib]
crate-type = ["cdylib"]

[dependencies]
node-app-sdk-rust = "1.0.1-experimental"
serde_json = "1.0"
ⓘ
use node_app_sdk_rust::*;

#[derive(Default)]
pub struct MyApp;

impl NodeApp for MyApp {
    fn metadata() -> NodeAppInfo {
        NodeAppInfo {
            name: "my-app".into(),
            version: "0.1.0".into(),
            author: "Me".into(),
            description: "Hello-world Node-App".into(),
            capabilities: vec!["http_handler".into()],
        }
    }

    fn handle_request(&self, _req: AppRequest) -> Result<AppResponse, NodeAppError> {
        Ok(AppResponse {
            status: 200,
            headers: Default::default(),
            body: serde_json::json!({ "hello": "world" }),
        })
    }
}

declare_node_app!(MyApp);

Build with cargo build --release; the resulting shared library plus a manifest.json is installed into the host’s app directory.

§Calling host capabilities

Use invoke_capability to call any capability registered with the host’s capability router (e.g. core.storage.get, core.lightning.payment.send):

ⓘ
use node_app_sdk_rust::{invoke_capability, CapabilityRequest};

let response = invoke_capability(&CapabilityRequest {
    id: "req-1".into(),
    capability: "core.storage.get".into(),
    payload: serde_json::json!({ "key": "user_pref" }),
    caller_node_id: None,
    trace_id: None,
    span_id: None,
    parent_span_id: None,
    trace_depth: None,
})?;

Trace context (trace_id, span_id, trace_depth) is propagated automatically when invoking from inside handle_capability — you do not need to thread it manually.

§Publishing events

ⓘ
use node_app_sdk_rust::publish_event;

publish_event(
    "my-app.something_happened",
    &serde_json::json!({ "user_id": 42 }),
)?;

Event names must be namespaced with the app name (my-app.*); the host rejects un-namespaced events.

Modules§

log_level
Log levels accepted by the log function.

Macros§

declare_node_app
Generate all FFI boilerplate for a NodeApp implementation.
log_debug
Log a DEBUG-level message using format!-style arguments.
log_error
Log an ERROR-level message using format!-style arguments.
log_info
Log an INFO-level message using format!-style arguments.
log_trace
Log a TRACE-level message using format!-style arguments.
log_warn
Log a WARN-level message using format!-style arguments.

Structs§

AppEvent
Domain event forwarded to apps
AppRequest
HTTP request forwarded to an app
AppResponse
HTTP response from an app
Capabilities
Capability flags declaring what an app can do
CapabilityExample
An example request payload for a capability.
CapabilityRequest
A service capability request dispatched to a provider app. Used for both FFI (serialized as JSON bytes) and IPC (serialized as JSON).
CapabilityResponse
Response from a provider app after handling a capability request.
FfiResult
Result type returned by FFI functions
NodeAppContext
Host context provided to native apps.
NodeAppInfo
App metadata returned during initialization
NodeAppMetadata
App metadata returned by the entry point function
NodeAppVTable
VTable of function pointers for app operations. Returned by the _node_app_entry symbol.
ProvidedCapability
Declaration of a service capability that an app provides. Used in app manifests and registration APIs.

Enums§

NodeAppError
Error type returned by app operations.

Constants§

API_VERSION
API version for compatibility checking between host and native apps. Host and app must have matching API_VERSION to load successfully.
MAX_CAPABILITY_RESPONSE_SIZE
Maximum response size for capability handlers (16 MiB).
MAX_EVENT_DATA_LEN
Maximum event data length in bytes (64 KiB).
MAX_EVENT_NAME_LEN
Maximum event name length in bytes (256).

Traits§

NodeApp
Trait implemented by node-app plugins.

Functions§

get_config
Get a configuration value from the host by key.
get_storage
Get a storage value by key, scoped to this app.
invoke_capability
Invoke a capability on the host via the capability router.
log
Log a message to the host using the stored context.
publish_event
Publish a domain event to the host event bus.
set_storage
Set a storage value scoped to this app.