danos/docs/vfs-protocol.md

# The VFS wire protocol

> **Status:** built and spoken today between `runtime.fs` (the client) and the
> filesystem BACKENDS (the FAT server). The mount router lives in the
> **kernel** (`system/kernel/vfs.zig`): `fs_resolve` routes a path and either
> serves it directly (the read-only /system initrd mount, via `fs_node`) or
> redirects the caller to the owning backend's endpoint plus the rewritten
> mount-relative path — after which the client speaks THIS protocol to the
> backend, unchanged. The Zig source of truth is `system/vfs-protocol.zig`
> (the `vfs-protocol` module), whose unit tests pin the sizes and values
> below. This page is the **language-neutral wire specification** of that
> contract — what a Rust or C client implements ([vdso.md](vdso.md) explains
> why the IPC protocols, not the syscall numbers, are danos's public ABI).

## Transport

A VFS exchange is one synchronous IPC rendezvous (`ipc_call`,
docs/ipc.md): the client sends one message and blocks; the server replies
with one message. The endpoint comes from the kernel's `fs_resolve` — which
also hands back the path rewritten relative to the mount — not from a
registry lookup. (Service id 1, the old userspace router, is retired.)

- A message is at most **256 bytes** (`message_maximum`).
- A request is a fixed 32-byte **Request** header followed by an inline
  payload of at most **224 bytes** (`maximum_payload`) — a path, or write
  bytes. There is no multi-message request: paths and single reads/writes
  must fit, and larger transfers loop (see *read* / *write*).
- A reply is a fixed 24-byte **Reply** header followed by an inline payload —
  read bytes, a `FileStatus`, or a `DirectoryEntry`.
- All integers are **little-endian**; layouts are C layout for x86-64
  (`extern struct`), offsets given below so nothing need be inferred.

The kernel resolves NAMES (the mount table) but never parses these
messages — it moves the bytes; file state is entirely the backend's affair.
With clients holding backend node ids directly, a backend records each open
handle's owner and sweeps a dead client's handles via the published process
exit events.

## Request header — 32 bytes

| offset | size | field | meaning |
|-------:|-----:|-------|---------|
| 0 | 4 | `operation` | an **Operation** value (below) |
| 4 | 4 | — | padding |
| 8 | 8 | `node` | the server-side open-node id from a prior `open`; 0 for path-based operations |
| 16 | 8 | `offset` | byte position for read/write; entry index (cursor) for readdir; else 0 |
| 24 | 4 | `len` | payload length for path/write operations; requested byte count for read |
| 28 | 4 | `flags` | open flags (below); else 0 |

## Reply header — 24 bytes

| offset | size | field | meaning |
|-------:|-----:|-------|---------|
| 0 | 4 | `status` | **0 = success**, negative = failure (signed) |
| 4 | 4 | — | padding |
| 8 | 8 | `node` | the new open-node id (for `open`); else 0 |
| 16 | 4 | `len` | reply payload length in bytes |
| 20 | 4 | — | padding |

On failure the router replies `status = -1`; a mounted backend's negative
status is forwarded to the client verbatim. A richer errno vocabulary is
future work — clients must treat *any* negative status as failure, not match
on -1.

## Operations

Values are append-only and never renumbered (the same evolution rule every
danos protocol follows); an unrecognised operation gets a `status = -1`
reply.

| value | operation | request payload | reply |
|------:|-----------|-----------------|-------|
| 0 | `open` | the path (`len` = its length), `flags` as below | `node` = open-node id |
| 1 | `close` | — (`node` set) | status only |
| 2 | `read` | — (`node`, `offset`, `len` = wanted count) | `len` bytes read, payload = the bytes; `len` 0 at end of file |
| 3 | `write` | the bytes (`node`, `offset`, `len` = count) | `len` = bytes accepted (may be short — loop) |
| 4 | `status` | — (`node` set) | payload = **FileStatus** (24 bytes) |
| 5 | `readdir` | — (`node` = a directory, `offset` = cursor) | payload = one **DirectoryEntry** + name; `len` 0 at end |
| 6 | `mount` | the mount-point path; the backend endpoint rides as the call's **capability** | status only |
| 7 | `unmount` | the mount-point path | status only |
| 8 | `mkdir` | the path | status only |
| 9 | `unlink` | the path | status only |
| 10 | `rename` | old path, one `0x00`, new path (`len` = total) | status only |

Notes per operation:

- **open** — paths are absolute (`/mnt/usb/notes.txt`) or bare names
  (`greeting`); bare names resolve in the VFS's flat ramfs, absolute paths
  route through the mount table (below). The returned `node` is an id in the
  *router's* open table; clients never see a backend's own ids.
- **read / write** — a single exchange moves at most 224 bytes
  (`maximum_payload`); the client loops, advancing `offset` by the returned
  `len`, until done (read) or the slice is written (write). A `write` reply
  shorter than requested is progress, not an error; a `len` of 0 means no
  forward progress — stop rather than spin.
- **readdir** — `offset` is a **cursor: the entry index**, not a byte
  position. Each call returns exactly one entry; the client increments the
  cursor by 1. A reply with `len` 0 is end-of-directory. The directory must
  have been opened with the `directory` flag.
- **mount / unmount** — RETIRED from the wire: mounting is the `fs_mount`
  syscall now (a filesystem server passes its endpoint handle; possession is
  the capability, exactly the trust of the old cap-passing op). The op
  numbers stay reserved. Mount-prefix semantics are unchanged: prefixes
  match at path boundaries only (`/mnt/usb` never captures `/mnt/usbextra`),
  the longest matching prefix wins, and an optional backend-side rewrite
  prefix maps a mount into the backend's namespace (fat serves `/mnt/usb`
  from its volume root and `/var` from its `/var` subtree).
