feat: add try fn for with test contract frame (#1628)

### What

Add a function that returns errors when executing a closure for a test
contract frame

### Why

stellar/rs-soroban-sdk#1434

### Known limitations

None

---------

Co-authored-by: Dmytro Kozhevin <dmytro@stellar.org>

Author: mootz12

soroban-env-host/observations/25/test__frame__try_with_test_contract_frame_catches_host_error.json

@@ -0,0 +1,20 @@
+{
+  "   0 begin": "cpu:14488, mem:0, prngs:-/9b4a753, objs:-/-, vm:-/-, evt:-, store:-/-, foot:-, stk:-, auth:-/-",
+  "   1 call vec_new()": "cpu:14930, mem:80, objs:-/1@6e27cef",
+  "   2 ret vec_new -> Ok(Vec(obj#3))": "cpu:15433, mem:160, objs:-/2@19dff6ca",
+  "   3 call symbol_new_from_slice(13)": "cpu:36979, mem:2038, objs:-/3@52e71cc, store:-/2@7bc024e1, foot:2@d6be0e71",
+  "   4 ret symbol_new_from_slice -> Ok(Symbol(obj#7))": "cpu:37989, mem:2147, objs:-/4@d72f5dc1",
+  "   5 push TEST:   0:sym#7()": "cpu:48533, mem:3291, objs:-/5@af7c85bb, stk:1@8e5c3d6a, auth:1@8b9c58a5/-",
+  "   6 call symbol_new_from_slice(13)": "",
+  "   7 ret symbol_new_from_slice -> Ok(Symbol(obj#11))": "cpu:49543, mem:3400, objs:-/6@6c5fdc1a",
+  "   8 call obj_cmp(Symbol(obj#11), Symbol(obj#7))": "",
+  "   9 ret obj_cmp -> Ok(0)": "cpu:49832",
+  "  10 pop TEST:   0:sym#7 -> Ok(Void)": "",
+  "  11 push TEST:   0:test()": "cpu:54601, mem:4360, objs:-/7@e5e0c6fc, stk:1@6c0a26dc, auth:1@ff08e997/-",
+  "  12 call symbol_new_from_slice(11)": "",
+  "  13 ret symbol_new_from_slice -> Ok(Symbol(obj#15))": "cpu:55611, mem:4467, objs:-/8@75aa5756",
+  "  14 call get_contract_data(Symbol(obj#15), Persistent)": "",
+  "  15 ret get_contract_data -> Err(Error(Storage, MissingValue))": "cpu:59507, mem:4941, store:-/3@d3f11b10, foot:3@a65ae30e",
+  "  16 pop TEST:   0:test -> Err(Error(Storage, MissingValue))": "",
+  "  17 end": "cpu:59507, mem:4941, prngs:-/9b4a753, objs:-/8@75aa5756, vm:-/-, evt:-, store:-/2@7bc024e1, foot:3@a65ae30e, stk:-, auth:-/-"
+}

soroban-env-host/observations/25/test__frame__try_with_test_contract_frame_catches_panic.json

@@ -0,0 +1,16 @@
+{
+  "   0 begin": "cpu:14488, mem:0, prngs:-/9b4a753, objs:-/-, vm:-/-, evt:-, store:-/-, foot:-, stk:-, auth:-/-",
+  "   1 call vec_new()": "cpu:14930, mem:80, objs:-/1@6e27cef",
+  "   2 ret vec_new -> Ok(Vec(obj#3))": "cpu:15433, mem:160, objs:-/2@19dff6ca",
+  "   3 call symbol_new_from_slice(13)": "cpu:36979, mem:2038, objs:-/3@52e71cc, store:-/2@7bc024e1, foot:2@d6be0e71",
+  "   4 ret symbol_new_from_slice -> Ok(Symbol(obj#7))": "cpu:37989, mem:2147, objs:-/4@d72f5dc1",
+  "   5 push TEST:   0:sym#7()": "cpu:48533, mem:3291, objs:-/5@af7c85bb, stk:1@8e5c3d6a, auth:1@8b9c58a5/-",
+  "   6 call symbol_new_from_slice(13)": "",
+  "   7 ret symbol_new_from_slice -> Ok(Symbol(obj#11))": "cpu:49543, mem:3400, objs:-/6@6c5fdc1a",
+  "   8 call obj_cmp(Symbol(obj#11), Symbol(obj#7))": "",
+  "   9 ret obj_cmp -> Ok(0)": "cpu:49832",
+  "  10 pop TEST:   0:sym#7 -> Ok(Void)": "",
+  "  11 push TEST:   0:test()": "cpu:54601, mem:4360, objs:-/7@e5e0c6fc, stk:1@6c0a26dc, auth:1@ff08e997/-",
+  "  12 pop TEST:   0:test -> Err(Error(WasmVm, InvalidAction))": "",
+  "  13 end": "cpu:54601, mem:4360, prngs:-/9b4a753, objs:-/7@e5e0c6fc, vm:-/-, evt:-, store:-/2@7bc024e1, foot:2@d6be0e71, stk:-, auth:-/-"
+}

soroban-env-host/observations/25/test__frame__try_with_test_contract_frame_has_frame.json

@@ -0,0 +1,16 @@
+{
+  "   0 begin": "cpu:14488, mem:0, prngs:-/9b4a753, objs:-/-, vm:-/-, evt:-, store:-/-, foot:-, stk:-, auth:-/-",
+  "   1 call vec_new()": "cpu:14930, mem:80, objs:-/1@6e27cef",
+  "   2 ret vec_new -> Ok(Vec(obj#3))": "cpu:15433, mem:160, objs:-/2@19dff6ca",
+  "   3 call symbol_new_from_slice(13)": "cpu:36979, mem:2038, objs:-/3@52e71cc, store:-/2@7bc024e1, foot:2@d6be0e71",
+  "   4 ret symbol_new_from_slice -> Ok(Symbol(obj#7))": "cpu:37989, mem:2147, objs:-/4@d72f5dc1",
+  "   5 push TEST:   0:sym#7()": "cpu:48533, mem:3291, objs:-/5@af7c85bb, stk:1@8e5c3d6a, auth:1@8b9c58a5/-",
+  "   6 call symbol_new_from_slice(13)": "",
+  "   7 ret symbol_new_from_slice -> Ok(Symbol(obj#11))": "cpu:49543, mem:3400, objs:-/6@6c5fdc1a",
+  "   8 call obj_cmp(Symbol(obj#11), Symbol(obj#7))": "",
+  "   9 ret obj_cmp -> Ok(0)": "cpu:49832",
+  "  10 pop TEST:   0:sym#7 -> Ok(Void)": "",
+  "  11 push TEST:   0:test()": "cpu:54601, mem:4360, objs:-/7@e5e0c6fc, stk:1@6c0a26dc, auth:1@ff08e997/-",
+  "  12 pop TEST:   0:test -> Ok(Void)": "",
+  "  13 end": "cpu:54601, mem:4360, prngs:-/9b4a753, objs:-/7@e5e0c6fc, vm:-/-, evt:-, store:-/2@7bc024e1, foot:2@d6be0e71, stk:-, auth:-/-"
+}

soroban-env-host/observations/25/test__lifecycle__test_contract_wasm_update.json

@@ -82,10 +82,10 @@
   "  80 ret update_current_contract_wasm -> Ok(Void)": "cpu:7091002, mem:9026990, objs:1@8099ea12/34@d3d5f07b, evt:2@951fccd4, store:1@f369ddeb/3@63e40642",
   "  81 pop VM:7013ae53:update -> Ok(I32(123))": "cpu:7095920, mem:9027762, vm:1048576@740599e7/6@c559546a, store:1@f369ddeb/3@d5018297",
   "  82 ret call -> Ok(I32(123))": " objs:-/34@d3d5f07b, vm:-/-, store:-/3@d5018297, stk:-, auth:-/-",
-  "  83 push TEST:ba863dea:()": "cpu:7101804, mem:9028953, objs:-/35@3aed3f2c, stk:1@c72009c2, auth:1@2a4a1617/-",
+  "  83 push TEST:ba863dea:check_foo()": "cpu:7101804, mem:9028953, objs:-/35@3aed3f2c, stk:1@b527bc58, auth:1@72792528/-",
   "  84 call get_contract_data(Symbol(foo), Instance)": "",
-  "  85 ret get_contract_data -> Ok(I32(111))": "cpu:7102475, mem:9029009, store:1@f369ddeb/3@d5018297, stk:1@fed36e41",
-  "  86 pop TEST:ba863dea: -> Ok(Void)": "",
+  "  85 ret get_contract_data -> Ok(I32(111))": "cpu:7102475, mem:9029009, store:1@f369ddeb/3@d5018297, stk:1@cf598e77",
+  "  86 pop TEST:ba863dea:check_foo -> Ok(Void)": "",
   "  87 call vec_new_from_slice(2)": "cpu:7112562, mem:9030691, store:-/3@d5018297, stk:-, auth:-/-",
   "  88 ret vec_new_from_slice -> Ok(Vec(obj#71))": "cpu:7113529, mem:9030803, objs:-/36@7643ae9e",
   "  89 call call(Address(obj#17), Symbol(add), Vec(obj#71))": "",

soroban-env-host/src/host/frame.rs

@@ -648,14 +648,92 @@ impl Host {
         F: FnOnce() -> Result<Val, HostError>,
     {
         let _invocation_meter_scope = self.maybe_meter_invocation(
-            crate::host::invocation_metering::MeteringInvocation::CreateContractEntryPoint,
+            crate::host::invocation_metering::MeteringInvocation::contract_invocation(
+                self, &id, func,
+            ),
         );
         self.with_frame(
             Frame::TestContract(self.create_test_contract_frame(id, func, vec![])?),
             f,
         )
     }
 
+    /// Pushes a test contract [`Frame`], runs a closure, and then pops the
+    /// frame, rolling back if the closure returned an error. Returns the result
+    /// that the closure returned (or any error that occurred during the closure
+    /// or the frame push/pop). Used for testing.
+    #[cfg(any(test, feature = "testutils"))]
+    pub fn try_with_test_contract_frame<F>(
+        &self,
+        id: ContractId,
+        func: Symbol,
+        f: F,
+    ) -> Result<Val, HostError>
+    where
+        F: FnOnce() -> Result<Val, HostError>,
+    {
+        let _invocation_meter_scope = self.maybe_meter_invocation(
+            crate::host::invocation_metering::MeteringInvocation::contract_invocation(
+                self, &id, func,
+            ),
+        );
+
+        // Code taken from `call_n_internal` to handle panics inside the closure `f`.
+        // Modified to run as a closure within a test contract frame instead of invoking
+        // a contract function.
+        let frame = self.create_test_contract_frame(id.clone(), func, vec![])?;
+        let panic = frame.panic.clone();
+        self.with_frame(Frame::TestContract(frame), || {
+            use std::any::Any;
+            use std::panic::AssertUnwindSafe;
+            type PanicVal = Box<dyn Any + Send>;
+
+            let closure = AssertUnwindSafe(move || f());
+            let res: Result<Result<Val, HostError>, PanicVal> =
+                crate::testutils::call_with_suppressed_panic_hook(closure);
+            match res {
+                Ok(res) => res,
+                Err(panic_payload) => {
+                    let mut error: Error =
+                        Error::from(wasmi::core::TrapCode::UnreachableCodeReached);
+
+                    let mut recovered_error_from_panic_refcell = false;
+                    if let Ok(panic) = panic.try_borrow() {
+                        if let Some(err) = *panic {
+                            recovered_error_from_panic_refcell = true;
+                            error = err;
+                        }
+                    }
+
+                    if !recovered_error_from_panic_refcell {
+                        self.with_debug_mode(|| {
+                            // only include func in log if a non-empty name is provided
+                            let func_str = match format!("{:?}", func).as_str() {
+                                "Symbol()" => String::new(),
+                                formatted => format!(" with fn name '{}'", formatted),
+                            };
+                            if let Some(str) = panic_payload.downcast_ref::<&str>() {
+                                let msg: String = format!(
+                                    "caught panic '{}' from test contract frame{}",
+                                    str, func_str
+                                );
+                                let _ = self.log_diagnostics(&msg, &[]);
+                            } else if let Some(str) = panic_payload.downcast_ref::<String>() {
+                                let msg: String = format!(
+                                    "caught panic '{}' from test contract frame{}",
+                                    str, func_str
+                                );
+                                let _ = self.log_diagnostics(&msg, &[]);
+                            };
+                            Ok(())
+                        })
+                    }
+                    Err(self.error(error, "caught error from test contract frame", &[]))
+                }
+            }
+        })
+    }
+
     #[cfg(any(test, feature = "testutils"))]
     fn create_test_contract_frame(
         &self,

soroban-env-host/src/test/frame.rs

@@ -1,31 +1,33 @@
+use soroban_env_common::{Env, StorageType};
+
 use crate::{
     host::HostError,
-    xdr::{ContractId, Hash, ScAddress},
-    Compare, ContractFunctionSet, EnvBase, Host, Symbol, Val,
+    xdr::{ContractId, Hash, ScAddress, ScErrorCode, ScErrorType},
+    Compare, ContractFunctionSet, EnvBase, Error, Host, Symbol, Val,
 };
 
 use std::rc::Rc;
 
-#[test]
-fn has_frame() -> Result<(), HostError> {
-    struct NoopContractFunctionSet;
-    impl ContractFunctionSet for NoopContractFunctionSet {
-        fn call(&self, func: &Symbol, host: &Host, _args: &[Val]) -> Option<Val> {
-            if host
-                .compare(
-                    &host.symbol_new_from_slice(b"__constructor").unwrap().into(),
-                    func,
-                )
-                .unwrap()
-                .is_ne()
-            {
-                None
-            } else {
-                Some(().into())
-            }
+struct NoopContractFunctionSet;
+impl ContractFunctionSet for NoopContractFunctionSet {
+    fn call(&self, func: &Symbol, host: &Host, _args: &[Val]) -> Option<Val> {
+        if host
+            .compare(
+                &host.symbol_new_from_slice(b"__constructor").unwrap().into(),
+                func,
+            )
+            .unwrap()
+            .is_ne()
+        {
+            None
+        } else {
+            Some(().into())
         }
     }
+}
 
+#[test]
+fn has_frame() -> Result<(), HostError> {
     let host = observe_host!(Host::test_host_with_recording_footprint());
 
     // Host has no frame outside of executing a contract.
@@ -35,14 +37,115 @@ fn has_frame() -> Result<(), HostError> {
     let id = [0u8; 32];
     let address = host.add_host_object(ScAddress::Contract(ContractId(Hash(id))))?;
     host.register_test_contract(address, Rc::new(NoopContractFunctionSet))?;
-    let func = Symbol::try_from_small_str("")?;
-    host.with_test_contract_frame(ContractId(Hash(id)), func, || {
-        assert!(host.has_frame()?);
-        Ok(().into())
-    })?;
+    host.with_test_contract_frame(
+        ContractId(Hash(id)),
+        Symbol::try_from_small_str("").unwrap(),
+        || {
+            assert!(host.has_frame()?);
+            Ok(().into())
+        },
+    )?;
+    // Host has no frame outside of executing a contract.
+    assert!(!host.has_frame()?);
+
+    Ok(())
+}
+
+#[test]
+fn try_with_test_contract_frame_has_frame() -> Result<(), HostError> {
+    let host = observe_host!(Host::test_host_with_recording_footprint());
 
     // Host has no frame outside of executing a contract.
     assert!(!host.has_frame()?);
 
+    // Host has a frame when executing a contract.
+    let id = [0u8; 32];
+    let address = host.add_host_object(ScAddress::Contract(ContractId(Hash(id))))?;
+    host.register_test_contract(address, Rc::new(NoopContractFunctionSet))?;
+    host.try_with_test_contract_frame(
+        ContractId(Hash(id)),
+        Symbol::try_from_small_str("test").unwrap(),
+        || {
+            assert!(host.has_frame()?);
+            Ok(().into())
+        },
+    )?;
+
+    // Host has no frame outside of executing a contract.
+    assert!(!host.has_frame()?);
+
+    Ok(())
+}
+
+#[test]
+fn try_with_test_contract_frame_catches_host_error() -> Result<(), HostError> {
+    // Setup host and contract
+    let host = observe_host!(Host::test_host_with_recording_footprint());
+    let id = [0u8; 32];
+    let address = host.add_host_object(ScAddress::Contract(ContractId(Hash(id))))?;
+    host.register_test_contract(address, Rc::new(NoopContractFunctionSet))?;
+
+    // Cause a HostError inside the contract frame
+    let result = host.try_with_test_contract_frame(
+        ContractId(Hash(id)),
+        Symbol::try_from_small_str("test").unwrap(),
+        || {
+            let key = host.symbol_new_from_slice(b"nonexistent")?;
+            host.get_contract_data(key.as_val().clone(), StorageType::Persistent)?;
+            Ok(().into())
+        },
+    );
+    assert!(result.is_err());
+    assert_eq!(
+        result.unwrap_err(),
+        HostError::from(Error::from_type_and_code(
+            ScErrorType::Storage,
+            ScErrorCode::MissingValue
+        ))
+    );
+
+    Ok(())
+}
+
+#[test]
+fn try_with_test_contract_frame_catches_panic() -> Result<(), HostError> {
+    // Setup host and contract
+    let host = observe_host!(Host::test_host_with_recording_footprint());
+    host.set_diagnostic_level(crate::DiagnosticLevel::Debug)?;
+    let id = [0u8; 32];
+    let address = host.add_host_object(ScAddress::Contract(ContractId(Hash(id))))?;
+    host.register_test_contract(address, Rc::new(NoopContractFunctionSet))?;
+
+    // Cause a panic inside the contract frame
+    let panic_str = "intentional panic for testing";
+    let result = host.try_with_test_contract_frame(
+        ContractId(Hash(id)),
+        Symbol::try_from_small_str("test").unwrap(),
+        || {
+            panic!("{panic_str}");
+        },
+    );
+    assert!(result.is_err());
+
+    // Validate that a diagnostic event was logged with the contents of the panic
+    let events = host.get_events()?.0;
+    let mut has_diagnostic_event = false;
+    for (_, event) in events.iter().enumerate() {
+        let as_str = format!("{:?}", event);
+        if as_str.contains(panic_str) {
+            has_diagnostic_event = true;
+            break;
+        }
+    }
+    assert!(has_diagnostic_event);
+
+    assert_eq!(
+        result.unwrap_err(),
+        HostError::from(Error::from_type_and_code(
+            ScErrorType::WasmVm,
+            ScErrorCode::InvalidAction
+        ))
+    );
+
     Ok(())
 }

soroban-env-host/src/test/lifecycle.rs

@@ -431,10 +431,11 @@ fn test_contract_wasm_update() {
     // Make sure execution continued after the update and we've got the function
     // return value.
     assert_eq!(res, 123);
+
     // Verify that instance storage has been updated as well.
     host.with_test_contract_frame(
         host.contract_id_from_address(contract_addr_obj).unwrap(),
-        Symbol::try_from_small_str("").unwrap(),
+        Symbol::try_from_small_str("check_foo").unwrap(),
         || {
             let stored_value: i32 = host
                 .get_contract_data(

soroban-env-host/src/testutils.rs

@@ -355,16 +355,18 @@ impl Host {
             panic!()
         };
 
-        let test = SymbolSmall::try_from_str("test").unwrap();
-
         // First step: insert all the data values in question into the storage map.
-        host.with_test_contract_frame(contract_hash.clone(), test.into(), || {
-            for (k, (t, _)) in data_keys.iter() {
-                let v = host.to_host_val(k).unwrap();
-                host.put_contract_data(v, v, *t).unwrap();
-            }
-            Ok(Val::VOID.into())
-        })
+        host.with_test_contract_frame(
+            contract_hash.clone(),
+            SymbolSmall::try_from_str("test").unwrap().into(),
+            || {
+                for (k, (t, _)) in data_keys.iter() {
+                    let v = host.to_host_val(k).unwrap();
+                    host.put_contract_data(v, v, *t).unwrap();
+                }
+                Ok(Val::VOID.into())
+            },
+        )
         .unwrap();
 
         // Second step: generate some accounts to sign things with.