Add an optional per-thread fuel budget

Thread interruption lets a host stop a running program once it decides
to act, but it cannot express "this program may run for at most N units
of work". A host that shares one machine between many untrusted programs
needs that, and today it can only get it from the execution listener,
which the compiler does not call.

Fuel is consumed inside checkInterruption, so it lands at the points the
engine already checks -- backward jumps and calls -- and needs no new
emission sites. It is per thread because interruption is per thread, so
one program per thread gets one budget per program.

Metering is off until a host calls Fuel.set, and while it is off the
cost is one static read at points that already do more work than that.

Author: philip-segerfast

compiler-tests/src/test/java/run/endive/testing/FuelTest.java

@@ -0,0 +1,90 @@
+package run.endive.testing;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import run.endive.compiler.MachineFactoryCompiler;
+import run.endive.runtime.Fuel;
+import run.endive.runtime.Instance;
+import run.endive.runtime.WasmOutOfFuelException;
+import run.endive.wabt.Wat2Wasm;
+import run.endive.wasm.Parser;
+import run.endive.wasm.WasmModule;
+
+public class FuelTest {
+
+    // A loop with no exit condition. Without a budget it never returns.
+    private static final String ENDLESS = "(module (func (export \"run\") (loop $l (br $l))))";
+
+    // A loop that runs a fixed number of times, so a generous budget must let it finish.
+    private static final String COUNTED =
+            "(module (func (export \"run\") (result i32) (local $i i32)"
+                    + " (loop $l (local.set $i (i32.add (local.get $i) (i32.const 1)))"
+                    + " (br_if $l (i32.lt_s (local.get $i) (i32.const 1000))))"
+                    + " (local.get $i)))";
+
+    @AfterEach
+    public void stopMetering() {
+        Fuel.clear();
+    }
+
+    @Test
+    public void endlessLoopRunsOutOfFuel() {
+        var run = compiled(ENDLESS).export("run");
+
+        Fuel.set(10_000);
+        assertThrows(WasmOutOfFuelException.class, run::apply);
+        assertEquals(0, Fuel.remaining());
+    }
+
+    @Test
+    public void aBudgetedProgramStillFinishes() {
+        var run = compiled(COUNTED).export("run");
+
+        Fuel.set(10_000);
+        assertEquals(1000, run.apply()[0]);
+        assertTrue(Fuel.remaining() > 0);
+    }
+
+    @Test
+    public void withoutABudgetNothingIsMetered() {
+        var run = compiled(COUNTED).export("run");
+
+        assertEquals(Fuel.UNLIMITED, Fuel.remaining());
+        assertEquals(1000, run.apply()[0]);
+        assertEquals(Fuel.UNLIMITED, Fuel.remaining());
+    }
+
+    @Test
+    public void aBudgetAppliesOnlyToTheThreadThatSetIt() throws Exception {
+        var run = compiled(COUNTED).export("run");
+        Fuel.set(10);
+
+        var other = new Thread(() -> assertEquals(Fuel.UNLIMITED, Fuel.remaining()));
+        other.start();
+        other.join();
+
+        assertThrows(WasmOutOfFuelException.class, run::apply);
+    }
+
+    @Test
+    public void theInterpreterIsMeteredToo() {
+        // Fuel is not a compiler-only feature: an API that silently did nothing on the
+        // interpreter would be its own trap.
+        WasmModule module = Parser.parse(Wat2Wasm.parse(ENDLESS));
+        var run = Instance.builder(module).build().export("run");
+
+        Fuel.set(10_000);
+        assertThrows(WasmOutOfFuelException.class, run::apply);
+    }
+
+    private static Instance compiled(String wat) {
+        WasmModule module = Parser.parse(Wat2Wasm.parse(wat));
+        return Instance.builder(module)
+                .withMachineFactory(MachineFactoryCompiler.compile(module))
+                .build();
+    }
+}

compiler/src/main/java/run/endive/compiler/internal/Shaded.java

@@ -6,6 +6,7 @@
 import java.util.Arrays;
 import run.endive.runtime.CallResult;
 import run.endive.runtime.ConstantEvaluators;
+import run.endive.runtime.Fuel;
 import run.endive.runtime.Instance;
 import run.endive.runtime.MemCopyWorkaround;
 import run.endive.runtime.Memory;
