hydrust_sdk/
lib.rs

1#![deny(missing_docs)]
2
3//! # Hydrust Plugin SDK
4//!
5//! The official SDK for developing plugins for the Hydrust platform.
6//!
7//! This crate provides the necessary types, traits, and macros to define a guest
8//! module that can be loaded by the Hydrust host. It abstracts away the low-level
9//! `wit-bindgen` details and provides a clean, idiomatic Rust API.
10//!
11//! ## Usage
12//!
13//! To create a plugin, implement the [`Handler`] trait on a struct that derives
14//! [`Default`], and then call [`register_plugin!`] with that struct type.
15//!
16//! ```rust,ignore
17//! use hydrust_sdk::{register_plugin, Handler};
18//! use hydrust_sdk::events::Event;
19//! use hydrust_sdk::metadata::PluginInfo;
20//! 
21//! #[derive(Default)]
22//! struct MyPlugin;
23//! 
24//! impl Handler for MyPlugin {
25//!     fn metadata(&self) -> PluginInfo {
26//!         PluginInfo {
27//!             name: "My Plugin".to_string(),
28//!             version: "0.1.0".to_string(),
29//!             author: "MyName".to_string(),
30//!             description: "My plugin does wonders".to_string()
31//!         }
32//!     }
33//! 
34//!     fn on_event(&self, event: Event) {
35//!         // Handle event logic here
36//!     }
37//! }
38//! 
39//! register_plugin!(MyPlugin);
40//! ```
41
42/// Low-level access to the underlying `wit_bindgen` crate.
43pub use wit_bindgen;
44
45// --- INTERNAL RUNTIME & BINDINGS ---
46
47/// Runtime support for the generated bindings.
48///
49/// This module is required by the `wit-bindgen` generated code.
50#[doc(hidden)]
51pub mod rt {
52    pub use wit_bindgen::rt::*;
53}
54
55/// Generated bindings from the WIT definition.
56///
57/// These are hidden from the documentation to provide a cleaner user API,
58/// but are public so the macro can access them.
59#[doc(hidden)]
60pub mod bindings {
61    use super::wit_bindgen;
62
63    wit_bindgen::generate!({
64        path: "wit",
65        world: "site-provider",
66        runtime_path: "crate::rt",
67        pub_export_macro: true,
68    });
69}
70
71// --- PUBLIC API ---
72
73/// The core trait for implementing a Hydrust plugin.
74///
75/// Users must implement this trait to define how the plugin identifies itself
76/// and how it responds to events.
77///
78/// **Note:** Your implementation struct must also implement [`Default`], as
79/// the plugin instance is instantiated ephemerally for each call.
80pub trait Handler {
81    /// Returns metadata about the plugin.
82    ///
83    /// This is called by the host to register the plugin's name, version, and capabilities.
84    fn metadata(&self) -> metadata::PluginInfo;
85
86    /// Handles an incoming event from the host.
87    ///
88    /// # Arguments
89    ///
90    /// * `event` - The event data containing context and payload.
91    fn on_event(&self, event: events::Event);
92}
93
94/// Registers a struct as the Plugin entry point.
95///
96/// This macro generates the necessary boilerplate to export the WASM component
97/// functions expected by the Hydrust host.
98///
99/// # Requirements
100///
101/// The type passed to this macro must:
102/// 1. Implement the [`Handler`] trait.
103/// 2. Implement [`Default`] (or define a zero-argument `new` via `#[derive(Default)]`).
104///
105/// # Example
106///
107/// ```rust,ignore
108/// register_plugin!(MyPlugin);
109/// ```
110#[macro_export]
111macro_rules! register_plugin {
112    ($plugin_type:ty) => {
113        struct GuestImpl;
114
115        impl $crate::Guest for GuestImpl {
116            fn get_info() -> $crate::metadata::PluginInfo {
117                // We create a temporary instance to call the method.
118                // This implies the plugin is stateless between calls in this design.
119                let plugin: $plugin_type = Default::default();
120                $crate::Handler::metadata(&plugin)
121            }
122
123            fn on_event(event: $crate::events::Event) {
124                let plugin: $plugin_type = Default::default();
125                $crate::Handler::on_event(&plugin, event);
126            }
127        }
128
129        // Export the implementation using the generated macro from wit-bindgen
130        $crate::bindings::export!(GuestImpl with_types_in $crate::bindings);
131    };
132}
133
134// --- DOMAIN EXPORTS ---
135
136// Re-export the Guest trait so the macro can refer to it easily,
137// but users generally don't need to implement this directly.
138#[doc(hidden)]
139pub use bindings::Guest;
140
141/// Functionality related to publishing content.
142pub use bindings::publish;
143
144/// Event definitions and related types.
145pub mod events {
146    pub use crate::bindings::hydrust::protocol::events::*;
147}
148
149/// Core data types used throughout the protocol.
150pub mod types {
151    pub use crate::bindings::hydrust::protocol::types::*;
152}
153
154/// Metadata structures for plugin registration.
155pub mod metadata {
156    pub use crate::bindings::hydrust::protocol::metadata::*;
157}
hydrust_sdk/lib.rs

hydrust_sdk/
lib.rs
