Trait NodeApp 

pub trait NodeApp:
    Default
    + Send
    + Sync
    + 'static {
    // Required method
    fn metadata() -> NodeAppInfo;

    // Provided methods
    fn init(
        &mut self,
        _ctx: Option<&NodeAppContext>,
    ) -> Result<(), NodeAppError> { ... }
    fn shutdown(&mut self) -> Result<(), NodeAppError> { ... }
    fn handle_request(
        &self,
        _request: AppRequest,
    ) -> Result<AppResponse, NodeAppError> { ... }
    fn handle_event(&self, _event: AppEvent) -> Result<(), NodeAppError> { ... }
    fn provided_capabilities() -> Vec<ProvidedCapability> { ... }
    fn handle_capability(
        &self,
        _request: CapabilityRequest,
    ) -> Result<CapabilityResponse, NodeAppError> { ... }
}

Trait implemented by node-app plugins.

Pair this with declare_node_app! to generate all the FFI boilerplate. Implementors must be Default + Send + Sync + 'static because the macro stores the singleton instance behind a static OnceLock<Mutex<T>>.

All trait methods have sensible default implementations; override only the hooks the app uses. Apps that opt into a hook must also declare the matching capability in their manifest, e.g. "http_handler" for HTTP request routing.

Required Methods

fn metadata() -> NodeAppInfo

Return app metadata (name, version, author, description, capabilities).

Called once when the host loads the shared library. The values are cached for the lifetime of the process.

Provided Methods

fn init(&mut self, _ctx: Option<&NodeAppContext>) -> Result<(), NodeAppError>

Initialize the app with the host context.

Called once after loading. The default impl is a no-op — override to set up state (DB connections, caches, etc.). The context may be None if the host has not wired up callbacks yet (very early in bootstrap or in unit tests).

fn shutdown(&mut self) -> Result<(), NodeAppError>

Shut down the app gracefully.

Called before unloading. Default is a no-op. Override to flush pending writes, close connections, etc.

fn handle_request( &self, _request: AppRequest, ) -> Result<AppResponse, NodeAppError>

Handle an incoming HTTP request proxied from the host.

Only invoked if the app declared the http_handler capability. Default returns 501 Not Implemented.

fn handle_event(&self, _event: AppEvent) -> Result<(), NodeAppError>

Handle a domain event from the host event bus.

Only invoked if the app declared the event_listener capability and subscribed to the event’s namespace via the manifest.

fn provided_capabilities() -> Vec<ProvidedCapability>

Return the list of service capabilities this app provides.

Override to declare capabilities for the host’s capability registry. Default returns an empty list (no capabilities provided). Each entry must use the namespace {app_name}.{domain}.{action} — the core.* namespace is reserved for first-party apps.

fn handle_capability( &self, _request: CapabilityRequest, ) -> Result<CapabilityResponse, NodeAppError>

Handle a capability invocation from another app via the capability router.

Override to implement capability handling logic. The default returns NodeAppError::CapabilityError indicating the capability is not implemented.

Trace context is automatically captured into thread-local state for the duration of this call so invoke_capability can propagate it on outbound calls without explicit threading.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors