ClassExtender plugin first draft #73

Author: Polleps

Cargo.lock

@@ -1,6 +1,6 @@
 [workspace]
 resolver = "2"
-members = ["server", "cli", "lib"]
+members = ["server", "cli", "lib", "plugin-examples/random-folder-extender"]
 # Tauri build is deprecated, see
 # https://github.com/atomicdata-dev/atomic-server/issues/718
 exclude = ["desktop"]

Cargo.toml

@@ -33,3 +33,27 @@ When a plugin is installed, the Server needs to be aware of when the functionali
 
 Is run before a Commit is applied.
 Useful for performing authorization or data shape checks.
+
+## Wasm class extenders
+
+Atomic Server can load class extenders that are compiled to WASM + WASI Preview 2 (aka wasip2).
+Every extender implements the [`class-extender.wit`](../../lib/wit/class-extender.wit) world and exports:
+
+- `class-url` – the Subject URL of the class to extend
+- `on-resource-get`
+- `before-commit`
+- `after-commit`
+
+Handlers receive JSON-AD payloads that describe the Resource or Commit they should work with and can return an updated JSON-AD document. See the WIT file for the exact record layouts.
+
+### Installing a WASM class extender
+
+1. Build a component that targets `wasm32-wasip2`. Use `wit-bindgen` or `cargo component` to satisfy the interface defined in `lib/wit/class-extender.wit`.
+2. Copy the resulting `.wasm` file into the `wasm-class-extenders/` directory inside your Atomic data directory (next to the sled store).
+3. Restart `atomic-server` (or recreate the `Db`) so it scans the folder and instantiates your component.
+
+All `.wasm` files in that folder are loaded on startup. Errors are logged but do not prevent the server from running, making it safe to iterate on plugins.
+
+### Sample Wasm extender
+
+See `wasm-plugins/examples/random-folder-extender` for a minimal Rust project that implements the `class-extender` WIT interface. It appends a random suffix to the `name` property of every `https://atomicdata.dev/classes/Folder` resource whenever it is fetched. Build it with `cargo component build --release -p random-folder-extender --target wasm32-wasip2` and copy the resulting `.wasm` into your `wasm-class-extenders/` directory to try it out.

docs/src/plugins.md

@@ -40,6 +40,10 @@ url = "2"
 urlencoding = "2"
 ulid = "1.1.3"
 yrs = "0.24.0"
+wasmtime = { version = "39.0.1", optional = true, features = [
+  "component-model",
+] }
+wasmtime-wasi = { version = "39.0.1", optional = true, features = ["p2"] }
 
 [dev-dependencies]
 criterion = "0.5"
@@ -49,6 +53,7 @@ ntest = "0.9"
 
 [features]
 config = ["directories", "toml"]
-db = ["sled", "rmp-serde", "bincode1"]
+db = ["sled", "rmp-serde", "bincode1", "wasm-plugins"]
 html = ["kuchikiki", "lol_html", "html2md"]
 rdf = ["rio_api", "rio_turtle"]
+wasm-plugins = ["wasmtime", "wasmtime-wasi"]

lib/Cargo.toml

@@ -1,3 +1,5 @@
+use std::sync::Arc;
+
 use crate::{
     agents::ForAgent, errors::AtomicResult, storelike::ResourceResponse, urls, Commit, Db, Resource,
 };
@@ -15,12 +17,16 @@ pub struct CommitExtenderContext<'a> {
     pub resource: &'a Resource,
 }
 
+pub type ResourceGetHandler =
+    Arc<dyn Fn(GetExtenderContext) -> AtomicResult<ResourceResponse> + Send + Sync>;
+pub type CommitHandler = Arc<dyn Fn(CommitExtenderContext) -> AtomicResult<()> + Send + Sync>;
+
 #[derive(Clone)]
 pub struct ClassExtender {
     pub class: String,
-    pub on_resource_get: Option<fn(GetExtenderContext) -> AtomicResult<ResourceResponse>>,
-    pub before_commit: Option<fn(CommitExtenderContext) -> AtomicResult<()>>,
-    pub after_commit: Option<fn(CommitExtenderContext) -> AtomicResult<()>>,
+    pub on_resource_get: Option<ResourceGetHandler>,
+    pub before_commit: Option<CommitHandler>,
+    pub after_commit: Option<CommitHandler>,
 }
 
 impl ClassExtender {
@@ -31,4 +37,18 @@ impl ClassExtender {
 
         Ok(is_a.to_subjects(None)?.iter().any(|c| c == &self.class))
     }
+
+    pub fn wrap_get_handler<F>(handler: F) -> ResourceGetHandler
+    where
+        F: Fn(GetExtenderContext) -> AtomicResult<ResourceResponse> + Send + Sync + 'static,
+    {
+        Arc::new(handler)
+    }
+
+    pub fn wrap_commit_handler<F>(handler: F) -> CommitHandler
+    where
+        F: Fn(CommitExtenderContext) -> AtomicResult<()> + Send + Sync + 'static,
+    {
+        Arc::new(handler)
+    }
 }

