Abstract away json in atomic-plugin #73

Author: Polleps

atomic-plugin/README.md

@@ -0,0 +1,44 @@
+# atomic-plugin
+
+A helper library that removes a lot of the boilerplate when building AtomicServer Wasm plugins.
+
+## Class Extenders
+
+Atomic Data Classextenders are plugins that can modify the behavior of an Atomic Data class.
+For example you might want to add some custom verification logic to a class
+
+## How to use
+
+Simply implement the `ClassExtender` trait on a struct and export it using the `export_plugin!` macro.
+
+```rust
+use atomic_plugin::{ClassExtender, Commit, Resource};
+
+struct FolderExtender;
+
+impl ClassExtender for FolderExtender {
+  // REQUIRED: Returns the class that this class extender applies to.
+    fn class_url() -> String {
+        "https://atomicdata.dev/classes/Folder".to_string()
+    }
+
+    // Prevent commits where the name contains "Tailwind CSS".
+    fn before_commit(commit: &Commit, _snapshot: Option<&Resource>) -> Result<(), String> {
+        let Some(set) = &commit.set else {
+            return Ok(());
+        };
+
+        let Some(name) = set.get(NAME_PROP).and_then(|val| val.as_str()) else {
+            return Ok(());
+        };
+
+        if name.contains("Tailwind CSS") {
+            return Err("Tailwind CSS is not allowed".into());
+        }
+
+        Ok(())
+    }
+}
+
+atomic_plugin::export_plugin!(FolderExtender);
+```

atomic-plugin/src/bindings.rs

@@ -591,6 +591,7 @@ macro_rules! __export_class_extender_impl {
     };
 }
 #[doc(inline)]
+#[allow(unused)]
 pub(crate) use __export_class_extender_impl as export;
 #[cfg(target_arch = "wasm32")]
 #[unsafe(link_section = "component-type:wit-bindgen:0.41.0:atomic:class-extender@0.1.0:class-extender:encoded world")]

atomic-plugin/src/lib.rs

@@ -10,76 +10,114 @@ pub use bindings::atomic::class_extender::types::{
 };
 pub use bindings::Guest;
 
+use serde::Deserialize;
 use serde_json::Value as JsonValue;
 
+pub struct Resource {
+    pub subject: String,
+    pub props: serde_json::Map<String, JsonValue>,
+}
+
+#[derive(Clone, Debug, Deserialize)]
+pub struct Commit {
+    /// The subject URL that is to be modified by this Delta
+    #[serde(rename = "https://atomicdata.dev/properties/subject")]
+    pub subject: String,
+    /// The date it was created, as a unix timestamp
+    #[serde(rename = "https://atomicdata.dev/properties/createdAt")]
+    pub created_at: i64,
+    /// The URL of the one signing this Commit
+    #[serde(rename = "https://atomicdata.dev/properties/signer")]
+    pub signer: String,
+    /// The set of PropVals that need to be added.
+    /// Overwrites existing values
+    #[serde(rename = "https://atomicdata.dev/properties/set")]
+    pub set: Option<std::collections::HashMap<String, JsonValue>>,
+    #[serde(rename = "https://atomicdata.dev/properties/yUpdate")]
+    pub y_update: Option<std::collections::HashMap<String, JsonValue>>,
+    #[serde(rename = "https://atomicdata.dev/properties/remove")]
+    /// The set of property URLs that need to be removed
+    pub remove: Option<Vec<String>>,
+    /// If set to true, deletes the entire resource
+    #[serde(rename = "https://atomicdata.dev/properties/destroy")]
+    pub destroy: Option<bool>,
+    /// Base64 encoded signature of the JSON serialized Commit
+    #[serde(rename = "https://atomicdata.dev/properties/signature")]
+    pub signature: Option<String>,
+    /// List of Properties and Arrays to be appended to them
+    #[serde(rename = "https://atomicdata.dev/properties/push")]
+    pub push: Option<std::collections::HashMap<String, JsonValue>>,
+    /// The previously applied commit to this Resource.
+    #[serde(rename = "https://atomicdata.dev/properties/previousCommit")]
+    pub previous_commit: Option<String>,
+    /// The URL of the Commit
+    pub url: Option<String>,
+}
+
 /// High-level trait for implementing a Class Extender plugin.
