feat(stack-guest-abi): a step loop, so a guest operation pauses on its HTTP requests instead of blocking

A guest export that reaches ZeroKMS blocked on the host's synchronous
transport_send import. A host whose HTTP client cannot block — fetch in a
JavaScript edge runtime — cannot satisfy that import, and in Go the client
held its lock for the whole round trip.

The new `step` module runs an operation's work as a future polled once.
A request the work makes is recorded and the future stays pending; the
operation is kept in a table under a handle and its requests are handed to
the host. The host performs them and resumes the operation with the
responses, in order, until it is done; or it aborts it, which drops the
future and wipes everything it held. Each request stores the waker it was
polled with and resuming wakes it first, so combinators that poll an inner
future only when woken (buffered, as the ZeroKMS client's 500-key chunking
uses) do not stall. Handles are issued in increasing order and never
reused, at most 64 operations may be paused, an unknown handle is
STATUS_STATE, and work that pauses with nothing to wait on is
STATUS_INTERNAL.

STATUS_NEEDS_IO (29) is how an export says it paused. It is not a failure:
call::run records no error for it. The module holds no encoding; each guest
decides how a step's requests and responses cross. Refs #1064.

Author: coderdan

Cargo.lock

@@ -36,3 +36,6 @@ vitaminc-protected = { workspace = true }
 # host holds, run natively and under Miri. `std` only: the `fork` and
 # `timeout` defaults spawn processes and threads Miri cannot interpret.
 proptest = { version = "1.7", default-features = false, features = ["std"] }
+# `step`'s tests drive the loop through the combinators the ZeroKMS client
+# runs its requests with (`buffered`, `join`).
+futures = { version = "0.3", default-features = false, features = ["std", "async-await"] }

packages/stack-guest-abi/Cargo.toml

@@ -135,6 +135,7 @@ pub fn wipe_all() {
     // The recorded last error is one of these buffers; its slot must not
     // outlive the wipe and name freed memory.
     crate::last_error::forget();
+    crate::step::forget_pending();
     let live = BUFFERS.with(|b| core::mem::take(&mut *b.borrow_mut()));
     for (ptr, len) in live {
         // SAFETY: every entry was registered by `register`, which leaked a

packages/stack-guest-abi/src/buffers.rs

@@ -16,6 +16,7 @@ use std::panic::{catch_unwind, AssertUnwindSafe};
 
 use crate::buffers;
 use crate::last_error;
+use crate::status::STATUS_NEEDS_IO;
 
 /// Run an export's body: clear the last error, run `f` (a panic is an
 /// internal failure), and then clear the last error again if `f` succeeded,
@@ -34,6 +35,11 @@ pub fn run<T>(f: impl FnOnce() -> Result<T, u32>) -> Result<T, u32> {
             last_error::clear();
             Ok(out)
         }
+        // A paused operation has not failed: nothing is recorded.
+        Err(STATUS_NEEDS_IO) => {
+            last_error::clear();
+            Err(STATUS_NEEDS_IO)
+        }
         Err(status) => {
             last_error::ensure(status);
             Err(status)
@@ -93,6 +99,18 @@ pub fn take_last_error() -> Option<Vec<u8>> {
 mod tests {
     use super::*;
     use crate::status::{STATUS_ENCODING, STATUS_INTERNAL};
+
+    /// A paused operation is not a failure: it records no error, and clears
+    /// one recorded on the way to the pause.
+    #[test]
+    fn a_pause_records_no_error() {
+        let paused = run::<()>(|| {
+            let _ = last_error::malformed("on the way");
+            Err(STATUS_NEEDS_IO)
+        });
+        assert_eq!(paused, Err(STATUS_NEEDS_IO));
+        assert!(!last_error::is_set());
+    }
     use crate::value::HostValue;
 
     /// A packed result, read the way the Go host reads it.

packages/stack-guest-abi/src/call.rs

@@ -104,6 +104,7 @@ pub mod call;
 pub mod headers;
 pub mod last_error;
 pub mod status;
+pub mod step;
 pub mod value;
 
 #[cfg(target_arch = "wasm32")]

packages/stack-guest-abi/src/lib.rs

@@ -15,8 +15,8 @@
 //! run this call against. Codes 5–10 are the outcomes of a request to
 //! ZeroKMS, so a host can distinguish a refused credential from a tampered
 //! ciphertext without parsing strings; 11 and 12 were appended by the
-//! crypto guest, 13–27 by the credential guest, and 28 by the crypto guest
-//! again.
+//! crypto guest, 13–27 by the credential guest, and 28 and 29 by the
+//! crypto guest again. 29 is not a failure: see [`STATUS_NEEDS_IO`].
 //!
 //! Each code is documented here as the *verdict* it carries to a host — the
 //! thing the host can act on. Which of a library's errors reach which code,
@@ -122,10 +122,16 @@ pub const STATUS_AUTH_REFRESH_REQUIRED: u32 = 27;
 /// and only that — never a verdict on the record's integrity.
 pub const STATUS_CONTEXT_MISMATCH: u32 = 28;
 
+/// Not a failure: the operation is paused, waiting for the host to perform
+/// HTTP requests on its behalf (the step loop, [`crate::step`]). The host
+/// takes the requests and the operation's handle from the guest, performs
+/// them, and resumes it with the responses. No error is recorded.
+pub const STATUS_NEEDS_IO: u32 = 29;
+
 /// The last code in the table. A guest appending a code of its own starts
 /// at `LAST_STATUS + 1` and moves this constant with it, so two guests can
 /// never claim one number.
-pub const LAST_STATUS: u32 = STATUS_CONTEXT_MISMATCH;
+pub const LAST_STATUS: u32 = STATUS_NEEDS_IO;
 
 #[cfg(test)]
 mod tests {
@@ -164,6 +170,7 @@ mod tests {
             STATUS_AUTH_OTHER,
             STATUS_AUTH_REFRESH_REQUIRED,
             STATUS_CONTEXT_MISMATCH,
+            STATUS_NEEDS_IO,
         ];
         for (i, code) in codes.iter().enumerate() {
             assert_eq!(*code, i as u32 + 1, "code {i} is out of sequence");