lib/src/class_extender.rs

@@ -30,7 +30,7 @@ use crate::{
     },
     endpoints::{Endpoint, HandleGetContext},
     errors::{AtomicError, AtomicResult},
-    plugins::plugins,
+    plugins::{plugins, wasm},
     resources::PropVals,
     storelike::{Query, QueryResult, ResourceResponse, Storelike},
     values::SortableValue,
@@ -108,6 +108,9 @@ impl Db {
         let query_index = db.open_tree(Tree::QueryMembers)?;
         let prop_val_sub_index = db.open_tree(Tree::PropValSub)?;
         let watched_queries = db.open_tree(Tree::WatchedQueries)?;
+        let mut class_extenders = plugins::default_class_extenders();
+        class_extenders.extend(wasm::load_wasm_class_extenders(path));
+
         let store = Db {
             path: path.into(),
             db,
@@ -119,7 +122,7 @@ impl Db {
             server_url,
             watched_queries,
             endpoints: plugins::default_endpoints(),
-            class_extenders: plugins::default_class_extenders(),
+            class_extenders,
             on_commit: None,
         };
         migrate_maybe(&store).map(|e| format!("Error during migration of database: {:?}", e))?;
@@ -688,7 +691,7 @@ impl Storelike for Db {
         if let Some(resource_new) = &commit_response.resource_new {
             for extender in self.class_extenders.iter() {
                 if extender.resource_has_extender(resource_new)? {
-                    let Some(handler) = extender.before_commit else {
+                    let Some(handler) = extender.before_commit.as_ref() else {
                         continue;
                     };
 
@@ -753,7 +756,7 @@ impl Storelike for Db {
                 if extender.resource_has_extender(resource_new)? {
                     use crate::class_extender::CommitExtenderContext;
 
-                    let Some(handler) = extender.after_commit else {
+                    let Some(handler) = extender.after_commit.as_ref() else {
                         continue;
                     };
 
@@ -853,7 +856,7 @@ impl Storelike for Db {
                     return Ok(resource.into());
                 }
 
-                if let Some(handler) = extender.on_resource_get {
+                if let Some(handler) = extender.on_resource_get.as_ref() {
                     let resource_response = (handler)(GetExtenderContext {
                         store: self,
                         url: &url,

lib/src/db.rs

@@ -203,6 +203,17 @@ impl From<std::string::FromUtf8Error> for AtomicError {
     }
 }
 
+#[cfg(feature = "wasm-plugins")]
+impl From<wasmtime::Error> for AtomicError {
+    fn from(error: wasmtime::Error) -> Self {
+        AtomicError {
+            message: error.to_string(),
+            error_type: AtomicErrorType::OtherError,
+            subject: None,
+        }
+    }
+}
+
 impl From<ParseFloatError> for AtomicError {
     fn from(error: ParseFloatError) -> Self {
         AtomicError {

lib/src/errors.rs

@@ -131,7 +131,7 @@ pub fn after_apply_commit_message(context: CommitExtenderContext) -> AtomicResul
 pub fn build_chatroom_extender() -> ClassExtender {
     ClassExtender {
         class: urls::CHATROOM.to_string(),
-        on_resource_get: Some(construct_chatroom),
+        on_resource_get: Some(ClassExtender::wrap_get_handler(construct_chatroom)),
         before_commit: None,
         after_commit: None,
     }
@@ -142,6 +142,8 @@ pub fn build_message_extender() -> ClassExtender {
         class: urls::MESSAGE.to_string(),
         on_resource_get: None,
         before_commit: None,
-        after_commit: Some(after_apply_commit_message),
+        after_commit: Some(ClassExtender::wrap_commit_handler(
+            after_apply_commit_message,
+        )),
     }
 }

lib/src/plugins/chatroom.rs

@@ -9,15 +9,17 @@ use crate::{
 pub fn build_collection_extender() -> ClassExtender {
     ClassExtender {
         class: urls::COLLECTION.to_string(),
-        on_resource_get: Some(|context| -> AtomicResult<ResourceResponse> {
+        on_resource_get: Some(ClassExtender::wrap_get_handler(
+            |context| -> AtomicResult<ResourceResponse> {
             let GetExtenderContext {
                 store,
                 url,
                 db_resource: resource,
                 for_agent,
             } = context;
             construct_collection_from_params(store, url.query_pairs(), resource, for_agent)
-        }),
+            },
+        )),
         before_commit: None,
         after_commit: None,
     }

lib/src/plugins/collections.rs

@@ -174,8 +174,8 @@ pub fn before_apply_commit(context: CommitExtenderContext) -> AtomicResult<()> {
 pub fn build_invite_extender() -> ClassExtender {
     ClassExtender {
         class: urls::INVITE.to_string(),
-        on_resource_get: Some(construct_invite_redirect),
-        before_commit: Some(before_apply_commit),
+        on_resource_get: Some(ClassExtender::wrap_get_handler(construct_invite_redirect)),
+        before_commit: Some(ClassExtender::wrap_commit_handler(before_apply_commit)),
         after_commit: None,
     }
 }