Fileserver

Defined in: packages/core/src/kernel/types.ts:200

The universal filesystem interface. Any object implementing these 10 methods is a fileserver.

Remarks

The kernel routes all I/O through fileservers via namespace resolution. A fileserver never sees process-level fd numbers — open() returns an opaque token that the kernel maps to a process fd. All data on the wire is Uint8Array.

Fileservers are composable: overlayFS layers two fileservers for copy-on-write, union bind stacks multiple fileservers at one mount point. The protocol is small enough that fundamental capabilities (overlay, readonly, proxy) are just more fileservers.

Example

// Mount a custom fileserver
const fs = memoryFS()
Unix().mount('/data', fs).use(stdSystem()).build()

Properties

type?

readonly optional type?: string

Defined in: packages/core/src/kernel/types.ts:202

Optional human-readable type tag (e.g. ‘memory’, ‘overlay’, ‘proc’).

Methods

checkAccess()?

optional checkAccess(path, flags, caller): Promise<void>

Defined in: packages/core/src/kernel/types.ts:232

Optional permission override. When present, kernel calls this INSTEAD of the default mode-bit check. Allows synthetic fileservers (procFS, devFS, etc.) to implement custom access control semantics.

Parameters

path

InnerPath

flags

OpenFlags

caller

egid

Gid

euid

Uid

Returns

Promise<void>

---

close()

close(fd): Promise<void>

Defined in: packages/core/src/kernel/types.ts:211

Close an open fd token.

Parameters

fd

unknown

Returns

Promise<void>

---

mkdir()

mkdir(path): Promise<void>

Defined in: packages/core/src/kernel/types.ts:220

Create a directory. Throws EEXIST if it already exists.

Parameters

path

InnerPath

Returns

Promise<void>

---

open()

open(path, flags, pid?): Promise<unknown>

Defined in: packages/core/src/kernel/types.ts:205

Open a file or directory, returning an opaque fd token.

Parameters

path

InnerPath

flags

OpenFlags

pid?

Pid

Returns

Promise<unknown>

---

read()

read(fd, offset, count): Promise<Uint8Array<ArrayBufferLike>>

Defined in: packages/core/src/kernel/types.ts:207

Read up to count bytes from an open fd at the given offset.

Parameters

fd

unknown

offset

number

count

number

Returns

Promise<Uint8Array<ArrayBufferLike>>

---

readdir()

readdir(path): Promise<DirEntry[]>

Defined in: packages/core/src/kernel/types.ts:217

List entries in a directory. Throws ENOTDIR if path is a file.

Parameters

path

InnerPath

Returns

Promise<DirEntry[]>

---

remove()

remove(path): Promise<void>

Defined in: packages/core/src/kernel/types.ts:222

Remove a file or empty directory.

Parameters

path

InnerPath

Returns

Promise<void>

---

rename()

rename(oldPath, newPath): Promise<void>

Defined in: packages/core/src/kernel/types.ts:224

Rename/move a file or directory.

Parameters

oldPath

InnerPath

newPath

InnerPath

Returns

Promise<void>

---

stat()

stat(path, opts?): Promise<Stat>

Defined in: packages/core/src/kernel/types.ts:215

Return metadata for a path. Throws ENOENT if not found. When opts.nofollow is true, return the symlink node itself (lstat behavior).

Parameters

path

InnerPath

opts?

nofollow?

boolean

Returns

Promise<Stat>

---

write()

write(fd, offset, data): Promise<number>

Defined in: packages/core/src/kernel/types.ts:209

Write data at the given offset, returning bytes written.

Parameters

fd

unknown

offset

number

data

Uint8Array

Returns

Promise<number>

---

wstat()

wstat(path, changes): Promise<void>

Defined in: packages/core/src/kernel/types.ts:227

Update metadata fields (mode, uid, gid, mtime, size).

Parameters

path

InnerPath

changes

Partial<StatChanges>

Returns

Promise<void>