@nogoo9/mcp-server-cloud-fs / VirtualFS
Class: VirtualFS
Defined in: vfs.ts:117
FUSE-inspired write-back overlay filesystem.
Provides a coherent filesystem view by overlaying an in-memory inode table, directory index, and tombstone set on top of the backing StorageProvider. All MCP tool handlers use this as their single access point.
Example
const vfs = new VirtualFS(provider, cacheStore);
await vfs.hydrate();
await vfs.put(root, "hello.txt", Buffer.from("world"));
const content = await vfs.get(root, "hello.txt");Constructors
Constructor
new VirtualFS(
provider,cache):VirtualFS
Defined in: vfs.ts:127
Parameters
provider
cache
Returns
VirtualFS
Methods
copy()
copy(
srcRoot,srcKey,dstRoot,dstKey):Promise<void>
Defined in: vfs.ts:423
Copy an object. Same-bucket uses server-side copy; cross-bucket uses get+put. Destination inode and dirIndex are updated immediately.
Parameters
srcRoot
srcKey
string
dstRoot
dstKey
string
Returns
Promise<void>
createPrefix()
createPrefix(
root,prefix):Promise<void>
Defined in: vfs.ts:457
Create a directory prefix placeholder in the provider and register it in the VFS.
Parameters
root
prefix
string
Returns
Promise<void>
flush()
flush():
Promise<void>
Defined in: vfs.ts:470
Flush all dirty cache entries to the provider. Called on graceful shutdown.
Returns
Promise<void>
get()
get(
root,key,range?):Promise<Buffer<ArrayBufferLike>>
Defined in: vfs.ts:185
Read file content. Cache-first, then provider fallback. Throws if the object is tombstoned and not in cache.
Parameters
root
key
string
range?
endByte?
number
startByte
number
Returns
Promise<Buffer<ArrayBufferLike>>
hydrate()
hydrate():
Promise<void>
Defined in: vfs.ts:138
Load persisted VFS metadata from the CacheStore. Call once after construction. Safe to call on a cold start (keys simply won't exist).
Returns
Promise<void>
list()
list(
root,prefix,delimiter?):Promise<ListResult>
Defined in: vfs.ts:253
List objects under a prefix. Merges the provider's listing with the VFS directory index overlay (pending writes) and removes tombstoned entries.
Parameters
root
prefix
string
delimiter?
string
Returns
Promise<ListResult>
put()
put(
root,key,buffer,contentType?):Promise<void>
Defined in: vfs.ts:370
Write content into the VFS. Immediately visible to stat, list, and get. Content is flushed to the provider asynchronously via the CacheStore debounce.
Parameters
root
key
string
buffer
Buffer
contentType?
string
Returns
Promise<void>
remove()
remove(
root,key):Promise<void>
Defined in: vfs.ts:406
Remove an object. Deletes from provider, tombstones in VFS. Immediately invisible to stat, list, and get.
Parameters
root
key
string
Returns
Promise<void>
stat()
stat(
root,key):Promise<VfsStat>
Defined in: vfs.ts:222
Return stat (metadata) for an object. Resolution order: inode overlay → cache content size → provider headObject.
Parameters
root
key
string
Returns
Promise<VfsStat>