feat(hermes): auto stub untyped (#519)

Author: no30bit

docs/src/architecture/08_concepts/hermes_runtime_engine/hre_structure.md

@@ -108,7 +108,7 @@ impl HermesEventPayload for OnCronEvent {
     }
 
     fn execute(&self, module: &mut crate::wasm::module::ModuleInstance) -> anyhow::Result<()> {
-       module.instance.hermes_cron_event().call_on_cron(
+       module.instance.call_hermes_cron_event_on_cron(
             &mut module.store,
             &self.tag,
             self.last,

hermes/Cargo.lock

@@ -95,8 +95,8 @@ test-wasm-integration:
     COPY ../wasm/integration-test/localtime+build/localtime.wasm ../wasm/test-components/
     COPY ../wasm/integration-test/logger+build/logger.wasm ../wasm/test-components/
     COPY ../wasm/integration-test/sqlite+build/sqlite.wasm ../wasm/test-components/
-    COPY ../wasm/integration-test/smoke-test+build/smoke-test.wasm ../wasm/test-components/
-    COPY ../wasm/integration-test/wasi-filesystem+build/wasi-filesystem.wasm ../wasm/test-components/
+    COPY ../wasm/integration-test/smoke-test+build/smoke_test.wasm ../wasm/test-components/
+    COPY ../wasm/integration-test/wasi-filesystem+build/wasi_filesystem.wasm ../wasm/test-components/
 
     # List all WASM integration tests/benches and also run them.
     RUN cargo test --release --test wasm-component-integration-tests -- --list
@@ -111,19 +111,19 @@ test-wasm-examples:
 
     # Copy all wasm module artifacts for running as Hermes applications
 
-    COPY ../wasm/examples/c/cardano_age+build/cardano_age.c.wasm ../wasm/app-components/
-    COPY ../wasm/examples/c/next_century+build/next_century.c.wasm ../wasm/app-components/
-    COPY ../wasm/examples/rust/cardano_age+build/cardano_age.rs.wasm ../wasm/app-components/
-    COPY ../wasm/examples/rust/next_century+build/next_century.rs.wasm ../wasm/app-components/
-    # COPY ../wasm/examples/rust/cardano+build/cardano.rs.wasm ../wasm/app-components/
+    COPY ../wasm/examples/c/cardano_age+build/cardano_age_c.wasm ../wasm/app-components/
+    COPY ../wasm/examples/c/next_century+build/next_century_c.wasm ../wasm/app-components/
+    COPY ../wasm/examples/rust/cardano_age+build/cardano_age_rs.wasm ../wasm/app-components/
+    COPY ../wasm/examples/rust/next_century+build/next_century_rs.wasm ../wasm/app-components/
+    # COPY ../wasm/examples/rust/cardano+build/cardano_rs.wasm ../wasm/app-components/
 
-    RUN ./hermes playground ../wasm/app-components/cardano_age.c.wasm --timeout-ms 10000; \
+    RUN ./hermes playground ../wasm/app-components/cardano_age_c.wasm --timeout-ms 10000; \
         test $? -eq 0
-    RUN ./hermes playground ../wasm/app-components/next_century.c.wasm --timeout-ms 10000; \
+    RUN ./hermes playground ../wasm/app-components/next_century_c.wasm --timeout-ms 10000; \
         test $? -eq 1
-    RUN ./hermes playground ../wasm/app-components/cardano_age.rs.wasm --timeout-ms 10000; \
+    RUN ./hermes playground ../wasm/app-components/cardano_age_rs.wasm --timeout-ms 10000; \
         test $? -eq 0
-    RUN ./hermes playground ../wasm/app-components/next_century.rs.wasm --timeout-ms 10000; \
+    RUN ./hermes playground ../wasm/app-components/next_century_rs.wasm --timeout-ms 10000; \
         test $? -eq 1
     # Example of how to run the Cardano module test
     # Comment out because this is a long running test

hermes/Earthfile

@@ -95,6 +95,7 @@ uuid = { version = "1.18.0", features = ["v4"] }
 reqwest = "0.12.23"
 url = "2.5.7"
 num-traits = "0.2.19"
+paste = "1.0.15"
 traitreg = "0.3.0"
 orx-concurrent-vec = "3.7.0"
 keyed-lock = "0.2.3"
@@ -104,8 +105,8 @@ build-info-build = "0.0.41"
 
 [dev-dependencies]
 serial_test = { version = "3.2.0", features = ["file_locks"] }
-# An override with the "wat" feature added.
-wasmtime = { version = "36.0.2", default-features = false, features = ["runtime", "cranelift", "component-model", "wat"] }
+# An override with the "wat" and "addr2line" features added (debug purposes).
+wasmtime = { version = "36.0.2", default-features = false, features = ["runtime", "cranelift", "component-model", "wat", "addr2line"] }
 httpmock = "0.7.0"
 
 [package.metadata.cargo-machete]

hermes/bin/Cargo.toml

@@ -15,7 +15,7 @@ use temp_dir::TempDir;
 use crate::{
     app::{Application, ApplicationName},
     event::queue::Exit,
-    ipfs, reactor,
+    ipfs, pool, reactor,
     vfs::VfsBootstrapper,
     wasm::module::Module,
 };
@@ -56,13 +56,15 @@ impl Playground {
         init_ipfs(&temp_dir)?;
 
         let exit_lock = reactor::init()?;
-
+        pool::init()?;
         println!(
             "{} Loading {} application(s)...",
             Emoji::new("🛠️", ""),
             apps.len(),
         );
         for app in apps {
+            // TODO[RC]: Prevent the app from receiving any events until it is fully initialized.
+            // TODO[RC]: Currently, when a module fails to initialize, the whole app fails to run.
             reactor::load_app(app)?;
         }
 
@@ -72,6 +74,8 @@ impl Playground {
             exit_lock.wait()
         };
 
+        // Wait for scheduled tasks to be finished.
+        pool::terminate();
         Ok(exit)
     }
 }

hermes/bin/src/cli/playground.rs

@@ -8,6 +8,8 @@
 
 use wasmtime::component::bindgen;
 
+pub(crate) mod unchecked_exports;
+
 bindgen!({
     path: "../../wasm/wasi/wit",
     imports: {

hermes/bin/src/runtime_extensions/bindings.rs renamed to hermes/bin/src/runtime_extensions/bindings/mod.rs

@@ -0,0 +1,99 @@
+//! Hermes WIT exports for event handlers.
+//!
+//! Unlike the functions of [`super::Hermes`] (generated by
+//! [`wasmtime::component::bindgen`]), these aren't checked for presence in WASM until
+//! use.
+
+use wasmtime::{
+    component::{self, ComponentNamedList, TypedFunc},
+    AsContextMut,
+};
+
+use crate::runtime_context::HermesRuntimeContext;
+
+/// WASM function lookup failure.
+#[derive(Debug, thiserror::Error)]
+pub(crate) enum Error {
+    /// A WIT interface and/or function is missing from WASM exports.
+    #[error("event handler is not exported")]
+    NotExported,
+    /// An export is found but its signature doesn't match the one defined in WIT.
+    #[error("invalid event handler signature")]
+    InvalidSignature,
+}
+
+/// Lookup a function in WASM by its path and signature.
+pub(crate) fn get_typed_func<Params, Return>(
+    instance: &component::Instance,
+    store: &mut wasmtime::Store<HermesRuntimeContext>,
+    wit_interface_name: &str,
+    wit_func_name: &str,
+) -> Result<TypedFunc<Params, Return>, Error>
+where
+    Params: ComponentNamedList + component::Lower,
+    Return: ComponentNamedList + component::Lift,
+{
+    let Some(untyped) = instance
+        .get_export_index(store.as_context_mut(), None, wit_interface_name)
+        .and_then(|interface_idx| {
+            instance.get_export_index(store.as_context_mut(), Some(&interface_idx), wit_func_name)
+        })
+        .and_then(|func_idx| instance.get_func(store.as_context_mut(), func_idx))
+    else {
+        return Err(Error::NotExported);
+    };
+    untyped.typed(store).map_err(|_| Error::InvalidSignature)
+}
+
+/// Defines an extension trait for [`wasmtime::component::Instance`] and immediately
+/// implements it. Uses [`get_typed_func`] internally.
+macro_rules! define {
+    ($(#[$attr:meta])* $vis:vis trait $ext_trait:ident {$(
+        #[wit($wit_interface:literal, $wit_func:literal)]
+        fn $rust_func:ident$(<$l:lifetime>)?($($param_name:ident: $param:ty),* $(,)?) $(-> $return:ty)?;
+    )*}) => {::paste::paste! {
+        $vis trait $ext_trait {$(
+            #[doc = concat!("Looks up \"", $wit_func , "\" from \"", $wit_interface, "\".\n\n")]
+            #[doc = "# Panic\n\n Lookup never panics, calling the export can panic if misused (see [`wasmtime::component::Func::call`]).\n"]
+            fn [<lookup_ $rust_func>]$(<$l>)?(
+                &self,
+                store: &mut ::wasmtime::Store<$crate::runtime_context::HermesRuntimeContext>
+            ) -> Result<
+                ::wasmtime::component::TypedFunc<($($param,)*), ($($return,)?)>,
+                $crate::runtime_extensions::bindings::unchecked_exports::Error
+            >;
+
+            #[doc = concat!("Looks up and calls \"", $wit_func , "\" from \"", $wit_interface, "\".\n")]
+            #[doc = concat!("This wraps around [`Self::", stringify!([<lookup_ $rust_func>]), "`].\n\n")]
+            #[doc = "# Panic\n\n Calling the export can panic if misused (see [`wasmtime::component::Func::call`]).\n"]
+            #[allow(unused_parens, dead_code, reason = "needed for codegen in no-return case")]
+            fn $rust_func$(<$l>)?(
+                &self,
+                store: &mut ::wasmtime::Store<$crate::runtime_context::HermesRuntimeContext>,
+                $($param_name: $param,)*
+            ) -> ::anyhow::Result<($($return)?)> {
+                use anyhow::Context as _;
+                self.[<lookup_ $rust_func>](store)
+                    .context(concat!("when looking up the export (",$wit_func, " from ", $wit_interface, ')'))?
+                    .call(store, ($($param_name,)*))
+                    .context(concat!("when calling the export (",$wit_func, " from ", $wit_interface, ')'))
+                    $(.map(|(ret,): ($return,)| ret))?
+            }
+        )*}
+
+        impl $ext_trait for ::wasmtime::component::Instance {$(
+            fn [<lookup_ $rust_func>]$(<$l>)?(
+                &self,
+                store: &mut ::wasmtime::Store<$crate::runtime_context::HermesRuntimeContext>
+            ) -> Result<
+                ::wasmtime::component::TypedFunc<($($param,)*), ($($return,)?)>,
+                $crate::runtime_extensions::bindings::unchecked_exports::Error
+            >
+            {
+                $crate::runtime_extensions::bindings::unchecked_exports::get_typed_func(self, store, $wit_interface, $wit_func)
+            }
+        )*}
+    }};
+}
+
+pub(crate) use define;

hermes/bin/src/runtime_extensions/bindings/unchecked_exports.rs

@@ -1,14 +1,36 @@
 //! Cardano Blockchain runtime extension event handler implementation.
 
 use tracing::error;
+use wasmtime::component::Resource;
 
 use crate::{
     app::ApplicationName,
     event::{HermesEvent, HermesEventPayload, TargetApp, TargetModule},
-    runtime_extensions::hermes::cardano::STATE,
+    runtime_extensions::{
+        bindings::{
+            hermes::cardano::api::{Block, SubscriptionId},
+            unchecked_exports,
+        },
+        hermes::cardano::STATE,
+    },
     wasm::module::ModuleId,
 };
 
+unchecked_exports::define! {
+    /// Extends [`wasmtime::component::Instance`] with guest functions for cardano.
+    trait ComponentInstanceExt {
+      #[wit("hermes:cardano/event-on-block", "on-cardano-block")]
+        fn hermes_cardano_event_on_block_on_cardano_block(
+            subscription_id: Resource<SubscriptionId>, block_id: Resource<Block>,
+        );
+
+        #[wit("hermes:cardano/event-on-immutable-roll-forward", "on-immutable-roll-forward")]
+        fn hermes_cardano_event_on_immutable_roll_forward_on_cardano_immutable_roll_forward(
+            subscription_id: Resource<SubscriptionId>, block_id: Resource<Block>,
+        );
+    }
+}
+
 /// On Cardano block event
 pub(super) struct OnCardanoBlockEvent {
     /// An underlying 32-bit integer representation used to originally create this
@@ -31,13 +53,16 @@ impl HermesEventPayload for OnCardanoBlockEvent {
         module: &mut crate::wasm::module::ModuleInstance,
     ) -> anyhow::Result<()> {
         // Create borrow resources to send to wasm
-        let subscription_id = wasmtime::component::Resource::new_borrow(self.subscription_id);
-        let block = wasmtime::component::Resource::new_borrow(self.block);
+        let subscription_id = Resource::new_borrow(self.subscription_id);
+        let block = Resource::new_borrow(self.block);
 
         module
             .instance
-            .hermes_cardano_event_on_block()
-            .call_on_cardano_block(&mut module.store, subscription_id, block)?;
+            .hermes_cardano_event_on_block_on_cardano_block(
+                &mut module.store,
+                subscription_id,
+                block,
+            )?;
         Ok(())
     }
 }
@@ -80,13 +105,16 @@ impl HermesEventPayload for OnCardanoImmutableRollForwardEvent {
         module: &mut crate::wasm::module::ModuleInstance,
     ) -> anyhow::Result<()> {
         // Create borrow resources to send to wasm
-        let subscription_id = wasmtime::component::Resource::new_borrow(self.subscription_id);
-        let block = wasmtime::component::Resource::new_borrow(self.block);
+        let subscription_id = Resource::new_borrow(self.subscription_id);
+        let block = Resource::new_borrow(self.block);
 
         module
             .instance
-            .hermes_cardano_event_on_immutable_roll_forward()
-            .call_on_cardano_immutable_roll_forward(&mut module.store, subscription_id, block)?;
+            .hermes_cardano_event_on_immutable_roll_forward_on_cardano_immutable_roll_forward(
+                &mut module.store,
+                subscription_id,
+                block,
+            )?;
         Ok(())
     }
 }

hermes/bin/src/runtime_extensions/hermes/cardano/event.rs

@@ -6,9 +6,18 @@ use saffron::Cron;
 
 use super::state::cron_queue_rm;
 use crate::{
-    event::HermesEventPayload, runtime_extensions::bindings::hermes::cron::api::CronTagged,
+    event::HermesEventPayload,
+    runtime_extensions::bindings::{hermes::cron::api::CronTagged, unchecked_exports},
 };
 
+unchecked_exports::define! {
+    /// Extends [`wasmtime::component::Instance`] with guest functions for cron.
+    trait ComponentInstanceExt {
+        #[wit("hermes:cron/event", "on-cron")]
+        fn hermes_cron_event_on_cron(event: &CronTagged, last: bool) -> bool;
+    }
+}
+
 /// Duration in nanoseconds used for the Cron Service.
 #[derive(PartialEq, Eq, PartialOrd, Ord, Copy, Clone)]
 #[cfg_attr(debug_assertions, derive(Debug))]
@@ -71,11 +80,10 @@ impl HermesEventPayload for OnCronEvent {
         &self,
         module: &mut crate::wasm::module::ModuleInstance,
     ) -> anyhow::Result<()> {
-        let res: bool = module.instance.hermes_cron_event().call_on_cron(
-            &mut module.store,
-            &self.tag,
-            self.last,
-        )?;
+        let res =
+            module
+                .instance
+                .hermes_cron_event_on_cron(&mut module.store, &self.tag, self.last)?;
         // if the response is `false`, check if the event would
         // re-trigger, if so, remove it.
         if !res && !self.last {

hermes/bin/src/runtime_extensions/hermes/cron/event.rs

@@ -13,7 +13,9 @@ use url::Url;
 
 use crate::{
     event::HermesEventPayload,
-    runtime_extensions::bindings::exports::hermes::http_gateway::event::HttpGatewayResponse,
+    runtime_extensions::bindings::{
+        exports::hermes::http_gateway::event::HttpGatewayResponse, unchecked_exports,
+    },
 };
 
 // ============================================================================
@@ -204,6 +206,19 @@ fn validate_path(
 // HTTP Event Processing
 // ============================================================================
 
+unchecked_exports::define! {
+    /// Extends [`wasmtime::component::Instance`] with guest functions for HTTP gateway.
+    trait ComponentInstanceExt {
+        #[wit("hermes:http-gateway/event", "reply")]
+        fn hermes_http_gateway_event_reply<'p> (
+            body: &'p [u8],
+            headers: &'p [(String, Vec<String>)],
+            path: &'p str,
+            method: &'p str,
+        ) -> Option<HttpGatewayResponse>;
+    }
+}
+
 impl HermesEventPayload for HTTPEvent {
     fn event_name(&self) -> &'static str {
         "http-event"
@@ -213,9 +228,9 @@ impl HermesEventPayload for HTTPEvent {
         &self,
         module: &mut crate::wasm::module::ModuleInstance,
     ) -> anyhow::Result<()> {
-        let event_response = module.instance.hermes_http_gateway_event().call_reply(
+        let event_response = module.instance.hermes_http_gateway_event_reply(
             &mut module.store,
-            &self.body.as_ref().to_vec(),
+            &self.body,
             &self.headers,
             &self.path,
             &self.method,