The dotfs protocol for 9P 2026-11-19 · doc Nov 19, 2026 · Jeff Lindsay, h.d.a. ## Summary The dotfs protocol (9p-dotfs in full) is four small, independent extensions a 9P server can expose as synthetic files under `.fs/`. A server implements only the ones it needs, and a client discovers each one by whether its file exists. | Extension | File | What it gives a client | Useful alone for | | --- | --- | --- | --- | | Index | `.fs/index` | the whole tree's metadata in one read | caching metadata of read-only trees, the `.h9index` use case | | Events | `.fs/events` | a stream of changes after a sequence number | inotify-style watching of any mutable server | | Path operations | `.fs/ctl` | `mv`, `rm`, `mkdir`, `cp`, and flag changes by path, optionally conditional on a version | quick operations without walk, open, and clunk sequences, and cross-directory rename on plain 9P2000 | | Staged commit | `.fs/stage/` plus `commit` on ctl | resumable uploads published atomically if a path is still at an expected version | conflict-safe writes | Together, index, events, path operations, and staged commit are enough to build a Dropbox-style synced folder, with one server ordering every change (the sync profile below), but nothing in the first three depends on sync. The protocol works over any 9P transport. 9P2000.L over a WebSocket is the expected transport for browser clients, with authentication on the HTTP upgrade. This document is separate from hyper9's mount-index proposal and does not change it. ## Conventions These rules apply to every extension. **Location and scope** - `.fs/` lives at the top of an attach root. A directory may carry its own `.fs/` (see nested indexes); everything in that `.fs/` is scoped to that directory's subtree. - `.fs/` is synthetic. It is never listed in its own index, never reported in events, and cannot be removed or renamed. - A server that implements none of the extensions has no `.fs/`. Clients must treat `Enotfound` on any `.fs/` file as "not supported" and fall back to plain 9P. **Discovery** A client walks to `.fs/` and reads the directory. Each extension is present if and only if its file is: `index`, `events`, `ctl`, `stage/`. `ctl` additionally answers `caps` with the commands it accepts, so a server can offer path operations without staged commit. **Paths** - Paths are absolute from the scope root and use `/`. The scope root itself is `/`. - In every line format, bytes outside printable ASCII, space, `%`, and the newline are percent-escaped (`%20`). Every valid name can be listed, so there is no `!unindexed`. **Versions and sequence numbers** - A scope with events or staged commit has a **seq**: an unsigned 64-bit counter that increases by one on every change in the scope. - A path's **version** is the seq of its last change; `0` means the path does not exist. - A server with an index but no events (a read-only tree) may report version `0` for every path and a fixed seq. - 9P qid.vers carries the low 32 bits of the version. **Line formats** Index lines, event records, and ctl commands are UTF-8 text, one record per line, fields separated by single spaces, unknown trailing fields ignored. A `-` stands for an empty field. Optional `key=value` fields may follow the positional ones. **ctl exchange** A client writes one command per `Twrite` to an open `ctl` fid, then reads the reply from the same fid before writing again. Replies start with `ok` or with an error word (`conflict`, `missing`, `denied`, `invalid`). Different fids are independent, so a client opens one ctl fid per concurrent operation. **Errors** Normal 9P errors (`Rerror` or `Rlerror`) report transport and permission failures. Protocol outcomes that a client acts on, such as a version conflict, are reply words on ctl rather than 9P errors. ## Extension 1: index `.fs/index` is a read-only snapshot of every path in the scope at one seq, so a client can answer walks, stats, and directory reads without asking the server. **Format** ``` fsindex 1 seq [] [] [key=value...] ... ``` ``` fsindex 1 seq 48211 / d 0755 0 1763491200 48000 - - /.config d 0755 0 1763491100 47950 - p /.config/git/config f 0644 212 1763400000 31002 b3:5e1a… p /Documents/Tax%202025.pdf f 0644 284113 1763480011 46990 b3:9f2c… - /Photos d 0755 0 1763491000 48100 - i /bin l 0777 7 1763000000 120 - - usr/bin ``` | Field | Meaning | | --- | --- | | path | escaped path from the scope root; lines sorted by path in byte order | | type | `d` directory, `f` file, `l` symlink | | mode | permission bits, octal | | length | bytes; 0 for directories, target length for symlinks | | mtime | seconds since the epoch | | version | see Conventions; `0` allowed for read-only trees | | hash | `:` content hash for files (`b3` is BLAKE3-256), or `-` | | flags | `-`, or a set of letters: `p` prefetch, `i` nested index | | target | symlink target, escaped, only for type `l` | **Reading** - The header line is always plain text. Before reading, a client may write `accept [...]` to the index fid; the server then may name one of them as the header's last word and send the rest of the file in that encoding. `zstd` (one frame) is the only encoding defined. With no `accept`, the body is plain, so `cat .fs/index` works. - The snapshot is consistent at seq N: every line reflects the scope after change N and before change N+1. - qid.vers of `.fs/index` is the low 32 bits of N, and its qid.path is stable, so a client can tell from `Tstat` whether a cached copy is current. - Length in `Tstat` may be 0 when the server generates the file on open. **Nested indexes (flag `i`)** A directory flagged `i` has its own `.fs/` with its own index (and, if the server supports them, its own events and ctl). The parent's index lists the directory itself but none of its children, and versions inside are scoped to it. Use it for very large or busy subtrees, or for a different server mounted under a path. A client reads a nested index the first time it needs anything inside. **Prefetch (flag `p`)** A hint that a client keeping a local copy should fetch the file's content right after reading the index. On a directory it covers everything below. It is advisory and shared by all clients; per-device pinning is a client matter. **Read-only servers** A server with only an index (like a package cache) may use version `0`, a fixed seq, and `-` for hashes and flags. That is exactly the role `/.h9index` plays today. ## Extension 2: events `.fs/events` streams change records for the scope, so a client can watch a tree like inotify without polling, with or without an index. **Opening a stream** Each open fid is its own stream. Before the first read a client may write any of: | Write | Effect | | --- | --- | | `since ` | start with the first change after seq N | | `path ` | only report changes at or below `` (repeatable) | | `coalesce` | allow the server to merge consecutive changes to one path into the latest | Without `since`, the first record is `seq ` and only later changes follow. **Reading** Each `Tread` returns one or more whole records and blocks while there are none. A pending read is the push channel; `Tflush` cancels it. A record never spans two reads. **Records** ``` put del [key=value...] mv [key=value...] flags [key=value...] reset ``` ``` 48212 put /Notes/todo.md f 0644 830 1763491250 48212 b3:77d0… p dev=mac-a1 48213 del /Downloads/old.zip dev=linux-b2 48214 mv /Draft.md /Posts/Final.md dev=mac-a1 48215 flags /Projects p dev=mac-a1 ``` - `put` is a create or modify and carries the whole index line, so a client never needs a follow-up stat. - `mv` of a directory moves everything below it; there is no record per child. - `dev=` names the client that made the change, when known. - Records arrive in seq order. With `coalesce` a client may see gaps in seq; without it there are none. **Falling behind** A server keeps a bounded log. If `since N` names a seq it no longer has, or a reader falls too far behind, the server sends ` reset` and ends the stream; the client must re-read the index (or simply rescan) and reopen with `since`. **Bootstrapping with an index** Two gap-free ways: read the index at seq N, then open events with `since N`; or open events first (getting `seq `), read the index at some M, and drop records at or below M. ## Extension 3: path operations `ctl` performs namespace operations by path in one round trip, optionally conditional on a version. It needs no index or events, though a server with events reports every change it makes. **Commands** | Command | Effect | Replies | | --- | --- | --- | | `caps` | lists supported commands | `ok ...` | | `hello ` | names this client in events (`dev=`) | `ok` | | `mkdir []` | creates a directory | `ok `, `conflict ` | | `rm []` | removes a file, symlink, or empty directory | `ok `, `conflict `, `missing` | | `rmtree []` | removes a directory and everything below it | `ok `, `conflict `, `missing` | | `mv [] []` | renames, across directories, atomically | `ok `, `conflict `, `missing` | | `cp []` | copies on the server; cheap when content is deduplicated | `ok `, `conflict `, `missing` | | `flags ` | sets the index flags (`p`, `i`) | `ok ` | | `stat ` | returns the path's index line | `ok `, `missing` | **Conditional operations** - `` is the version the client expects `` (or ``) to have; `` is the expected version of the destination, `0` meaning it must not exist. - If a base is given and does not match, nothing changes and the reply is `conflict `. - Omitted bases make the operation unconditional, as with plain 9P. - A server without versions (no events, no staged commit) rejects any base with `invalid`. **Why this exists** - 9P2000 `wstat` can only rename within one directory, so a cross-directory move otherwise means copy plus delete. 9P2000.L has `Trenameat`, but it is not conditional. - Path operations need no walk, open, and clunk sequence, which matters over high-latency WebSockets. - A conditional `rm` or `mv` lets a client act without racing another client's change. ## Extension 4: staged commit Staged commit lets a client upload a file's bytes over any number of connections and attempts, then publish them atomically at a path only if that path is still at the version the client expects. **Staging** - A client creates a file under `.fs/stage/` with any name it chooses (a UUID is recommended) and writes bytes at any offsets. Re-opening an existing stage file and writing more resumes an interrupted upload. - Stage files are private to the attaching user and invisible in the index and events. - A server removes stage files that have not been written for a period it chooses, at least one hour. **Publishing** | Command | Effect | Replies | | --- | --- | --- | | `commit [hash=]` | publishes the stage file at `` if it is at ``, then removes the stage file | `ok `, `conflict `, `invalid` | | `commit-hash ` | publishes content the server already holds, with no upload | `ok `, `conflict `, `missing` | | `abort ` | discards a stage file | `ok` | - `` is required, `0` for a new path. There is no unconditional commit; plain 9P writes serve that role. - With `hash=`, the server verifies the content and replies `invalid` on a mismatch. - The publish is atomic: other clients see either the old content or the new, never a mix. - `commit-hash` answers `missing` when the server lacks the content; the client then stages and commits normally. A server decides how widely it searches (one scope, or every scope of the same user); see Security considerations. **Ordering guarantee** On a server with events, the `put` record for a commit is assigned before the `ok` reply is sent, and the reply carries that version. A client therefore recognizes its own change in the stream by version, and never mistakes it for a remote edit. **Plain writes** A server with staged commit should still accept ordinary 9P writes. They apply as last-writer-wins when the fid is clunked and produce events like any other change. ## Profiles A profile is a named set of extensions plus the behavior a client can expect. Servers state the profiles they meet; the reference implementation meets all three. | Profile | Extensions | Typical server | | --- | --- | --- | | Read-only cache | index | package and image caches such as wanix-cache | | Watchable | index (optional), events, path operations | a mutable file server that other tools watch | | Sync | index, events, path operations, staged commit | a server holding user roots for synced folders | ### Sync, as a composition (non-normative) A sync client keeps a local copy of a scope and needs nothing beyond the four extensions: 1. **Bootstrap:** `hello`, read the index with `accept zstd`, store every entry, then fetch content for `p` files not already held locally by hash. 2. **Follow:** open events `since `. Apply `put`, `del`, `mv`, and `flags` to the local copy; a changed hash makes a local copy stale. 3. **Write:** remember the version a local edit started from. Publish with `commit` (or `commit-hash` first), and use conditional `rm` and `mv` for deletes and renames. 4. **Conflict:** on `conflict`, keep the server's copy at the path, rename the local copy to `name.sync-conflict--.ext`, and commit it as a new file with base `0`. A delete that conflicts with an edit loses, so the edit stays. 5. **Offline:** queue changes with their base versions and replay them in order on reconnect. 6. **Reset:** on a `reset` record, re-read the index and reconcile. Because the server assigns one version per path, this needs no version vectors, and every change reaches every connected client in one round trip. The first commit to arrive wins, which is deterministic and never loses the other side's work. ## Future extension: history (sketch) A server that keeps old content and does not trim its log can expose past states with one more read-only extension, and no git-style checkout is needed: every seq already names a consistent state of the scope, so a past state can simply be served as a tree. - **`.fs/at//`** is a read-only view of the scope as it was right after change ``, with its own `.fs/index` at that seq. `.fs/at//` (RFC 3339) resolves to the last seq at or before that time. - **`history ` on ctl** lists a path's versions, newest first, as ` dev=` lines. - **Restore is an ordinary commit.** `cp /.fs/at/46990/Documents/Tax%202025.pdf /Documents/Tax%202025.pdf ` copies an old version over the current one with a base version, so it goes through conflict detection and reaches every client as a normal `put`. With content deduplicated by hash, the copy costs nothing. - **Retention** is the server's policy (for example, every version for 30 days, then daily). `.fs/at/` answers `Enotfound` once a state is pruned. Branches, merges, and per-client checkouts stay out of scope; the sketch only covers browsing and restoring the single line of history the server already orders. It needs nothing from the other extensions beyond what they define, so it can be added later without changing them. ## Security considerations The protocol adds no authentication of its own; it relies on the transport and on 9P's per-attach identity, and adds a few concerns to handle. - **Authentication.** Over WebSocket, authenticate on the HTTP upgrade (cookie or bearer token) and map that to the attach user. 9P `Tauth` is not used. Raw TCP transports should be limited to localhost or wrapped in TLS. - **Scope.** Every `.fs/` file and command is limited to the attach root. Paths in ctl are resolved within the scope, and `..` never leaves it. - **Hash probing.** `commit-hash` and `cp` reveal whether the server holds some content. A server must only consider content the attaching user can already read, so a user cannot learn about another user's files. - **Metadata exposure.** The index exposes every name in the scope at once. A server must only serve indexes of scopes the user can fully read, or leave unreadable subtrees out. - **Resource limits.** Servers should cap index size, the number of open event streams per user, stage space per user, and ctl command length, and return `denied` or a 9P error when a limit is hit. - **Event retention.** The log reveals recent names, including of deleted files, to anyone who can read the scope; keep the retention window no longer than needed. ## Relation to mount-index The index extension is a deliberate iteration on `/.h9index`, but the mount-index proposal stays unchanged until this is proven. If it is later folded in: | | `/.h9index` today | `.fs/index` | | --- | --- | --- | | Location | `/.h9index` at the root | `.fs/index`, alongside the other extensions | | Names with spaces or non-UTF-8 | left out, directory marked `!unindexed` | percent-escaped, always listed | | qid.vers of entries | 0 | the path's version, or 0 for read-only trees | | Changes | regenerate the file | the events extension | | Content identity | none | optional hash per file | | Hints | none | `p` prefetch, `i` nested index | | Encoding | plain text | plain, or zstd after an opt-in | ## Prior art | System | What this borrows | | --- | --- | | Coda (CMU, from AFS) | disconnected operation: a log of local changes replayed with conflict detection | | Plan 9 replica(1) | a database of paths plus a change log to bring a copy up to date | | Upspin | `Watch(name, sequence)`, a change stream after a sequence number | | Dropbox API v2 | snapshot with a cursor, deltas, and a long-poll to block; hash dedupe; resumable uploads | | WebDAV sync-collection (RFC 6578), Nextcloud | sync tokens for deltas; `If-Match` compare-and-swap writes | | Syncthing BEP | index and index updates keyed by sequence; conflict-copy naming | | inotify, fanotify | event vocabulary for local watching | These are from memory; links and checks against each system's documentation are still to add. ## Open questions - [ ] Is one snapshot per scope fine at user-data scale (about 100 bytes a line, roughly 10 MB uncompressed for 100k files), with nested indexes only for large subtrees? - [ ] Should events offer an index diff for a client slightly behind, or is `since N` always enough? - [ ] Should ignore rules (temp files, `.DS_Store`) be part of the protocol, for example as a flag or a shared file, or left to clients? - [ ] Is `hello` worth keeping, or should the device id come from the transport? - [ ] Which hash algorithms are allowed besides BLAKE3, and is the hash ever required? -- https://progrium.xyz/docs/proposals/9p-dotfs