feat: CompiledPlugin with fuel limit (#143)

This follows extism/extism#883 and Extism
1.13.0, which allows to create a CompiledPlugin with a fuel limit.
Previously, we could only create a (non-compiled) Plugin with a fuel
limit, or a CompiledPlugin without a fuel limit.

A CompiledPlugin with a fuel limit is interesting for the scenario
where:
- the host is instantiating many times the same wasm file (for example,
a Python interpreter)
- and needs a fuel limit to ensure resource usage is controlled while
running untrusted scripts

On practical example is when using Extism to implement a Python sandbox
in a .NET host, that is exposed as a tool to an LLM chatbot embedded in
the app. The LLM can generate Python code that calls host functions or
perform calculations to fulfill the user's request.

Setting a fuel limit is important for the security of the approach,
since the executed code cannot be trusted, as it is produced by the LLM.
The fuel limit ensures that resources stay in check, along with memory
limits, time-based cancellation, and the isolation properties of WASM.

Until now, we could only use the non-compiled Plugin, since this one
exposes the fuel limit. But it makes sense to use the CompiledPlugin,
since the same wasm (the Python interpreter) is used over and over
again.

Author: tlecomte

samples/Extism.Sdk.FSharpSample/Extism.Sdk.FSharpSample.fsproj

@@ -11,7 +11,7 @@
 	</ItemGroup>
 
 	<ItemGroup>
-		<PackageReference Include="Extism.runtime.win-x64" Version="1.9.1" />
+		<PackageReference Include="Extism.runtime.win-x64" Version="1.13.0" />
 		<ProjectReference Include="..\..\src\Extism.Sdk\Extism.Sdk.csproj" />
 	</ItemGroup>
 

samples/Extism.Sdk.Sample/Extism.Sdk.Sample.csproj

@@ -17,7 +17,7 @@
 	</ItemGroup>
 
 	<ItemGroup>
-		<PackageReference Include="Extism.runtime.all" Version="1.9.1" />
+		<PackageReference Include="Extism.runtime.all" Version="1.13.0" />
 	</ItemGroup>
 
 	<ItemGroup>

src/Extism.Sdk/LibExtism.cs

@@ -237,6 +237,7 @@ internal struct ExtismCurrentPlugin { }
     /// <param name="plugin">Pointer to the plugin you want to free.</param>
     [DllImport("extism")]
     unsafe internal static extern void extism_plugin_free(ExtismPlugin* plugin);
+
     /// <summary>
     /// Pre-compile an Extism plugin
     /// </summary>
@@ -250,6 +251,20 @@ internal struct ExtismCurrentPlugin { }
     [DllImport("extism")]
     unsafe internal static extern ExtismCompiledPlugin* extism_compiled_plugin_new(byte* wasm, long wasmSize, IntPtr* functions, long nFunctions, [MarshalAs(UnmanagedType.I1)] bool withWasi, out char** errmsg);
 
+    /// <summary>
+    /// Pre-compile an Extism plugin with fuel limit
+    /// </summary>
+    /// <param name="wasm">A WASM module (wat or wasm) or a JSON encoded manifest.</param>
+    /// <param name="wasmSize">The length of the `wasm` parameter.</param>
+    /// <param name="functions">Array of host function pointers.</param>
+    /// <param name="nFunctions">Number of host functions.</param>
+    /// <param name="withWasi">Enables/disables WASI.</param>
+    /// <param name="fuelLimit">Max number of instructions that can be executed by the plugin.</param>
+    /// <param name="errmsg"></param>
+    /// <returns></returns>
+    [DllImport("extism")]
+    unsafe internal static extern ExtismCompiledPlugin* extism_compiled_plugin_new_with_fuel_limit(byte* wasm, long wasmSize, IntPtr* functions, long nFunctions, [MarshalAs(UnmanagedType.I1)] bool withWasi, long fuelLimit, out char** errmsg);
+
     /// <summary>
     /// Free `ExtismCompiledPlugin`
     /// </summary>

src/Extism.Sdk/Plugin.cs

@@ -541,20 +541,30 @@ public unsafe class CompiledPlugin : IDisposable
     /// <param name="manifest"></param>
     /// <param name="functions"></param>
     /// <param name="withWasi"></param>
-    public CompiledPlugin(Manifest manifest, HostFunction[] functions, bool withWasi)
+    public CompiledPlugin(Manifest manifest, HostFunction[] functions, bool withWasi) : this(manifest, functions, new PluginIntializationOptions { WithWasi = withWasi })
+    {
+    }
+
+    /// <summary>
+    /// Compile a plugin from a Manifest.
+    /// </summary>
+    /// <param name="manifest"></param>
+    /// <param name="functions"></param>
+    /// <param name="options"></param>
+    public CompiledPlugin(Manifest manifest, HostFunction[] functions, PluginIntializationOptions options)
     {
         Functions = functions;
 
-        var options = new JsonSerializerOptions
+        var jsonOptions = new JsonSerializerOptions
         {
             DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
             PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
         };
 
-        options.Converters.Add(new WasmSourceConverter());
-        options.Converters.Add(new JsonStringEnumConverter<HttpMethod>());
+        jsonOptions.Converters.Add(new WasmSourceConverter());
+        jsonOptions.Converters.Add(new JsonStringEnumConverter<HttpMethod>());
 
-        var jsonContext = new ManifestJsonContext(options);
+        var jsonContext = new ManifestJsonContext(jsonOptions);
         var json = JsonSerializer.Serialize(manifest, jsonContext.Manifest);
 
         var bytes = Encoding.UTF8.GetBytes(json);
@@ -563,7 +573,7 @@ public CompiledPlugin(Manifest manifest, HostFunction[] functions, bool withWasi
         fixed (byte* wasmPtr = bytes)
         fixed (IntPtr* functionsPtr = functionHandles)
         {
-            NativeHandle = Initialize(wasmPtr, bytes.Length, functions, withWasi, functionsPtr);
+            NativeHandle = Initialize(wasmPtr, bytes.Length, functions, options.WithWasi, options.FuelLimit, functionsPtr);
         }
     }
 
@@ -577,11 +587,14 @@ public Plugin Instantiate()
         return new Plugin(this);
     }
 
-    private unsafe LibExtism.ExtismCompiledPlugin* Initialize(byte* wasmPtr, int wasmLength, HostFunction[] functions, bool withWasi, IntPtr* functionsPtr)
+    private unsafe LibExtism.ExtismCompiledPlugin* Initialize(byte* wasmPtr, int wasmLength, HostFunction[] functions, bool withWasi, long? fuelLimit, IntPtr* functionsPtr)
     {
         char** errorMsgPtr;
 
-        var handle = LibExtism.extism_compiled_plugin_new(wasmPtr, wasmLength, functionsPtr, functions.Length, withWasi, out errorMsgPtr);
+        LibExtism.ExtismCompiledPlugin* handle = fuelLimit.HasValue
+            ? LibExtism.extism_compiled_plugin_new_with_fuel_limit(wasmPtr, wasmLength, functionsPtr, functions.Length, withWasi, fuelLimit.Value, out errorMsgPtr)
+            : LibExtism.extism_compiled_plugin_new(wasmPtr, wasmLength, functionsPtr, functions.Length, withWasi, out errorMsgPtr);
+
         if (handle == null)
         {
             var msg = "Unable to compile plugin";

test/Extism.Sdk.Benchmarks/Extism.Sdk.Benchmarks.csproj

@@ -18,7 +18,7 @@
 	</ItemGroup>
 
 	<ItemGroup>
-		<PackageReference Include="Extism.runtime.win-x64" Version="1.9.1" />
+		<PackageReference Include="Extism.runtime.win-x64" Version="1.13.0" />
 	</ItemGroup>
 
 	<ItemGroup>

test/Extism.Sdk/CompiledPluginTests.cs

@@ -56,4 +56,19 @@ long HelloWorld(CurrentPlugin plugin, long ptr)
         }
     }
 
+    [Fact]
+    public void FuelLimit()
+    {
+        using var compiledPlugin = Helpers.CompilePlugin("loop.wasm", options: new PluginIntializationOptions
+        {
+            FuelLimit = 1000,
+            WithWasi = true
+        });
+
+        using var plugin = compiledPlugin.Instantiate();
+
+        Should.Throw<ExtismException>(() => plugin.Call("loop_forever", Array.Empty<byte>()))
+            .Message.ShouldContain("fuel");
+    }
+
 }

