Skip to content

Git designed for AI agents.

docs: the watermark fsync before git's lock, and bucket directories never removed while served

Federico Elia2dda256714e5
diff --git a/doc/graft/PLAN7.md b/doc/graft/PLAN7.md
index e8a6292..62d9dcb 100644
--- a/doc/graft/PLAN7.md
+++ b/doc/graft/PLAN7.md
@@ -714,10 +714,12 @@ repository-wide lock.
* It fsyncs the tables not yet fsynced, `tables.list` and the directory.
* When the repository has been idle for a second, or the process stops,
and nothing is live, the step clears the marker:
+ * It fsyncs the watermark and its directory (see *Watermark* below),
+ before git's lock, so that this fsync does not hold the transactions.
* It takes git's lock without waiting. The lock is created by linking a
temporary file that holds a tag and a random nonce.
- * It fsyncs what was written since, then the watermark and its directory,
- marks the state clean, and releases the lock. The release removes the lock only if it is still the same
+ * It fsyncs what was written since, marks the state clean, and releases
+ the lock. The release removes the lock only if it is still the same
file with the same nonce: an inode is reused as soon as it is freed, so
a lock that someone else replaced is never removed.
* Last, it removes the marker, under a per-repository file lock that
@@ -728,15 +730,19 @@ repository-wide lock.
servers stopped, so a clean reboot does not rehydrate them.
* *Watermark.* While a repository of the owner is dirty and has a reftable
stack, the syncer writes its watermark (`graft/storage/applied`) atomically
- without fsync (`CanDefer`).
+ without fsync (`DefersWatermark`).
* After a kernel restart a dirty cache is moved aside whatever its watermark
holds, and after a process restart the page cache kept the write. An
advance only changes the sequence; the repository ID was written with
fsync by the hydration, so a lost or torn advance leaves the recovery's
decision as it was.
- * The step that clears the marker under git's lock, and `Forget` of a
- repository kept in place, fsync the watermark and its directory first. A
+ * Every removal of a dirty marker fsyncs the watermark and its directory
+ first, if there is one: the step that clears it (before it takes git's
+ lock), the step of a repository whose stack is gone, and `Forget`. A
failed fsync makes the repository untrusted, as for the stack.
+ * The watermark cannot change between that fsync and the removal: the
+ syncer writes it only under its repository lock, which the step and
+ `Forget` hold.
* Hydration, import and the gate write it with fsync, as does a write
whose directory is missing.
* *Write failure.* Only a failed fsync means the kernel may have dropped
diff --git a/doc/graft/STORAGE.md b/doc/graft/STORAGE.md
index 54504e7..7b10dbd 100644
--- a/doc/graft/STORAGE.md
+++ b/doc/graft/STORAGE.md
@@ -50,7 +50,10 @@ maintenance). Where they differ, PLAN7.md is the later decision.
link(2), because gocloud's file driver does not make its own create-only write
atomic (it checks that the key is absent, then renames onto it, so two writers
of one key would both succeed). A file bucket therefore needs a filesystem
- with hard links. A changeset never references a pack that is not completely
+ with hard links. Never remove or replace a directory of a file bucket while a
+ server uses the bucket: a node remembers which directories it has made
+ durable, by inode, and a directory created again could reuse an inode it
+ remembers. A changeset never references a pack that is not completely
uploaded. Changesets written by v0.1.0 keep their keys
(`repos/<repo_id>/packs/<sha256>.pack`, shared by identical packs), which
stay readable; the database refuses such a key in a new changeset, so every