Class WasiContext

java.lang.Object
ai.tegmentum.wasmtime4j.panama.wasi.WasiContext
All Implemented Interfaces:
AutoCloseable
public final class WasiContext extends Object implements AutoCloseable
Panama FFI implementation of WASI context management.

This class provides comprehensive WASI (WebAssembly System Interface) context management for Panama FFI-based WebAssembly execution. It includes:

  • Configurable permission system with fine-grained controls
  • Security validation and path traversal protection
  • Resource limiting and quota enforcement
  • Thread-safe context management
  • Comprehensive error mapping for system operation failures

Security is the highest priority - all file system operations are validated against sandbox permissions and checked for path traversal attacks before execution.

This implementation uses Panama Foreign Function Interface for native interop and integrates with the ArenaResourceManager for proper memory management.

Since:
1.0.0

  • Method Details

    • getNativeHandle

      public MemorySegment getNativeHandle()
      Gets the native handle for this WASI context.
      Returns:
      the native handle
      Throws:
      IllegalStateException - if the context is closed

    • getEnvironmentVariable

      public String getEnvironmentVariable(String name)
      Gets an environment variable value.
      Parameters:
      name - the environment variable name
      Returns:
      the environment variable value, or null if not set
      Throws:
      IllegalArgumentException - if name is null or empty
      IllegalStateException - if the context is closed

    • getEnvironment

      public Map<String,String> getEnvironment()
      Gets all environment variables.
      Returns:
      a copy of all environment variables
      Throws:
      IllegalStateException - if the context is closed

    • getArguments

      public String[] getArguments()
      Gets the command-line arguments.
      Returns:
      a copy of the command-line arguments
      Throws:
      IllegalStateException - if the context is closed

    • getPreopenedDirectories

      public Map<String,Path> getPreopenedDirectories()
      Gets all pre-opened directories.
      Returns:
      a copy of all pre-opened directories
      Throws:
      IllegalStateException - if the context is closed

    • getWorkingDirectory

      public Path getWorkingDirectory()
      Gets the working directory.
      Returns:
      the working directory
      Throws:
      IllegalStateException - if the context is closed

    • validatePath

      public Path validatePath(String path)
      Validates that a file path is accessible within the sandbox.

      Security validation checks for path traversal attacks. Filesystem sandboxing is enforced by the Wasmtime native runtime through pre-opened directory configuration.

      Parameters:
      path - the file path to validate
      Returns:
      the resolved and validated path
      Throws:
      IllegalArgumentException - if path is null or empty
      IllegalStateException - if the context is closed

    • isClosed

      public boolean isClosed()
      Checks if this WASI context has been closed.
      Returns:
      true if closed, false otherwise

    • close

      public void close()
      Closes this WASI context and releases all associated resources.

      This method is idempotent and thread-safe. After calling this method, all other methods will throw IllegalStateException.

      Specified by:
      close in interface AutoCloseable

    • builder

      public static WasiContextBuilder builder()
      Creates a new WASI context builder.
      Returns:
      a new WASI context builder

    • toString

      public String toString()
      Overrides:
      toString in class Object