Struct VirtualOverlayBackend 

pub struct VirtualOverlayBackend { /* private fields */ }

Backend that overlays virtual paths (/v/*) on top of a custom backend.

This enables embedders to provide their own storage backend while still getting kaish’s virtual filesystem features like /v/jobs for job observability.

Implementations

impl VirtualOverlayBackend

pub fn new(inner: Arc<dyn KernelBackend>, vfs: Arc<VfsRouter>) -> Self

Create a new virtual overlay backend.

Arguments

• inner - The custom backend to delegate non-virtual paths to
• vfs - VFS router containing virtual filesystem mounts (typically at /v/*)

Example

let overlay = VirtualOverlayBackend::new(my_backend, vfs);

pub fn inner(&self) -> &Arc<dyn KernelBackend>

Get the inner backend.

pub fn vfs(&self) -> &Arc<VfsRouter>

Get the VFS router.

Trait Implementations

impl Debug for VirtualOverlayBackend

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl KernelBackend for VirtualOverlayBackend

fn canonicalize<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, allow_missing_final: bool, ) -> Pin<Box<dyn Future<Output = BackendResult<PathBuf>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

The same three-way split every other operation here uses: a kaish-owned virtual path canonicalizes through self.vfs; a shared ancestor (/v, /, …) is a directory this backend synthesizes, never a symlink, so it canonicalizes to itself; everything else canonicalizes through the embedder’s own backend.

Delegating rather than inheriting the trait default matters here specifically: the default’s per-hop walk calls lstat/read_link on this type for every component, re-running is_virtual_path / is_shared_ancestor at each hop instead of asking the owning side once for the whole path. A symlink that lives entirely under the embedder’s backend must resolve — and be contained — through that one backend’s own resolver, not be re-routed through this split hop by hop.

fn path_access<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = BackendResult<PathAccess>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Routes the same way stat does, so the answer comes from the layer that owns the path. The trait default would use read_only() above, which is the AND of both layers and belongs to neither path.

fn read<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, range: Option<ReadRange>, ) -> Pin<Box<dyn Future<Output = BackendResult<Vec<u8>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read file contents, optionally with a range specification.

fn write<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, path: &'life1 Path, content: &'life2 [u8], mode: WriteMode, ) -> Pin<Box<dyn Future<Output = BackendResult<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Write content to a file with the specified mode.

fn set_mtime<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, mtime: SystemTime, ) -> Pin<Box<dyn Future<Output = BackendResult<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Set the modification time of an existing path.

fn append<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, path: &'life1 Path, content: &'life2 [u8], ) -> Pin<Box<dyn Future<Output = BackendResult<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Append content to a file.

fn patch<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, path: &'life1 Path, ops: &'life2 [PatchOp], ) -> Pin<Box<dyn Future<Output = BackendResult<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Apply a sequence of patch operations to a file.

fn list<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = BackendResult<Vec<DirEntry>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

List a directory’s entries.

fn stat<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = BackendResult<DirEntry>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Stat a path (following symlinks).

fn mkdir<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = BackendResult<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Create a directory.

fn remove<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, recursive: bool, ) -> Pin<Box<dyn Future<Output = BackendResult<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Remove a file, directory, or symlink; recursive descends into a directory. The final component is never followed: a symlink is unlinked and its target kept, and a link to a directory is not descended into.

fn rename<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, from: &'life1 Path, to: &'life2 Path, ) -> Pin<Box<dyn Future<Output = BackendResult<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Rename/move a path. Neither side follows a final symlink: a symlink source moves as a link, and a symlink at the destination is replaced, never written through.

fn exists<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Whether a path exists, following symlinks: a dangling link does not exist, and an error reads as false. Use lstat to ask whether a link is present.

fn lstat<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = BackendResult<DirEntry>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Stat a path without following symlinks.

fn read_link<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = BackendResult<PathBuf>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read a symlink’s target as stored, without resolving it.

fn symlink<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, target: &'life1 Path, link: &'life2 Path, ) -> Pin<Box<dyn Future<Output = BackendResult<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Create a symlink at link pointing to target. The target is stored verbatim; a relative target resolves from the link’s directory. An absolute target is rewritten relative to the link when both are on one mount, and refused when they are not.

fn call_tool<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, name: &'life1 str, args: ToolArgs, ctx: &'life2 mut dyn ToolCtx, ) -> Pin<Box<dyn Future<Output = BackendResult<ToolResult>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Call a tool by name with the given arguments and execution context.

fn list_tools<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = BackendResult<Vec<ToolInfo>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List available external tools.

fn get_tool<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, ) -> Pin<Box<dyn Future<Output = BackendResult<Option<ToolInfo>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get information about a specific tool.

fn read_only(&self) -> bool

Returns true if this backend is read-only.

fn backend_type(&self) -> &str

Returns the backend type identifier (e.g. “local”, “kaijutsu”).

fn mounts(&self) -> Vec<MountInfo>

List all mount points.

fn resolve_real_path(&self, path: &Path) -> Option<PathBuf>

Resolve a VFS path to a real filesystem path.