@@ -483,6 +484,7 @@ public static void checkInterruption() {
         if (Thread.currentThread().isInterrupted()) {
             throw new WasmInterruptedException("Thread interrupted");
         }
+        Fuel.consume();
     }
 
     public static long readGlobal(int index, Instance instance) {

docs/docs/advanced/cpu-limits.md

@@ -11,7 +11,7 @@ Wasm modules can contain infinite loops. When running untrusted code, always set
 
 Often, when running untrusted user code in our infrastructure, we want to have strong guarantees around the termination of the program.
 
-To achieve this result there are, currently, two mechanisms in Endive:
+To achieve this result there are, currently, three mechanisms in Endive:
 
 ## Interrupts
 
@@ -83,6 +83,35 @@ var instance =
             System.out.println("current instruction: " + instruction + ", stack size: " + stack.size())).build();
 ```
 
+## Fuel
+
+Interrupts let you stop a program once you decide to act, but they cannot express "this program may run for at most so much work". Fuel can: you give the current thread a budget of work, and execution stops with a `WasmOutOfFuelException` once it is spent.
+
+A budget is spent by doing work rather than by time passing, so it does not move with how busy the machine is: the same module given the same fuel gets the same distance every time.
+
+```java
+import run.endive.runtime.Fuel;
+import run.endive.runtime.WasmOutOfFuelException;
+
+Fuel.set(1_000_000);
+try {
+    function.apply();
+} catch (WasmOutOfFuelException e) {
+    // the module outstayed its budget
+} finally {
+    Fuel.clear();
+}
+```
+
+Fuel is consumed wherever the engine already checks for interruption — backward jumps and calls — so it is not per-instruction accounting. It is enough to bound a loop that would otherwise never end, and unlike the execution listener it keeps working when the module is run through the compiler.
+
+The budget belongs to the thread that set it, because interruption does too, so running one module per thread gives you one budget per module with no further bookkeeping.
+
+Fuel bounds work, not memory. It will stop a module that computes forever; it will not stop one that allocates heavily, which is a separate problem with separate mechanisms.
+
+Modules that never use fuel are unaffected. Metering is off until some thread calls `Fuel.set`, and while it is off the check reads one static field, on a path that already does more work than that.
+
+
 <!--
 ```java
 docs.FileOps.writeResult("docs/advanced", "cpu-limits.md.result", "empty");

runtime/src/main/java/run/endive/runtime/Fuel.java

@@ -0,0 +1,88 @@
+package run.endive.runtime;
+
+/**
+ * An optional per-thread execution budget.
+ *
+ * <p>A host that runs untrusted Wasm needs to stop a program that never finishes. Thread
+ * interruption already does that when the host decides to act, but it cannot express "this program
+ * may run for at most N units of work", which is what a scheduler sharing one machine between many
+ * programs needs.
+ *
+ * <p>Fuel is consumed wherever the engine already checks for interruption: backward jumps and
+ * calls. That is not per-instruction accounting, and it is not meant to be — it is enough to bound
+ * a loop that would otherwise never end, and it costs nothing at the points in between.
+ *
+ * <p>Fuel bounds work, not memory. It will stop a module that computes forever; it will not stop
+ * one that allocates heavily.
+ *
+ * <p>Fuel is per thread because interruption is per thread, so a host that runs one program per
+ * thread gets one budget per program with no further bookkeeping:
+ *
+ * <pre>{@code
+ * Fuel.set(1_000_000);
+ * try {
+ *     instance.export("_start").apply();
+ * } catch (WasmOutOfFuelException e) {
+ *     // the program outstayed its budget
+ * } finally {
+ *     Fuel.clear();
+ * }
+ * }</pre>
+ *
+ * <p>Metering is off unless a host turns it on, and while it is off the only cost is one static
+ * read at points that already do more work than that.
+ */
+public final class Fuel {
+
+    /** The value {@link #remaining()} reports when this thread is not metered. */
+    public static final long UNLIMITED = -1;
+
+    /**
+     * False until some thread first sets a budget. Kept as a fast path so hosts that never meter
+     * do not pay for a thread-local lookup on every backward jump.
+     */
+    private static volatile boolean enabled;
+
+    private static final ThreadLocal<long[]> REMAINING =
+            ThreadLocal.withInitial(() -> new long[] {UNLIMITED});
+
+    private Fuel() {}
+
+    /**
+     * Consumes one unit on the current thread, throwing {@link WasmOutOfFuelException} once the
+     * budget is exhausted. Called by the engine; hosts do not need to call it.
+     */
+    public static void consume() {
+        if (!enabled) {
+            return;
+        }
+        long[] cell = REMAINING.get();
+        long remaining = cell[0];
+        if (remaining == UNLIMITED) {
+            return;
+        }
+        if (remaining == 0) {
+            throw new WasmOutOfFuelException("Out of fuel");
+        }
+        cell[0] = remaining - 1;
+    }
+
+    /** Gives the current thread a budget of {@code units}, replacing any budget it already had. */
+    public static void set(long units) {
+        if (units < 0) {
+            throw new IllegalArgumentException("Fuel budget must not be negative");
+        }
+        enabled = true;
+        REMAINING.get()[0] = units;
+    }
+
+    /** Stops metering the current thread. */
+    public static void clear() {
+        REMAINING.get()[0] = UNLIMITED;
+    }
+
+    /** What is left on the current thread, or {@link #UNLIMITED} when it is not metered. */
+    public static long remaining() {
+        return REMAINING.get()[0];
+    }
+}

runtime/src/main/java/run/endive/runtime/InterpreterMachine.java

@@ -3412,6 +3412,7 @@ private static void checkInterruption() {
         if (Thread.currentThread().isInterrupted()) {
             throw new WasmInterruptedException("Thread interrupted");
         }
+        Fuel.consume();
     }
 
     // ===== GC opcode implementations =====

runtime/src/main/java/run/endive/runtime/WasmOutOfFuelException.java

@@ -0,0 +1,18 @@
+package run.endive.runtime;
+
+import run.endive.wasm.WasmEngineException;
+
+/** Thrown when a running Wasm execution exhausts the fuel budget set by the host. */
+public class WasmOutOfFuelException extends WasmEngineException {
+    public WasmOutOfFuelException(String msg) {
+        super(msg);
+    }
+
+    public WasmOutOfFuelException(Throwable cause) {
+        super(cause);
+    }
+
+    public WasmOutOfFuelException(String msg, Throwable cause) {
+        super(msg, cause);
+    }
+}