-pub trait AtomicPlugin {
+pub trait ClassExtender {
     fn class_url() -> String;
 
-    fn on_resource_get(
-        _subject: &str,
-        _resource: &mut JsonValue,
-    ) -> Result<Option<JsonValue>, String> {
-        Ok(None)
+    /// Called when a resource is fetched from the server. You can modify the resource in place.
+    fn on_resource_get<'a>(resource: &'a mut Resource) -> Result<Option<&'a Resource>, String> {
+        Ok(Some(resource))
     }
 
-    fn before_commit(_subject: &str, _resource: &JsonValue) -> Result<(), String> {
+    /// Called before a Commit that targets the class is persisted. If you return an error, the commit will be rejected.
+    fn before_commit(_commit: &Commit, _snapshot: Option<&Resource>) -> Result<(), String> {
         Ok(())
     }
 
-    fn after_commit(_subject: &str, _resource: &JsonValue) -> Result<(), String> {
+    /// Called after a Commit that targets the class has been applied. Returning an error will not cancel the commit.
+    fn after_commit(_commit: &Commit, _resource: Option<&Resource>) -> Result<(), String> {
         Ok(())
     }
 }
 
 #[doc(hidden)]
 pub struct PluginWrapper<T>(std::marker::PhantomData<T>);
 
-impl<T: AtomicPlugin> Guest for PluginWrapper<T> {
+impl<T: ClassExtender> Guest for PluginWrapper<T> {
     fn class_url() -> String {
         T::class_url()
     }
 
     fn on_resource_get(ctx: GetContext) -> Result<Option<ResourceResponse>, String> {
-        let mut json_value: JsonValue =
-            serde_json::from_str(&ctx.snapshot.json_ad).map_err(|e| e.to_string())?;
-
-        let result = T::on_resource_get(&ctx.snapshot.subject, &mut json_value)?;
-
-        match result {
-            Some(updated_json) => {
-                let updated_payload = serde_json::to_string(&updated_json)
-                    .map_err(|e| format!("Serialize error: {e}"))?;
-                Ok(Some(ResourceResponse {
-                    primary: ResourceJson {
-                        subject: ctx.snapshot.subject,
-                        json_ad: updated_payload,
-                    },
-                    referenced: Vec::new(),
-                }))
-            }
-            None => Ok(None),
-        }
+        let mut resource = Resource::try_from(ctx.snapshot)?;
+
+        let Some(result) = T::on_resource_get(&mut resource)? else {
+            return Ok(None);
+        };
+
+        let updated_payload = result.to_json()?;
+
+        Ok(Some(ResourceResponse {
+            primary: ResourceJson {
+                subject: resource.subject,
+                json_ad: updated_payload,
+            },
+            referenced: Vec::new(),
+        }))
     }
 
     fn before_commit(ctx: CommitContext) -> Result<(), String> {
-        if let Some(snapshot) = ctx.snapshot {
-            let json_value: JsonValue =
-                serde_json::from_str(&snapshot.json_ad).map_err(|e| e.to_string())?;
-            T::before_commit(&ctx.subject, &json_value)
-        } else {
-            Ok(())
-        }
+        let commit: Commit = serde_json::from_str(&ctx.commit_json).map_err(|e| e.to_string())?;
+        let snapshot: Option<Resource> = match ctx.snapshot {
+            Some(snapshot) => Some(Resource::try_from(snapshot)?),
+            None => None,
+        };
+
+        T::before_commit(&commit, snapshot.as_ref())
     }
 
     fn after_commit(ctx: CommitContext) -> Result<(), String> {
-        if let Some(snapshot) = ctx.snapshot {
-            let json_value: JsonValue =
-                serde_json::from_str(&snapshot.json_ad).map_err(|e| e.to_string())?;
-            T::after_commit(&ctx.subject, &json_value)
-        } else {
-            Ok(())
-        }
+        let commit: Commit = serde_json::from_str(&ctx.commit_json).map_err(|e| e.to_string())?;
+        let snapshot: Option<Resource> = match ctx.snapshot {
+            Some(snapshot) => Some(Resource::try_from(snapshot)?),
+            None => None,
+        };
+
+        T::after_commit(&commit, snapshot.as_ref())
     }
 }
 
@@ -105,3 +143,32 @@ macro_rules! export_plugin {
        $crate::__export_world_class_extender_cabi!(Shim with_types_in $crate::bindings);
     };
 }
+
+impl TryFrom<ResourceJson> for Resource {
+    type Error = String;
+
+    fn try_from(resource_json: ResourceJson) -> Result<Self, Self::Error> {
+        let json_value: JsonValue = serde_json::from_str(&resource_json.json_ad)
+            .map_err(|e| format!("Invalid JSON: {}", e))?;
+
+        let Some(obj) = json_value.as_object() else {
+            return Err("Resource is not a JSON object".into());
+        };
+
+        let mut props = obj.clone();
+        props.remove("@id");
+
+        Ok(Self {
+            subject: resource_json.subject,
+            props,
+        })
+    }
+}
+
+impl Resource {
+    pub fn to_json(&self) -> Result<String, String> {
+        let mut props = self.props.clone();
+        props.insert("@id".to_string(), JsonValue::String(self.subject.clone()));
+        serde_json::to_string(&props).map_err(|e| format!("Serialize error: {e}"))
+    }
+}

lib/src/plugins/wasm.rs

@@ -32,7 +32,7 @@ use bindings::atomic::class_extender::types::{
     ResourceJson as WasmResourceJson, ResourceResponse as WasmResourceResponse,
 };
 
-const WASM_EXTENDER_DIR: &str = "../plugins/class-extenders";
+const WASM_EXTENDER_DIR: &str = "../plugins/class-extenders"; // Relative to the store path.
 
 pub fn load_wasm_class_extenders(store_path: &Path) -> Vec<ClassExtender> {
     let plugins_dir = store_path.join(WASM_EXTENDER_DIR);

plugin-examples/random-folder-extender/Cargo.toml

@@ -4,12 +4,10 @@ version = "0.1.0"
 edition = "2021"
 
 [lib]
+# This is important for the Wasm build.
 crate-type = ["cdylib"]
 
 [dependencies]
 atomic-plugin = { path = "../../atomic-plugin" }
 rand = { version = "0.8", features = ["std", "std_rng"] }
 serde_json = "1"
-
-[package.metadata.component]
-package = "atomic:class-extender"

plugin-examples/random-folder-extender/README.md

@@ -1,21 +1,25 @@
 # Random Folder Class Extender
 
-This crate shows how to build a Wasm-based class extender for Atomic Server. It targets the `class-extender` world defined in `lib/wit/class-extender.wit` and appends a random four-digit suffix to every folder name whenever a resource of class [`https://atomicdata.dev/classes/Folder`](https://atomicdata.dev/classes/Folder) is fetched.
+This crate shows how to build a Wasm-based class extender for Atomic Server.
+It appends a random number to the end of the folder name each time it is fetched.
+It also prevents commits to the folder if the name contains uppercase letters.
 
 ## Building
 
-You'll need [`cargo-component`](https://github.com/bytecodealliance/cargo-component) to compile the component:
+AtomicServer plugins are compiled to WebAssempbly (Wasm) using the component model.
+You should target the `wasm32-wasip2` architecture when building the project.
 
 ```bash
-cargo component build --release -p random-folder-extender --target wasm32-wasip2
-```
-
-The compiled Wasm component will be written to:
+# Install the target if you haven't already.
+rustup target add wasm32-wasip2
 
+# Build the plugin.
+cargo build --release -p random-folder-extender --target wasm32-wasip2
 ```
-target/wasm32-wasip2/release/random-folder-extender.wasm
-```
-
-Copy that file into your server's `wasm-class-extenders/` directory (sits next to the sled database). Atomic Server will discover it on startup and automatically append random suffixes to folder names.
 
+In this example the build output location is `target/wasm32-wasip2/release/random-folder-extender.wasm`.
 
+Copy that file into your servers `plugins/class-extenders/` directory and restart AtomicServer.
+The plugin should be automatically loaded.
+The plugin folder is located in the same directory as your AtomicServer store.
+Check the [docs](https://docs.atomicdata.dev/atomicserver/faq.html#where-is-my-data-stored-on-my-machine) to find this directory.

plugin-examples/random-folder-extender/src/lib.rs

@@ -1,35 +1,50 @@
-use atomic_plugin::AtomicPlugin;
+use atomic_plugin::{ClassExtender, Commit, Resource};
 use rand::Rng;
-use serde_json::{json, Value as JsonValue};
 
 struct RandomFolderExtender;
 
 const FOLDER_CLASS: &str = "https://atomicdata.dev/classes/Folder";
 const NAME_PROP: &str = "https://atomicdata.dev/properties/name";
 
-impl AtomicPlugin for RandomFolderExtender {
+impl ClassExtender for RandomFolderExtender {
     fn class_url() -> String {
         FOLDER_CLASS.to_string()
     }
 
-    fn on_resource_get(
-        _subject: &str,
-        resource: &mut JsonValue,
-    ) -> Result<Option<JsonValue>, String> {
-        let Some(obj) = resource.as_object_mut() else {
-            return Err("Resource is not a JSON object".into());
-        };
-
-        let base_name = obj
+    // Modify the response from the server every time a folder is fetched.
+    // Appends a random number to the end of the folder name.
+    fn on_resource_get(resource: &mut Resource) -> Result<Option<&Resource>, String> {
+        let base_name = resource
+            .props
             .get(NAME_PROP)
             .and_then(|val| val.as_str())
             .unwrap_or("Folder");
 
         let random_suffix = rand::thread_rng().gen_range(0..=9999);
         let updated_name = format!("{} {}", base_name.trim_end(), random_suffix);
 
-        obj.insert(NAME_PROP.to_string(), json!(updated_name));
-        Ok(Some(resource.clone()))
+        resource
+            .props
+            .insert(NAME_PROP.to_string(), updated_name.into());
+
+        Ok(Some(resource))
+    }
+
+    // Prevent commits if the folder name contains uppercase letters.
+    fn before_commit(commit: &Commit, _snapshot: Option<&Resource>) -> Result<(), String> {
+        let Some(set) = &commit.set else {
+            return Ok(());
+        };
+
+        let Some(name) = set.get(NAME_PROP).and_then(|val| val.as_str()) else {
+            return Ok(());
+        };
+
+        if name.chars().any(|c| c.is_uppercase()) {
+            return Err("Folder name cannot contain uppercase letters".into());
+        }
+
+        Ok(())
     }
 }