Section 4: A Library, Not a Mount Point - API Design (with Pushback)

Executive Summary: Applications link a user-space client library, not a kernel mount. It exposes ten calls: the usual namespace and file operations plus two that POSIX has no verb for, recordAppend and snapshot. Underneath, the library speaks two small RPC vocabularies, a control vocabulary with the master (FindChunks, GetLeaseHolder, HeartBeat) and a data vocabulary with chunkservers (PushData, Write, Append, Read, CloneChunk). Because chunks have a fixed size, the client turns a byte offset into a chunk index by division, so the master only ever answers a cacheable question. Four pushbacks defend that shape.

The interviewer taps Section 3's numbers. "Twelve thousand RPCs a second at the master, and none of them carry data. Show me the calls that make that true."

You: "Two layers: what the crawler and the indexer call, and what the library says on the wire. The master shows up on the wire only for names, chunk locations and leases."

The Client Library Contract

create(path)                          delete(path)
rename(src, dst)                      list(dir) -> [entries]
open(path) -> handle                  close(handle)
read(handle, offset, length) -> bytes
write(handle, offset, data)           # rare: overwrite at a client-chosen offset
recordAppend(handle, data) -> offset  # data <= 16 MB, offset chosen by the system
snapshot(src, dst)                    # file or directory tree, copy-on-write

Namespace calls are atomic at the master (Section 7 covers the locks and the operation log). rename is atomic too, which is the pattern writers depend on: write under a temporary name, then rename it into place. recordAppend returns the offset where the system put the record, and that offset is the whole promise. The record landed there atomically, at the same offset on every replica, at least once. The 16 MB cap is a quarter of a chunk, so padding waste stays under 25% in the worst case and around 0.8% for the crawl's 1 MB records.

There's no data cache in the library. The crawl file is streamed once and never reread, so coherence machinery would protect nothing. The library caches metadata only: chunk locations, with a 60 s TTL or until the file is reopened.