test/Extism.Sdk/Extism.Sdk.Tests.csproj

@@ -9,7 +9,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Extism.runtime.all" Version="1.9.1" />
+    <PackageReference Include="Extism.runtime.all" Version="1.13.0" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.13.0" />
     <PackageReference Include="Shouldly" Version="4.3.0" />
     <PackageReference Include="xunit" Version="2.9.3" />

test/Extism.Sdk/Helpers.cs

@@ -26,6 +26,12 @@ public static Plugin LoadPlugin(string name, Action<Manifest>? config = null, pa
     }
 
     public static CompiledPlugin CompilePlugin(string name, Action<Manifest>? config = null, params HostFunction[] hostFunctions)
+    {
+        var options = new PluginIntializationOptions { WithWasi = true };
+        return CompilePlugin(name, options, config, hostFunctions);
+    }
+
+    public static CompiledPlugin CompilePlugin(string name, PluginIntializationOptions options, Action<Manifest>? config = null, params HostFunction[] hostFunctions)
     {
         var binDirectory = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location)!;
         var manifest = new Manifest(new PathWasmSource(Path.Combine(binDirectory, "wasm", name), "main"));
@@ -34,6 +40,6 @@ public static CompiledPlugin CompilePlugin(string name, Action<Manifest>? config
             config(manifest);
         }
 
-        return new CompiledPlugin(manifest, hostFunctions, withWasi: true);
+        return new CompiledPlugin(manifest, hostFunctions, options);
     }
 }