improve

Author: andrewgazelka

README.md

@@ -28,6 +28,31 @@ runtime.execute(kernel_bytes, transport, codec).await?;
 
 WASM kernel: 14KB, sandboxed via wasmtime.
 
+## CPU time limiting
+
+Servers enforce maximum kernel execution time using epoch-based interruption:
+
+```rust
+use std::time::Duration;
+use rpc_wasm_runtime::WasmRuntime;
+
+// Server creates runtime with maximum 5 second timeout (enforced server-side)
+let mut runtime = WasmRuntime::new(Duration::from_secs(5))?;
+
+// Client can request shorter timeout, but not longer than server maximum
+runtime.execute(kernel_bytes, transport, codec, Some(Duration::from_millis(500))).await?;
+
+// Server maximum is enforced if client requests longer or no timeout
+runtime.execute(kernel_bytes, transport, codec, Some(Duration::from_secs(10))).await?;  // Capped at 5s
+runtime.execute(kernel_bytes, transport, codec, None).await?;  // Uses 5s default
+```
+
+Timeout behavior:
+- Server sets `max_timeout` when creating `WasmRuntime`
+- Actual timeout: `min(client_requested, server_max)`
+- Prevents malicious clients from monopolizing resources
+- Epoch interruption has approximately 10% overhead (vs 2-3x for fuel-based limiting)
+
 ## Example: data aggregation
 
 ```rust

crates/rpc-wasm-runtime/src/lib.rs

@@ -4,6 +4,7 @@
 
 use rpc_core::{Codec, Transport};
 use std::sync::Arc;
+use std::time::Duration;
 use tokio::sync::Mutex;
 use wasmtime::component::{Component, Linker};
 use wasmtime::{Config, Engine, Store};
@@ -71,42 +72,74 @@ where
 {
     engine: Engine,
     linker: Linker<RuntimeState<T, C>>,
+    max_timeout: Duration,
 }
 
 impl<T, C> WasmRuntime<T, C>
 where
     T: Transport + Send + 'static,
     C: Codec + Send + 'static,
 {
-    /// Create a new WASM runtime
-    pub fn new() -> Result<Self> {
+    /// Create a new WASM runtime with a maximum execution timeout
+    ///
+    /// # Arguments
+    /// * `max_timeout` - Maximum CPU time any kernel can use (enforced server-side)
+    pub fn new(max_timeout: Duration) -> Result<Self> {
         let mut config = Config::new();
         config.wasm_component_model(true);
         config.async_support(true);
+        // Enable epoch-based interruption for CPU time limiting
+        config.epoch_interruption(true);
 
         let engine = Engine::new(&config)?;
         let mut linker = Linker::new(&engine);
 
         // Add WASI support
         wasmtime_wasi::add_to_linker_async(&mut linker)?;
 
-        Ok(Self { engine, linker })
+        Ok(Self { engine, linker, max_timeout })
     }
 
-    /// Execute a WASM component kernel
+    /// Execute a WASM component kernel with timeout
+    ///
+    /// # Arguments
+    /// * `component_bytes` - The compiled WASM component
+    /// * `transport` - Transport for RPC calls
+    /// * `codec` - Codec for serialization
+    /// * `requested_timeout` - Optional client-requested timeout (capped at max_timeout)
+    ///
+    /// # Timeout Behavior
+    /// The actual timeout used is `min(requested_timeout, max_timeout)`, ensuring the server
+    /// always enforces its maximum limit regardless of client requests.
     pub async fn execute(
         &mut self,
         component_bytes: &[u8],
         transport: T,
         codec: C,
+        requested_timeout: Option<Duration>,
     ) -> Result<Vec<u8>> {
+        // Client can request shorter timeout, but not longer than server max
+        let timeout = requested_timeout
+            .map(|t| t.min(self.max_timeout))
+            .unwrap_or(self.max_timeout);
+
         let component = Component::from_binary(&self.engine, component_bytes)?;
 
         let state = RuntimeState::new(transport, codec);
         let mut store = Store::new(&self.engine, state);
 
+        // Set epoch deadline for timeout
+        store.set_epoch_deadline(1);
+
+        // Spawn background task to increment epoch after timeout
+        let engine = self.engine.clone();
+        tokio::spawn(async move {
+            tokio::time::sleep(timeout).await;
+            engine.increment_epoch();
+        });
+
         // Instantiate the component
-        let instance = self.linker.instantiate_async(&mut store, &component).await?;
+        let _instance = self.linker.instantiate_async(&mut store, &component).await?;
 
         // TODO: Call the kernel's exported function and get result
         // For now, return empty result
@@ -119,7 +152,8 @@ where
     T: Transport + Send + 'static,
     C: Codec + Send + 'static,
 {
+    /// Create a default runtime with 5 second timeout
     fn default() -> Self {
-        Self::new().expect("Failed to create WASM runtime")
+        Self::new(Duration::from_secs(5)).expect("Failed to create WASM runtime")
     }
 }

examples-crate/Cargo.toml

@@ -16,6 +16,7 @@ rpc-transport-ws.workspace = true
 rpc-transport-stdio.workspace = true
 rpc-transport-inprocess.workspace = true
 rpc-openapi.workspace = true
+rpc-wasm-runtime.workspace = true
 tokio.workspace = true
 serde.workspace = true
 serde_json.workspace = true