mssbkit/wit/vfs.wit

package decomp-toolkit:vfs@0.1.0-draft;

use wasi:logging/logging@0.1.0-draft;

// Types shared by both sides
interface types {
  variant vfs-error {
    not-found,
    not-a-directory,
    is-a-directory,
    other(string),
  }

  enum vfs-file-type {
    file,
    directory,
  }

  record vfs-metadata {
    file-type: vfs-file-type,
    size: u64,
    // Timestamp in seconds relative to the Unix epoch
    modified: option<s64>,
  }
}

// Imported host VFS API
interface host-vfs {
  use types.{vfs-metadata};

  // File resource implemented by the host.
  resource host-file {
    // Read *up to* the specified `size` at `offset`.
    // An empty list indicates EOF. Continue reading until
    // you get enough data or reach the end of the file.
    read: func(offset: u64, size: u32) -> result<list<u8>, string>;

    // Get file metadata.
    metadata: func() -> result<vfs-metadata, string>;
  }
}

// Exported guest VFS API
interface guest-vfs {
  use logging.{level};
  use types.{vfs-error, vfs-metadata, vfs-file-type};
  use host-vfs.{host-file};

  // VFS resource implemented by the guest.
  resource vfs {
    // Open a file at the specified path. If the path is a directory,
    // returns vfs-error.is-a-directory.
    open: func(path: string) -> result<file, vfs-error>;

    // Check if a file or directory exists at the specified path.
    exists: func(path: string) -> result<bool, vfs-error>;

    // Read the contents of a directory. If the path is a file,
    // returns vfs-error.not-a-directory.
    read-dir: func(path: string) -> result<list<string>, vfs-error>;

    // Get metadata for a file or directory.
    metadata: func(path: string) -> result<vfs-metadata, vfs-error>;
  }

  // File resource implemented by the guest.
  resource file {
    // Read *up to* the specified `size` at `offset`.
    // An empty list indicates EOF. Continue reading until
    // you get enough data or reach the end of the file.
    read: func(offset: u64, size: u32) -> result<list<u8>, string>;

    // Get file metadata.
    metadata: func() -> result<vfs-metadata, string>;
  }

  // Initialize the component with a logging level.
  init: func(level: level);

  // Checks whether this VFS component should handle this path. 
  // For a VFS path `foo/bar:custom`, the `base-path` is `foo/bar`
  // and the `segment` is `custom`.
  detect: func(base-path: string, segment: string) -> bool;

  // Open a file or directory. For a VFS path `foo/bar:custom`,
  // the `base-path` is `foo/bar` and the `segment` is `custom`.
  open: func(base-path: string, segment: string, file: host-file) -> result<open-result, vfs-error>;

  // The result of opening a file or directory.
  variant open-result {
    none,
    file(file),
    directory(vfs),
  }
}

// The world wires directions: host provides host-vfs; guest provides guest-vfs
world api {
  import logging;
  import host-vfs;
  export guest-vfs;
}