- **rename** — same-directory rename only (the router requires old and new to
  resolve under one mount).

## Open flags

Bitwise OR in `Request.flags`, meaningful for `open` only:

| bit | name | meaning |
|----:|------|---------|
| 1 | `create` | create the file if it does not exist |
| 2 | `directory` | open a directory node for `readdir` rather than a file |
| 4 | `truncate` | truncate an existing file to zero length on open (replace, don't overwrite in place) |

## FileStatus — 24 bytes (the `status` reply payload)

| offset | size | field | meaning |
|-------:|-----:|-------|---------|
| 0 | 8 | `size` | file size in bytes |
| 8 | 4 | `kind` | a **NodeKind** value |
| 12 | 4 | — | padding |
| 16 | 8 | `mtime` | modification time, Unix epoch seconds UTC; 0 if the backend keeps none |

## DirectoryEntry — 16 bytes + name (the `readdir` reply payload)

| offset | size | field | meaning |
|-------:|-----:|-------|---------|
| 0 | 4 | `kind` | a **NodeKind** value |
| 4 | 4 | `name_len` | length of the name that follows |
| 8 | 8 | `size` | the entry's size in bytes |
| 16 | `name_len` | name | the entry's name, not NUL-terminated |

## NodeKind

Aligned to the FSH file-type table
(docs/danos-file-system-hierarchy-FSH.md):

| value | kind |
|------:|------|
| 0 | regular file |
| 1 | directory |
| 2 | character device |
| 3 | block device |
| 4 | symbolic link |
| 5 | fifo |
| 6 | socket |

Clients should map unknown values to *regular* rather than reject — the
table can grow.

## Lifetimes and trust

Open-node ids live in the server. A client that dies without closing leaks
nothing permanently: the VFS subscribes to the kernel's published process-exit
events (docs/process-lifecycle.md) and releases a dead client's handles,
closing forwarded backend nodes best-effort. Ids are plain integers, not
capabilities — the VFS trusts its callers with each other's ids today, which
is acceptable while every client is part of the system image and worth
revisiting (per-client id namespaces) before third-party binaries arrive.

## Evolution rules

What a non-Zig implementation may rely on, and what it must not:

- Operation values, flag bits, `NodeKind` values, and struct layouts are
  **append-only and frozen once shipped** — the unit tests in `protocol.zig`
  pin them exactly so a refactor can't silently move them.
- The 256-byte message ceiling is a property of the current IPC transport,
  not a promise; clients should read `maximum_payload`-shaped limits from the
  reply lengths they actually get (loop-until-done), not hard-code 224.
- Negative statuses beyond -1 will appear (an errno vocabulary); success is
  exactly 0.